ISS TDFlim Reader

🔬 A napari plugin to read and write ISS TD-FLIM acquisition files (.iss-tdflim).

✨ Features

📂 Reader

Opens .iss-tdflim files directly in napari.
Each file is a ZIP archive produced by the ISS ALBA FLIM system and contains:

• dataProps/Core.xml — acquisition metadata (pixel size, TAC range, channel IDs, …)
• data/PrimaryDecayData.bin — raw photon-count decay histograms

Two image layers are added per channel:

Spatial calibration (µm/pixel) and TAC time axis (ns/bin) are embedded as napari scale and axis_labels so physical units are always correct.

💾 Writer

Saves any napari Image layer (including those loaded by the reader) to ImageJ-hyperstack TIFF files.

• ✅ Supports both intensity (H, W) and FLIM decay (T, H, W) layers
• 🗜️ Lossless zlib compression (requires imagecodecs)
• 📐 Spatial calibration (XResolution/YResolution tags + unit) preserved for Fiji/ImageJ
• ⏱️ Time-axis interval (finterval) embedded for FLIM cubes
• 🏷️ Full acquisition metadata (channel IDs, ADC resolution, TAC range, …) stored as JSON in the TIFF Info field — visible in Fiji via Image › Info… and recoverable in Python via:

  import json, tifffile
  with tifffile.TiffFile('my_file.tif') as tf:
      meta = json.loads(tf.imagej_metadata['Info'])
  
  

• 🔄 Non-ImageJ-compatible integer dtypes (e.g. uint32, uint64) are automatically cast to float32

🚀 Installation

Install from PyPI:

pip install napari-iss-tdflim-reader

To install with napari and all optional dependencies (including Qt backend and compression support):

pip install "napari-iss-tdflim-reader[all]"

Install the latest development version directly from GitHub:

pip install git+https://github.com/DBP008/napari-iss-tdflim-reader.git

🛠️ Usage

Reading

Drag and drop an .iss-tdflim file onto the napari window, or open it via File › Open File(s)….
The plugin is selected automatically based on the file extension.

Writing

Select one or more Image layers in the napari layer list, then use File › Save Selected Layer(s)… and choose a .tif / .tiff destination.
When saving multiple layers, each is written to a separate file with a _0, _1, … suffix.

🤝 Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

📄 License

Distributed under the terms of the Apache Software License 2.0 license.
napari-iss-tdflim-reader is free and open source software.

🐛 Issues

If you encounter any problems, please file an issue along with a detailed description.