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, chromatic shift correction and pixel size changes. → 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
zarrsmith resample -i INPUT_ZARR -z OUTPUT_ZARR -ps 1 0.5 0.5 # change the pixel size (Z Y X)
Documentation
Getting started
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, zarrsmith resample (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.
