bioio-openreadout 0.1.0__tar.gz

bioio_openreadout-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+/target
+/corpus/files/
+/oracle/bftools/
+/oracle/.venv/
+/oracle/.cache/
+/oracle/__pycache__/
+**/__pycache__/
+*.pyc
+/dist/
+/wheels/
+*.ome.tiff
+*.ome.tif
+!/docs/**/*.ome.tiff
+.DS_Store
+/.env
+# maturin develop drops the compiled extension next to the Python sources
+/crates/openreadout-py/python/openreadout/_native*.so
+/crates/openreadout-py/python/openreadout/_native*.pyd
+*.egg-info/
+.pytest_cache/
+# cargo-fuzz build output, crash artifacts and the growing working corpus (seeds: fuzz/corpus)
+/fuzz/target/
+/fuzz/artifacts*/
+/fuzz/work/
+/fuzz/logs/
+/fuzz/coverage/
+/book/book/
+/book/node_modules/
+/book/.astro/
+/.venv/
+/fuzz/local-seeds/
+/fuzz/found/
+# WebAssembly package build output (scripts/wasm.sh) and npm installs
+/packaging/wasm/pkg/
+/packaging/wasm/node_modules/
+/web/node_modules/
+# Claude Code worktrees and local state
+/.claude/
+# eval run output (reports, per-run records, transcripts, logs)
+/evals/results/

bioio_openreadout-0.1.0/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

bioio_openreadout-0.1.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The OpenReadout Authors
+
+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.

bioio_openreadout-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: bioio-openreadout
+Version: 0.1.0
+Summary: bioio reader plugin that reads microscopy files with OpenReadout
+Project-URL: Homepage, https://github.com/openreadout/openreadout
+Project-URL: Repository, https://github.com/openreadout/openreadout
+Project-URL: Documentation, https://openreadout.github.io/openreadout/guides/python.html
+Author-email: The OpenReadout Authors <openreadout@gmail.com>
+License-Expression: MIT OR Apache-2.0
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Keywords: bioio,czi,imaging,lif,microscopy,nd2
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: bioio-base<4,>=3.4
+Requires-Dist: dask[array]>=2022.2
+Requires-Dist: fsspec>=2022.8.0
+Requires-Dist: numpy>=1.22
+Requires-Dist: ome-types>=0.4
+Requires-Dist: openreadout[xarray]<0.2,>=0.1.0
+Requires-Dist: xarray>=2022.6
+Provides-Extra: test
+Requires-Dist: bioio-nd2; extra == 'test'
+Requires-Dist: bioio>=3; extra == 'test'
+Requires-Dist: czifile; extra == 'test'
+Requires-Dist: liffile; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# bioio-openreadout
+
+A [bioio](https://github.com/bioio-devs/bioio) reader plugin that reads microscopy files with [OpenReadout](https://github.com/openreadout/openreadout)'s Rust readers. It is licensed MIT OR Apache-2.0 and depends on no GPL plugin, vendor SDK or Java. Wheels need no compiler. Each plane is one dask chunk and is decoded only when a computation needs it.
+
+```bash
+pip install bioio bioio-openreadout
+```
+
+```python
+from bioio import BioImage
+import bioio_openreadout
+
+img = BioImage("run42.czi", reader=bioio_openreadout.Reader)
+img.scenes  # ('P2', 'P3', 'P1') — one per CZI scene / ND2 position / LIF series
+img.dims  # <Dimensions [T: 1, C: 3, Z: 5, Y: 325, X: 475]>
+img.channel_names  # ['EGFP', 'TaRFP', 'Bright']
+img.physical_pixel_sizes  # PhysicalPixelSizes(Z=1.0, Y=1.083, X=1.083)  (µm)
+img.set_scene(1)
+zyx = img.get_image_dask_data("ZYX", T=0, C=1).compute()  # decodes 5 planes, not the file
+img.ome_metadata  # ome_types.OME built from the normalized metadata
+```
+
+`BioImage(path)` without `reader=` also works for `.czi`, `.nd2`, `.lif`, `.vsi`, `.svs`, `.ndpi`, `.qptiff`, `.ims`, `.oir`, `.oib`, `.oif` and `.zvi`: the plugin registers these extensions through the `bioio.readers` entry point. Other formats OpenReadout reads, such as OME-TIFF or OME-Zarr, open with `reader=bioio_openreadout.Reader`. When another plugin for the same extension is installed (for example `bioio-nd2`), bioio's own ordering decides which is tried first; pass `reader=` to choose.
+
+## What you get
+
+| bioio | from OpenReadout |
+|---|---|
+| `scenes` | image names (`Image:<n>` when the file has none; duplicates are suffixed with the index) |
+| `dims` | `TCZYX`, or `TCZYXS` for RGB (interleaved samples) |
+| `channel_names` | channel names (`Channel:<scene>:<c>` when the file has none) |
+| `physical_pixel_sizes` | µm, `None` where the file records no size |
+| `time_interval` | the recorded time increment |
+| `metadata` / `ome_metadata` | `ome_types.OME` (one `Image` per scene, `MetadataOnly` pixels) |
+| `xarray_dask_data.attrs["unprocessed"]` | the vendor's own metadata tree as JSON, names untouched |
+
+Mosaics are returned stitched (no `M` dimension); pyramidal files at full resolution only. Remote (fsspec) paths are not supported: the file must be local.
+
+## Tests
+
+```bash
+pip install -e 'python/bioio-openreadout[test]'
+OPENREADOUT_CORPUS_DIR=corpus/files pytest python/bioio-openreadout/tests
+```
+
+The tests compare `img.data` against `bioio-nd2`, `czifile` and `liffile` (all BSD) on files from the public test corpus and skip when those files or readers are absent.
+
+Guide: <https://openreadout.github.io/openreadout/guides/python.html>. Part of [OpenReadout](https://github.com/openreadout/openreadout). Licensed MIT OR Apache-2.0. OpenReadout is not affiliated with any instrument vendor.

bioio_openreadout-0.1.0/README.md

@@ -0,0 +1,48 @@
+# bioio-openreadout
+
+A [bioio](https://github.com/bioio-devs/bioio) reader plugin that reads microscopy files with [OpenReadout](https://github.com/openreadout/openreadout)'s Rust readers. It is licensed MIT OR Apache-2.0 and depends on no GPL plugin, vendor SDK or Java. Wheels need no compiler. Each plane is one dask chunk and is decoded only when a computation needs it.
+
+```bash
+pip install bioio bioio-openreadout
+```
+
+```python
+from bioio import BioImage
+import bioio_openreadout
+
+img = BioImage("run42.czi", reader=bioio_openreadout.Reader)
+img.scenes  # ('P2', 'P3', 'P1') — one per CZI scene / ND2 position / LIF series
+img.dims  # <Dimensions [T: 1, C: 3, Z: 5, Y: 325, X: 475]>
+img.channel_names  # ['EGFP', 'TaRFP', 'Bright']
+img.physical_pixel_sizes  # PhysicalPixelSizes(Z=1.0, Y=1.083, X=1.083)  (µm)
+img.set_scene(1)
+zyx = img.get_image_dask_data("ZYX", T=0, C=1).compute()  # decodes 5 planes, not the file
+img.ome_metadata  # ome_types.OME built from the normalized metadata
+```
+
+`BioImage(path)` without `reader=` also works for `.czi`, `.nd2`, `.lif`, `.vsi`, `.svs`, `.ndpi`, `.qptiff`, `.ims`, `.oir`, `.oib`, `.oif` and `.zvi`: the plugin registers these extensions through the `bioio.readers` entry point. Other formats OpenReadout reads, such as OME-TIFF or OME-Zarr, open with `reader=bioio_openreadout.Reader`. When another plugin for the same extension is installed (for example `bioio-nd2`), bioio's own ordering decides which is tried first; pass `reader=` to choose.
+
+## What you get
+
+| bioio | from OpenReadout |
+|---|---|
+| `scenes` | image names (`Image:<n>` when the file has none; duplicates are suffixed with the index) |
+| `dims` | `TCZYX`, or `TCZYXS` for RGB (interleaved samples) |
+| `channel_names` | channel names (`Channel:<scene>:<c>` when the file has none) |
+| `physical_pixel_sizes` | µm, `None` where the file records no size |
+| `time_interval` | the recorded time increment |
+| `metadata` / `ome_metadata` | `ome_types.OME` (one `Image` per scene, `MetadataOnly` pixels) |
+| `xarray_dask_data.attrs["unprocessed"]` | the vendor's own metadata tree as JSON, names untouched |
+
+Mosaics are returned stitched (no `M` dimension); pyramidal files at full resolution only. Remote (fsspec) paths are not supported: the file must be local.
+
+## Tests
+
+```bash
+pip install -e 'python/bioio-openreadout[test]'
+OPENREADOUT_CORPUS_DIR=corpus/files pytest python/bioio-openreadout/tests
+```
+
+The tests compare `img.data` against `bioio-nd2`, `czifile` and `liffile` (all BSD) on files from the public test corpus and skip when those files or readers are absent.
+
+Guide: <https://openreadout.github.io/openreadout/guides/python.html>. Part of [OpenReadout](https://github.com/openreadout/openreadout). Licensed MIT OR Apache-2.0. OpenReadout is not affiliated with any instrument vendor.

bioio_openreadout-0.1.0/bioio_openreadout/__init__.py

@@ -0,0 +1,23 @@
+"""bioio reader plugin for Zeiss CZI, Nikon ND2 and Leica LIF, backed by OpenReadout.
+
+Installed alongside ``bioio``, it is discovered through the ``bioio.readers`` entry point::
+
+    from bioio import BioImage
+    import bioio_openreadout
+
+    img = BioImage("run42.czi", reader=bioio_openreadout.Reader)
+    img.dims, img.channel_names, img.physical_pixel_sizes
+    stack = img.get_image_dask_data("ZYX", T=0, C=1).compute()
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .reader import Reader
+from .reader_metadata import ReaderMetadata
+
+try:
+    __version__ = version("bioio-openreadout")
+except PackageNotFoundError:  # pragma: no cover - running from a source checkout
+    __version__ = "uninstalled"
+
+__all__ = ["Reader", "ReaderMetadata", "__version__"]

bioio_openreadout-0.1.0/bioio_openreadout/reader.py

@@ -0,0 +1,201 @@
+"""The bioio ``Reader`` implemented on top of :mod:`openreadout`."""
+
+from __future__ import annotations
+
+import logging
+from datetime import timedelta
+from numbers import Integral
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+import openreadout
+import xarray as xr
+from bioio_base import constants, exceptions, io, reader, types
+from fsspec.implementations.local import LocalFileSystem  # type: ignore[import-untyped]
+from fsspec.spec import AbstractFileSystem  # type: ignore[import-untyped]
+
+__all__ = ["Reader"]
+
+log = logging.getLogger(__name__)
+
+_PLUGIN = "bioio-openreadout"
+
+
+class Reader(reader.Reader):
+    """Read Zeiss CZI, Nikon ND2, Leica LIF and the other microscopy formats of the clean-room
+    OpenReadout core (whole-slide SVS/NDPI/QPTIFF/VSI, Imaris, ...).
+
+    Each image in the file (CZI scene, ND2 position, LIF series) is a bioio scene. Data is
+    ``TCZYX`` (``TCZYXS`` for RGB), read lazily: one plane per dask chunk, or the file's own
+    tiles grouped into chunks of about 16 MiB for large tiled planes, so only what a
+    computation touches is decoded. Mosaics are returned stitched. Pyramidal files expose their
+    levels as bioio resolution levels (``resolution_levels``, ``set_resolution_level``); physical
+    pixel sizes follow the level.
+
+    Parameters
+    ----------
+    image : Path or str
+        Path to a local file.
+    fs_kwargs : Dict[str, Any]
+        Passed to the fsspec filesystem. Only local files are supported.
+    keep_open : bool
+        Keep the file open between reads (faster on files with large indexes, e.g. whole-slide
+        CZIs). Default ``False``: as bioio expects of plugins, no file handle stays open; every
+        read reopens the file.
+
+    Raises
+    ------
+    exceptions.UnsupportedFileFormatError
+        The path is not a local CZI, ND2 or LIF file that OpenReadout can open.
+    """
+
+    NAME = _PLUGIN
+
+    _file: Optional[openreadout.File] = None
+    _scene_ids: Optional[Tuple[str, ...]] = None
+    _ome: Any = None
+    _vendor: Any = None
+
+    @staticmethod
+    def _is_supported_image(fs: AbstractFileSystem, path: str, **kwargs: Any) -> bool:
+        if not isinstance(fs, LocalFileSystem):
+            raise exceptions.UnsupportedFileFormatError(
+                _PLUGIN, path, "OpenReadout reads local files only."
+            )
+        try:
+            detected = openreadout.info(path, view="format")
+        except openreadout.OpenReadoutError as e:
+            raise exceptions.UnsupportedFileFormatError(_PLUGIN, path, str(e)) from e
+        if detected["confidence"] == "extension-only":
+            raise exceptions.UnsupportedFileFormatError(
+                _PLUGIN, path, "The extension matches but the file signature does not."
+            )
+        return True
+
+    def __init__(
+        self,
+        image: types.PathLike,
+        fs_kwargs: Dict[str, Any] = {},
+        keep_open: bool = False,
+        **kwargs: Any,
+    ):
+        self._fs, self._path = io.pathlike_to_fs(image, enforce_exists=True, fs_kwargs=fs_kwargs)
+        self._is_supported_image(self._fs, self._path)
+        try:
+            self._file = openreadout.File(self._path, keep_open=keep_open)
+        except openreadout.OpenReadoutError as e:
+            raise exceptions.UnsupportedFileFormatError(_PLUGIN, self._path, str(e)) from e
+
+    @property
+    def file(self) -> openreadout.File:
+        """The underlying :class:`openreadout.File`."""
+        assert self._file is not None
+        return self._file
+
+    @property
+    def scenes(self) -> Tuple[str, ...]:
+        """Image names from the file, made unique; ``Image:<n>`` where the file has none."""
+        if self._scene_ids is None:
+            ids: List[str] = []
+            for i, im in enumerate(self.file.images):
+                name = (im.get("name") or "").strip() or f"Image:{i}"
+                if name in ids:
+                    name = f"{name} ({i})"
+                ids.append(name)
+            self._scene_ids = tuple(ids)
+        return self._scene_ids
+
+    def _image(self) -> openreadout.ImageInfo:
+        return self.file.images[self.current_scene_index]
+
+    def _attach_metadata(self, xarr: xr.DataArray) -> xr.DataArray:
+        xarr.attrs[constants.METADATA_UNPROCESSED] = self._vendor_metadata()
+        try:
+            xarr.attrs[constants.METADATA_PROCESSED] = self.ome_metadata
+        except Exception as err:  # ome-types missing or a document it rejects
+            log.debug("OME metadata unavailable: %s", err)
+        return xarr
+
+    @property
+    def resolution_levels(self) -> Tuple[int, ...]:
+        """Pyramid levels of the current scene (0 = full resolution), as stored in the file."""
+        return tuple(lv["level"] for lv in self.file.levels(self.current_scene_index))
+
+    def _level(self) -> int:
+        return int(self.current_resolution_level)
+
+    def _read_delayed(self) -> xr.DataArray:
+        return self._attach_metadata(
+            self.file.to_xarray(self.current_scene_index, level=self._level(), delayed=True)
+        )
+
+    def _read_immediate(self) -> xr.DataArray:
+        return self._attach_metadata(
+            self.file.to_xarray(self.current_scene_index, level=self._level(), delayed=False)
+        )
+
+    def _read_indexed(self, given_dims: str, dim_specs: List[Any]) -> np.ndarray:
+        # Index the lazy array axis by axis (dask allows one list index at a time), so only
+        # the planes (and tiles) the selection touches are decoded.
+        arr = self.file.to_dask(self.current_scene_index, level=self._level())
+        axis = 0
+        for spec in dim_specs:
+            if isinstance(spec, Integral):
+                arr = arr[(slice(None),) * axis + (int(spec),)]
+            else:
+                arr = arr[(slice(None),) * axis + (spec,)]
+                axis += 1
+        return np.asarray(arr.compute())  # type: ignore[no-untyped-call]
+
+    def _vendor_metadata(self) -> Any:
+        if self._vendor is None:
+            self._vendor = self.file.vendor
+        return self._vendor
+
+    @property
+    def ome_metadata(self) -> Any:
+        """OME model (``ome_types.OME``) built from OpenReadout's normalized metadata.
+
+        One ``Image`` per scene; ``Pixels`` are ``MetadataOnly``. RGB images report
+        ``SizeC = 3 × channels`` as OME requires.
+        """
+        if self._ome is None:
+            from ome_types import from_xml
+
+            self._ome = from_xml(self.file.ome_xml())
+        return self._ome
+
+    @property
+    def physical_pixel_sizes(self) -> types.PhysicalPixelSizes:
+        """Pixel sizes in µm for Z, Y, X at the current resolution level (``None`` where the
+        file records none)."""
+        im = self._image()
+        ps = im["physical_size"]
+        lv = self.file.levels(self.current_scene_index)[self._level()]
+        fx, fy = float(lv.get("downsample_x") or 1.0), float(lv.get("downsample_y") or 1.0)
+        z, y, x = ps.get("z"), ps.get("y"), ps.get("x")
+        if z is not None and lv.get("size_z"):
+            z = z * im["size_z"] / lv["size_z"]
+        return types.PhysicalPixelSizes(
+            z,
+            y * fy if y is not None else None,
+            x * fx if x is not None else None,
+        )
+
+    @property
+    def channel_names(self) -> Optional[List[str]]:
+        """Channel names; ``Channel:<scene>:<c>`` where the file records none."""
+        im = self._image()
+        by_index = {ch["index"]: ch for ch in im["channels"]}
+        names = []
+        for c in range(im["size_c"]):
+            ch = by_index.get(c)
+            name = ch.get("name") if ch is not None else None
+            names.append(name if name else f"Channel:{self.current_scene_index}:{c}")
+        return names
+
+    @property
+    def time_interval(self) -> types.TimeInterval:
+        """Time between T frames, or ``None`` when the file records no increment."""
+        dt = self._image().get("time_increment_s")
+        return timedelta(seconds=dt) if dt else None

bioio_openreadout-0.1.0/bioio_openreadout/reader_metadata.py

@@ -0,0 +1,41 @@
+"""Plugin metadata bioio reads through the ``bioio.readers`` entry point."""
+
+from __future__ import annotations
+
+from typing import List
+
+import bioio_base.reader
+import bioio_base.reader_metadata
+
+__all__ = ["ReaderMetadata"]
+
+
+class ReaderMetadata(bioio_base.reader_metadata.ReaderMetadata):
+    """Extensions this plugin reads and the reader class that reads them."""
+
+    @staticmethod
+    def get_supported_extensions() -> List[str]:
+        """File extensions routed to this plugin: the proprietary microscopy formats (other
+        extensions, such as ``.tiff`` or ``.zarr``, are read with ``reader=`` as well, but left
+        to their dedicated plugins by default)."""
+        return [
+            ".czi",
+            ".nd2",
+            ".lif",
+            ".vsi",
+            ".svs",
+            ".ndpi",
+            ".qptiff",
+            ".ims",
+            ".oir",
+            ".oib",
+            ".oif",
+            ".zvi",
+        ]
+
+    @staticmethod
+    def get_reader() -> bioio_base.reader.Reader:
+        """The :class:`bioio_openreadout.Reader` class."""
+        from .reader import Reader
+
+        return Reader  # type: ignore[return-value]  # bioio's annotation says instance

bioio_openreadout-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bioio-openreadout"
+version = "0.1.0"
+description = "bioio reader plugin that reads microscopy files with OpenReadout"
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+license-files = ["LICENSE-MIT", "LICENSE-APACHE"]
+requires-python = ">=3.10"
+authors = [{ name = "The OpenReadout Authors", email = "openreadout@gmail.com" }]
+keywords = ["bioio", "microscopy", "czi", "nd2", "lif", "imaging"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Scientific/Engineering :: Image Processing",
+  "Typing :: Typed",
+]
+# Exactly one `bioio-base` requirement: bioio reads it to check plugin compatibility.
+# Deliberately no dependency on the GPL-licensed bioio-czi / bioio-lif.
+dependencies = [
+  "bioio-base>=3.4,<4",
+  "openreadout[xarray]>=0.1.0,<0.2",
+  "dask[array]>=2022.2",
+  "fsspec>=2022.8.0",
+  "numpy>=1.22",
+  "ome-types>=0.4",
+  "xarray>=2022.6",
+]
+
+[project.optional-dependencies]
+# Oracles for the tests (all permissively licensed).
+test = ["pytest>=7", "bioio>=3", "bioio-nd2", "czifile", "liffile"]
+
+[project.entry-points."bioio.readers"]
+# bioio uses the entry point name as the distribution name, so they must match.
+bioio-openreadout = "bioio_openreadout"
+
+[project.urls]
+Homepage = "https://github.com/openreadout/openreadout"
+Repository = "https://github.com/openreadout/openreadout"
+Documentation = "https://openreadout.github.io/openreadout/guides/python.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["bioio_openreadout"]
+
+[tool.hatch.build.targets.sdist]
+include = ["bioio_openreadout", "tests", "README.md", "LICENSE-MIT", "LICENSE-APACHE"]
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib"

bioio_openreadout-0.1.0/tests/conftest.py

@@ -0,0 +1,25 @@
+"""Fixtures: locate corpus files (``OPENREADOUT_CORPUS_DIR`` or ``<repo>/corpus/files``)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Callable
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[3]
+
+
+@pytest.fixture(scope="session")
+def corpus() -> Callable[[str], Path]:
+    """``corpus("name.czi")`` → path, or skip the test if the file is absent."""
+    root = Path(os.environ.get("OPENREADOUT_CORPUS_DIR") or REPO / "corpus" / "files")
+
+    def get(name: str) -> Path:
+        p = root / name
+        if not p.is_file():
+            pytest.skip(f"corpus file {name} not present (cargo xtask corpus fetch --tier smoke)")
+        return p
+
+    return get

bioio_openreadout-0.1.0/tests/test_bioio_openreadout.py

@@ -0,0 +1,312 @@
+"""bioio-openreadout against bioio and permissively licensed oracle readers.
+
+``img.data`` is compared with bioio-nd2 (ND2), czifile (CZI) and liffile (LIF) where those are
+installed; each comparison skips when its reader or corpus file is absent.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from importlib.metadata import entry_points, requires
+from pathlib import Path
+from typing import Any, Callable, List
+
+import numpy as np
+import pytest
+
+bioio = pytest.importorskip("bioio")
+import bioio_openreadout  # noqa: E402
+from bioio import BioImage  # noqa: E402
+from bioio_base import exceptions  # noqa: E402
+from bioio_openreadout import Reader  # noqa: E402
+
+Corpus = Callable[[str], Path]
+
+CZI = "aics-s-3-t-1-c-3-z-5.czi"
+CZI_MOSAIC = "zenodo7015307-S-2-2x2-T-3-CH-1.czi"
+ND2_RGB_MULTI = "aics-ND2-dims-rgb-t3p2c2z3x64y64.nd2"
+ND2_MULTIPOS = "aics-ND2-dims-p4z5t3c2y32x32.nd2"
+LIF = "aics-s-1-t-4-c-2-z-1.lif"
+
+PLUGIN = "bioio-openreadout"
+
+
+def _to_tczyxs(dims: List[str], arr: np.ndarray) -> np.ndarray:
+    """Reorder an oracle array to T, C, Z, Y, X, S (adding size-1 axes, dropping size-1 extras)."""
+    for i in reversed(range(len(dims))):
+        if dims[i] not in "TCZYXS":
+            assert arr.shape[i] == 1, (dims, arr.shape)
+            arr = arr.take(0, axis=i)
+            dims = dims[:i] + dims[i + 1 :]
+    for d in "TCZYXS":
+        if d not in dims:
+            arr = arr[np.newaxis]
+            dims = [d, *dims]
+    return arr.transpose([dims.index(d) for d in "TCZYXS"])
+
+
+def _ours_tczyxs(img: BioImage) -> np.ndarray:
+    data = img.data
+    return data if data.ndim == 6 else data[..., np.newaxis]
+
+
+# ----- packaging / discovery ---------------------------------------------------------------------
+
+
+def test_entry_point_is_registered() -> None:
+    eps = {ep.name: ep for ep in entry_points(group="bioio.readers")}
+    assert PLUGIN in eps and eps[PLUGIN].value == "bioio_openreadout"
+    assert eps[PLUGIN].load().ReaderMetadata.get_reader() is Reader
+
+
+def test_no_copyleft_dependencies() -> None:
+    reqs = " ".join(requires(PLUGIN) or []).lower()
+    for gpl in ("bioio-czi", "bioio-lif", "pylibczirw", "readlif", "bioformats"):
+        assert gpl not in reqs
+
+
+def test_plugin_is_offered_for_each_extension() -> None:
+    from bioio.plugins import get_plugins
+
+    plugins = get_plugins(use_cache=False)
+    for ext in (".czi", ".nd2", ".lif"):
+        assert PLUGIN in [p.entrypoint.name for p in plugins[ext]], ext
+
+
+@pytest.mark.parametrize("name", [CZI, ND2_MULTIPOS, LIF])
+def test_bioimage_picks_plugin_by_extension(corpus: Corpus, monkeypatch: Any, name: str) -> None:
+    """With bioio-openreadout the only plugin for the extension, BioImage(path) selects it."""
+    import bioio.bio_image
+    from bioio.plugins import get_plugins
+
+    path = corpus(name)
+    ours_only = {
+        ext: [p for p in plugins if p.entrypoint.name == PLUGIN]
+        for ext, plugins in get_plugins(use_cache=False).items()
+    }
+    monkeypatch.setattr(bioio.bio_image, "get_plugins", lambda use_cache=False: ours_only)
+    img = BioImage(path)
+    assert isinstance(img.reader, Reader)
+    assert img.reader.name == PLUGIN
+
+
+@pytest.mark.parametrize("name", [CZI, ND2_MULTIPOS, LIF])
+def test_bioimage_plugin_order_in_this_environment(corpus: Corpus, name: str) -> None:
+    """Without overrides, bioio picks us unless a more specific plugin for the extension exists."""
+    from bioio.plugins import get_plugins
+
+    path = corpus(name)
+    ext = "." + name.rsplit(".", 1)[1]
+    candidates = [p.entrypoint.name for p in get_plugins(use_cache=False)[ext]]
+    chosen = BioImage.determine_plugin(path).entrypoint.name
+    assert chosen == candidates[0] or chosen == PLUGIN
+    if candidates == [PLUGIN]:
+        assert isinstance(BioImage(path).reader, Reader)
+
+
+def test_explicit_reader(corpus: Corpus) -> None:
+    img = BioImage(corpus(CZI), reader=Reader)
+    assert isinstance(img.reader, Reader)
+    assert img.scenes == ("P2", "P3", "P1")
+    assert img.dims.order == "TCZYX" and img.shape == (1, 3, 5, 325, 475)
+    assert img.channel_names == ["EGFP", "TaRFP", "Bright"]
+    ps = img.physical_pixel_sizes
+    assert ps.X == pytest.approx(1.0833333) and ps.Y == pytest.approx(1.0833333) and ps.Z == 1.0
+    assert img.dtype == np.uint16
+
+
+def test_unsupported_file_is_rejected(tmp_path: Path) -> None:
+    junk = tmp_path / "junk.czi"
+    junk.write_bytes(b"\0" * 4096)
+    with pytest.raises(exceptions.UnsupportedFileFormatError):
+        Reader(junk)
+    with pytest.raises(exceptions.UnsupportedFileFormatError):
+        Reader.is_supported_image(junk)
+    with pytest.raises(FileNotFoundError):
+        Reader(tmp_path / "missing.czi")
+
+
+# ----- data equality against oracles --------------------------------------------------------------
+
+
+@pytest.mark.parametrize("name", [ND2_RGB_MULTI, ND2_MULTIPOS])
+def test_nd2_matches_bioio_nd2(corpus: Corpus, name: str) -> None:
+    bioio_nd2 = pytest.importorskip("bioio_nd2")
+    path = corpus(name)
+    ours = BioImage(path, reader=Reader)
+    ref = BioImage(path, reader=bioio_nd2.Reader)
+    assert len(ours.scenes) == len(ref.scenes)
+    for s in range(len(ref.scenes)):
+        ours.set_scene(s)
+        ref.set_scene(s)
+        assert ours.dims.order == ref.dims.order
+        assert ours.shape == ref.shape
+        assert ours.channel_names == [str(c) for c in ref.channel_names]
+        assert ours.physical_pixel_sizes.X == pytest.approx(ref.physical_pixel_sizes.X)
+        want = ref.data
+        if "S" in ref.dims.order and ref.dims.S == 3:
+            # bioio-nd2 (nd2) returns colour planes in stored B, G, R order; we return R, G, B
+            # (docs/formats/nd2.md § RGB sample order).
+            want = want[..., ::-1]
+        np.testing.assert_array_equal(ours.data, want)
+
+
+@pytest.mark.parametrize("name", [CZI, CZI_MOSAIC])
+def test_czi_matches_czifile(corpus: Corpus, name: str) -> None:
+    czifile = pytest.importorskip("czifile")
+    if not hasattr(czifile.CziFile, "asxarray"):  # pre-2025 czifile (e.g. on Python 3.10)
+        pytest.skip("czifile with scenes/asxarray (Python >= 3.11) is required")
+    path = corpus(name)
+    img = BioImage(path, reader=Reader)
+    with czifile.CziFile(path, squeeze=False) as czi:
+        scene_keys = list(czi.scenes.keys())
+        assert len(scene_keys) == len(img.scenes)
+        for s, key in enumerate(scene_keys):
+            ref = czi.asxarray(scene=key)
+            img.set_scene(s)
+            expected = _to_tczyxs(list(ref.dims), ref.values)
+            np.testing.assert_array_equal(_ours_tczyxs(img), expected)
+
+
+def test_lif_matches_liffile(corpus: Corpus) -> None:
+    liffile = pytest.importorskip("liffile")
+    path = corpus(LIF)
+    img = BioImage(path, reader=Reader)
+    with liffile.LifFile(path) as lif:
+        assert len(lif.images) == len(img.scenes)
+        for s, series in enumerate(lif.images):
+            ref = series.asxarray()
+            img.set_scene(s)
+            np.testing.assert_array_equal(_ours_tczyxs(img), _to_tczyxs(list(ref.dims), ref.values))
+
+
+# ----- lazy reads and metadata --------------------------------------------------------------------
+
+
+def test_lazy_selection_matches_full_read(corpus: Corpus) -> None:
+    img = BioImage(corpus(ND2_MULTIPOS), reader=Reader)
+    img.set_scene("point name 3")
+    full = img.data
+    lazy = img.get_image_dask_data("ZYX", T=2, C=1)
+    np.testing.assert_array_equal(lazy.compute(), full[2, 1])
+    np.testing.assert_array_equal(img.get_image_data("CYX", T=1, Z=4), full[1, :, 4])
+    np.testing.assert_array_equal(
+        img.reader._read_indexed("TCZYX", [0, [1, 0], slice(0, 2), 3, slice(None)]),
+        full[0][[1, 0]][:, 0:2, 3],
+    )
+
+
+def test_scene_names_fallback_and_rgb(corpus: Corpus) -> None:
+    img = BioImage(corpus(ND2_RGB_MULTI), reader=Reader)
+    assert img.scenes == ("Position 0", "Position 1")
+    assert img.dims.order == "TCZYXS" and img.dims.S == 3
+
+
+def test_metadata(corpus: Corpus) -> None:
+    img = BioImage(corpus(LIF), reader=Reader)
+    ome = img.ome_metadata
+    assert len(ome.images) == len(img.scenes)
+    assert ome.images[0].pixels.size_t == 4 and ome.images[0].pixels.size_c == 2
+    assert img.metadata is ome
+    assert img.xarray_dask_data.attrs["unprocessed"]  # vendor tree
+    assert img.time_interval == timedelta(seconds=img.reader.file.images[0]["time_increment_s"])
+    std = img.standard_metadata
+    assert std.image_size_t == 4 and std.pixel_size_x == pytest.approx(img.physical_pixel_sizes.X)
+
+
+def test_version() -> None:
+    assert isinstance(bioio_openreadout.__version__, str)
+
+
+# ----- bioio's own plugin checks, resolution levels ----------------------------------------------
+
+KIDNEY = "zenodo10577621-Kidney-RAC-3color.czi"  # 5 pyramid levels, 4 channels, uint16 mosaic
+
+
+def test_bioio_base_reader_checks(corpus: Corpus) -> None:
+    """bioio-base's own plugin test suite: no file handle left open, scene and resolution-level
+    switching, dims, dtype, physical sizes, lazy vs in-memory reads, (de)serialization."""
+    tu = pytest.importorskip("bioio_base.test_utilities")
+    pytest.importorskip("distributed")
+    from ome_types import OME
+
+    scenes = Reader(corpus(CZI)).scenes
+    tu.run_image_file_checks(
+        ImageContainer=Reader,
+        image=corpus(CZI),
+        set_scene=scenes[1],
+        expected_scenes=scenes,
+        expected_current_scene=scenes[1],
+        expected_shape=(1, 3, 5, 325, 475),
+        expected_dtype=np.dtype(np.uint16),
+        expected_dims_order="TCZYX",
+        expected_channel_names=["EGFP", "TaRFP", "Bright"],
+        expected_physical_pixel_sizes=Reader(corpus(CZI)).physical_pixel_sizes,
+        expected_metadata_type=OME,
+        reader_kwargs={},
+    )
+
+
+def test_bioio_base_checks_at_a_resolution_level(corpus: Corpus) -> None:
+    tu = pytest.importorskip("bioio_base.test_utilities")
+    pytest.importorskip("distributed")
+    from ome_types import OME
+
+    path = corpus(KIDNEY)
+    base = Reader(path)
+    ps0 = base.physical_pixel_sizes
+    levels = base.file.levels(0)
+    lv = levels[3]
+    tu.run_image_file_checks(
+        ImageContainer=Reader,
+        image=path,
+        set_scene=base.scenes[0],
+        expected_scenes=base.scenes,
+        expected_current_scene=base.scenes[0],
+        expected_shape=(1, 4, 1, lv["size_y"], lv["size_x"]),
+        expected_dtype=np.dtype(np.uint16),
+        expected_dims_order="TCZYX",
+        expected_channel_names=base.channel_names,
+        expected_physical_pixel_sizes=type(ps0)(
+            ps0.Z, ps0.Y * lv["downsample_y"], ps0.X * lv["downsample_x"]
+        ),
+        expected_metadata_type=OME,
+        set_resolution_level=3,
+        expected_current_resolution_level=3,
+        expected_resolution_levels=(0, 1, 2, 3, 4),
+        reader_kwargs={},
+    )
+
+
+def test_resolution_level_matches_oracle(corpus: Corpus) -> None:
+    """Level 4 equals the committed ground truth: czifile's pixels on the level grid of
+    ``oracle/czi_levels.py`` (``floor(w / 16) x floor(h / 16)`` from the scene origin, as
+    pylibCZIrw's scaled reads). czifile's own ``levels[4]`` spans the union of the subblocks, a
+    grid 1-2 px larger, so it is not compared directly."""
+    import json
+
+    xxhash = pytest.importorskip("xxhash")
+    path = corpus(KIDNEY)
+    repo = Path(__file__).resolve().parents[3]
+    oracle = repo / "corpus" / "oracle" / "zenodo10577621-Kidney-RAC-3color.json"
+    truth = json.loads(oracle.read_text())
+    lv = next(lv for lv in truth["images"][0]["levels"] if lv["level"] == 4)
+    img = BioImage(path, reader=Reader)
+    img.set_resolution_level(4)
+    ours = img.get_image_data("CYX")
+    assert ours.shape[1:] == (lv["size_y"], lv["size_x"])
+    assert len(lv["planes"]) == ours.shape[0]
+    for p in lv["planes"]:
+        plane = np.ascontiguousarray(ours[p["c"]], dtype=ours.dtype.newbyteorder("<"))
+        assert xxhash.xxh3_128_hexdigest(plane.tobytes()) == p["xxh3"], p
+
+
+def test_keep_open_reader_holds_the_file(corpus: Corpus) -> None:
+    psutil = pytest.importorskip("psutil")
+    path = str(corpus(CZI))
+    r = Reader(path, keep_open=True)
+    assert path in [f.path for f in psutil.Process().open_files()]
+    r.file.close()
+    lazy = Reader(path)  # default: nothing stays open
+    lazy.get_image_data("YX", Z=1, C=2)
+    assert path not in [f.path for f in psutil.Process().open_files()]