Metadata-Version: 2.4
Name: oirfile
Version: 2026.10.22
Summary: Read Olympus/Evident OIR, POIR, and MPOIR files
Home-page: https://www.cgohlke.com
Author: Christoph Gohlke
Author-email: cgohlke@cgohlke.com
License: BSD-3-Clause
Project-URL: Bug Tracker, https://github.com/cgohlke/oirfile/issues
Project-URL: Source Code, https://github.com/cgohlke/oirfile
Project-URL: Documentation, https://www.cgohlke.com/docs/oirfile/
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=2.1
Provides-Extra: all
Requires-Dist: xarray; extra == "all"
Requires-Dist: tifffile; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

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

:Author: `Christoph Gohlke <https://www.cgohlke.com>`_
:License: BSD-3-Clause
:Version: 2026.10.22
: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`_ and `Documentation <https://www.cgohlke.com/docs/oirfile/>`_
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.17, 3.14.9, 3.15.1 64-bit
- `Numpy <https://pypi.org/project/numpy>`_ 2.5.4
- `Xarray <https://pypi.org/project/xarray>`_ 2026.9.0 (recommended)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.11.2 (optional)
- `Tifffile <https://pypi.org/project/tifffile/>`_ 2026.10.15 (optional)

Revisions
---------

2026.10.22

- Support MPOIR archives via MpoirFile class.
- Read OirFile.producer software name from file header.
- Recover blocks by walking chain when index is unusable (untested).
- Warn when returning partial data from OIR files.
- Preserve gaps of missing planes in partial OIR files.
- Fix reading planes truncated mid-sample.
- Fix UID axis parsing with order-independent matching.
- Fix reading multi-channel line scans.
- Use struct.unpack_from when possible.

2026.9.6

- Fix reading snapshot (COLOR2D) OIR files.

2026.7.28

- Fix spatial and time coordinates.
- Add OirFile.timestamps, scanner, and is_linescan properties.

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

- …

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 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.
MPOIR files are ZIP archives containing a ``matl.omp2info`` tile layout
file and one POIR file per field of a mosaic acquisition.

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

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

Import functions and classes used in these examples:

>>> from oirfile import OirFile

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 2.486... 1.589e+03
  * X        (X) float64 5kB 0.0 2.486... 1.589e+03
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
