Sdtfile is a Python library to read SDT files produced by Becker & Hickl SPCM software. SDT files contain time correlated single photon counting instrumentation parameters and measurement data.
Becker & Hickl GmbH is a manufacturer of equipment for photon counting.
| Author: | Christoph Gohlke |
|---|---|
| License: | BSD-3-Clause |
| Version: | 2026.7.30 |
| DOI: | 10.5281/zenodo.10125608 |
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.
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)
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.
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.
- 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/
- 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/
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