Metadata-Version: 2.4
Name: napari-flowreg-formats
Version: 0.1.0a1
Summary: napari reader and writer plugin for 2-photon microscopy formats (TIFF/ScanImage, HDF5, MAT, MDF)
Author-email: Philipp Flotho <Philipp.Flotho@uni-saarland.de>
License-Expression: MIT
Project-URL: Homepage, https://github.com/FlowRegSuite/napari-flowreg-formats
Project-URL: Source, https://github.com/FlowRegSuite/napari-flowreg-formats
Project-URL: Tracker, https://github.com/FlowRegSuite/napari-flowreg-formats/issues
Project-URL: Documentation, https://napari-flowreg-formats.readthedocs.io/
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pyflowreg>=0.1.0a9
Requires-Dist: flowreg3d>=0.1.0a1
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: h5py>=3.10
Requires-Dist: tifffile>=2024.9.0
Requires-Dist: dask[array]>=2023.5.0
Requires-Dist: qtpy
Provides-Extra: testing
Requires-Dist: pytest>=7.0; extra == "testing"
Requires-Dist: pytest-cov>=4.0; extra == "testing"
Requires-Dist: pytest-qt; extra == "testing"
Requires-Dist: npe2>=0.7; extra == "testing"
Requires-Dist: cloudpickle; extra == "testing"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "testing"
Requires-Dist: napari[pyqt6]; extra == "testing"
Provides-Extra: dev
Requires-Dist: napari[pyqt6]>=0.4.18; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx~=7.3; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: linkify-it-py; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Dynamic: license-file

[![PyPI - Version](https://img.shields.io/pypi/v/napari-flowreg-formats)](https://pypi.org/project/napari-flowreg-formats/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/napari-flowreg-formats)](https://pypi.org/project/napari-flowreg-formats/)
[![PyPI - License](https://img.shields.io/pypi/l/napari-flowreg-formats)](LICENSE.txt)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/napari-flowreg-formats)](https://pypistats.org/packages/napari-flowreg-formats)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/napari-flowreg-formats?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=all+time+downloads)](https://pepy.tech/projects/napari-flowreg-formats)[![Tests](https://github.com/FlowRegSuite/napari-flowreg-formats/actions/workflows/test.yml/badge.svg)](https://github.com/FlowRegSuite/napari-flowreg-formats/actions/workflows/test.yml)
[![Documentation Status](https://readthedocs.org/projects/napari-flowreg-formats/badge/?version=latest)](https://napari-flowreg-formats.readthedocs.io/en/latest/?badge=latest)

# <img src="https://raw.githubusercontent.com/FlowRegSuite/napari-flowreg-formats/HEAD/img/flowreglogo.png" alt="FlowReg logo" height="64"> napari-FlowReg-Formats

This repository contains the file format support for the Flow-Registration toolbox in napari. It reads and writes the microscopy formats used across the FlowRegSuite through the `pyflowreg` and `flowreg3d` I/O layers, so a recording that opens here opens identically in the motion correction pipeline.

**Everything works out of the box.** Drag a recording into napari and it opens: **TIFF** (including **ScanImage**, **OME-TIFF**, **ImageJ hyperstacks** and **BigTIFF**), **HDF5**, **MATLAB MAT** in both the classic and the **v7.3** container, and **Sutter MDF**. **MAT and HDF5 videos work in both 2D and 3D**, including multi-channel recordings, volumetric time series, and the MATLAB axis order that older Flow-Registration data is written in. The structure is detected from the file itself, so no configuration is needed for the common cases.

Recordings load lazily, so a volumetric stack larger than memory can be inspected frame by frame. An import dialog covers what automatic detection cannot settle on its own: 2D against 3D interpretation, axis order, which datasets are channels, and folding a flat ScanImage page sequence into `(T, Z, Y, X)` volumes.

The publication for the underlying toolbox can be found [here](https://doi.org/10.1002/jbio.202100330) and the project website with video results [here](https://www.snnu.uni-saarland.de/flow-registration/).

**[Read the Documentation](https://napari-flowreg-formats.readthedocs.io/)**

**Related projects**
- PyFlowReg: https://github.com/FlowRegSuite/pyflowreg
- flowreg3D: https://github.com/FlowRegSuite/flowreg3d
- napari motion correction plugin: https://github.com/FlowRegSuite/napari-flowreg
- Original Flow-Registration repo: https://github.com/FlowRegSuite/flow_registration
- ImageJ/Fiji plugin: https://github.com/FlowRegSuite/flow_registration_IJ

![Fig1](https://raw.githubusercontent.com/FlowRegSuite/napari-flowreg-formats/HEAD/img/bg.jpg)

## Installation via pip and conda

To install the plugin via conda, you can create a new environment and install `napari` along with the plugin:

    conda create -n flowreg -c conda-forge python=3.11
    conda activate flowreg

You can then install `napari-flowreg-formats` via [pip]:

    pip install napari[all] napari-flowreg-formats

or directly from the GitHub repository:

    pip install git+https://github.com/FlowRegSuite/napari-flowreg-formats.git

`napari` is not a runtime dependency of this package, following napari plugin practice, so install it alongside as shown above.

The plugin depends on `pyflowreg` and `flowreg3d`, which are currently published as pre-releases. The dependency specifiers name those pre-releases explicitly, so a plain `pip install` resolves them and no `--pre` flag is needed.

## Supported formats

| Family | Extensions | 2D | 3D | Lazy | Auto-detected |
|---|---|---|---|---|---|
| **TIFF** | `.tif` `.tiff` | **yes** | **yes** | **yes** | series axes, ImageJ hyperstack structure |
| **BigTIFF** | `.btf` `.tf8` `.tf2` | **yes** | **yes** | **yes** | as above, without the 4 GB limit |
| **OME-TIFF** | `.ome.tif` `.ome.tiff` | **yes** | **yes** | **yes** | OME axes, physical pixel size |
| **ScanImage TIFF** | `.tif` | **yes** | **yes** | **yes** | slices per volume, frames per slice, channels, z step, frame rate |
| **HDF5** | `.h5` `.hdf5` `.hdf` | **yes** | **yes** | **yes** | dataset discovery, writer provenance, stored axis order |
| **MATLAB MAT** | `.mat` (v5/v7 and v7.3) | **yes** | **yes** | v7.3 only | variable discovery, MATLAB axis order and dimension reversal |
| **Sutter MDF** | `.mdf` | **yes** | — | no | acquisition metadata; **Windows only** |

Extension matching is case-insensitive, so `.TIF`, `.H5` and `.MAT` work as written. See the [supported formats reference](https://napari-flowreg-formats.readthedocs.io/en/latest/supported_formats.html) for the full matrix, including the formats this plugin deliberately leaves to others.

## Usage

Drag a recording into napari. For extensions that napari's built-in reader also claims, such as `.tif` and `.h5`, napari shows a reader chooser; select **FlowReg Formats** and tick the box to remember that choice for the extension.

For explicit control over dimensions, channels and TIFF reshaping, open **File > FlowReg Import** or **Plugins > FlowReg Formats > FlowReg Import**. The dialog reports the detected structure, lets you override every field, and loads off the Qt event loop so the viewer stays responsive.

![FlowReg Import dialog in napari](https://raw.githubusercontent.com/FlowRegSuite/napari-flowreg-formats/HEAD/img/import-gui.png)

Above, a flat ScanImage page sequence has been probed: the volume structure was read from the acquisition metadata, the recording was identified as a volumetric time series, and the 16 slices per volume were filled in automatically. **Load** applies it; **Copy as Python** emits the equivalent script.

Layers are written back with **File > Save Selected Layers**, or through **File > FlowReg Export** for control over the dataset naming pattern, MATLAB axis order, the MAT container version and compression. Selected layers become the channels of one recording.

![FlowReg Export dialog in napari](https://raw.githubusercontent.com/FlowRegSuite/napari-flowreg-formats/HEAD/img/export-gui.png)

The same import is available from a script, with no GUI:

```python
import napari
from napari_flowreg_formats import ImportSpec, load

viewer = napari.Viewer()

# automatic: the structure is detected from the file
viewer.open("recording.tif", plugin="napari-flowreg-formats")

# explicit: fold a flat ScanImage page sequence into volumes
for data, meta, layer_type in load(
    "scanimage_volumes.tif",
    ImportSpec(is_3d=True, slices_per_volume=30, frames_per_slice=1, lazy="always"),
):
    viewer._add_layer_from_data(data, meta, layer_type)

napari.run()
```

The **Copy as Python** button in the import dialog emits exactly this call for the settings currently on screen, so an interactive import is always reproducible.

Two synthetic sample recordings are available under **File > Open Sample > FlowReg Formats**, so the plugin can be tried without any data on disk.

## Citation

Details on the original method and video results can be found [here](https://www.snnu.uni-saarland.de/flow-registration/).

If you use parts of this code or the plugin for your work, please cite

> "Pyflowreg," (in preparation), 2025.

and

> P. Flotho, S. Nomura, B. Kuhn and D. J. Strauss, "Software for Non-Parametric Image Registration of 2-Photon Imaging Data," J Biophotonics, 2022. [doi:https://doi.org/10.1002/jbio.202100330](https://doi.org/10.1002/jbio.202100330)

BibTeX entry
```
@article{flotea2022a,
    author = {Flotho, P. and Nomura, S. and Kuhn, B. and Strauss, D. J.},
    title = {Software for Non-Parametric Image Registration of 2-Photon Imaging Data},
    year = {2022},
  journal = {J Biophotonics},
  doi = {https://doi.org/10.1002/jbio.202100330}
}
```

## License

Distributed under the MIT License. See [LICENSE.txt](LICENSE.txt).
