napari-ome-arrow

napari-ome-arrow is a minimal plugin for napari that opens image data through the OME-Arrow toolkit.

It provides a single, explicit pathway for loading OME-style bioimage data:

• OME-TIFF (.ome.tif, .ome.tiff, .tif, .tiff)
• OME-Zarr (.ome.zarr, .zarr stores and URLs)
• OME-Parquet (.ome.parquet, .parquet, .pq)
• Bio-Formats–style stack patterns (paths containing <, >, or *)
• A simple .npy fallback for quick testing / ad-hoc arrays

Key features

• ✅ Unified reader via OMEArrow All supported formats are loaded through OME-Arrow, which normalizes data into a common TCZYX-like representation.

• ✅ Explicit image vs labels mode This plugin never guesses whether your data are intensities or segmentation masks. You must tell it:

  • via the GUI prompt when you drop/open a file in napari, or
  • via an environment variable for scripted/CLI usage.

• ✅ Interactive choice in the GUI When NAPARI_OME_ARROW_LAYER_TYPE is not set and you open a supported file, napari shows a small dialog:

  How should my_data.ome.tif be loaded? [Image] [Labels] [Cancel]

  This makes the “image vs labels” choice explicit at load time without relying on file naming conventions.

• ✅ Image mode

  • Returns a napari image layer
  • Preserves channels and sets channel_axis when appropriate (e.g. multi-channel OME-TIFF or stack patterns)
  • Works for 2D, 3D (Z-stacks), and higher-dimensional data (T, C, Z, Y, X)

• ✅ Labels mode

  • Returns a napari labels layer
  • Converts data to an integer dtype (suitable for labels)
  • Applies a reasonable default opacity for overlaying on images

• ✅ Automatic 3D for Z-stacks If the loaded data include a true Z dimension (Z > 1, assuming a TCZYX subset), the plugin asks the current viewer to switch to 3D (viewer.dims.ndisplay = 3) so z-stacks open directly in volume mode.

• ✅ Headless / scripted friendly When Qt is not available (e.g., in headless or purely programmatic contexts), the reader:

  • respects NAPARI_OME_ARROW_LAYER_TYPE, and
  • defaults to "image" if the variable is not set.

• ✅ Grid view for multi-row OME-Parquet When a Parquet file contains multiple OME-Arrow rows, each row is loaded as its own layer and the viewer is switched to napari’s grid mode. Set NAPARI_OME_ARROW_PARQUET_COLUMN to pick which image column to visualize.

---

This napari plugin was generated with copier using the napari-plugin-template (None).

Installation

You can install napari-ome-arrow via pip:

pip install napari-ome-arrow

If napari is not already installed, you can install napari-ome-arrow with napari and Qt via:

pip install "napari-ome-arrow[all]"

To install latest development version :

pip install git+https://github.com/wayscience/napari-ome-arrow.git

Usage

From the napari GUI

1. Install the plugin (see above).
2. Start napari.
3. Drag and drop an OME-TIFF, OME-Zarr, OME-Parquet file, or stack pattern into the viewer.
4. When prompted, choose Image or Labels.

The plugin will:

• load the data through OMEArrow,
• map channels and axes appropriately, and
• automatically switch to 3D if there is a Z-stack.

From the command line

You can control the mode via an environment variable:

# Load as regular images
NAPARI_OME_ARROW_LAYER_TYPE=image napari my_data.ome.tif

# Load as labels (segmentation)
NAPARI_OME_ARROW_LAYER_TYPE=labels napari my_labels.ome.parquet

# Pick a specific column in a multi-row OME-Parquet and show in grid mode
NAPARI_OME_ARROW_LAYER_TYPE=image \\
NAPARI_OME_ARROW_PARQUET_COLUMN=Image_FileName_OrigDNA_OMEArrow_ORIG \\
napari tests/data/cytodataframe/BR00117006.ome.parquet

Contributing

Contributions are very welcome. Please reference our CONTRIBUTING.md guide.

License

Please see the LICENSE file for more information.

Issues

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