Quickstart

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

python -m pip install -U "ptufile[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

• Xarray 2026.9.0 (recommended)

• Matplotlib 3.11.2 (optional)

• Tifffile 2026.10.15 (optional)

• Numcodecs 0.17.1 (optional)

• Python-dateutil 2.9.0 (optional)

• Cython 3.3.1 (build)

Revisions

2026.11.5

• Fix undefined enum values overwriting UNKNOWN member value (breaking).

• Fix length of time axis of T3 point measurements (breaking).

• Fix PtuFile.decode_image silently accepting positional integer (breaking).

• Fix decoding bidirectional images with binned Y axis.

• Fix decoding line scans with unpaired line stop markers.

• Fix PhuFile.histograms with negative index or asxarray.

• Fix PtuFile.decode_histogram of T2 records without channel trimming.

• Fix parsing indexed tags that follow scalar tags or arrive out of order.

2026.10.16

• Support z-stack images in PTU reader and writer (#5).

• Support sparse tag indices (#5, breaking).

• Replace PtuWriter has_frames with dims parameter (breaking).

• Add volume_time and global_volume_time properties to PtuFile.

• Add plane parameter to PtuFile.decode_image and imread.

• Generalize decode_t3_image to 6-dimensional data.

2026.8.8

• Add PQOVER file type.

2026.6.6

• Remove memmap parameter from PtuFile.read_records (breaking).

• Return copy of records from PtuFile.read_records by default (breaking).

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

• Add option to memory-map PTU files.

• Drop support for numpy 2.0 (SPEC0).

• Support Python 3.15.

2026.3.21

• Add bounds checking to encode_t3_image function.

• Use format-dispatch in hot decode loops to allow compiler inlining.

• Build wheels on Windows with LLVM (30% faster decoding than MSVC).

• Drop support for Python 3.11.

2026.2.6

• …

Refer to the CHANGES file for older revisions.

Notes

PicoQuant GmbH is a manufacturer of photonic components and instruments.

The PicoQuant unified file formats are documented at the PicoQuant-Time-Tagged-File-Format-Demos.

All PicoQuant unified tagged formats use the same basic layout: a file header followed by typed tags and an optional data block. PTU is the main container for TTTR event streams, whereas related formats store histograms, instrument settings, analysis results, or other auxiliary data.

The following features are currently not implemented due to the lack of test files or documentation: PT2 and PT3 files, decoding images from T2 and SPQR formats, bidirectional per frame, and deprecated image reconstruction.

Compatibility with PTU files written by non-PicoQuant software (for example, Leica LAS X or Abberior Imspector) is limited, as is decoding line, bidirectional, and sinusoidal scanning.

Other modules for reading or writing PicoQuant files are Read_PTU.py, readPTU, readPTU_FLIM, fastFLIM, PyPTU, PTU_Reader, PTU_Writer, FlimReader, tangy, tttrlib, picoquantio, ptuparser, phconvert, trattoria (wrapper of trattoria-core, tttr-toolbox), PAM, FLOPA, FLIMKit, and napari-flim-phasor-plotter.

Examples

Import functions and classes used in these examples:

>>> from ptufile import PqFile, PtuFile, imwrite, imread

Read properties and tags from any type of PicoQuant unified tagged file:

>>> pq = PqFile('tests/data/Settings.pfs')
>>> pq.type
<PqFileType.PFS: ...>
>>> pq.guid
UUID('86d428e2-cb0b-4964-996c-04456ba6be7b')
>>> pq.tags
{...'CreatorSW_Name': 'SymPhoTime 64', 'CreatorSW_Version': '2.1'...}
>>> pq.close()

Read metadata from a PicoQuant PTU FLIM file:

>>> ptu = PtuFile('tests/data/FLIM.ptu')
>>> ptu.type
<PqFileType.PTU: ...>
>>> ptu.record_type
<PtuRecordType.PicoHarpT3: 66307>
>>> ptu.measurement_mode
<PtuMeasurementMode.T3: 3>
>>> ptu.measurement_submode
<PtuMeasurementSubMode.IMAGE: 3>

Decode TTTR records from the PTU file to numpy.recarray:

>>> decoded = ptu.decode_records()
>>> decoded.dtype
dtype([('time', '<u8'), ('dtime', '<i2'), ('channel', 'i1'), ('marker', 'u1')])

Get global times of frame changes from markers:

>>> decoded['time'][(decoded['marker'] & ptu.frame_change_mask) > 0]
array([1571185680], dtype=uint64)

Decode TTTR records to overall delay-time histograms per channel:

>>> ptu.decode_histogram(dtype='uint8')
array([[ 5,  7,  7, ..., 10,  9,  2]], shape=(2, 3126), dtype=uint8)

Get information about the FLIM image histogram in the PTU file:

>>> ptu.shape
(1, 256, 256, 2, 3126)
>>> ptu.dims
('T', 'Y', 'X', 'C', 'H')
>>> ptu.coords
{'T': ..., 'Y': ..., 'X': ..., 'H': ...}
>>> ptu.dtype
dtype('uint16')
>>> ptu.active_channels
(0, 1)

Decode parts of the image histogram to numpy.ndarray using slice notation. Slice step sizes define binning, -1 being used to integrate along axis:

>>> ptu[:, ..., 0, ::-1]
array([[[103, ..., 38],
              ...
        [ 47, ..., 30]]],
      shape=(1, 256, 256), dtype=uint16)

Alternatively, decode the first channel and integrate all histogram bins into a xarray.DataArray, keeping reduced axes:

>>> ptu.decode_image(channel=0, dtime=-1, asxarray=True)
<xarray.DataArray (T: 1, Y: 256, X: 256, C: 1, H: 1)> ...
array([[[[[103]],
           ...
         [[ 30]]]]], shape=(1, 256, 256, 1, 1), dtype=uint16)
Coordinates:
  * T        (T) float64... 0.05625
  * Y        (Y) float64... -0.0001304 ... 0.0001294
  * X        (X) float64... -0.0001304 ... 0.0001294
  * C        (C) uint8... 0
  * H        (H) float64... 0.0
Attributes...
    name:                     FLIM.ptu
...

Write the TCSPC histogram and metadata to a PicoHarpT3 image mode PTU file:

>>> imwrite(
...     '_test.ptu',
...     ptu[:],
...     ptu.global_resolution,
...     ptu.tcspc_resolution,
...     # optional metadata
...     pixel_time=ptu.pixel_time,
...     record_type=PtuRecordType.PicoHarpT3,
...     comment='Written by ptufile.py',
...     tags={'File_RawData_GUID': [ptu.guid]},
... )

Read back the TCSPC histogram from the file:

>>> tcspc_histogram = imread('_test.ptu')
>>> import numpy
>>> numpy.array_equal(tcspc_histogram, ptu[:])
True

Close the file handle:

>>> ptu.close()

Preview the image and metadata in a PTU file from the console:

python -m ptufile tests/data/FLIM.ptu