pyfli.io.flim_decay_cube#
flim_decay_cube.py#
Build a TCSPC decay-cube tensor from a Leica LIF file that contains LifFlimImage data encoded with the patent-pending Leica “reduced Time Tagged” compression scheme (US20230344447A1 / US12278654B2).
Dimensions explained#
M - mosaic / tile index (number of tiles or time-lapse frames) Y - image height (pixels) X - image width (pixels) H - TCSPC histogram bin index (number_bins_in_period ≈ laser-period / clock-period)
The resulting decay cube has shape (M, Y, X, H) with dtype uint16. Each voxel [m, y, x, h] counts the photons that arrived in bin h of the TCSPC histogram for pixel (y, x) of mosaic tile / frame m.
Compression format (from patent)#
The memory block is a standard zlib/Deflate stream (RFC 1950 / 1951). Inside, photon data are stored as a sequence of 16-bit “reduced Time Tagged” records, one record-stream per pixel, organised as follows (Fig. 2b / Fig. 5 of US20230344447A1):
Record type Bit layout (16 bits, little-endian) —————- ————————————————— Class marker [bit15=0, bits14-11=detector(4), bit10=single_photon] Photon record [bits6-0=arrival_time_low(7), bit7=has_extension] Extension record [bits12-7=arrival_time_high(6)] – appended after
a photon record when bit7 of that record is set
Pixel end marker [bit15=1, bits9-0=run_length(skip empty pixels)] Line end marker [specific reserved bit pattern, marks end of scan line]
Within each group (pixel), records are sorted by arrival time and then delta-encoded: each record stores (current – previous) arrival time. Decoding therefore requires a cumulative sum (prefix-sum) within each group.
Usage#
from flim_decay_cube import build_decay_cube, plot_decay_cube import liffile
- with liffile.LifFile(‘example.lif’) as lif:
flim_img = lif.images[‘T23_005304_I1_2/FLIM’] # LifFlimImage cube = build_decay_cube(flim_img) # (M, Y, X, H) uint16
# Plot a single frame / pixel plot_decay_cube(cube, flim_img)
Functions
|
Return the raw uint16 record stream from the LifFlimImage memory block. |
|
Build decay cube. |
|
Sum the M (mosaic/frame) axis to get a single (Y, X, H) image. |
|
High-level entry point. |
|
Visualise the decay cube with four panels: |
|
Display a grid of all pre-computed FLIM parameter maps. |
|
Plot xyt. |
|
Read all Leica-computed FLIM parameter maps for a given image series. |
- build_decay_cube(flim_image, *, channel=0, dtype=np.uint16)[source]#
Build decay cube.
- Parameters:
flim_image (
'lf.LifFlimImage') – Leica LifFlimImage object containing raw FLIM data.channel (
int) – Detector channel index to read or decode.dtype (
np.dtype) – NumPy dtype used for output accumulation.
- Returns:
Decay cube assembled from time-gated image data.
- Return type:
np.ndarray
- read_derived_images(lif_file, series_name)[source]#
Read all Leica-computed FLIM parameter maps for a given image series.
These are stored as ordinary LifImage objects (not LifFlimImage) so they are always accessible without touching the patent-protected raw stream.
- Parameters:
lif_file (
LifFile) – Open LifFile object.series_name (
str) – Base name of the image series, e.g.'T23_005304_I1_2'.
- Returns:
dict mapping short name → numpy array (shape M,Y,X per image).Keys include (
'Intensity','FastFlim','StdDev','PhasorReal',)'PhasorImaginary','PhasorIntensity','PhasorMask','DecayTime','Amplitude','TailOffset','IRFBackground','IRFShift','FlimIntensity','AmplitudeSum','IntensitySum','MeanPhotonArrivalTime','MeanDecayTime','ChiSquare'
- Return type:
- plot_decay_cube(cube, flim_image=None, *, frame=0, pixel_yx=None, save_path=None)[source]#
- Visualise the decay cube with four panels:
Intensity image (sum over H axis)
Mean arrival-time image (weighted mean over H)
Summed decay curve (sum over all pixels in the frame)
Single-pixel decay curve (central pixel or specified pixel)
- Parameters:
cube (
np.ndarray,shape (M,Y,X,H))flim_image (
LifFlimImage, optional) – Used to recover physical time axis (ns).frame (
int) – Which mosaic tile / time frame to display.pixel_yx (
(y,x) tuple, optional) – Pixel for the single-pixel decay panel. Defaults to image centre.save_path (
str, optional) – If given, save figure to this path instead of showing interactively.
- Return type:
- plot_derived_images(derived, series_name='', frame=0, save_path=None)[source]#
Display a grid of all pre-computed FLIM parameter maps.
- load_flim_data(lif_path, series_name=None, *, channel=0, use_derived_fallback=True)[source]#
High-level entry point.
Opens the LIF file.
Locates the LifFlimImage for series_name (or the first one found).
Attempts to decode the raw photon-tag stream into a (M,Y,X,H) cube.
If decoding fails (format not yet supported), reads the pre-computed derived FLIM maps instead.
- collapse_to_xyt(cube)[source]#
Sum the M (mosaic/frame) axis to get a single (Y, X, H) image.
- Parameters:
cube (
np.ndarray,shape (M,Y,X,H))- Returns:
xyt
- Return type:
np.ndarray,shape (Y,X,H) — dtype promotedtouint32toavoid overflow
- plot_xyt(xyt, tcspc_resolution_s=97e-12, *, pixel_yx=None, cmap_intensity='hot', cmap_lifetime='RdYlGn_r', save_path=None)[source]#
Plot xyt.
- Parameters:
xyt (
np.ndarray) – Decay cube with shape (Y, X, T).tcspc_resolution_s (
float) – TCSPC bin width in seconds.pixel_yx (
tuple[int,int] | None) – Selected pixel as a (row, column) coordinate.cmap_intensity (
str) – Colormap used for intensity images.cmap_lifetime (
str) – Colormap used for lifetime or mean-arrival-time images.save_path (
str | None) – Path where the generated figure or array is saved.
- Returns:
No object is returned; the function plot xyt.
- Return type: