oirfile

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

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

Revisions

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

License

Copyright (c) 2025-2026, Christoph Gohlke
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

oirfile module

oirfile.__version__ = '2026.4.25'

Oirfile version string.

class oirfile.OirChannel(id, name, order, start_wavelength=None, end_wavelength=None)

Bases: object

Channel information extracted from OIR metadata.

Parameters:

  • id (str)

  • name (str)

  • order (int)

  • start_wavelength (float | None)

  • end_wavelength (float | None)

__delattr__(name)

Implement delattr(self, name).

__eq__(other)

Return self==value.

__getstate__()

Helper for pickle.

__hash__()

Return hash(self).

__init__(id, name, order, start_wavelength=None, end_wavelength=None)
Parameters:

  • id (str)

  • name (str)

  • order (int)

  • start_wavelength (float | None)

  • end_wavelength (float | None)

Return type:

None

__repr__()

Return repr(self).

__setattr__(name, value)

Implement setattr(self, name, value).

id: str

Channel GUID.

name: str

Display name.

order: int

Channel order index.

start_wavelength: float | None

Emission start wavelength in nm or None.

end_wavelength: float | None

Emission end wavelength in nm or None.

final class oirfile.OirFile(file, /, *, squeeze=True, mode=None)

Bases: BinaryFile

OIR file.

OirFile instances are not thread-safe. All attributes are read-only.

OirFile instances must be closed with OirFile.close(), which is automatically called when using the ‘with’ context manager.

OIR files contain one image. Dimensions are ordered T, L, Z, C/S, Y, X (slowest to fastest varying).

Dimension labels:

  • T: time (timelapse). Coordinates in seconds.

  • L: lambda (spectral / wavelength axis). Coordinates in nm.

  • Z: depth (z-stack). Coordinates in micrometers.

  • C: fluorescence channel (one per acquisition channel). Coordinate values are channel display names.

  • S: sample (RGB color component, planar). Present instead of C when colortype is 'RGB'. Coordinate values are channel display names.

  • Y: image row. Coordinates in native units (pixel pitch * index).

  • X: image column. Coordinates in native units (pixel pitch * index).

Y and X are always present. Dimensions not part of the acquisition are always omitted. When squeeze=True, acquired dimensions of length one are also omitted.

Parameters:

  • file (str | os.PathLike[Any] | IO[bytes]) – Name of OIR file or seekable binary stream.

  • mode (Literal['r', 'r+'] | None) – File open mode if file is file name. The default is ‘r’. Files are always opened in binary mode.

  • squeeze (bool) – Also remove acquired dimensions of length one from images.

Raises:

OirFileError – File is not in OIR or is corrupted.

__init__(file, /, *, squeeze=True, mode=None)
Parameters:

  • file (str | os.PathLike[Any] | IO[bytes])

  • squeeze (bool)

  • mode (Literal['r', 'r+'] | None)

Return type:

None

property dtype: numpy.dtype[Any]

NumPy data type of image.

property bitspersample: int

Number of significant bits per sample.

property colortype: str

Color type string, for example 'GrayScale' or 'RGB'.

property sizes: dict[str, int]

Ordered mapping of dimension name to length.

Dimension order is T, L, Z, C, Y, X (or S instead of C for RGB images). Y and X are always present. Dimensions not part of the acquisition are always omitted. When squeeze=True, acquired dimensions of length one are also omitted.

property shape: tuple[int, ...]

Shape of image.

property dims: tuple[str, ...]

Dimension names of image.

property ndim: int

Number of image dimensions.

property nbytes: int

Number of bytes consumed by image.

property size: int

Number of elements in image.

property channels: tuple[OirChannel, ...]

Channel information.

property coords: dict[str, NDArray[Any]]

Mapping of dimension names to physical coordinate arrays.

property coord_units: dict[str, str]

Coordinate unit strings per axis.

Map dimension character codes to their full name unit string. Only axes with numeric coordinates are included.

property coord_offsets: dict[str, float]

Coordinate offsets (first pixel position) per axis.

Map dimension character codes to the coordinate value of the first pixel. Only axes with numeric coordinates are included.

property coord_scales: dict[str, float]

Coordinate step sizes per axis.

Map dimension character codes to the spacing between consecutive coordinate values. Only axes with numeric, regularly spaced coordinates are included.

property reference: OirReference | None

Reference image, or None if not present.

Reference images are full-field overview images stored alongside certain acquisition modes like line scans.

property thumbnail: bytes | None

Thumbnail image as BMP bytes, or None if not present.

Returns raw Windows BMP file bytes that can be written to a .bmp file or decoded with an image library.

property attrs: dict[str, Any]

Image metadata as dict.

property xml_metadata: MappingProxyType

Metadata XML strings keyed by METADATA type.

The mapping maps METADATA integer keys to lists of raw XML strings for each metadata block type present in the file. Most types have one entry; METADATA.LUT and METADATA.CAMERAIMAGE may have multiple (one per channel); METADATA.FRAMEPROPERTIES has one entry per acquired plane.

property datetime: str | None

Image creation date and time string, or None if absent.

asarray(*, out=None)

Return image data as NumPy array.

Parameters:

out (OutputType) – Output destination for image data. If None, create a new NumPy array in main memory. If 'memmap', create a memory-mapped array in a temporary file. If a numpy.ndarray, a writable, initialized array of shape and dtype. If a file name or open file, create a memory-mapped array in the specified file.

Returns:

NumPy array containing image data.

Return type:

NDArray[Any]

asxarray(*, out=None)

Return image data as xarray DataArray.

Parameters:

out (OutputType) – Output destination for image data. Passed to asarray().

Returns:

xarray.DataArray

Image data with coordinates, dimensions, and attributes.

Return type:

DataArray

__str__()

Return str(self).

Return type:

str

__repr__()

Return repr(self).

Return type:

str

class oirfile.OirFileError

Bases: ValueError

Exception to indicate invalid OIR file structure.

__weakref__

list of weak references to the object

class oirfile.OirReference(oir, height, width, pixel_map, line_roi, /)

Bases: object

Reference image from OIR file.

Reference images are full-field overview images stored alongside certain acquisition modes like line scans. They are 2D (Y, X) or 3D (C, Y, X) arrays of the same dtype as the main image.

OirReference objects are returned by OirFile.reference and should not be created directly. They hold a reference to the parent OirFile and become invalid after it is closed.

Parameters:

  • oir (OirFile)

  • height (int)

  • width (int)

  • pixel_map (dict[str, list[tuple[int, int]]])

  • line_roi (tuple[float, float, float, float] | None)

__init__(oir, height, width, pixel_map, line_roi, /)
Parameters:

  • oir (OirFile)

  • height (int)

  • width (int)

  • pixel_map (dict[str, list[tuple[int, int]]])

  • line_roi (tuple[float, float, float, float] | None)

Return type:

None

property dtype: numpy.dtype[Any]

NumPy data type of reference image.

property sizes: dict[str, int]

Ordered mapping of dimension name to length.

property shape: tuple[int, ...]

Shape of reference image.

property dims: tuple[str, ...]

Dimension names of reference image.

property ndim: int

Number of reference image dimensions.

property size: int

Number of elements in reference image.

property nbytes: int

Number of bytes consumed by reference image.

property line_roi: tuple[float, float, float, float] | None

Line ROI coordinates (x1, y1, x2, y2), or None.

property attrs: dict[str, Any]

Selected metadata as dict.

property coords: dict[str, NDArray[Any]]

Mapping of dimension names to physical coordinate arrays.

property coord_units: dict[str, str]

Coordinate unit strings per axis.

Map dimension character codes to their full name unit string. Only axes with numeric coordinates are included.

property coord_offsets: dict[str, float]

Coordinate offsets (first pixel position) per axis.

Map dimension character codes to the coordinate value of the first pixel. Only axes with numeric coordinates are included.

property coord_scales: dict[str, float]

Coordinate step sizes per axis.

Map dimension character codes to the spacing between consecutive coordinate values. Only axes with numeric, regularly spaced coordinates are included.

asarray(*, out=None)

Return reference image data as NumPy array.

Parameters:

out (OutputType) – Output destination for image data. Passed to create_output().

Returns:

NumPy array containing reference image data.

Return type:

NDArray[Any]

asxarray(*, out=None)

Return reference image data as xarray DataArray.

Parameters:

out (OutputType) – Output destination for image data. Passed to asarray().

Returns:

xarray.DataArray

Reference image data with coordinates and dimensions.

Return type:

DataArray

__str__()

Return str(self).

Return type:

str

__repr__()

Return repr(self).

Return type:

str

__weakref__

list of weak references to the object

final class oirfile.PoirFile(file, /, *, squeeze=True)

Bases: Mapping[str, OirFile]

POIR file.

POIR files are ZIP archives containing one or more OIR files. PoirFile implements the collections.abc.Mapping interface, mapping OIR file paths within the archive to lazily opened OirFile instances.

PoirFile instances must be closed with PoirFile.close(), which is automatically called when using the ‘with’ context manager.

Parameters:

  • file (str | os.PathLike[Any] | IO[bytes]) – Path to POIR file or readable binary stream.

  • squeeze (bool) – Passed to each OirFile.

Raises:

OirFileError – File is not a valid POIR (ZIP) archive.

__init__(file, /, *, squeeze=True)
Parameters:

  • file (str | os.PathLike[Any] | IO[bytes])

  • squeeze (bool)

Return type:

None

__repr__()

Return repr(self).

Return type:

str

__str__()

Return str(self).

Return type:

str

property closed: bool

File is closed.

close()

Close POIR file and all open OIR files.

Return type:

None

__weakref__

list of weak references to the object

oirfile.imread(file: str | os.PathLike[Any] | IO[bytes], /, *, name: str | int | None = None, squeeze: bool = True, asxarray: Literal[False] = False, out: OutputType = None) → NDArray[Any]
oirfile.imread(file: str | os.PathLike[Any] | IO[bytes], /, *, name: str | int | None = None, squeeze: bool = True, asxarray: Literal[True] = False, out: OutputType = None) → DataArray

Return image from OIR or POIR file.

Parameters:

  • file (str | os.PathLike[Any] | IO[bytes]) – Name of OIR or POIR file or seekable binary stream.

  • name (str | int | None) – Select OIR file from POIR archive by name (str) or index (int). If None, return the first OIR file in the archive. Ignored for plain OIR files.

  • squeeze (bool) – Remove acquired dimensions of length one from image.

  • asxarray (bool) – Return image data as xarray.DataArray instead of numpy.ndarray.

  • out (OutputType) – Output destination for image data. Passed to OirFile.asarray().

Returns:

Image data as numpy array or xarray DataArray.

Return type:

NDArray[Any] | DataArray

oirfile.FILE_EXTENSIONS
class oirfile.METADATA(*values)

Bases: IntEnum

Metadata block types in OIR file.

__format__(format_spec, /)

Convert to a string according to format_spec.

__new__(value)
FILEINFO = 1

File information (creation date, system name, version).

LSMIMAGE = 2

Laser scanning microscope image settings (channels, axes, sizes).

ANNOTATION = 3

Annotation data.

OVERLAY = 4

Overlay data.

LUT = 5

Lookup table data (one entry per channel).

IMAGEDEFINITION = 6

Image definition data.

EVENTLIST = 7

Event list data.

CAMERAIMAGE = 8

Camera image properties and channel data (one entry per channel).

FRAMEPROPERTIES = 9

Frame properties (one entry per acquired plane).