oirfile 2026.3.28

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

License:

BSD-3-Clause

Version:

2026.3.28

DOI:

10.5281/zenodo.18916509

Quickstart

Install the oirfile package and all dependencies from the Python Package Index:

python -m pip install -U oirfile[all]

See Examples for using the programming interface.

Source code and support are available on GitHub.

Requirements

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

• CPython 3.12.10, 3.13.12, 3.14.3 64-bit

• NumPy 2.4.3

• Xarray 2026.2.0 (recommended)

• Matplotlib 3.10.8 (optional)

• 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 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 (C++) and bio-formats (Java).

Examples

Read an image and metadata from an OIR file:

>>> 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