Quickstart

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

python -m pip install -U obffile[all]

See Examples and Documentation 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.16, 3.14.8, 3.15.0 64-bit

• Numpy 2.5.4

• Xarray 2026.9.0 (recommended)

• Matplotlib 3.11.2 (optional)

• Tifffile 2026.10.15 (optional)

Revisions

2026.10.20

• Preserve stacks with duplicate names (#1).

2026.10.19

• Return writable stack arrays (memory-mapped views only in ‘r+’ mode).

• Return zero-copy view of uncompressed, unchunked memory-mapped stacks.

• Read and decompress stack data directly into output array.

• Read flush and chunk position tables in one block.

• Raise ObfFileError on unsupported compression types.

• Raise ObfFileError on cyclic stack links.

• Fix LICENSE file.

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

Import functions and classes used in these examples:

>>> from obffile import ObfFile

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