napari-ome-zarr-navigator 0.4.0

A plugin to browse OME-Zarr plates by conditions and load images, labels and features from ROIs

napari-ome-zarr-navigator

A plugin to interact with OME-Zarr images and plates. Enables integrating OME-Zarrs & Fractal tables, browsing plates by conditions, loading ROIs from ROI tables, loading features from feature tables, annotating new ROI tables and saving labels back into OME-Zarr.

(click the picture above to see the walkthrough video)

Usage

Plate Browser

The Plate Browser loads an OME-Zarr plate from the local filesystem or via authenticated HTTPS (e.g. a Fractal Server instance). It also auto-detects plates opened via napari-ome-zarr. The Plate Browser lets you zoom to a selected well ("Go to well"), which draws a bounding box and centers the camera on that well.

Using ngio condition tables, the Plate Browser can filter the well list to any subset defined by one or more conditions. Plate-level condition tables (fast) and image-level condition tables (slower, aggregated on the fly) are both supported.

ROI Loader

The ROI Loader can be launched directly from napari's Plugins menu (standalone) or by selecting a well in the Plate Browser ("Select ROI to load"). It supports:

• Loading images from different multiplexing cycles / acquisitions
• Loading any ROI from ROI tables, or the whole image when no ROI table is selected
• Loading label images
• Loading feature measurements from feature tables
• Multi-resolution (lazy) mode — streams a full dask pyramid, optimal for large images and remote data
• Fixed resolution mode — loads a single numpy array, optimal for 3D images and downstream tools in napari that don't handle multi-resolution layers (e.g. the label layer needs to be loaded as fixed resolution for using it in the classifier)

Once a ROI has been loaded for one well, "Load selected ROI for additional well(s)" reuses the same settings for any further wells selected in the Plate Browser.

This plugin is tested with OME-Zarr files generated by Fractal and is designed to work with any OME-Zarr ≥ v0.4. The feature loading workflow is optimised for use with the napari-feature-classifier.

ROI Annotator

The ROI Annotator can be launched from napari's Plugins menu (standalone, for single images), from the ROI Loader, or from the Plate Browser ("Annotate ROIs", for individual wells). It writes ROI tables and Masking ROI tables back to the OME-Zarr store using ngio.

Interactive ROI annotation

Draw rectangular ROIs by hand on any loaded image. Select Initialize empty ROI layer, click Initialize ROI Layer to create a shapes layer in drawing mode, then draw rectangles. The table name, backend (CSV, JSON, Parquet, AnnData), and overwrite flag can all be configured before saving. Only rectangle annotations are supported.

Limitations (napari shapes layer)

• Interactively drawn ROIs are always 2D — napari shapes cannot represent 3D extents.
• Each ROI covers a single time point — shapes do not span multiple frames.

ROI creation from labels (Masking ROI table)

Select Masking ROI layer, choose a label layer that has been loaded into the viewer for a given OME-Zarr image (e.g. loaded by the ROI loader above), and click Calculate masking ROI table. The annotator computes one bounding-box ROI per labelled object using ngio's compute_masking_roi and adds the results as a shapes layer for review. Z-extents are inferred from the label data and stored as shape properties; 3D bounding boxes are supported when the image is 3D. Clicking Save ROI Table writes the result as a Masking ROI table to the OME-Zarr, if a corresponding label is available.

Remote OME-Zarr stores

The annotator opens images from local files or authenticated HTTPS stores. Saving back to a remote store is not supported (the store is read-only from the plugin's perspective). When a remote image is loaded, a Save to folder picker appears so the table can be written to a local directory instead.

Save Labels

The Save Labels widget can be launched from napari's Plugins menu (standalone, for single images) or from the ROI Loader ("Save label layer to OME-Zarr"). It saves any napari label layer back to an OME-Zarr image as a label image using ngio, with optional Masking ROI table generation.

Three write modes cover the main use cases:

• Save as new label — creates the label for the first time; fails if the label already exists
• Edit existing label — patches only the pixels in the currently loaded ROI; every pixel outside that region stays unchanged (intended for proof-reading individual ROIs)
• Reset existing label — overwrites the full label with the current layer

Creating new labels

Load an image with the ROI Loader, segment or annotate it in napari, then open the Save Labels widget. Select the label layer, choose a name, and click Save label to OME-Zarr. The pixel size metadata is taken from the napari label layer. Optionally enable Save masking ROI table to derive per-object bounding-box ROIs at the same time.

Proof-reading labels ROI by ROI

Load a single ROI using the ROI Loader, edit the label layer in napari, then switch the write mode to Edit existing label and save. Only the pixels within the loaded ROI are written back; the rest of the label is untouched. Importantly, neither the ROI loader nor the label saving perform masking. Thus, if you load masking ROI tables, be aware that labels outside the mask will still load and you should not remove them, otherwise they get removed from the final label image.

Remote OME-Zarr stores

When the source image is on an authenticated remote store (e.g. served by the Fractal data service), the label cannot be written back to the read-only remote container. In this case a Local output folder picker appears and the label is saved there instead.

---

Test data

Test & sample data is available at https://zenodo.org/records/20429951

Installation

Via pixi (recommended)

pixi manages all Python and system dependencies in a single step:

git clone https://github.com/fractal-napari-plugins-collection/napari-ome-zarr-navigator
cd napari-ome-zarr-navigator
pixi run napari

To launch with the full feature-analysis environment (adds napari-feature-classifier and napari-feature-visualization):

pixi run --frozen napari-fractal

Via pip

Install into an existing Python ≥ 3.11 environment with napari already present:

pip install napari-ome-zarr-navigator

For a fresh environment we recommend miniforge:

conda create -n napari-ome-zarr python=3.12 napari pyqt -c conda-forge
conda activate napari-ome-zarr
pip install napari-ome-zarr-navigator
napari

Optionally also install additional plugins like napari-feature-classifier and napari-feature-visualization, as in:

pip install napari-feature-classifier napari-feature-visualization

Contributing

Contributions are very welcome. Tests can be run with pixi run test; please ensure coverage stays the same before submitting a pull request.

License

Distributed under the terms of the BSD-3 license, "napari-ome-zarr-navigator" is free and open source software

Issues

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