👨‍💻 Command Line Interface¶

ngff-zarr provides a command line interface to convert a variety of scientific file formats to ome-zarr and inspect and ome-zarr store’s contents.

Installation¶

To install the command line interface (CLI):

pip install 'ngff-zarr[cli]'

Usage¶

Convert an image file¶

Convert any scientific image file format supported by either itk, tifffile (TIFF/OME-TIFF with metadata extraction), liffile (Leica LIF), or imageio.

Example:

ngff-zarr -i ./MR-head.nrrd -o ./MR-head.ome.zarr

ngff-zarr convert

Convert a TIFF file¶

TIFF files, including multi-series OME-TIFF files, can be converted with automatic extraction of physical size metadata when available.

Convert a single TIFF file:

ngff-zarr -i microscopy.ome.tiff -o output.ome.zarr

Convert all series from a multi-series TIFF:

ngff-zarr -i multi_series.ome.tiff -o output/

Convert a specific series by index:

ngff-zarr -i multi_series.ome.tiff -o output.ome.zarr --series 0

Convert series matching a pattern:

ngff-zarr -i multi_series.ome.tiff -o output/ --series "*channel_1*"

When converting OME-TIFF files, physical size metadata (PhysicalSizeX/Y/Z and units) is automatically extracted and applied to the output OME-Zarr.

For more details on TIFF conversion, see TIFF Support.

Convert a Leica LIF file¶

Convert all series from a LIF file:

ngff-zarr -i microscopy.lif -o output/

Convert a specific series by index:

ngff-zarr -i microscopy.lif -o output.ome.zarr --series 0

Convert series matching a pattern:

ngff-zarr -i microscopy.lif -o output/ --series "*GFP*"

For more details on LIF conversion, see Leica LIF Support.

Convert an image volume slice series¶

Note the quotes:

ngff-zarr -i "series/*.tif" -o ome-ngff.ome.zarr

Print information about generated multiscales¶

To print information about the input, omit the output argument.

ngff-zarr -i ./MR-head.nrrd

ngff-zarr information

Specify output chunks¶

ngff-zarr -c 64 -i ./MR-head.nrrd

ngff-zarr output chunks

Specify metadata¶

ngff-zarr --dims "z" "y" "x" --scale x 1.4 y 1.4 z 2.5 --translation x 6.24 y 360.0 z 332.5 --name LIDC2 -i "series/*.tif"

ngff-zarr metadata

Limit memory consumption¶

Limit memory consumption by passing a rough memory limit in human-readable units, e.g. 8GB with the --memory-target option.

ngff-zarr --memory-target 50M -i ./LIDCFull.vtk -o ./LIDCFull.ome.zarr

ngff-zarr memory-target

OME-Zarr Zip (.ozx) files¶

RFC-9 introduces support for OME-Zarr Zip (.ozx) files, which package an entire OME-Zarr hierarchy into a single ZIP archive. This format enables:

Single-file distribution: Share complete multiscale datasets as one file
Version metadata: Embedded NGFF version in ZIP comment

Write .ozx files¶

ngff-zarr -i MR-head.nrrd -o MR-head.ozx

Inspect .ozx files¶

ngff-zarr -i ./MR-head.ozx

High Content Screening (HCS) plate data¶

HCS plates contain multiple wells and images. To convert a specific well and field from an HCS plate, use sub-path syntax:

# Convert well A/1, field 0
ngff-zarr -i plate.ome.zarr/A/1/0 -o well_A1_field0.ome.zarr

# Convert well B/2, field 1
ngff-zarr -i plate.ome.zarr/B/2/1 -o well_B2_field1.ome.zarr

Attempting to convert an entire plate will display available wells:

$ ngff-zarr -i plate.ome.zarr -o output.ome.zarr
Error: The input appears to be an HCS plate structure with 96 wells.
Provide the full path: 'plate.ome.zarr/A/1/0', 'plate.ome.zarr/A/2/0', ...

For more details on HCS support, see HCS Support.

Upgrade an OME-Zarr store to a new version¶

The ngff-zarr upgrade subcommand changes the OME-Zarr specification version recorded in an existing store. It has two modes.

Omitting -o/--output performs an in-place, metadata-only upgrade: only the store’s group metadata is rewritten and every array chunk on disk is left untouched.

ngff-zarr upgrade path/to/image.zarr --to 0.6

Passing -o/--output writes an upgraded copy to a new store through the standard write pipeline, leaving the source store intact. This is the mode to use for a transition across the Zarr v2/v3 boundary that the in-place mode cannot do safely (for example a 0.5/0.6 downgrade back to 0.4).

ngff-zarr upgrade src.zarr -o dst.zarr --to 0.5

The target version is selected with --to (alias --version), one of 0.4, 0.5, or 0.6 (default 0.6). Add --validate to validate the source metadata against the NGFF schema while reading. For the write-to-new-store mode, --overwrite (the default) replaces any pre-existing data at the output store, while --no-overwrite refuses to; both flags are ignored for an in-place upgrade, which never overwrites array data.

# Validate the source, and refuse to overwrite an existing destination store.
ngff-zarr upgrade src.zarr -o dst.zarr --to 0.6 --validate --no-overwrite

The command prints the detected source version, the target version, and which mode it ran. ngff-zarr upgrade --help lists every option.

More options¶

ngff-zarr --help