fbdfile 2026.8.30

Quickstart

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

python -m pip install -U fbdfile[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.15, 3.14.7, 3.15.0rc 64-bit

• Numpy 2.5.2

• Xarray 2026.7.0 (optional)

• Matplotlib 3.11.1 (optional)

• Tifffile 2026.8.23 (optional)

• Click 8.5.0 (optional, for command line apps)

• Cython 3.2.9 (build)

Revisions

2026.8.30

• Do not refine user-provided laser_factor (breaking; see PhasorPy issue 372).

• Add FbdFile.asxarray method (requires xarray).

• Add imread convenience function.

2026.8.8

• Update BinaryFile class.

2026.6.6

• Fix potential file handle leak in FbdFile init.

• Fix pixel_dwell_time when scanner_line_start > 0.

• Add options for memory-mapping and locked reading to BinaryFile.

• Add option to memory-map FBD files.

• Drop support for numpy 2.0 (SPEC0).

• Support Python 3.15.

2026.3.20

• Frames and asimage methods always refine laser_factor by default (breaking).

• Add tri-state refine option to frames and asimage methods.

• Add refine_settings method to refine pixel_dwell_time and laser_factor.

• Add more decoder settings (not tested).

• Fix decode to read all bytes from streams and fix skip/count guard.

• Fix cluster-to-frame-marker mapping in frames fallback path.

• Fix from_fbs header detection to use fbf_parse_header.

• Fix decoder_settings to not swallow errors from valid decoders.

• Use fbd_decode return value to trim markers array.

• Drop support for Python 3.11.

2026.2.6

• Fix code review issues.

2026.1.14

• Improve code quality.

2025.12.12

• Add attrs property to FbdFile.

• Improve code quality.

2025.11.8

• Allow to override FbdFile decoder, firmware, and settings.

• Always try to load settings from .fbs.xml file.

• Factor out BinaryFile base class.

• Derive FbdFileError from ValueError.

• Build ABI3 wheels.

2025.9.18

• Fix reading FBF and FBS files from streams.

2025.9.17

• Make frame_markers a numpy array.

• Add options to specify number of OpenMP threads.

2025.9.16

• Initial alpha release based on lfdfiles 2025.7.31.

Notes

The API is not stable yet and might change between revisions.

The latest Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 is required on Windows.

The FLIMbox formats are undocumented and may vary between software and firmware revisions. This implementation is based on reverse engineering existing files. No guarantee can be made as to the correctness of code and documentation.

FBD (FLIMbox data) files contain a raw stream of encoded 16-bit or 32-bit words produced by the FLIMbox FPGA. Some newer files contain embedded firmware and acquisition headers before the encoded data stream. Legacy-format files have no header; acquisition settings are inferred from a 4-character tag in the filename that encodes frame size, pixel dwell time, FLIMbox configuration (time windows, channels, and harmonics), and scanner type.

FBF (FLIMbox firmware) files contain a NULL-terminated ASCII string of slash-separated key=value pairs followed by the binary FPGA firmware. They may be embedded at the start of an FBD file or distributed as standalone files.

FBS.XML files are XML settings files written by ISS VistaVision that may accompany FBD files and provide acquisition parameters such as frame size, pixel dwell time, scanner, and laser settings.

SimFCS, a.k.a. Globals for Images, is software for fluorescence image acquisition, analysis, and simulation, developed by Enrico Gratton at UCI.

VistaVision is commercial software for instrument control, data acquisition, and data processing by ISS Inc (Champaign, IL).

Examples

Import functions and classes used in these examples:

>>> from fbdfile import FbdFile

Read a FLIM lifetime image and metadata from an FBD file:

>>> with FbdFile(
...     'tests/data/flimbox_data$CBCO.fbd', pixel_dwell_time=0.937
... ) as fbd:
...     bins, times, markers = fbd.decode()
...     image = fbd.asimage()
>>> image.shape
(1, 2, 256, 256, 64)
>>> print(bins[0, :2], times[:2], markers[:2])
[50 58] [ 0 32] [1944097 2024815]
>>> import numpy
>>> hist = [numpy.bincount(b[b >= 0]) for b in bins]
>>> int(hist[0].argmax())
53

View the histogram and metadata in a FLIMbox data file from the console:

$ python -m fbdfile tests/data/flimbox_data$CBCO.fbd