OMIO: A policy-driven Python library for reproducible microscopy image I/O

OMIO (Open Microscopy Image I/O) is a policy-driven Python library for reading, organizing, merging, visualizing, and exporting multidimensional microscopy image data under explicit OME-compliant axis and metadata semantics.

OMIO is designed as an infrastructure layer between heterogeneous microscopy file formats and downstream analysis or visualization workflows. It provides a unified I/O interface that enforces consistent axis ordering, metadata normalization, and memory-aware data handling across NumPy, Zarr, Dask, napari, and OME-TIFF.

Note

NOTE: OMIO is currently under active development. The API and feature set may change in future releases. We also welcome feedback, feature requests, and contributions via GitHub issues. Please report any bugs or inconsistencies you encounter.

Contents

• Overview
  • Motivation and Problem Statement
  • Design Principles
    • Explicit Axis Semantics
    • OME Aware, but Not OME Exclusive
    • Policy Driven Behavior
    • Memory Aware by Construction
    • Separation of Concerns
  • Core Functionality
    • Unified Image Reading
    • Metadata Normalization and Enforcement
    • Controlled Merging along Semantic Axes
    • Folder Based and BIDS Like Workflows
    • OME TIFF Export
    • Napari Integration
    • Creating Metadata and Image Templates
  • Typical Usage Patterns
  • Scope and Non Goals
  • Installation
  • Further Reading
  • License
  • Citation
  • Acknowledgements
• Installation
  • Recommended Installation Method
  • For Developers
• Usage
  • Example Data Sets
    • Licensing and attribution
  • Core Workflow: Read, Inspect, View, Write
    • Hello World
    • Single File Reading and Metadata Inspection
    • Opening Images in Napari and Metadata Modification
    • Ensured OME Compliance upon Reading
    • Ensured OME Compliance upon Writing
    • The imconvert Convenience Function
  • Supported File Formats
    • Reading LSM Files
    • Reading CZI Files
    • Reading Thorlabs RAW Files
  • TIFF Container Policies and Special Layouts
    • Reading Multi-Series TIFF Stacks
    • Reading Paginated TIFF Stacks
    • Reading Multi-File OME-TIFF Stacks
  • Large File Handling and Out of Core Workflows
    • Read Large Files Lazily With Zarr Backend
    • Efficiently View Large Images in Napari With OMIO’s DASK Support
  • Folder Reading and Semantic Merging
    • Imread’s Folder Reading and Merging Capability
    • Folder Stacks Reading and Merging
  • Batch Conversion over a BIDS-like Tree
    • OMIO’s Batch Conversion Function
  • Creating Empty Images and Metadata
    • Creating Empty, OME-Compliant Image Arrays and Metadata
• API Reference
  • High level I/O
    • imread()
    • imwrite()
    • imconvert()
    • bids_batch_convert()
  • Checks and utilities
    • hello_world()
    • OME_metadata_checkup()
    • cleanup_omio_cache()
    • open_in_napari()
  • Readers
    • read_tif()
    • read_czi()
    • read_thorlabs_raw()
  • Metadata and image helpers
    • create_empty_metadata()
    • create_empty_image()
    • update_metadata_from_image()
• What’s New?
  • OMIO Changelog
  • 🚀 OMIO v0.2.1
    • 📃 Changes
  • 🚀 OMIO v0.2.0
    • 📃 Changes
  • 🚀 OMIO v0.1.4
    • 📃 Changes
  • 🚀 OMIO v0.1.3
  • 🚀 OMIO v0.1.2
    • 📃 Changes
  • 🚀 OMIO v0.1.1
    • 📃 Changes
• Contributing and Community Guidelines
  • How to Contribute
  • Contribution Guidelines
  • Requests for New File Formats and Reader Extensions
  • Code of Conduct
  • Where to Start?

OMIO is free and open-source software (FOSS) distributed under the GPL-3.0 license.