obffile 2026.6.28

Quickstart

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

python -m pip install -U obffile[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.5, 3.15.0b3 64-bit

• NumPy 2.5.0

• Xarray 2026.4.0 (recommended)

• Matplotlib 3.11.0 (optional)

• Tifffile 2026.6.1 (optional)

Revisions

2026.6.28

• Add option to memory-map OBF files.

• Support Python 3.15.

• Drop support for Python 3.11 and numpy 2.0 (SPEC0).

2026.2.20

• Initial alpha release.

• …

Notes

This library is in its early stages of development. Large, backwards-incompatible changes may occur between revisions.

Imspector is a software platform for super-resolution and confocal microscopy developed by Abberior Instruments.

The Imspector image file formats (OBF and MSR) are documented at https://imspectordocs.readthedocs.io/en/latest/fileformat.html.

OBF is a little-endian binary format storing named, multidimensional image stacks with metadata. Each file has a magic header (OMAS_BF\n\xff\xff), a format version, an XML description, and a linked list of stack records. Stack data may be uncompressed or zlib-compressed. MSR files embed OBF and add Imspector-specific data such as window layout and hardware configuration. The format is designed for forward and backward compatibility.

This library is not feature-complete. Unsupported features currently include 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.

Other implementations for reading Imspector image files are msr-reader, obf_support.py, and bio-formats.

Examples

Read an image stack and metadata from an 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 an OBF file from the console:

$ python -m obffile tests/data/Test.obf