..
  This file is generated by setup.py

Read Olympus/Evident OIR and POIR files
=======================================

Oirfile is a Python library to read images and metadata from OIR (Olympus
Image Format Raw) files and POIR archives (ZIP collections of OIR files)
produced by Olympus/Evident FluoView fluorescence microscopy software.

:Author: `Christoph Gohlke <https://www.cgohlke.com>`_
:License: BSD-3-Clause
:Version: 2026.3.28
:DOI: `10.5281/zenodo.18916509 <https://doi.org/10.5281/zenodo.18916509>`_

Quickstart
----------

Install the oirfile package and all dependencies from the
`Python Package Index <https://pypi.org/project/oirfile/>`_::

    python -m pip install -U oirfile[all]

See `Examples`_ for using the programming interface.

Source code and support are available on
`GitHub <https://github.com/cgohlke/oirfile>`_.

Requirements
------------

This revision was tested with the following requirements and dependencies
(other versions may work):

- `CPython <https://www.python.org>`_ 3.12.10, 3.13.12, 3.14.3 64-bit
- `NumPy <https://pypi.org/project/numpy>`_ 2.4.3
- `Xarray <https://pypi.org/project/xarray>`_ 2026.2.0 (recommended)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.10.8 (optional)
- `Tifffile <https://pypi.org/project/tifffile/>`_ 2026.3.3 (optional)

Revisions
---------

2026.3.28

- Fix reading long line scan where Y exceeds per-frame height.

2026.3.8

- Initial alpha release.
- …

Notes
-----

This library is in its early stages of development.
Large, backwards-incompatible changes may occur between revisions.

`Olympus/Evident <https://www.olympus-evident.com/>`_ is a manufacturer of
microscopes and scientific instruments.
Olympus Image Format Raw (OIR) files are proprietary formats written by
Evident FluoView acquisition software to store microscopy images and metadata.

No public specification for the OIR file format exists. The format has been
reverse-engineered from sample files.

OIR files begin with the magic bytes OLYMPUSRAWFORMAT followed by
a header pointing to a block index at the end of the file.
The block index lists offsets to typed blocks: UID blocks paired with
PIXEL blocks (raw image planes), BMP blocks (bitmap thumbnails),
FRAMEPROPERTIES blocks (per-frame XML with dimensions and axis positions),
and METADATA blocks (XML documents for file info, LSM image settings,
channels, axes, pixel size, acquisition parameters, annotations, overlays,
and LUTs).
Image data is organized as up to six dimensions: T (timelapse),
L (lambda/spectral), Z (z-stack), C/S (channel or RGB sample), Y, and X.
Each plane is stored as one or more PIXEL blocks identified by a structured
UID encoding the plane's dimensional indices and channel GUID.
POIR files are ZIP archives containing one or more OIR files.

This library is not feature-complete. Unsupported features currently include
reading BMP block data and writing OIR files.

The library has been tested with only a limited number of files.

Other implementations for reading OIR files are
`Image5D <https://github.com/Silver-Fang/Image5D>`_ (C++) and
`bio-formats <https://github.com/ome/bioformats>`_ (Java).

Examples
--------

Read an image and metadata from an OIR file:

.. code-block:: python

    >>> with OirFile('tests/data/Test.oir') as oir:
    ...     xml_metadata = oir.xml_metadata
    ...     oir.asxarray()
    ...
    <xarray.DataArray 'Test.oir' (Z: 10, C: 4, Y: 640, X: 640)> Size: 33MB
    array([[[[...]]]],
          shape=(10, 4, 640, 640), dtype=uint16)
    Coordinates:
      * Z        (Z) float64 80B 6.115e+03 6.15e+03... 6.43e+03
      * C        (C) <U3 48B 'CH1' 'CH2' 'CH3' 'CH4'
      * Y        (Y) float64 5kB 0.0 0.003884... 2.482
      * X        (X) float64 5kB 0.0 0.003884... 2.482
    Attributes...
        bitspersample:        12
        colortype:            GlayScale
        channel_wavelengths:  {'CH1': (None, None), 'CH2': (500.0, 600.0),...
        datetime:             2020-12-23T14:44:50.939+13:00

View the image and metadata in an OIR file from the console::

    $ python -m oirfile tests/data/Test.oir