micro-reader 0.0.4__tar.gz → 0.2.0__tar.gz

{micro_reader-0.0.4 → micro_reader-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: micro-reader
-Version: 0.0.4
+Version: 0.2.0
 Summary: Low-level, memory-bounded pixel reading for microscopy formats: read exactly the rectangle you ask for.
 Project-URL: Homepage, https://github.com/bugraoezdemir/micro-reader
 Project-URL: Source, https://github.com/bugraoezdemir/micro-reader
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Image Processing
 Requires-Python: >=3.11
-Requires-Dist: micro-reader-codecs<0.1,>=0.0.1
+Requires-Dist: micro-reader-codecs<0.1,>=0.0.2
 Requires-Dist: numpy>=1.24
 Requires-Dist: tifffile>=2025.5.21
 Provides-Extra: all
@@ -36,6 +36,8 @@ Requires-Dist: pylibczirw; (python_version < '3.14') and extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: readlif; extra == 'dev'
 Requires-Dist: zstandard; extra == 'dev'
+Provides-Extra: hdf5
+Requires-Dist: h5py>=3.11; extra == 'hdf5'
 Provides-Extra: ims
 Requires-Dist: h5py>=3.11; extra == 'ims'
 Provides-Extra: test
@@ -75,6 +77,14 @@ pip install "micro-reader[ims]"      # Imaris (.ims)
 pip install "micro-reader[codecs]"   # additional codecs
 ```
 
+## Compatibility with eubi-bridge
+
+micro-reader 0.1.0 renamed the image index `scene` to `series`. eubi-bridge 0.1.3 to 0.2.x and eubi-bridge-lite below 0.3.0 still read `scene`, so `import micro_reader` refuses to load next to them. It raises an `ImportError` that names the installed eubi version and the two ways out: upgrade eubi (`pip install -U 'eubi-bridge>=0.3.0'`, or the same for `eubi-bridge-lite`), or keep that eubi with the micro-reader it was built for (`pip install 'micro-reader<0.1'`). The check reads the versions of the installed packages; it never imports eubi. An editable install of eubi is checked like any other: its recorded version can be out of date, so the message then says to reinstall it.
+
+To skip the check, set the environment variable `MICRO_READER_SKIP_EUBI_CHECK=1`. Only the value `1` skips it; any other value keeps the check. micro-reader then warns once that the check was skipped. This is meant for work on an eubi checkout, not for normal use.
+
+The check will be removed when every eubi-bridge / eubi-bridge-lite line below 0.3.0 has left the support window, checked by the release version matrix; not before.
+
 ## Quick start
 
 ```python
@@ -116,7 +126,7 @@ print(image.stats.over_read)
 
 * **File**: the opened microscopy file
 * **Image**: one image or frame that can be read as an array
-* **Index**: identifies images that are separated by dimensions such as scene, tile, view, or emission wavelength
+* **Index**: identifies images that are separated by dimensions such as series, tile, view, or emission wavelength
 
 The key distinction is:
 
@@ -169,7 +179,7 @@ Each image has an index describing where it came from:
 
 ```python
 image.index
-# {"scene": 0, "tile": 3, "view": 0}
+# {"series": 0, "tile": 3, "view": 0}
 ```
 
 You can inspect all indices in the file:
@@ -182,10 +192,10 @@ f.index_range
 And select images by index:
 
 ```python
-f.select(scene=1, view=0)
+f.select(series=1, view=0)
 ```
 
-This returns the images matching the requested indices. For example, if a file contains several scenes, tiles, and views, selecting `scene=1, view=0` returns the tiles belonging to that scene and view.
+This returns the images matching the requested indices. For example, if a file contains several series, tiles, and views, selecting `series=1, view=0` returns the tiles belonging to that series and view.
 
 ### Available index dimensions
 
@@ -196,7 +206,7 @@ plate
 acquisition
 well
 field
-scene
+series
 tile
 rotation
 view
@@ -340,13 +350,13 @@ For example, a plain multi-page TIFF may contain 80 pages without saying whether
 f = micro_reader.open("stack.tif")
 
 print(f.index_range)
-# {"scene": 1, "sequence": 80}
+# {"series": 1, "sequence": 80}
 
 print(len(f.images))
 # 80
 
 print(f.images[0].index)
-# {"scene": 0, "sequence": 0}
+# {"series": 0, "sequence": 0}
 
 print(f.images[0].axes)
 # yx
@@ -392,10 +402,10 @@ Each image of a pyramidal file carries its resolution level in its index. In thi
 
 ```python
 print(f.index_range)
-# {"scene": 4, "resolution": 1}
+# {"series": 4, "resolution": 1}
 
 print(f.images[0].index)
-# {"scene": 0, "resolution": 0}
+# {"series": 0, "resolution": 0}
 ```
 
 `index_range` shows `"resolution": 1` because only the full-resolution level is in `f.images`.
@@ -403,15 +413,15 @@ print(f.images[0].index)
 Lower-resolution versions are available through the image via `image.resolutions`:
 
 ```python
-image_scene0 = f.images[0]
+image_series0 = f.images[0]
 
-image_scene0.is_pyramidal
+image_series0.is_pyramidal
 # True
 
-img_scene0_level2 = image_scene0.resolutions[2]  # a lower-resolution image
+img_series0_level2 = image_series0.resolutions[2]  # a lower-resolution image
 
-img_scene0_level2.index
-# {"scene": 0, "resolution": 2}
+img_series0_level2.index
+# {"series": 0, "resolution": 2}
 ```
 
 If you prefer to expose every resolution level as an image directly under the `File` object:
@@ -423,37 +433,37 @@ f = micro_reader.open(
 )
 
 print(f.index_range)
-# {"scene": 4, "resolution": 6}
+# {"series": 4, "resolution": 6}
 
-img_scene0_level2 = f.select(scene=0, resolution=2)[0]
+img_series0_level2 = f.select(series=0, resolution=2)[0]
 ```
 
 Supported pyramids include:
 
 * **Imaris**: all stored levels
 * **TIFF**: OME-TIFF and whole-slide pyramids (SVS, NDPI, SCN, BIF, QPTIFF, Philips)
-* **CZI**: stored pyramids of whole scenes
+* **CZI**: stored pyramids of whole series
 
 Other formats expose a single resolution level.
 
-CZI pyramids belong to whole scenes. Separately opened CZI mosaic tiles therefore do not have their own resolution levels.
+CZI pyramids belong to whole series. Separately opened CZI mosaic tiles therefore do not have their own resolution levels.
 
 ## Mosaic tiles
 
-Mosaic tiles are separate images by default.
+Mosaic tiles are separate images by default, each with its own position.
 
-For CZI files, you can instead request stitched scenes:
+For CZI files and FluoView tiling sets (`.omp2info`), you can instead get one image per series, its tiles placed on one canvas:
 
 ```python
 f = micro_reader.open(
     path,
-    tiles="stitched",
+    tiles="mosaic",
 )
 ```
 
-The tiles are composed according to the format's stitching information.
+CZI tiles are placed by the file's own stitching information, FluoView tiles by the tiling set's grid (where tiles overlap, the later tile is on top; areas without a tile read as 0). Other formats with tiles raise an error for `tiles="mosaic"`.
 
-Currently, stitching is supported for **CZI only**.
+`tiles="stitched"`, the name before 0.1.0, still works and warns.
 
 ## Plates
 
@@ -476,7 +486,7 @@ f.select(well=plate.well_index("B2"))
 
 `f.outline()` shows the plates, wells and fields of a file.
 
-Zeiss CZI plates are read as plates with `plates=True`, and as scenes otherwise:
+Zeiss CZI plates are read as plates with `plates=True`, and as series otherwise:
 
 ```python
 f = micro_reader.open("plate.czi", plates=True)
@@ -557,13 +567,18 @@ The position is omitted when it cannot be determined reliably.
 | -------------------- | ----------------------------------------------------- |
 | **TIFF / BigTIFF**   | TIFF, OME-TIFF, ImageJ, LSM, STK, Micro-Manager, whole-slide TIFFs |
 | **OME companion**    | `.companion.ome` sets of OME-TIFF files               |
-| **CZI**              | Zeiss CZI, including mosaic tiles and stitched scenes |
+| **CZI**              | Zeiss CZI, including mosaic tiles (separate or on one canvas) |
 | **ND2**              | Nikon ND2, including legacy JPEG 2000 ND2             |
 | **Leica**            | LIF, LOF, LIFEXT, XLIF, XLEF, XLCF                    |
-| **OIR**              | Olympus / Evident FluoView                            |
+| **OIR**              | Olympus / Evident FluoView, including tiling sets (`.omp2info`) |
 | **OIB / OIF**        | Olympus FluoView FV1000 / FV1200 / FV3000             |
 | **VSI**              | Olympus / Evident cellSens and VS120 / VS200 slide scanners |
-| **Imaris**           | `.ims`, with the `[ims]` extra                        |
+| **NDPIS**            | Hamamatsu NanoZoomer fluorescence sets (one NDPI per channel) |
+| **Imaris**           | `.ims`, with the `[hdf5]` extra                       |
+| **HDF5**             | ilastik, BigDataViewer / BigStitcher, Luxendo, Fiji HDF5, with the `[hdf5]` extra |
+| **ICS / IDS**        | Image Cytometry Standard 1.0 and 2.0 (SVI Huygens and others) |
+| **MetaMorph**        | `.nd` acquisitions and their TIFF / STK files         |
+| **Micro-Manager 1.4**| image-per-file acquisitions (`metadata.txt` + one TIFF per plane) |
 | **DeltaVision**      | `.dv`, `.r3d` (softWoRx, OMX, Priism)                 |
 | **MRC**              | Common MRC modes and extended headers                 |
 | **Plates (HCS)**     | Harmony, MetaXpress, IN Cell and CellVoyager plates   |
@@ -584,13 +599,13 @@ Supported TIFF formats include:
 * Zeiss LSM
 * MetaMorph STK
 * Micro-Manager stacks (MMStack and NDTiff), also when one acquisition is spread over several files
-* Whole-slide TIFFs: Aperio SVS, Hamamatsu NDPI, Leica SCN, Ventana BIF, PerkinElmer / Akoya QPTIFF and Philips
+* Whole-slide TIFFs: Aperio SVS, Hamamatsu NDPI, Leica SCN, Ventana / Roche BIF (VENTANA DP 200, iScan Coreo), PerkinElmer / Akoya QPTIFF and Philips
 
-Micro-Manager stage positions are scenes. NDTiff channel names and pixel sizes come from the dataset's index and frame metadata.
+Micro-Manager stage positions are series. NDTiff channel names and pixel sizes come from the dataset's index and frame metadata.
 
-A whole-slide file gives the slide first, then the other pictures it stores as further scenes, as Bio-Formats lists them: `label` and `macro` (overview), and for some formats `thumbnail` (QPTIFF) or `probability` (BIF tissue map). Pixel sizes, positions and channel names come from each vendor's own metadata.
+A whole-slide file gives the slide first, then the other pictures it stores as further series, as Bio-Formats lists them: `label` and `macro` (overview), and for some formats `thumbnail` (QPTIFF) or `probability` (BIF tissue map). Pixel sizes, positions and channel names come from each vendor's own metadata.
 
-Ventana BIF scans store overlapping tiles. They are composed as Roche's description of the format places them. Files from scanners other than the VENTANA DP 200 are not supported.
+Ventana BIF scans store overlapping tiles. VENTANA DP 200 scans are composed as Roche's description of the format places them. iScan Coreo scans, which that description does not cover, are composed as OpenSlide shows them, with one difference: each tile starts at the nearest whole pixel and keeps its stored pixels, where OpenSlide interpolates to a sub-pixel position. Areas outside the scanned regions read as 0. Layouts that were not checked on real files (other EncodeInfo versions, several focal planes, overlapping scan areas) raise an error.
 
 Compressed TIFF data is decoded only for the strips or tiles needed by the requested region.
 
@@ -622,14 +637,16 @@ An OME companion file (`.companion.ome`) describes images stored in separate TIF
 f = micro_reader.open("data.companion.ome")
 ```
 
-Opening one of the TIFF files on its own reads only that file, with its pixel sizes, channels and position taken from the companion. If the companion is missing, the file is read without pixel sizes, with a `CompanionWarning`. A TIFF whose metadata lives in another OME-TIFF (instead of a `.companion.ome`) takes it from that file in the same way.
-
-Some OME-TIFF sets keep the full OME-XML in their TIFF files instead of a companion. Opening one of those files reads the whole set. To read only the planes stored in that file, with the set's metadata:
+Opening one of the TIFF files of the set also reads the whole set, as if the companion had been opened: `f.path` is then the companion, and the companion's metadata is used. To read only that file, with its pixel sizes, channels and position taken from the companion:
 
 ```python
-f = micro_reader.open("set_t001.ome.tif", multifile=False)
+f = micro_reader.open("data_t001.ome.tif", multifile=False)
 ```
 
+If the companion is missing or does not list the file, opening the whole set raises an error that names `multifile=False`. With `multifile=False` the file is then read without pixel sizes, with a `CompanionWarning`. A TIFF whose metadata lives in another OME-TIFF (instead of a `.companion.ome`) works the same way, with that OME-TIFF in the companion's place.
+
+Some OME-TIFF sets keep the full OME-XML in their TIFF files instead of a companion. Opening one of those files also reads the whole set, and `multifile=False` reads only the planes stored in that file, with the set's metadata.
+
 Micro-Manager stacks always open whole, also with `multifile=False`: they split their files by size, so one file does not hold a complete part of the image.
 
 ### CZI
@@ -637,12 +654,12 @@ Micro-Manager stacks always open whole, also with `multifile=False`: they split
 CZI files support:
 
 * mosaic tiles
-* scenes
+* series
 * views
 * rotations
 * RGB
 * large files
-* stored scene pyramids
+* stored series pyramids
 
 CZI-specific operations include:
 
@@ -693,6 +710,8 @@ These are represented using the common image/index model.
 
 Olympus / Evident FluoView OIR files are supported, including companion files and spectral scans.
 
+A multi-area tiling set is opened through its index, `.omp2info`, or its folder: one image per tile, each at the stage position the index gives it (the tiles' own files record none), or one canvas per group with `tiles="mosaic"`. Positions follow the protocol's grid, not a registration. The grid step was derived from one sample, as the backend documents.
+
 ### Olympus OIB and OIF
 
 Older FluoView files come in two forms with the same content: an OIB is one file, an OIF is a `.oif` settings file plus a `.oif.files` folder with one TIFF per plane. Both open as one `t c z y x` image, with pixel sizes, z and time steps, channel names, colours and wavelengths. Opening any file in the `.oif.files` folder opens the OIF.
@@ -710,13 +729,40 @@ Opening the `_<name>_` folder, a `stack` folder or a file in it opens the `.vsi`
 Install Imaris support with:
 
 ```bash
-pip install "micro-reader[ims]"
+pip install "micro-reader[hdf5]"
 ```
 
+(`[ims]` is the extra's former name and still works.)
+
 Imaris resolution level 0 is exposed at the actual image size, with Imaris chunk padding removed.
 
 Chunked compression is decoded in parallel.
 
+### HDF5: ilastik, BigDataViewer, Luxendo, Fiji
+
+These need the `[hdf5]` extra as well.
+
+* **ilastik**: every dataset with ilastik's `axistags` (its exports, its input files, steinbock's `img`) is one image, in the dataset's own axis order. Pixel sizes are read where ilastik recorded units (`axis_units`, since 2025-09).
+* **BigDataViewer / BigStitcher**: the XML with its HDF5 file (also partitioned). One image per tile, angle and illumination, channels on `c` and time points on `t`, with the stored resolution levels. Opening the HDF5 file opens its XML.
+* **Luxendo / Bruker light-sheet** (`.lux.h5`): one stack per file. A whole acquisition opens through the Imaris file Luxendo writes next to it.
+* **Fiji HDF5** (the Vibez plugin): datasets with `element_size_um`; `t<n>/channel<n>` datasets make one `t c z y x` image.
+
+### ICS / IDS
+
+ICS 1.0 (an `.ics` header with an `.ids` pixel file; opening either opens the image) and ICS 2.0 (one file), as written by SVI Huygens and others. Gzip-compressed pixels are read without decompressing the whole file. Images that store rows bottom-up (`coordinates cartesian`) are returned top-down, as Bio-Formats does.
+
+### MetaMorph .nd
+
+A MetaMorph multi-dimensional acquisition: an `.nd` file and the TIFF / STK files named after it. One image per stage position (`series`), `t c z y x`, channels named by the wavelengths. Opening the `.nd` file, any of its files or its folder opens the whole set. The stage coordinates the files record are kept as `Metadata.stage_position`, not as a position: which point of the field they mark is not recorded.
+
+### Micro-Manager 1.4
+
+Image-per-file acquisitions (Micro-Manager 1.4 and the 2.0 betas): a folder per stage position with a `metadata.txt` and one TIFF per plane. One image per stage position, `t c z y x`, with channel names and colours, pixel sizes and the z step. Opening any file or folder of the acquisition opens the whole acquisition.
+
+### Hamamatsu NDPIS
+
+An `.ndpis` set lists one NDPI file per fluorescence channel. Opened, it is one slide image with one channel per file, at every stored resolution level; channels are named by their filter set. Each NDPI file still opens alone as an ordinary slide.
+
 ### DeltaVision
 
 DeltaVision files (`.dv`, `.r3d`, `.r3d_d3d`, also deconvolved and projected ones) are recognised by their content, whatever their extension. The image keeps the file's own order of time, waves and z (for example `ctzyx`).

{micro_reader-0.0.4 → micro_reader-0.2.0}/README.md

@@ -23,6 +23,14 @@ pip install "micro-reader[ims]"      # Imaris (.ims)
 pip install "micro-reader[codecs]"   # additional codecs
 ```
 
+## Compatibility with eubi-bridge
+
+micro-reader 0.1.0 renamed the image index `scene` to `series`. eubi-bridge 0.1.3 to 0.2.x and eubi-bridge-lite below 0.3.0 still read `scene`, so `import micro_reader` refuses to load next to them. It raises an `ImportError` that names the installed eubi version and the two ways out: upgrade eubi (`pip install -U 'eubi-bridge>=0.3.0'`, or the same for `eubi-bridge-lite`), or keep that eubi with the micro-reader it was built for (`pip install 'micro-reader<0.1'`). The check reads the versions of the installed packages; it never imports eubi. An editable install of eubi is checked like any other: its recorded version can be out of date, so the message then says to reinstall it.
+
+To skip the check, set the environment variable `MICRO_READER_SKIP_EUBI_CHECK=1`. Only the value `1` skips it; any other value keeps the check. micro-reader then warns once that the check was skipped. This is meant for work on an eubi checkout, not for normal use.
+
+The check will be removed when every eubi-bridge / eubi-bridge-lite line below 0.3.0 has left the support window, checked by the release version matrix; not before.
+
 ## Quick start
 
 ```python
@@ -64,7 +72,7 @@ print(image.stats.over_read)
 
 * **File**: the opened microscopy file
 * **Image**: one image or frame that can be read as an array
-* **Index**: identifies images that are separated by dimensions such as scene, tile, view, or emission wavelength
+* **Index**: identifies images that are separated by dimensions such as series, tile, view, or emission wavelength
 
 The key distinction is:
 
@@ -117,7 +125,7 @@ Each image has an index describing where it came from:
 
 ```python
 image.index
-# {"scene": 0, "tile": 3, "view": 0}
+# {"series": 0, "tile": 3, "view": 0}
 ```
 
 You can inspect all indices in the file:
@@ -130,10 +138,10 @@ f.index_range
 And select images by index:
 
 ```python
-f.select(scene=1, view=0)
+f.select(series=1, view=0)
 ```
 
-This returns the images matching the requested indices. For example, if a file contains several scenes, tiles, and views, selecting `scene=1, view=0` returns the tiles belonging to that scene and view.
+This returns the images matching the requested indices. For example, if a file contains several series, tiles, and views, selecting `series=1, view=0` returns the tiles belonging to that series and view.
 
 ### Available index dimensions
 
@@ -144,7 +152,7 @@ plate
 acquisition
 well
 field
-scene
+series
 tile
 rotation
 view
@@ -288,13 +296,13 @@ For example, a plain multi-page TIFF may contain 80 pages without saying whether
 f = micro_reader.open("stack.tif")
 
 print(f.index_range)
-# {"scene": 1, "sequence": 80}
+# {"series": 1, "sequence": 80}
 
 print(len(f.images))
 # 80
 
 print(f.images[0].index)
-# {"scene": 0, "sequence": 0}
+# {"series": 0, "sequence": 0}
 
 print(f.images[0].axes)
 # yx
@@ -340,10 +348,10 @@ Each image of a pyramidal file carries its resolution level in its index. In thi
 
 ```python
 print(f.index_range)
-# {"scene": 4, "resolution": 1}
+# {"series": 4, "resolution": 1}
 
 print(f.images[0].index)
-# {"scene": 0, "resolution": 0}
+# {"series": 0, "resolution": 0}
 ```
 
 `index_range` shows `"resolution": 1` because only the full-resolution level is in `f.images`.
@@ -351,15 +359,15 @@ print(f.images[0].index)
 Lower-resolution versions are available through the image via `image.resolutions`:
 
 ```python
-image_scene0 = f.images[0]
+image_series0 = f.images[0]
 
-image_scene0.is_pyramidal
+image_series0.is_pyramidal
 # True
 
-img_scene0_level2 = image_scene0.resolutions[2]  # a lower-resolution image
+img_series0_level2 = image_series0.resolutions[2]  # a lower-resolution image
 
-img_scene0_level2.index
-# {"scene": 0, "resolution": 2}
+img_series0_level2.index
+# {"series": 0, "resolution": 2}
 ```
 
 If you prefer to expose every resolution level as an image directly under the `File` object:
@@ -371,37 +379,37 @@ f = micro_reader.open(
 )
 
 print(f.index_range)
-# {"scene": 4, "resolution": 6}
+# {"series": 4, "resolution": 6}
 
-img_scene0_level2 = f.select(scene=0, resolution=2)[0]
+img_series0_level2 = f.select(series=0, resolution=2)[0]
 ```
 
 Supported pyramids include:
 
 * **Imaris**: all stored levels
 * **TIFF**: OME-TIFF and whole-slide pyramids (SVS, NDPI, SCN, BIF, QPTIFF, Philips)
-* **CZI**: stored pyramids of whole scenes
+* **CZI**: stored pyramids of whole series
 
 Other formats expose a single resolution level.
 
-CZI pyramids belong to whole scenes. Separately opened CZI mosaic tiles therefore do not have their own resolution levels.
+CZI pyramids belong to whole series. Separately opened CZI mosaic tiles therefore do not have their own resolution levels.
 
 ## Mosaic tiles
 
-Mosaic tiles are separate images by default.
+Mosaic tiles are separate images by default, each with its own position.
 
-For CZI files, you can instead request stitched scenes:
+For CZI files and FluoView tiling sets (`.omp2info`), you can instead get one image per series, its tiles placed on one canvas:
 
 ```python
 f = micro_reader.open(
     path,
-    tiles="stitched",
+    tiles="mosaic",
 )
 ```
 
-The tiles are composed according to the format's stitching information.
+CZI tiles are placed by the file's own stitching information, FluoView tiles by the tiling set's grid (where tiles overlap, the later tile is on top; areas without a tile read as 0). Other formats with tiles raise an error for `tiles="mosaic"`.
 
-Currently, stitching is supported for **CZI only**.
+`tiles="stitched"`, the name before 0.1.0, still works and warns.
 
 ## Plates
 
@@ -424,7 +432,7 @@ f.select(well=plate.well_index("B2"))
 
 `f.outline()` shows the plates, wells and fields of a file.
 
-Zeiss CZI plates are read as plates with `plates=True`, and as scenes otherwise:
+Zeiss CZI plates are read as plates with `plates=True`, and as series otherwise:
 
 ```python
 f = micro_reader.open("plate.czi", plates=True)
@@ -505,13 +513,18 @@ The position is omitted when it cannot be determined reliably.
 | -------------------- | ----------------------------------------------------- |
 | **TIFF / BigTIFF**   | TIFF, OME-TIFF, ImageJ, LSM, STK, Micro-Manager, whole-slide TIFFs |
 | **OME companion**    | `.companion.ome` sets of OME-TIFF files               |
-| **CZI**              | Zeiss CZI, including mosaic tiles and stitched scenes |
+| **CZI**              | Zeiss CZI, including mosaic tiles (separate or on one canvas) |
 | **ND2**              | Nikon ND2, including legacy JPEG 2000 ND2             |
 | **Leica**            | LIF, LOF, LIFEXT, XLIF, XLEF, XLCF                    |
-| **OIR**              | Olympus / Evident FluoView                            |
+| **OIR**              | Olympus / Evident FluoView, including tiling sets (`.omp2info`) |
 | **OIB / OIF**        | Olympus FluoView FV1000 / FV1200 / FV3000             |
 | **VSI**              | Olympus / Evident cellSens and VS120 / VS200 slide scanners |
-| **Imaris**           | `.ims`, with the `[ims]` extra                        |
+| **NDPIS**            | Hamamatsu NanoZoomer fluorescence sets (one NDPI per channel) |
+| **Imaris**           | `.ims`, with the `[hdf5]` extra                       |
+| **HDF5**             | ilastik, BigDataViewer / BigStitcher, Luxendo, Fiji HDF5, with the `[hdf5]` extra |
+| **ICS / IDS**        | Image Cytometry Standard 1.0 and 2.0 (SVI Huygens and others) |
+| **MetaMorph**        | `.nd` acquisitions and their TIFF / STK files         |
+| **Micro-Manager 1.4**| image-per-file acquisitions (`metadata.txt` + one TIFF per plane) |
 | **DeltaVision**      | `.dv`, `.r3d` (softWoRx, OMX, Priism)                 |
 | **MRC**              | Common MRC modes and extended headers                 |
 | **Plates (HCS)**     | Harmony, MetaXpress, IN Cell and CellVoyager plates   |
@@ -532,13 +545,13 @@ Supported TIFF formats include:
 * Zeiss LSM
 * MetaMorph STK
 * Micro-Manager stacks (MMStack and NDTiff), also when one acquisition is spread over several files
-* Whole-slide TIFFs: Aperio SVS, Hamamatsu NDPI, Leica SCN, Ventana BIF, PerkinElmer / Akoya QPTIFF and Philips
+* Whole-slide TIFFs: Aperio SVS, Hamamatsu NDPI, Leica SCN, Ventana / Roche BIF (VENTANA DP 200, iScan Coreo), PerkinElmer / Akoya QPTIFF and Philips
 
-Micro-Manager stage positions are scenes. NDTiff channel names and pixel sizes come from the dataset's index and frame metadata.
+Micro-Manager stage positions are series. NDTiff channel names and pixel sizes come from the dataset's index and frame metadata.
 
-A whole-slide file gives the slide first, then the other pictures it stores as further scenes, as Bio-Formats lists them: `label` and `macro` (overview), and for some formats `thumbnail` (QPTIFF) or `probability` (BIF tissue map). Pixel sizes, positions and channel names come from each vendor's own metadata.
+A whole-slide file gives the slide first, then the other pictures it stores as further series, as Bio-Formats lists them: `label` and `macro` (overview), and for some formats `thumbnail` (QPTIFF) or `probability` (BIF tissue map). Pixel sizes, positions and channel names come from each vendor's own metadata.
 
-Ventana BIF scans store overlapping tiles. They are composed as Roche's description of the format places them. Files from scanners other than the VENTANA DP 200 are not supported.
+Ventana BIF scans store overlapping tiles. VENTANA DP 200 scans are composed as Roche's description of the format places them. iScan Coreo scans, which that description does not cover, are composed as OpenSlide shows them, with one difference: each tile starts at the nearest whole pixel and keeps its stored pixels, where OpenSlide interpolates to a sub-pixel position. Areas outside the scanned regions read as 0. Layouts that were not checked on real files (other EncodeInfo versions, several focal planes, overlapping scan areas) raise an error.
 
 Compressed TIFF data is decoded only for the strips or tiles needed by the requested region.
 
@@ -570,14 +583,16 @@ An OME companion file (`.companion.ome`) describes images stored in separate TIF
 f = micro_reader.open("data.companion.ome")
 ```
 
-Opening one of the TIFF files on its own reads only that file, with its pixel sizes, channels and position taken from the companion. If the companion is missing, the file is read without pixel sizes, with a `CompanionWarning`. A TIFF whose metadata lives in another OME-TIFF (instead of a `.companion.ome`) takes it from that file in the same way.
-
-Some OME-TIFF sets keep the full OME-XML in their TIFF files instead of a companion. Opening one of those files reads the whole set. To read only the planes stored in that file, with the set's metadata:
+Opening one of the TIFF files of the set also reads the whole set, as if the companion had been opened: `f.path` is then the companion, and the companion's metadata is used. To read only that file, with its pixel sizes, channels and position taken from the companion:
 
 ```python
-f = micro_reader.open("set_t001.ome.tif", multifile=False)
+f = micro_reader.open("data_t001.ome.tif", multifile=False)
 ```
 
+If the companion is missing or does not list the file, opening the whole set raises an error that names `multifile=False`. With `multifile=False` the file is then read without pixel sizes, with a `CompanionWarning`. A TIFF whose metadata lives in another OME-TIFF (instead of a `.companion.ome`) works the same way, with that OME-TIFF in the companion's place.
+
+Some OME-TIFF sets keep the full OME-XML in their TIFF files instead of a companion. Opening one of those files also reads the whole set, and `multifile=False` reads only the planes stored in that file, with the set's metadata.
+
 Micro-Manager stacks always open whole, also with `multifile=False`: they split their files by size, so one file does not hold a complete part of the image.
 
 ### CZI
@@ -585,12 +600,12 @@ Micro-Manager stacks always open whole, also with `multifile=False`: they split
 CZI files support:
 
 * mosaic tiles
-* scenes
+* series
 * views
 * rotations
 * RGB
 * large files
-* stored scene pyramids
+* stored series pyramids
 
 CZI-specific operations include:
 
@@ -641,6 +656,8 @@ These are represented using the common image/index model.
 
 Olympus / Evident FluoView OIR files are supported, including companion files and spectral scans.
 
+A multi-area tiling set is opened through its index, `.omp2info`, or its folder: one image per tile, each at the stage position the index gives it (the tiles' own files record none), or one canvas per group with `tiles="mosaic"`. Positions follow the protocol's grid, not a registration. The grid step was derived from one sample, as the backend documents.
+
 ### Olympus OIB and OIF
 
 Older FluoView files come in two forms with the same content: an OIB is one file, an OIF is a `.oif` settings file plus a `.oif.files` folder with one TIFF per plane. Both open as one `t c z y x` image, with pixel sizes, z and time steps, channel names, colours and wavelengths. Opening any file in the `.oif.files` folder opens the OIF.
@@ -658,13 +675,40 @@ Opening the `_<name>_` folder, a `stack` folder or a file in it opens the `.vsi`
 Install Imaris support with:
 
 ```bash
-pip install "micro-reader[ims]"
+pip install "micro-reader[hdf5]"
 ```
 
+(`[ims]` is the extra's former name and still works.)
+
 Imaris resolution level 0 is exposed at the actual image size, with Imaris chunk padding removed.
 
 Chunked compression is decoded in parallel.
 
+### HDF5: ilastik, BigDataViewer, Luxendo, Fiji
+
+These need the `[hdf5]` extra as well.
+
+* **ilastik**: every dataset with ilastik's `axistags` (its exports, its input files, steinbock's `img`) is one image, in the dataset's own axis order. Pixel sizes are read where ilastik recorded units (`axis_units`, since 2025-09).
+* **BigDataViewer / BigStitcher**: the XML with its HDF5 file (also partitioned). One image per tile, angle and illumination, channels on `c` and time points on `t`, with the stored resolution levels. Opening the HDF5 file opens its XML.
+* **Luxendo / Bruker light-sheet** (`.lux.h5`): one stack per file. A whole acquisition opens through the Imaris file Luxendo writes next to it.
+* **Fiji HDF5** (the Vibez plugin): datasets with `element_size_um`; `t<n>/channel<n>` datasets make one `t c z y x` image.
+
+### ICS / IDS
+
+ICS 1.0 (an `.ics` header with an `.ids` pixel file; opening either opens the image) and ICS 2.0 (one file), as written by SVI Huygens and others. Gzip-compressed pixels are read without decompressing the whole file. Images that store rows bottom-up (`coordinates cartesian`) are returned top-down, as Bio-Formats does.
+
+### MetaMorph .nd
+
+A MetaMorph multi-dimensional acquisition: an `.nd` file and the TIFF / STK files named after it. One image per stage position (`series`), `t c z y x`, channels named by the wavelengths. Opening the `.nd` file, any of its files or its folder opens the whole set. The stage coordinates the files record are kept as `Metadata.stage_position`, not as a position: which point of the field they mark is not recorded.
+
+### Micro-Manager 1.4
+
+Image-per-file acquisitions (Micro-Manager 1.4 and the 2.0 betas): a folder per stage position with a `metadata.txt` and one TIFF per plane. One image per stage position, `t c z y x`, with channel names and colours, pixel sizes and the z step. Opening any file or folder of the acquisition opens the whole acquisition.
+
+### Hamamatsu NDPIS
+
+An `.ndpis` set lists one NDPI file per fluorescence channel. Opened, it is one slide image with one channel per file, at every stored resolution level; channels are named by their filter set. Each NDPI file still opens alone as an ordinary slide.
+
 ### DeltaVision
 
 DeltaVision files (`.dv`, `.r3d`, `.r3d_d3d`, also deconvolved and projected ones) are recognised by their content, whatever their extension. The image keeps the file's own order of time, waves and z (for example `ctzyx`).

{micro_reader-0.0.4 → micro_reader-0.2.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "micro-reader"
-version = "0.0.4"
+version = "0.2.0"
 description = "Low-level, memory-bounded pixel reading for microscopy formats: read exactly the rectangle you ask for."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,7 +29,7 @@ classifiers = [
 # TIFF covers most microscopy images, so it is not an extra (Bugra,
 # 2026-10-01) until micro-reader parses TIFF itself (post-0.0.1). The floor
 # matches eubi-bridge's (tifffile>=2025.5.21), so both install together.
-dependencies = ["numpy>=1.24", "micro-reader-codecs>=0.0.1,<0.1", "tifffile>=2025.5.21"]
+dependencies = ["numpy>=1.24", "micro-reader-codecs>=0.0.2,<0.1", "tifffile>=2025.5.21"]
 
 [project.urls]
 Homepage = "https://github.com/bugraoezdemir/micro-reader"
@@ -37,9 +37,11 @@ Source = "https://github.com/bugraoezdemir/micro-reader"
 Issues = "https://github.com/bugraoezdemir/micro-reader/issues"
 
 [project.optional-dependencies]
-ims = ["h5py>=3.11"]          # first h5py for numpy 2; chunk offsets checked against user blocks
+# HDF5 files: Imaris, ilastik, BigDataViewer; `ims` is the older name, kept
+hdf5 = ["h5py>=3.11"]         # first h5py for numpy 2; chunk offsets checked against user blocks
+ims = ["micro-reader[hdf5]"]
 codecs = ["imagecodecs"]
-all = ["micro-reader[ims,codecs]"]
+all = ["micro-reader[hdf5,codecs]"]
 # the reference readers and encoders the tests compare with: never shipped
 # (readlif is GPL-3, pylibCZIrw LGPL-3: test-only, PLAN.md "Dependency policy")
 test = ["pytest", "pillow", "h5py>=3.11", "imagecodecs", "zstandard", "nd2", "readlif", "liffile",