sdtfile 2026.7.30

Quickstart

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

python -m pip install -U sdtfile[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.6, 3.15.0b4 64-bit

• Numpy 2.5.1

• Imagecodecs 2026.6.26 (optional for LZ4 compressed data blocks)

• Lz4 4.4.5 (optional alternative to imagecodecs for LZ4 compressed data blocks)

Revisions

2026.7.30

• Add sdtwrite function.

• Support SET files without measurement description and data blocks.

2026.7.17

• Fix decompression of LZ4-compressed data blocks.

• Add fallback to lz4 module if imagecodecs is not installed.

2026.7.12

• Fix BlockNo attribute names (breaking).

• Try power-of-two padded image shapes when block/adc_re > image_y * image_x.

• Support LZ4 compressed and larger than 4 GB data blocks (not tested).

• Update MeasureInfoExt structure with MeasStopInfoExt and MWL fields.

• Use BinaryFile for file I/O.

• Add simple CLI to preview data and metadata in SDT files.

2026.6.29

• Fix reading SDT files with truncated embedded ZIP files (#8).

2026.6.6

• Fix potential file handle leak in SdtFile init.

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

• Add option to memory-map SDT files.

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

• Support Python 3.15.

2026.2.8

• Derive SdtFile from BinaryFile (breaking).

• Rename MEASURE_INFO.MeasHISTInfo to HISTInfo to match C struct (breaking).

• Revise shaping of FCS_BLOCK data (breaking).

• Fix code review issues.

2026.1.14

• Improve code quality.

2025.12.12

• Add new SPC modules and MEASURE_INFO_EXT fields.

• Drop support for Python 3.10.

2025.5.10

• …

Refer to the CHANGES file for older revisions.

Notes

SDT files begin with a FILE_HEADER containing byte offsets to four sections: an ASCII info block, a setup block (ASCII and/or binary instrument parameters), one or more MEASURE_INFO records (CFD/TAC/ADC settings, scan geometry, timestamps, module identity), and one or more data blocks each preceded by a BLOCK_HEADER encoding the creation mode, content type (FLIM image, FCS, MCS, etc.), and element dtype. The data blocks are photon-count histograms shaped from MEASURE_INFO fields, typically (image_y, image_x, adc_re) of type uint16/uint32, and may be ZIP or LZ4-compressed.

Currently “Flow Data” are not supported.

References

1. W Becker. The bh TCSPC Handbook. 9th Edition. Becker & Hickl GmbH 2021. pp 879. https://www.becker-hickl.com/literature/documents/flim/the-bh-tcspc-handbook-9th-edition-2021/

2. SPC_data_file_structure.h header file. Part of the Becker & Hickl SPCM software installation. https://www.becker-hickl.com/products/spcm-data-acquisition-software/

Examples

Read image and metadata from an “SPC Setup & Data File”:

>>> sdt = SdtFile('image.sdt')
>>> int(sdt.header.revision)
588
>>> sdt.info.id[1:-1]
'SPC Setup & Data File'
>>> int(sdt.measure_info[0].scan_x)
128
>>> float(sdt.measure_info[0].tac_r)  # doctest: +NUMBER
5.0e-08
>>> len(sdt.data)
1
>>> image = sdt.data[0]
>>> image.shape
(128, 128, 256)
>>> sdt.times[0].shape
(256,)
>>> sdt.close()

Write image and select metadata to an SDT file:

>>> sdtwrite('image_out.sdt', image, tac_r=5e-8, compress=True)

Read data and metadata from an “SPC Setup & Data File” with multiple data sets:

>>> sdt = SdtFile('fluorescein.sdt')
>>> len(sdt.data)
4
>>> sdt.data[3].shape
(1, 1024)
>>> sdt.times[3].shape
(1024,)
>>> int(sdt.setup.bh_bin_hdr['soft_rev'])
850
>>> sdt.close()

Read image data from an “SPC FCS Data File” as numpy array:

>>> sdt = SdtFile('fcs.sdt')
>>> sdt.info.id[1:-1]
'SPC FCS Data File'
>>> len(sdt.data)
1
>>> sdt.data[0].shape
(512, 512, 256)
>>> sdt.times[0].shape
(256,)
>>> sdt.close()

View the image and metadata in an SDT file from the console:

$ python -m sdtfile image.sdt