pyisyntax-fastio

Important

This is an experimental, unofficial fork of pyisyntax. It preserves the public from isyntax import ISyntax API while evaluating positional I/O and bounded codeblock prefetching. The 64 KiB coalescing policy is enabled in this alpha but has not been accepted as a stable-release default; true OS-cold HDD validation is still pending.

A Python library for working with pathology images in the iSyntax file format, powered by libisyntax.

Installation

Pre-release wheels are distributed through the GitHub Releases page. Download the file matching your operating system and architecture, then run:

$ python -m pip install ./pyisyntax_fastio-0.2.0a1-<platform>.whl

The Windows x86-64, Linux x86-64, and macOS Intel/Apple Silicon wheels use the CPython Stable ABI (cp310-abi3) and require Python 3.10 or newer. CI tests cover CPython 3.10, 3.11, and 3.12.

Alternatively, install from a checked-out source tree with its submodule initialized:

$ git submodule update --init --recursive
$ python -m pip install .

This fork has not been published to PyPI. The existing pip install pyisyntax command installs the upstream project, not this experimental fork.

Usage

Read and display a region of the WSI via Pillow.

from isyntax import ISyntax
import PIL.Image

with ISyntax.open("my_file.isyntax") as isyntax:
    # Read pixels from the specified region into a numpy array
    pixels = isyntax.read_region(500, 500, 400, 200, level=4)
    # Convert numpy array into a PIL image
    pil_image = PIL.Image.fromarray(pixels)
    # Show the image
    pil_image.show()

Extract and save the associated macro image.

from isyntax import ISyntax

with ISyntax.open("my_file.isyntax") as isyntax:
    # The macro image will be returned as compressed JPEG data.
    jpeg_data = isyntax.read_macro_image_jpeg()
    # This JPEG data can be written directly to a file.
    with open("macro_image.jpg", "wb") as f:
        f.write(jpeg_data)
    # Alternatively, you could decompress the data using Pillow:
    # pil_image = PIL.Image.open(io.BytesIO(jpeg_data), formats=["JPEG"])

I/O backends

ISyntax.open(path) uses a native positional file source. Seekable Python file-like objects remain supported through ISyntax(stream, n_bytes) and use one atomic read_at callback per physical request. Both paths share the same decoder and strict short-read handling.

Tile reads plan missing codeblocks before decoding, read them in file-offset order, and merge only ranges separated by at most 64 KiB. A merged range is also capped at 1 MiB, limiting over-read and temporary memory use. These are private implementation details; the public NumPy/RGBA API is unchanged.

Threading safety

Pixel reads must currently run on the same Python thread that first opens an iSyntax slide. The vendored libisyntax initializes temporary-memory state only for that caller thread; calling read_tile() or read_region() from another Python thread can otherwise crash the process. pyisyntax temporarily rejects such calls with RuntimeError until the native library provides safe per-caller-thread initialization. Opening and reading a slide inside one worker thread is supported as long as that worker is also the first thread to initialize libisyntax in the process.

Provenance and licensing

This fork retains the upstream pyisyntax history and MIT license. Its modified native backend is based on libisyntax and retains the BSD-2-Clause license. See THIRD_PARTY_NOTICES.md for attribution and source links. This project is not an official release of either upstream project.

Development

Dependency management

To set up a development environment from the lock file:

1. Ensure that you have uv installed.
2. Create the virtual environment:

   $ uv sync --frozen

To modify pyisyntax project dependencies:

1. Edit dependencies in pyproject.toml.
2. Update the lock file using uv:

   $ uv lock