Metadata-Version: 2.4
Name: obffile
Version: 2026.6.28
Summary: Read Imspector object binary format files (OBF and MSR)
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/obffile/issues
Project-URL: Source Code, https://github.com/cgohlke/obffile
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 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.6.28
:DOI: `10.5281/zenodo.18706395 <https://doi.org/10.5281/zenodo.18706395>`_

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.12.10, 3.13.14, 3.14.5, 3.15.0b3 64-bit
- `NumPy <https://pypi.org/project/numpy>`_ 2.5.0
- `Xarray <https://pypi.org/project/xarray>`_ 2026.4.0 (recommended)
- `Matplotlib <https://pypi.org/project/matplotlib/>`_ 3.11.0 (optional)
- `Tifffile <https://pypi.org/project/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 <https://imspectordocs.readthedocs.io>`_ 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 <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 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
