ZarrSmith — microscopy I/O, OME-Zarr forging, and NGFF utilities

ZarrSmith is a Python package for reading microscopy datasets from multiple acquisition systems, building multiscale pyramids, writing OME-NGFF / OME-Zarr, and working with those datasets from Python, the command line and napari.

The rendered documentation is at embl-mif.github.io/zarrsmith.

Note

ZarrSmith was called PyMIF up to version 0.5.5. From 0.6.0, import zarrsmith and run the zarrsmith command instead of pymif. The Docker images of PyMIF stay available at ghcr.io/embl-mif/pymif:<version>; newer images are at ghcr.io/embl-mif/zarrsmith.

What ZarrSmith does

Microscope managers read Luxendo, Opera, SCAPE, Viventis, Zeiss, Evident (Olympus VSI) and OME-Zarr datasets into one lazy (Dask) API with a shared metadata schema. → Readers and conventions
OME-Zarr writing: full export, empty datasets and groups, image and label region updates, any subset of the tczyx axes. → Python API
Pyramids and subsetting: multiscale generation, cropping, channel reordering, metadata updates. → Python API
Mosaics: raw tiles shown at their stage position and fused into one OME-Zarr image (3D or projection, one timepoint or a timelapse). → Mosaics
Chromatic shift correction: the Z offset between channels measured on the sample itself, on the reference channel and timepoint you choose and applied to every timepoint, and a corrected copy with the same layout as the input. → Chromatic shift correction
Command line: one-off and CSV-batch conversion, mosaic fusion and chromatic shift correction. → Command line
Napari widgets: conversion with ROI selection, mosaic fusion, exploration of segmented objects (features plot linked with the viewer). → Napari plugin
Output tuning: sharding, singleton axes, parallel writing, progress bars. → Advanced writing options

Installation

conda create -n zarrsmith python=3.12
conda activate zarrsmith
pip install zarrsmith

Optional extras:

pip install "zarrsmith[napari]"      # napari widgets
pip install "zarrsmith[notebooks]"   # Jupyter, to run the example notebooks
pip install "zarrsmith[dev]"         # tests and packaging
pip install "zarrsmith[docs]"        # documentation build
pip install "zarrsmith[all]"         # all of the above

Extras can be combined, e.g. pip install "zarrsmith[napari,notebooks]".

Installing from source, development installs, versioning and releases: Installation and versioning.

Quick start

import zarrsmith.microscope_manager as mm

source = mm.ViventisManager("path/to/Position_1")   # any microscope manager
source.build_pyramid(num_levels=3)
source.to_zarr("output.zarr")                       # NGFF v0.5 / Zarr v3

z = mm.ZarrManager("output.zarr")
z.visualize()                                       # open in napari

zarrsmith convert -i INPUT_PATH -m MICROSCOPE -z OUTPUT_ZARR
zarrsmith fuse -i ACQUISITION_FOLDER -z OUTPUT_ZARR -rds 4 8 8   # fuse raw tiles
zarrsmith chromatic-shift -i INPUT_ZARR -z OUTPUT_ZARR -r shift.json   # align channels in Z

Documentation

Getting started

Page	Contents
Installation and versioning	environments, extras, release labels
Readers and conventions	supported microscopes, shared reader behaviour, logging

Working with data

Page	Contents
Python API	export, empty datasets, axis-aware metadata, labels, region writes
Mosaics	raw tiles, placement check, fusion options, timelapses
Chromatic shift correction	measuring the Z offset between channels, the corrected dataset, checking the result, `zarrsmith chromatic-shift`
Advanced writing options	sharding, singleton axes, parallel writing, progress bar

Interfaces

Page	Contents
Command line	`zarrsmith convert`, `zarrsmith fuse`, `zarrsmith chromatic-shift` (one dataset or a CSV batch)
Napari plugin	converter, mosaic fusion and objects explorer widgets

Reference

Page	Contents
API reference	generated from the docstrings
Contributing	package layout, adding a microscope manager or a mosaic manager, `zarrsmith.utils`, documentation

Help

For questions or bug reports, open an issue on GitHub, or contact the current maintainers.

Important

If ZarrSmith contributes to your work, please acknowledge ZarrSmith and the EMBL Mesoscopic Imaging Facility in your publications.