pyisyntax 0.1.0__tar.gz

pyisyntax-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2024 Aiden Nibali
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pyisyntax-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md
+include LICENSE
+
+graft isyntax_build
+prune isyntax_build/vendor/libisyntax
+graft isyntax_build/vendor/libisyntax/src
+include isyntax_build/vendor/libisyntax/LICENSE.txt
+include isyntax_build/vendor/libisyntax/README.md
+
+graft tests
+recursive-exclude tests *.isyntax
+
+prune */.pytest_cache
+prune */__pycache__

pyisyntax-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.1
+Name: pyisyntax
+Version: 0.1.0
+Summary: Python bindings for libisyntax
+Author-email: Aiden Nibali <dismaldenizen@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cffi>=1.12
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: conda-lock; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: ruff==0.2.1; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# pyisyntax
+
+A Python library for working with pathology images in the iSyntax file format,
+powered by [libisyntax](https://github.com/amspath/libisyntax).
+
+## Usage
+
+Read and display a region of the WSI via
+[Pillow](https://pillow.readthedocs.io/).
+
+```python
+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.
+
+```python
+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"])
+```
+
+## Development
+
+### Dependency management
+
+To set up a development environment from the lock file:
+
+1. Ensure that you have
+   [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html)
+   installed.
+2. Create the environment:
+   ```console
+   $ micromamba create -n pyisyntax -f conda-lock.yml --category main --category dev
+   ```
+3. Activate the environment:
+   ```console
+   $ micromamba activate pyisyntax
+   ```
+
+To modify pyisyntax project dependencies:
+
+1. Edit pyproject.toml.
+2. Update the lock file using conda-lock:
+   ```console
+   $ conda-lock lock -f pyproject.toml -p linux-64 --micromamba
+   ```

pyisyntax-0.1.0/README.md

@@ -0,0 +1,63 @@
+# pyisyntax
+
+A Python library for working with pathology images in the iSyntax file format,
+powered by [libisyntax](https://github.com/amspath/libisyntax).
+
+## Usage
+
+Read and display a region of the WSI via
+[Pillow](https://pillow.readthedocs.io/).
+
+```python
+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.
+
+```python
+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"])
+```
+
+## Development
+
+### Dependency management
+
+To set up a development environment from the lock file:
+
+1. Ensure that you have
+   [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html)
+   installed.
+2. Create the environment:
+   ```console
+   $ micromamba create -n pyisyntax -f conda-lock.yml --category main --category dev
+   ```
+3. Activate the environment:
+   ```console
+   $ micromamba activate pyisyntax
+   ```
+
+To modify pyisyntax project dependencies:
+
+1. Edit pyproject.toml.
+2. Update the lock file using conda-lock:
+   ```console
+   $ conda-lock lock -f pyproject.toml -p linux-64 --micromamba
+   ```

pyisyntax-0.1.0/isyntax/__init__.py

@@ -0,0 +1,5 @@
+from isyntax.wrapper import ISyntax
+
+__all__ = [
+    "ISyntax",
+]

pyisyntax-0.1.0/isyntax/lowlevel/io_management.py

@@ -0,0 +1,115 @@
+from collections.abc import Iterator
+from dataclasses import dataclass
+from io import BufferedIOBase, RawIOBase
+from typing import Generic, NewType, TypeVar
+
+from _pyisyntax import ffi, lib
+
+VoidPtr = NewType("VoidPtr", object)
+T = TypeVar("T")
+
+
+@dataclass
+class SizedIO:
+    #: The IO object.
+    f: RawIOBase | BufferedIOBase
+    #: The complete length of the IO object's data (in bytes).
+    n_bytes: int
+
+
+class ByHandleRegistry(Generic[T]):
+    class _EmptySlot:
+        pass
+
+    def __init__(self) -> None:
+        """Creates a registry of objects keyed by integer handles.
+
+        Handles start at 1, autoincrement, and will automatically be recycled
+        once objects are removed from the registry.
+        """
+        self._list = []
+        self._n_free = 0
+        self._empty_slot = self._EmptySlot()
+
+    def pop(self, handle: int) -> T:
+        element = self._list[handle - 1]
+        self._list[handle - 1] = self._empty_slot
+        self._n_free += 1
+        if len(self._list) == handle:
+            while len(self._list) > 0 and self._list[-1] is self._empty_slot:
+                self._list.pop()
+                self._n_free -= 1
+        return element
+
+    def add(self, element: T) -> int:
+        if self._n_free == 0:
+            self._list.append(element)
+            return len(self._list)
+        index = self._list.index(self._empty_slot)
+        self._list[index] = element
+        self._n_free -= 1
+        # Handles start at 1.
+        return index + 1
+
+    def __getitem__(self, handle: int) -> T:
+        return self._list[handle - 1]
+
+    def items(self) -> Iterator[tuple[int, T]]:
+        for i, element in enumerate(self._list):
+            if element is not self._empty_slot:
+                yield i + 1, element
+
+
+_io_registry = ByHandleRegistry[SizedIO]()
+
+
+def init_python_io_hooks() -> None:
+    @ffi.def_extern()
+    def python_file_set_pos(handle: int, offset: int) -> bool:
+        _io_registry[handle].f.seek(offset)
+        return True
+
+
+    @ffi.def_extern()
+    def python_file_read_into(handle: int, dest: VoidPtr, bytes_to_read: int) -> int:
+        bytes_read = _io_registry[handle].f.readinto(ffi.buffer(dest, bytes_to_read))
+        if bytes_read is None:
+            raise RuntimeError
+        return max(bytes_read, 1)
+
+
+    @ffi.def_extern()
+    def python_file_get_size(handle: int) -> int:
+        return _io_registry[handle].n_bytes
+
+
+    @ffi.def_extern()
+    def python_file_close(handle: int) -> None:
+        _io_registry.pop(handle).f.close()
+
+
+    lib.init_python_platform_utils(
+        lib.python_file_set_pos,
+        lib.python_file_read_into,
+        lib.python_file_get_size,
+        lib.python_file_close,
+    )
+
+
+def register_io(f: RawIOBase | BufferedIOBase, n_bytes: int) -> int:
+    """Registers a Python IO object for use with the underlying C library.
+
+    Args:
+        f: IO object to register.
+        n_bytes: Size of the IO object's data (in bytes).
+
+    Raises:
+        RuntimeError: When the IO object is not readable.
+
+    Returns:
+        New handle assigned to the IO object.
+    """
+    if not f.readable:
+        msg = "IO object must be readable"
+        raise RuntimeError(msg)
+    return _io_registry.add(SizedIO(f, n_bytes))

pyisyntax-0.1.0/isyntax/lowlevel/libisyntax.py

@@ -0,0 +1,260 @@
+import os
+from enum import IntEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, NewType
+
+from _pyisyntax import ffi, lib
+
+from isyntax.lowlevel.io_management import init_python_io_hooks, register_io
+
+if TYPE_CHECKING:
+    from cffi import FFI
+    from typing_extensions import Buffer
+
+
+Pointer = NewType("Pointer", "FFI.CData")
+ISyntaxPtr = NewType("ISyntaxPtr", Pointer)
+ISyntaxImagePtr = NewType("ISyntaxImagePtr", Pointer)
+ISyntaxLevelPtr = NewType("ISyntaxLevelPtr", Pointer)
+ISyntaxCachePtr = NewType("ISyntaxCachePtr", Pointer)
+
+
+LIBISYNTAX_OK = 0
+# Generic error that the user should not expect to recover from.
+LIBISYNTAX_FATAL = 1
+# One of the arguments passed to a function is invalid.
+LIBISYNTAX_INVALID_ARGUMENT = 2
+
+
+class ISyntaxPixelFormat(IntEnum):
+    RGBA = lib.LIBISYNTAX_PIXEL_FORMAT_RGBA
+    BGRA = lib.LIBISYNTAX_PIXEL_FORMAT_BGRA
+
+
+class LibISyntaxError(Exception):
+    pass
+
+
+class LibISyntaxFatalError(LibISyntaxError):
+    pass
+
+
+class LibISyntaxInvalidArgumentError(LibISyntaxError):
+    pass
+
+
+class LibISyntaxUnknownError(LibISyntaxError):
+    pass
+
+
+class NullPointerError(Exception):
+    pass
+
+
+def check_error(status: int) -> None:
+    if status == LIBISYNTAX_OK:
+        return
+    if status == LIBISYNTAX_FATAL:
+        raise LibISyntaxFatalError
+    if status == LIBISYNTAX_INVALID_ARGUMENT:
+        raise LibISyntaxInvalidArgumentError
+    raise LibISyntaxUnknownError
+
+
+def free(ptr: Pointer) -> None:
+    lib.free(ptr)
+
+
+def _do_init() -> None:
+    check_error(lib.libisyntax_init())
+    init_python_io_hooks()
+
+
+def init() -> None:
+    ffi.init_once(_do_init, "libisyntax_init")
+
+
+def open_from_registered_handle(handle: int, *, is_init_allocators: bool = False) -> ISyntaxPtr:
+    init()
+
+    isyntax = ffi.new("isyntax_t**")
+    check_error(lib.libisyntax_open(
+        ffi.new("char[]", str(handle).encode("utf-8")),
+        is_init_allocators,
+        isyntax,
+    ))
+    return isyntax[0]
+
+
+def open_from_filename(filename: str | Path, *, is_init_allocators: bool = False) -> ISyntaxPtr:
+    filename = Path(filename)
+    f = filename.open("rb")
+    handle = register_io(f, os.fstat(f.fileno()).st_size)
+    return open_from_registered_handle(handle, is_init_allocators=is_init_allocators)
+
+
+def close(isyntax: ISyntaxPtr) -> None:
+    # If a null pointer gets through the program will segfault.
+    if isyntax == ffi.NULL:
+        raise NullPointerError
+    lib.libisyntax_close(isyntax)
+
+
+def get_tile_width(isyntax: ISyntaxPtr) -> int:
+    return lib.libisyntax_get_tile_width(isyntax)
+
+
+def get_tile_height(isyntax: ISyntaxPtr) -> int:
+    return lib.libisyntax_get_tile_height(isyntax)
+
+
+def get_wsi_image_index(isyntax: ISyntaxPtr) -> int:
+    return lib.libisyntax_get_wsi_image_index(isyntax)
+
+
+def get_image(isyntax: ISyntaxPtr, wsi_image_index: int) -> ISyntaxImagePtr:
+    return lib.libisyntax_get_image(isyntax, wsi_image_index)
+
+
+def image_get_level_count(wsi_image: ISyntaxImagePtr) -> int:
+    return lib.libisyntax_image_get_level_count(wsi_image)
+
+
+def image_get_level(wsi_image: ISyntaxImagePtr, index: int) -> ISyntaxLevelPtr:
+    return lib.libisyntax_image_get_level(wsi_image, index)
+
+
+def level_get_scale(level: ISyntaxLevelPtr) -> int:
+    return lib.libisyntax_level_get_scale(level)
+
+
+def level_get_width_in_tiles(level: ISyntaxLevelPtr) -> int:
+    return lib.libisyntax_level_get_width_in_tiles(level)
+
+
+def level_get_height_in_tiles(level: ISyntaxLevelPtr) -> int:
+    return lib.libisyntax_level_get_height_in_tiles(level)
+
+
+def level_get_width(level: ISyntaxLevelPtr) -> int:
+    return lib.libisyntax_level_get_width(level)
+
+
+def level_get_height(level: ISyntaxLevelPtr) -> int:
+    return lib.libisyntax_level_get_height(level)
+
+
+def level_get_mpp_x(level: ISyntaxLevelPtr) -> float:
+    return lib.libisyntax_level_get_mpp_x(level)
+
+
+def level_get_mpp_y(level: ISyntaxLevelPtr) -> float:
+    return lib.libisyntax_level_get_mpp_y(level)
+
+
+def cache_create(debug_name: str | None, cache_size: int) -> ISyntaxCachePtr:
+    isyntax_cache = ffi.new("isyntax_cache_t**")
+    if debug_name is None:
+        debug_name_or_null = ffi.NULL
+    else:
+        debug_name_or_null = ffi.new("char[]", debug_name.encode("utf-8"))
+    check_error(lib.libisyntax_cache_create(
+        debug_name_or_null,
+        cache_size,
+        isyntax_cache,
+    ))
+    return isyntax_cache[0]
+
+
+def cache_inject(isyntax_cache: ISyntaxCachePtr, isyntax: ISyntaxPtr) -> None:
+    check_error(lib.libisyntax_cache_inject(isyntax_cache, isyntax))
+
+
+def cache_destroy(isyntax_cache: ISyntaxCachePtr) -> None:
+    if isyntax_cache == ffi.NULL:
+        raise NullPointerError
+    lib.libisyntax_cache_destroy(isyntax_cache)
+
+
+def tile_read(
+    isyntax: ISyntaxPtr,
+    isyntax_cache: ISyntaxCachePtr,
+    level: int,
+    tile_x: int,
+    tile_y: int,
+    pixels_buffer: "Buffer | FFI.buffer",
+    pixel_format: ISyntaxPixelFormat,
+) -> None:
+    check_error(lib.libisyntax_tile_read(
+        isyntax,
+        isyntax_cache,
+        level,
+        tile_x,
+        tile_y,
+        ffi.from_buffer("uint32_t[]", pixels_buffer, require_writable=True),
+        pixel_format,
+    ))
+
+
+def read_region(
+    isyntax: ISyntaxPtr,
+    isyntax_cache: ISyntaxCachePtr,
+    level: int,
+    x: int,
+    y: int,
+    width: int,
+    height: int,
+    pixels_buffer: "Buffer | FFI.buffer",
+    pixel_format: ISyntaxPixelFormat,
+) -> None:
+    check_error(lib.libisyntax_read_region(
+        isyntax,
+        isyntax_cache,
+        level,
+        x,
+        y,
+        width,
+        height,
+        ffi.from_buffer("uint32_t[]", pixels_buffer, require_writable=True),
+        pixel_format,
+    ))
+
+
+def read_label_image_jpeg(isyntax: ISyntaxPtr) -> memoryview:
+    jpeg_buffer_ptr = ffi.new("uint8_t**")
+    jpeg_size_ptr = ffi.new("uint32_t*")
+    check_error(lib.libisyntax_read_label_image_jpeg(
+        isyntax,
+        jpeg_buffer_ptr,
+        jpeg_size_ptr,
+    ))
+    jpeg_buffer = ffi.gc(jpeg_buffer_ptr[0], free)
+    jpeg_size = jpeg_size_ptr[0]
+    return memoryview(ffi.buffer(jpeg_buffer, jpeg_size))
+
+
+def read_macro_image_jpeg(isyntax: ISyntaxPtr) -> memoryview:
+    jpeg_buffer_ptr = ffi.new("uint8_t**")
+    jpeg_size_ptr = ffi.new("uint32_t*")
+    check_error(lib.libisyntax_read_macro_image_jpeg(
+        isyntax,
+        jpeg_buffer_ptr,
+        jpeg_size_ptr,
+    ))
+    jpeg_buffer = ffi.gc(jpeg_buffer_ptr[0], free)
+    jpeg_size = jpeg_size_ptr[0]
+    return memoryview(ffi.buffer(jpeg_buffer, jpeg_size))
+
+
+def read_icc_profile(isyntax: ISyntaxPtr, image: ISyntaxImagePtr) -> memoryview:
+    profile_buffer_ptr = ffi.new("uint8_t**")
+    profile_size_ptr = ffi.new("uint32_t*")
+    check_error(lib.libisyntax_read_icc_profile(
+        isyntax,
+        image,
+        profile_buffer_ptr,
+        profile_size_ptr,
+    ))
+    profile_buffer = ffi.gc(profile_buffer_ptr[0], free)
+    profile_size = profile_size_ptr[0]
+    return memoryview(ffi.buffer(profile_buffer, profile_size))