Add pylibCZIrw reader for CZI support

.gitignore

@@ -174,3 +174,6 @@ work/
 
 # Ignore version file
 *_version.py
+
+# LGPL-licensed test fixtures (downloaded at test time)
+tests/data/*.czi

docs/source/api/readers.rst

@@ -32,4 +32,5 @@ To retrieve a reader class
     OpenSlideReader
     TiffSlideReader
     BioFormatsReader
+    PylibCZIReader
     SpatialDataImage2DReader

docs/source/installation.rst

@@ -116,3 +116,23 @@ Installation for slide readers
 
             pip install pyisyntax
 
+    .. tab-item:: pylibCZIrw
+
+        `pylibCZIrw <https://github.com/ZEISS/pylibczirw>`_ is the official
+        Python binding to `libCZI <https://github.com/ZEISS/libczi>`_,
+        maintained by Zeiss, for reading and writing Zeiss CZI whole-slide
+        images. Unlike BioFormats, it decodes JPEG-XR natively on every
+        platform it ships wheels for - including ``arm64`` macOS, where
+        BioFormats cannot load the ``ome:jxrlib`` native library. It is
+        therefore the recommended backend for ``.czi`` files on Apple
+        Silicon.
+
+        .. code-block:: bash
+
+            pip install pylibCZIrw
+
+        Wheels are published for Linux (``x86_64`` and ``aarch64``),
+        macOS (``arm64``), and Windows (``x86_64``) on CPython 3.9-3.13.
+        There is no macOS ``x86_64`` wheel, so Intel Macs will need to
+        build from source or use BioFormats.
+

pyproject.toml

@@ -41,7 +41,9 @@ stain = ["torchstain"]
 bioformats = ["scyjava"]
 cucim = ["cucim"]
 tiffslide = ["tiffslide"]
+fastslide = ["fastslide"]
 isyntax = ["pyisyntax"]
+pylibczi = ["pylibCZIrw"]
 plot = ["matplotlib", "legendkit"]
 
 [tool.hatch.version]
@@ -108,6 +110,7 @@ dev = [
     "tiffslide>=2.4.0",
     "scyjava>=1.10.1",
     "pyisyntax>=0.1.5",
+    "pylibCZIrw>=6.0.0",
     "huggingface-hub>=1.7.2",
 ]
 docs = [

tests/conftest.py

@@ -5,6 +5,9 @@
 
 REPO_ID = "RendeiroLab/LazySlide-data"
 
+# Zeiss CZI test file (LGPL-licensed, not redistributable via our HF repo)
+CZI_URL = "https://github.com/ZEISS/pylibczirw/raw/main/test_data/c1_bgr24.czi"
+
 
 @pytest.fixture(scope="session")
 def test_slide():
@@ -16,6 +19,19 @@ def test_isyntax():
     return hf_hub_download(REPO_ID, "testslide.isyntax", repo_type="dataset")
 
 
+@pytest.fixture(scope="session")
+def test_czi():
+    # Zeiss c1_bgr24.czi from pylibczirw repo (LGPL license, fetched directly)
+    from urllib.request import urlretrieve
+
+    data_dir = Path(__file__).parent / "data"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    dest = data_dir / "c1_bgr24.czi"
+    if not dest.exists():
+        urlretrieve(CZI_URL, dest)
+    return str(dest)
+
+
 @pytest.fixture(scope="session")
 def test_store():
     slide_zarr_zip = hf_hub_download(REPO_ID, "sample.zarr.zip", repo_type="dataset")

tests/test_readers.py

@@ -17,6 +17,8 @@ def try_import(mod):
 def skip_reader(reader):
     if reader == "bioformats":
         return not try_import("scyjava")
+    elif reader == "pylibczi":
+        return not try_import("pylibCZIrw")
     else:
         return not try_import(reader)
 
@@ -58,6 +60,11 @@ def test_isyntax(test_isyntax):
     run_reader_test("isyntax", test_isyntax)
 
 
+@pytest.mark.skipif(skip_reader("pylibczi"), reason="pylibCZIrw not installed")
+def test_pylibczi(test_czi):
+    run_reader_test("pylibczi", test_czi)
+
+
 def test_spatialdata(test_slide):
     import numpy as np
     from spatialdata import SpatialData

wsidata/io/_wsi.py

@@ -20,7 +20,7 @@
 def open_wsi(
     wsi: str | Path | SpatialData,
     store: str = "auto",
-    reader: Literal["openslide", "tiffslide", "bioformats", "isyntax"] = None,
+    reader: str = None,
     attach_images: bool = False,
     image_key: str = None,
     save_images: bool = True,
@@ -48,7 +48,7 @@ def open_wsi(
         If a directory is supplied, the zarr file will be created in that directory.
         This is useful when you want to store all zarr files in a specific location.
     reader : str, optional
-        Reader to use, by default "auto", choosing available reader, first openslide, then tiffslide, then bioformats.
+        Reader to use, by default "auto", to check avaiable readers: `print(wsidata.READERS)`
     attach_images : bool, optional, default: False
         Whether to attach whole slide image to image slot in the spatial data object.
     image_key : str, optional

wsidata/reader/__init__.py

@@ -10,6 +10,7 @@
 from .fastslide import FastSlideReader
 from .isyntax import ISyntaxReader
 from .openslide import OpenSlideReader
+from .pylibczi import PylibCZIReader
 from .spatialdata_image2d import SpatialDataImage2DReader
 from .tiffslide import TiffSlideReader
 
@@ -30,6 +31,7 @@
     "CuCIMReader",
     "FastSlideReader",
     "ISyntaxReader",
+    "PylibCZIReader",
     "SpatialDataImage2DReader",
     "TiffSlideReader",
     "to_datatree",

wsidata/reader/_reader_registry.py

@@ -8,7 +8,22 @@
 
 
 class ReaderRegistry(MutableMapping):
-    priority = ["openslide", "tiffslide", "fastslide", "bioformats", "cucim", "isyntax"]
+    # ``pylibczi`` is deliberately placed ahead of ``bioformats`` because
+    # it is CZI-only: pyczi.open_czi raises on any non-CZI input, so
+    # ``try_open`` falls straight through to BioFormats for other formats.
+    # Placing it after BioFormats would mean a ``.czi`` file auto-detects
+    # to BioFormats on arm64 macOS, where the required JPEG-XR native lib
+    # is unavailable, and the user would only see the failure at first
+    # read.
+    priority = [
+        "openslide",
+        "tiffslide",
+        "fastslide",
+        "pylibczi",
+        "bioformats",
+        "cucim",
+        "isyntax",
+    ]
 
     def __init__(self):
         self._readers: Dict[str, type[ReaderBase]] = {}

wsidata/reader/fastslide.py

@@ -1,9 +1,11 @@
 from pathlib import Path
 from typing import Union
 
+from ._reader_registry import register
 from .base import AssociatedImages, ReaderBase, convert_image
 
 
+@register(name="fastslide")
 class FastSlideReader(ReaderBase):
     """
     Use FastSlide to interface with image files.
@@ -59,8 +61,8 @@ def get_thumbnail(self, size, **kwargs):
         return convert_image(img)
 
     def detach_reader(self):
-        if self.reader is not None:
-            self.reader.close()
+        if self._reader is not None:
+            self._reader.close()
             self.set_reader(None)
 
     def create_reader(self):

wsidata/reader/openslide.py

@@ -63,9 +63,9 @@ def get_thumbnail(self, size, **kwargs):
         return convert_image(img)
 
     def detach_reader(self):
-        if self.reader is not None:
+        if self._reader is not None:
             try:
-                self.reader.close()
+                self._reader.close()
                 self.set_reader(None)
             # There is a chance that the pointer
             # to C-library is already collected