Metadata-Version: 2.4
Name: napari-iss-tdflim-reader
Version: 0.2.0
Summary: A simple reader for .iss-tdfilm files
Author: Davide Panzeri
License-Expression: Apache-2.0
Project-URL: Bug Tracker, https://github.com/DBP008/napari-iss-tdflim-reader/issues
Project-URL: Documentation, https://github.com/DBP008/napari-iss-tdflim-reader#README.md
Project-URL: Source Code, https://github.com/DBP008/napari-iss-tdflim-reader
Project-URL: User Support, https://github.com/DBP008/napari-iss-tdflim-reader/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: tifffile
Provides-Extra: all
Requires-Dist: napari[all]; extra == "all"
Requires-Dist: imagecodecs; extra == "all"
Dynamic: license-file

# napari-iss-tdflim-reader

[![License Apache Software License 2.0](https://img.shields.io/pypi/l/napari-iss-tdflim-reader.svg?color=green)](https://github.com/DBP008/napari-iss-tdflim-reader/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/napari-iss-tdflim-reader.svg?color=green)](https://pypi.org/project/napari-iss-tdflim-reader)
[![Python Version](https://img.shields.io/pypi/pyversions/napari-iss-tdflim-reader.svg?color=green)](https://python.org)
[![tests](https://github.com/DBP008/napari-iss-tdflim-reader/workflows/tests/badge.svg)](https://github.com/DBP008/napari-iss-tdflim-reader/actions)
[![codecov](https://codecov.io/gh/DBP008/napari-iss-tdflim-reader/branch/main/graph/badge.svg)](https://codecov.io/gh/DBP008/napari-iss-tdflim-reader)
[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-iss-tdflim-reader)](https://napari-hub.org/plugins/napari-iss-tdflim-reader)
[![npe2](https://img.shields.io/badge/plugin-npe2-blue?link=https://napari.org/stable/plugins/index.html)](https://napari.org/stable/plugins/index.html)
[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-purple.json)](https://github.com/copier-org/copier)

> 🔬 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**:

| Layer | Shape | Description |
|---|---|---|
| `<stem>_intensity_Ch<id>` | `(H, W)` | Total photon counts (sum along TAC axis) |
| `<stem>_flim_Ch<id>` | `(T, H, W)` | Full FLIM decay cube — use the time slider to scrub through TAC bins |

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:
  ```python
  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:

```bash
pip install napari-iss-tdflim-reader
```

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

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

Install the latest development version directly from GitHub:

```bash
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.

[napari]: https://github.com/napari/napari
[copier]: https://copier.readthedocs.io/en/stable/
[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0
[napari-plugin-template]: https://github.com/napari/napari-plugin-template
[file an issue]: https://github.com/DBP008/napari-iss-tdflim-reader/issues
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/

