Quickstart

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

python -m pip install -U sdtfile[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.17, 3.14.10, 3.15.2 64-bit

• Numpy 2.5.4

• Imagecodecs 2026.10.10 (optional for LZ4 compressed data blocks)

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

Revisions

2026.11.6

• Fix reading files with more than 32767 data blocks.

• Fix BlockNo.module bit mask and repr (breaking).

• Pad truncated uncompressed data blocks with zeros.

• Return writable arrays for compressed data blocks.

• Read compressed data block to end of file if next_block_offs is invalid.

• Raise ValueError for invalid meas_desc_block_no, info, and setup blocks.

• Sanitize contents and validate adc_re in sdtwrite.

2026.10.14

• Limit decompressed data block size to block_length.

• Log warnings and recover data for unexpected block sizes.

• Raise ValueError for invalid meas_mode in sdtwrite.

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

• …

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

Import functions and classes used in these examples:

>>> from sdtfile import SdtFile, sdtwrite

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'
>>> mi = sdt.measure_info[0]
>>> float(mi.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=mi.tac_r,  # required
...     tac_g=mi.tac_g,
...     col_t=mi.col_t,
...     pix_time=mi.pix_time,
...     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