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 and the project website with video results here.

Read the Documentation

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

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

Extension matching is case-insensitive, so .TIF, .H5 and .MAT work as written. See the supported formats reference 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.

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.

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

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.

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

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.