See here for a detailed list of changes made in each release of OMIO. Please, also refer to the Repository Releases page.
Each release is also archived on Zenodo for long-term preservation and citation purposes:
This is a major refactor of OMIO's internal structure and batch-processing API. OMIO is now fully organized into focused internal modules for core helpers, cache handling, readers, writers, viewer integration, conversion, templates, and batch processing. This enables more maintainable code, better test coverage, and a more flexible public API for, e.g., adding new readers or custom batch-processing workflows.
This release also adds the new flexible BIDS-like batch processor under the public bids_batch_process() name, while the pre-v0.3.0 converter remains available as bids_batch_convert() for backward compatibility.
We recommend that users relying on OMIO's batch workflows upgrade to v0.3.0 and switch to the new bids_batch_process() API, which provides more robust discovery, filtering, error handling, and reporting features.
- Added a new public
bids_batch_process()implementation with explicit subject selection, subject-prefix discovery, arbitrary folder-token levels, image-pattern filtering, name-based exclusion, skip-if-already-converted logic, robust per-file error handling, persistent run reports, and structured root/local error reports. - Added
discover_bids_like_batch_imagesfor reusable discovery of image files in flexible BIDS-like folder trees. - Added
batch_create_thorlabs_raw_yaml_templates, which reads OMIO or ZenReg-style batch error reports and creates Thorlabs RAW YAML sidecars from editabletemplate_metadatablocks.
- Modularized OMIO's implementation into focused internal modules for core helpers, cache handling, readers, writers, viewer integration, conversion, templates, and batch processing while keeping
omio.omioas a compatibility facade for existing imports. - Kept the pre-v0.3.0 BIDS-like converter available as
bids_batch_convert()for backward compatibility, but marked it as deprecated in favor ofbids_batch_process(). - Batch run reports now automatically label successful custom
process_funcruns with the callable name and compactprocessing_optionswhen no explicitmethod_nameis provided. bids_batch_process(output_folder_name=...)now explicitly supports both relative output folders below each discovered image folder and absolute output folders.bids_batch_process()anddiscover_bids_like_batch_images()now collapse OME multi-file TIFF series during discovery by default, matching OMIO's existingimread/imconvertbehavior. Users can opt out withcollapse_ome_multifile_series=False.bids_batch_process()anddiscover_bids_like_batch_images()now support optionalfolder_stackstags for discovering tagged stack folders below the final folder-token level and loading them through OMIO's existing folder-stack merge path.
- Clarified OMIO's scope relative to Bio-Formats, explaining why Bio-Formats is not a default dependency and how OMIO can still be extended through dedicated pure-Python readers.
- Documented the new
bids_batch_process()workflow, report files, skip semantics, file-pattern filtering, nested tag-folder discovery, and RAW YAML template workflow in the RTD batch conversion guide, README, and interactive tutorial script. - Reintroduced a clearly marked legacy
bids_batch_convert()tutorial cell in the interactive usage script for users maintaining older workflows. - Added a custom
process_funcbatch example showing Z-projection with OMIO's canonicalTZCYXaxis convention while keeping default OMIO loading and saving. - Documented OME multi-file TIFF batch handling and tagged folder-stack batch processing in the RTD batch-processing guide and interactive tutorial script.
- Updated internal monkeypatch targets in the test suite to match the new module boundaries and kept the full regression suite passing after the refactor.
- Added regression coverage for flexible
bids_batch_process()discovery, skip-if-already-converted handling, load/process/save failures, persistent run-report updates, error-report creation, and batch RAW YAML sidecar generation. - Added regression coverage for automatic custom
process_funcnaming and option reporting in batch run reports. - Added regression coverage for OME multi-file TIFF series collapsing in flexible batch discovery.
- Added regression coverage for tagged folder-stack discovery and automatic forwarding of OMIO folder-stack merge options in
bids_batch_process().
August 11, 2026
This maintenance release improves Thorlabs RAW YAML fallback diagnostics.
- Thorlabs RAW size-mismatch warnings now explicitly identify YAML metadata as the source when a YAML fallback was used but its dimensions or bit depth do not match the RAW file.
- Added regression coverage for YAML-derived RAW size mismatches in both NumPy and Zarr-backed Thorlabs RAW reads.
August 10, 2026
This maintenance release fixes an additional Thorlabs RAW XML/YAML fallback edge case observed in batch workflows.
- Thorlabs XML metadata whose dimensions are inconsistent with the RAW file size now trigger the same YAML fallback instead of deriving invalid dimensions such as
Z=0. - Thorlabs YAML metadata now accepts both
pixelunitandPixelUnitfor the pixel-size unit field.
- Added regression coverage for XML dimensions that are internally parseable but inconsistent with the RAW file size.
August 07, 2026
This maintenance release improves robustness of Thorlabs RAW metadata discovery.
- The Thorlabs RAW reader now ignores hidden dot XML files such as
._Experiment.xmland.Experiment.xmlwhen looking for XML metadata. - If a Thorlabs XML metadata file is present but incomplete or inconsistent,
read_thorlabs_rawnow falls back to a valid YAML metadata file in the same folder instead of aborting immediately. - Added
on_error="raise"|"return_none"toimreadandread_thorlabs_rawso batch workflows can opt into(None, None)returns for unrecoverable Thorlabs RAW metadata problems.
- Added regression coverage for Thorlabs RAW folders that contain hidden dot XML sidecar files next to the real metadata XML.
- Added regression coverage for user-repaired Thorlabs RAW folders where a broken XML file remains next to a valid YAML metadata fallback.
- Added regression coverage for strict and batch-friendly Thorlabs RAW error policies.
July 29, 2026
This small maintenance release improves memory efficiency when exporting large Zarr-backed OMIO arrays to OME-TIFF.
imwritenow writes Zarr-backed inputs plane-wise instead of materializing the full Zarr store withnp.asarray.- Zarr-backed
imwriteexports still use the same OME-TIFF writer axis layout as before and remain compatible with OMIO readback to canonicalTZCYX.
- Added Large File Handling documentation for memory-aware OME-TIFF export from Zarr-backed OMIO arrays.
- Extended the interactive usage example with a disk-backed Zarr-to-OME-TIFF
imwriteworkflow and roundtrip check.
- Added regression coverage to ensure Zarr-backed
imwritedoes not perform full-array materialization while preserving OME-TIFF axis semantics and OMIO roundtrip behavior.
July 28, 2026
This maintenance release adds configurable on-disk cache locations for imread workflows.
- Added
zarr_store_pathtoimreadand the underlying TIFF, CZI, and Thorlabs RAW readers. imread(..., zarr_store="disk", zarr_store_path=<path>)now creates.omio_cacheunder the provided path instead of next to the source file.- Disk-cache metadata returned by
imreadnow recordsomio_cache_folder,omio_zarr_store_path,omio_zarr_store_name, andomio_zarr_store_typefor disk-backed reads.
reuse_disk_cache=Truenow checks the customzarr_store_pathlocation when one is provided, enabling reuse of local caches for source files stored on a server or external drive.
- Added an interactive tutorial example showing how to create and reuse a local OMIO disk cache via
zarr_store_path.
- Added regression tests for custom
zarr_store_pathcache creation and reuse through bothread_tifand publicimread.
July 27, 2026
This small follow-up release refines Napari layer naming so custom channel names remain grouped under the resolved image name.
open_in_napari(..., layer_names=[...])now prefixes custom channel/layer names with the resolved image name, keeping layer lists grouped and readable in Napari.
- Updated Napari examples in the interactive tutorial and Read the Docs pages to show image-name-prefixed per-channel
layer_names.
- Added regression coverage for custom
layer_namestogether with explicitimage_nameand metadata-derived image names.
July 27, 2026
This maintenance release improves documentation consistency across OMIO's main public API, extends disk-backed template-image workflows, and makes Napari visualization more convenient and customizable.
- Extended
create_empty_imagefor disk-backed Zarr workflows viazarr_store="disk"together withzarr_store_path. - Disk-backed empty images now record
omio_cache_folder,omio_zarr_store_path,omio_zarr_store_name, andomio_zarr_store_typein the returned metadata. - Disk-backed empty-image Zarr stores now persist OMIO metadata and cache information in their Zarr attributes.
- Added
image_name,layer_names, andblendingoptions toopen_in_napari. open_in_napari(..., image_name=None)now derives layer names from OMIO metadata such asAnnotations["original_filename"]when available.
create_empty_image(..., zarr_store="disk")now useszarr_store_name="empty_image"when no explicit store name is provided.cleanup_omio_cachecan now remove a directly provided.omio_cachefolder, enabling cleanup viaom.cleanup_omio_cache(my_metadata["omio_cache_folder"], full_cleanup=True).- Napari layers now use
blending="additive"by default, while still allowing any Napari-supported blending mode to be passed through. - The former
open_in_napari(..., fname=...)argument remains available as a backward-compatible alias forimage_name.
- Harmonized the
Parameters/Returns/Raisesdocstring layout ofimread,read_thorlabs_raw,imconvert, andbids_batch_convertwith OMIO's primary documentation style used by functions such asimwriteandcleanup_omio_cache. - Clarified return-value descriptions for high-level reader and conversion functions to make the generated API reference more uniform and easier to scan.
- Added tutorial coverage for creating empty OMIO arrays directly as on-disk Zarr stores and cleaning them up via metadata-recorded cache paths.
- Updated Napari examples in the interactive tutorial and Read the Docs pages to show metadata-derived layer naming, explicit
image_name, per-channellayer_names, and configurable blending.
- Added regression tests for disk-backed empty-image metadata, persisted Zarr attributes, default store naming, and cache cleanup using the metadata-provided cache folder.
- Added Napari regression tests for metadata-derived layer names, backward-compatible explicit names, per-channel layer names, and blending pass-through.
June 12, 2026
This maintenance release adds validated reuse of OMIO's on-disk Zarr caches and stores enough OMIO metadata inside each cache to reopen compatible datasets without rereading the original microscopy file.
- Added opt-in disk-cache reuse for
imread(..., zarr_store="disk", reuse_disk_cache=True). - Compatible existing
.omio_cache/<basename>.zarrstores can now be reopened directly instead of being rebuilt from the source file. - Added persisted OMIO cache manifests for disk-backed TIFF, CZI, and Thorlabs RAW reads.
- Added persisted OMIO metadata payloads for disk-backed TIFF, CZI, and Thorlabs RAW reads, enabling cache reuse without reopening the original source image for metadata extraction.
- OMIO now stores disk-cache metadata and cache validation info directly in Zarr attributes, which are persisted in the store's
zarr.jsonunder the current Zarr v3 layout. - Disk-cache reuse is validated against source path, file size, modification time, OMIO version, reader/backend identity, pixel unit, and any explicit physical-size overrides before reuse is allowed.
- If a disk cache is missing OMIO metadata, missing cache info, stale, or otherwise incompatible, OMIO now falls back automatically to a full rebuild and refreshes the cache in place.
- Added regression tests covering persisted disk-cache metadata payloads for TIFF-backed Zarr caches.
- Added regression tests verifying that TIFF, CZI, and Thorlabs RAW readers can reopen compatible disk caches without rereading the original source files.
- Added regression tests covering fallback behavior when a stale or incomplete disk cache is encountered.
- OMIO is now described in a dedicated preprint that can be cited in academic work:
May 13, 2026
This maintenance release restores compatibility with recent czifile, tifffile, and zarr/Dask dependency revisions and keeps OMIO's CZI, TIFF, conversion, and napari-cache workflows working across both legacy and current APIs.
- Restored CZI reader compatibility with
czifile2026.4.30and newer. read_czinow resolves axes via scene metadata whenCziFile.axesis no longer available.read_czinow retrieves structured CZI metadata viametadata(asdict=True)when the oldermetadata(raw=False)API is unavailable.- Compatibility is implemented via feature detection instead of a hard dependency-version check, preserving support for older
czifilereleases. - Restored TIFF axis handling for files where recent
tifffilerevisions collapse singleton dimensions inseries[0].axesbut still preserve the full shape inshaped_metadata. read_tifnow usesshaped_metadataas a fallback axis source whentifffiledrops singleton axes such asT=1orZ=1.- Restored compatibility with current
dask.array.to_zarr/zarrbehavior by switching napari-cache writes away from the deprecatedzarr_read_kwargspath and to the currentmode="w"API.
- Added regression tests covering both legacy and current
czifileCZI-reader APIs. - Added regression tests covering TIFF axis fallback from
shaped_metadatawhen singleton dimensions are omitted fromseries[0].axes. - Full
pytestsuite passes again under the current dependency set.
- OMIO has its first own logo now! (December 30, 2025) That's cool, but does not affect functionality or justify a dedicated release on its own.
December 29, 2025
This release introduces a more consistent public API, improves TIFF and OME-TIFF handling (including multi-file OME-TIFF series and paginated stacks), strengthens napari visualization robustness, and significantly expands documentation and example data.
- API consolidation:
write_ometiffhas been renamed toimwriteto align withimreadandimconvert. - Improved TIFF family robustness: better physical pixel size handling, clearer container policies, and correct behavior for multi-file OME-TIFF series.
- More robust napari visualization: clearer viewer summaries and safeguards against accidental loss of spatial axes.
- Major documentation expansion and a Zenodo-hosted example dataset for tutorials and testing.
write_ometiff→imwrite- Rationale: improves naming consistency across the core API (compared to
imreadandimconvert). - Migration: replace
write_ometiff(...)withimwrite(...).
- Rationale: improves naming consistency across the core API (compared to
read_tifnow emits explicit warnings whenPhysicalSizeX,PhysicalSizeY, orPhysicalSizeZcannot be read from metadata and default or user-provided values are used instead.- Improved fallback extraction of physical pixel sizes from TIFF tags when
imagej_metadatais incomplete._standardize_imagej_metadatahas been extended accordingly.
- Metadata inspection logic refined.
shaped_metadatais now ignored in "not yet implemented metadata types" checks, as it typically contains only shape information.
- README and
read_tifdocstrings now explicitly document support for multi-file OME-TIFF series.- Passing the path of a single file is sufficient, as OMIO reconstructs the full logical dataset via OME-XML references.
imreadnow correctly detects multi-file OME-TIFF series when a folder path is provided.- Previous behavior could incorrectly treat all TIFF files in a folder as independent images. This is now fixed.
- The same fix propagates to
imconvertandbids_batch_convert.
- Added
create_thorlabs_raw_yaml.- Allows users to generate an empty
experiment.yamltemplate for Thorlabs RAW folders whenExperiment.xmlis missing.
- Allows users to generate an empty
- Improved the final status message of the napari opener.
- Now prints a concise summary including layer names, scales, and shapes.
- Added internal safety checks to prevent spatial axes
XandYfrom being squeezed away when their dimension equals 1.
test_all_readers_with_dummy_data.pynow generates more informative dummy data.- Dummy TIFF files include text annotations.
- Additional folder structures are created to demonstrate batch processing and folder handling behavior.
Expanded and reorganized documentation, including:
- A Core Workflow guide covering reading, inspecting, viewing, and writing images, with examples for
imread,imwrite, andimconvert. - A detailed overview of supported formats (LSM, CZI, Thorlabs RAW) with usage examples.
- Clarified TIFF container policies:
- multi-series TIFF stacks
- paginated TIFF stacks
- multi-file OME-TIFF series
- Documentation of folder reading semantics in
imread, including tagged folders and folder stacks. - Guidance on large file handling using Zarr-backed lazy loading and memory mapping, including Dask-based napari visualization.
- A section on creating empty images and metadata with utilities for OME-compliant structures.
- A new section on batch conversion over a BIDS-like tree using
bids_batch_convert.
- Added a Zenodo-hosted example dataset containing artificially generated toy data and selected publicly available real-world microscopy data for tutorials and testing.
- Verify that all documentation and examples consistently use
imwrite. - Ensure that references to
write_ometiffare removed or updated. - Highlight the API rename prominently in upgrade notes and downstream documentation.
Dec 23, 2025
This release focuses on improving documentation and usability.
- OMIO releases are now linked to Zenodo, enabling long-term archiving and versioned software snapshots.
- A Zenodo DOI (10.5281/zenodo.18030883) is associated with the project, making OMIO formally citable in scientific publications.
- Citation metadata has been added to the repository to document the preferred citation form.
- The README has been revised to correct and clarify several example usage snippets.
- Example code now reflects the current public API and recommended usage patterns more accurately.
This release focuses on establishing a stable citation and archiving workflow and on improving the reliability of user-facing documentation. No changes to the core API or reader behavior were introduced.
Dec 23, 2025
This is just a dummy release for connecting the repository to Zenodo.
Dec 23, 2025
This release is a small maintenance update.
- Correctly resolve the installed package version at runtime when OMIO is distributed under the PyPI name omio-microscopy while being imported as
omio. - Ensure the reported OMIO version now matches the version defined in
pyproject.toml.
- All existing tests pass with the corrected version handling.
- No API or behavior changes for users beyond the version fix.
This release prepares OMIO for stable use via pip install omio-microscopy while keeping the familiar import omio interface.
Dec 23, 2025
This is the first public release of OMIO (Open Microscopy Image I/O), providing a unified, reproducible, and OME-compliant image loading layer for bioimaging and microscopy data.
OMIO v0.1.1 establishes the core design principles of the project: a single, canonical in-memory representation for microscopy images and metadata, explicit handling of OME axes, and robust support for large datasets via Zarr.
- Unified image reading interface for common microscopy formats, including TIFF, OME-TIFF, LSM, CZI, and Thorlabs RAW.
- Canonical internal image representation using the OME axis order TZCYX.
- Automatic axis normalization, validation, and correction based on file metadata.
- Consistent metadata handling aligned with OME concepts, including physical pixel sizes, time increments, and axis annotations.
- Explicit provenance tracking of original filenames, file types, and metadata sources.
- Native reading of Thorlabs RAW files using accompanying XML metadata.
- YAML metadata fallback when XML metadata is unavailable, enabling reproducible interpretation of legacy or incomplete datasets.
- Automatic correction of Z dimension inconsistencies based on RAW file size.
- Optional memory-efficient Zarr output for large RAW datasets, with slice-wise copying to limit peak RAM usage.
- Optional output as NumPy arrays or Zarr arrays (in-memory or on-disk).
- Automatic chunk size computation based on image shape and axis order.
- Incremental writing strategies to support large files and interactive environments.
- Built-in Napari viewer utilities for interactive inspection of OMIO-loaded images.
- Automatic handling of OME axes and dimensionality for Napari display.
- Support for efficient visualization of large Zarr-backed datasets without full materialization in memory.
- Concatenation of compatible 5D image stacks along selected OME axes.
- Optional zero-padding to merge datasets with mismatched non-merge dimensions.
- Robust handling of filename collisions and metadata provenance during merge operations.
- Helper utilities for Zarr group inspection, metadata recovery, and axis consistency checks.
- Extensive automated test coverage across readers, edge cases, and failure modes.
- Synthetic test data for RAW and TIFF paths, complemented by small CC BY 4.0 test images for CZI and LSM formats.
- Clear warning and error behavior for incomplete metadata, unsupported configurations, and inconsistent inputs.
- First PyPI release under the distribution name omio-microscopy.
- Importable Python package name remains omio.
- Python 3.12 or newer required.
This release focuses on correctness, transparency, and reproducibility rather than maximal format coverage. OMIO is designed as a stable foundation for downstream analysis pipelines, where consistent axis semantics and metadata integrity are critical.
Future releases will expand format support, refine metadata policies, and further improve performance and interoperability with downstream bioimaging tools.