oirfile 2026.7.10

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.14, 3.14.7, 3.15.0b3 64-bit

• Numpy 2.5.1

• Xarray 2026.7.0 (recommended)

• Matplotlib 3.11.0 (optional)

• Tifffile 2026.6.1 (optional)

Revisions

2026.7.10

• Fix reading reference images.

• Fix main image display when file also contains reference image.

• Add option to memory-map OIR files.

• Support multifile OIR (#4).

• Support Python 3.15.

2026.4.25

• Use full name unit strings in coord_units (breaking).

• Drop support for numpy 2.0 (SPEC0).

2026.4.18

• Omit axes from coords when no meaningful metadata is available (breaking).

• Add OirReference class for reference images and their line ROI coordinates.

• Add thumbnail and reference properties to OirFile (#3).

• Add coord_offsets and coord_scales properties to OirFile.

• Add bitspersample and colortype properties to OirFile.

• Normalize colortype “GlayScale” to “GrayScale”.

• Use per-frame positions for lambda (L) axis coordinates.

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 or reference images), FRAMEPROPERTIES blocks (per-frame XML with dimensions and axis positions), METADATA blocks (XML documents for file info, LSM image settings, channels, axes, pixel size, acquisition parameters, annotations, overlays, and LUTs), and BMP blocks (bitmap thumbnails). 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. Large acquisitions may be split across a main OIR file and one or more companion files named <basename>_00001, _00002, etc. (no extension). Companion files use the same binary format. The main file holds all metadata while companions contain additional pixel blocks. POIR files are ZIP archives containing one or more OIR files.

This library is not feature-complete. Writing OIR files, compressed pixel data, and mosaic acquisitions are not supported.

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:            GrayScale
    datetime:             2020-12-23T14:44:50.939+13:00
    ...
    channel_wavelengths:  {'CH1': (None, None), 'CH2': (500.0, 600.0),...

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

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