sdtfile¶

Read Becker & Hickl SDT files.

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. Currently only the “Setup & Data”, “DLL Data”, and “FCS Data” formats are supported.

Becker & Hickl GmbH is a manufacturer of equipment for photon counting.

Author:: Christoph Gohlke
License:: BSD-3-Clause
Version:: 2026.2.8
DOI:: 10.5281/zenodo.10125608

Quickstart¶

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

python -m pip install -U sdtfile

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.11.9, 3.12.10, 3.13.12, 3.14.3 64-bit
NumPy 2.4.2

Revisions¶

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

Support Python 3.14.

2025.3.25

Fix shape of data with routing channels.
Drop support for Python 3.9, support Python 3.13.

2024.12.6

Fix read MeasureInfo fields as scalars (breaking).
Update some structure field names with BH reference (breaking).
Parse some SetupBlock binary structures (#7).
Include more information in str(SdtFile).
Add subtype to FileRevision.

2024.11.24

…

Refer to the CHANGES file for older revisions.

References¶

W Becker. The bh TCSPC Handbook. 9th Edition. Becker & Hickl GmbH 2021. pp 879.
SPC_data_file_structure.h header file. Part of the Becker & Hickl SPCM software installation.

Examples¶

Read image and metadata from a “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
>>> len(sdt.data)
1
>>> sdt.data[0].shape
(128, 128, 256)
>>> sdt.times[0].shape
(256,)

Read data and metadata from a “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

Read image data from a “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,)

License¶

Copyright (c) 2007-2026, Christoph Gohlke
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

sdtfile module¶

sdtfile.__version__ = '2026.2.8'¶: Sdtfile version string.

class sdtfile.BlockNo(value, /)¶

Bases: object

BLOCK_HEADER.lblock_no field.

Parameters:: value (int) – Value of BLOCK_HEADER.lblock_no.

__init__(value, /)¶

Parameters:: value (int)
Return type:: None

data: int¶: Data.

module: int¶: Module.

__repr__()¶

Return repr(self).

Return type:: str

class sdtfile.BlockType(value, /)¶

Bases: object

BLOCK_HEADER.block_type field.

Parameters:: value (int) – Value of BLOCK_HEADER.block_type.

__init__(value, /)¶

Parameters:: value (int)
Return type:: None

mode: str¶: BLOCK_CREATION.

contents: str¶: BLOCK_CONTENT.

dtype: numpy.dtype[Any]¶: BLOCK_DTYPE.

compress: bool¶: Data is compressed.

__repr__()¶

Return repr(self).

Return type:: str

__str__()¶

Return str(self).

Return type:: str

class sdtfile.FileInfo(value, /)¶

Bases: str

File info string and attributes.

Parameters:: value (str) – File content from FILE_HEADER info_offs and info_length.

id: str¶: Identification.

__init__(value, /)¶

Parameters:: value (str)
Return type:: None

__weakref__¶: list of weak references to the object

class sdtfile.FileRevision(value, /)¶

Bases: object

FILE_HEADER.revision fields.

Parameters:: value (int) – Value of FILE_HEADER.revision.

__init__(value, /)¶

Parameters:: value (int)
Return type:: None

revision: int¶: Software revision.

module: str¶: BH module type.

subtype: str¶: BH module subtype.

__repr__()¶

Return repr(self).

Return type:: str

final class sdtfile.SdtFile(file, /, *, mode=None)¶

Bases: BinaryFile

Becker & Hickl SDT file.

Parameters:

arg – File name or open file.
file (str | os.PathLike[str] | IO[bytes])
mode (Literal['r', 'r+'] | None)

__init__(file, /, *, mode=None)¶

Parameters:

file (str | os.PathLike[str] | IO[bytes])
mode (Literal['r', 'r+'] | None)

Return type:

None

header: numpy.recarray[Any, Any]¶: File header of type FILE_HEADER.

info: FileInfo¶: File info string and attributes.

setup: SetupBlock | None¶: Setup block ascii and binary data.

measure_info: list[numpy.recarray[Any, Any]]¶: Measurement description blocks of type MEASURE_INFO.

times: list[NDArray[Any]]¶: Time axes for each data set.

data: list[NDArray[Any]]¶: Photon counts at each curve point.

block_headers: list[numpy.recarray[Any, Any]]¶: Data block headers of type BLOCK_HEADER.

block_measure_info(block, /)¶

Return measure_info record for data block.

Parameters:: block (int) – Block index.
Raises:: IndexError – If block index is out of range.
Return type:: numpy.recarray[Any, Any]

__repr__()¶

Return repr(self).

Return type:: str

__str__()¶

Return str(self).

Return type:: str

class sdtfile.SetupBlock(value, /)¶

Bases: object

Setup block ascii and binary data.

Parameters:: value (bytes) – File content from FILE_HEADER setup_offs and setup_length.

__init__(value, /)¶

Parameters:: value (bytes)
Return type:: None

binary: bytes¶: Binary data.

ascii: str¶: ASCII data.

bh_bin_hdr: numpy.recarray[Any, Any] | None¶: BHBinHdr structure.

spc_bin_hdr: numpy.recarray[Any, Any] | None¶: SPCBinHdr structure.

__weakref__¶: list of weak references to the object

property spc_bin_hdr_ext: numpy.recarray[Any, Any] | None¶: SPCBinHdrExt structure.

property gvd_param: numpy.recarray[Any, Any] | None¶: GVDParam structure.

__repr__()¶

Return repr(self).

Return type:: str

__str__()¶

Return str(self).

Return type:: str

sdtfile¶

Quickstart¶

Requirements¶

Revisions¶

References¶

Examples¶

License¶

sdtfile module¶

Documentation

Table of Contents

Related Topics