obffile 2026.2.20
Read Imspector object binary format files (OBF and MSR)
License: BSD-3-Clause
Requires Python: >=3.11

Read Imspector object binary format files (OBF and MSR)
=======================================================

Obffile is a Python library to read image and metadata from
Object Binary Format (OBF) and Measurement Summary Record (MSR) image files.
These files are written by Imspector software to store image and metadata
from microscopy experiments.

:Author: `Christoph Gohlke <https://www.cgohlke.com>`_
:License: BSD-3-Clause
:Version: 2026.2.20

Quickstart
----------

Install the obffile package and all dependencies from the
`Python Package Index <https://pypi.org/project/obffile/>`_::

    python -m pip install -U obffile[all]

See `Examples`_ for using the programming interface.

Source code and support are available on
`GitHub <https://github.com/cgohlke/obffile>`_.

Requirements
------------

This revision was tested with the following requirements and dependencies
(other versions may work):

- `CPython <https://www.python.org>`_ 3.11.9, 3.12.10, 3.13.12, 3.14.3 64-bit
- `NumPy <https://pypi.org/project/numpy>`_ 2.4.2
- `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.2.16 (optional)

Revisions
---------

2026.2.20

- Initial alpha release.
- …

Notes
-----

`Imspector <https://imspectordocs.readthedocs.io>`_ is a software platform for
super-resolution and confocal microscopy developed by Abberior Instruments.

This library is in its early stages of development. It is not feature-complete.
Large, backwards-incompatible changes may occur between revisions.

Specifically, the following features are not supported:
writing or modifying OBF/MSR files, non-OBF based MSR files, reading
MSR-specific non-image data (window positions, hardware configuration),
and compression types other than zlib.

The library has been tested with a limited number of files only.

The Imspector image file formats are documented at
https://imspectordocs.readthedocs.io/en/latest/fileformat.html.

Other implementations for reading Imspector image files are
`msr-reader <https://github.com/hoerlteam/msr-reader>`_,
`obf_support.py <https://github.com/biosciflo/VISION>`_, and
`bio-formats <https://github.com/ome/bioformats>`_.

Examples
--------

Read an image stack and metadata from a OBF file:

>>> with ObfFile('tests/data/Test.obf') as obf:
...     assert obf.header.metadata['ome_xml'].startswith('<?xml')
...     for stack in obf.stacks:
...         _ = stack.name, stack.dims, stack.shape, stack.dtype
...     obf.stacks[0].asxarray()
...
<xarray.DataArray 'Abberior STAR RED.Confocal' (T: 18, Z: 2, Y: 339, X: 381)...
array([[[[0, 0, 0, ..., 3, 3, 3],
         [0, 0, 0, ..., 4, 3, 3],
         ...,
         [0, 0, 0, ..., 0, 0, 0],
         [0, 0, 0, ..., 0, 0, 0]]]], shape=(18, 2, 339, 381), dtype=int16)
Coordinates:
    * T        (T) float64 144B 0.0 0.0 0.0 0.0 0.0 0.0 ...
    * Z        (Z) float64 16B 1.25e-07 3.75e-07
    * Y        (Y) float64 3kB 0.0 2e-07 4e-07 ...
    * X        (X) float64 3kB 0.0 2.002e-07 4.003e-07 ...
...

View the image stack and metadata in a OBF file from the console::

    $ python -m obffile tests/data/Test.obf