Command line
The zarrsmith command has three subcommands:
Command |
Does |
|---|---|
|
convert a dataset to OME-Zarr, or every dataset listed in a CSV file with |
|
fuse the raw tiles of a mosaic into one OME-Zarr image, or every mosaic listed in a CSV file with |
|
measure and correct the Z chromatic shift between the channels of an OME-Zarr image, or of every image listed in a CSV file with |
zarrsmith -h lists them, and zarrsmith convert -h, zarrsmith fuse -h and zarrsmith chromatic-shift -h show every option, examples and the batch CSV columns. zarrsmith --version prints the installed version.
Each command runs either one dataset (-i INPUT -z OUTPUT) or a CSV file (--batch FILE.csv), never both (chromatic-shift can also run with -i alone, to only measure). In a batch file, one row is one run and the columns take the place of the options.
Convert a dataset
zarrsmith convert -i INPUT_PATH -m MICROSCOPE -z OUTPUT_ZARR
zarrsmith convert --batch datasets.csv
-m is one of luxendo, opera, viventis, zeiss, evident, zarr, zarrv04, scape; leave it out to detect it from the input path. The output options:
Flag |
Meaning |
|---|---|
|
chunk size, one value per axis of the dataset |
|
max chunk size in MB (ignored with |
|
scene of a |
|
names and colours (hex or matplotlib names) of the channels |
|
2 (NGFF 0.4) or 3 (NGFF 0.5, default) |
|
pyramid factor and number of levels (estimated if omitted) |
|
crop or select before writing, e.g. |
|
sharding (see Advanced writing options) |
|
drop size-1 |
|
write threads |
|
replace an existing output (see Existing outputs) |
The batch CSV has the columns input, microscope, output, plus any of chunk_size, max_size(MB), scene_index, zarr_format, downscale_factor, subset, channel_colors, channel_names, num_levels, shards, shard_target_mb, shard_exclude_axes, drop_singleton, num_workers, overwrite. The napari converter writes such rows with Append to batch CSV.
An existing non-empty output is refused unless --overwrite is given, and only a Zarr store is ever replaced. With --batch, overwriting is set per row in the overwrite column (--overwrite is not accepted); a row whose output is in the way is skipped with a warning, the other rows still run, and the skipped rows are listed at the end. This also applies to fuse and chromatic-shift.
Fuse a mosaic
fuse fuses the raw tiles of a mosaic (see Mosaics) into one OME-Zarr image:
# 3D, downsampled 4 (z) x 8 (y) x 8 (x), smooth (sigmoid) transitions between tiles and illumination sides
zarrsmith fuse -i /path/to/2026-10-14_103957 -z acq_3D.ome.zarr -rds 4 8 8 -nl 3
# 2D maximum projection, downsampled 8 x 8 in y/x, sharp cut between illumination sides
zarrsmith fuse -i /path/to/2026-10-14_103957 -z acq_MIP.ome.zarr -rds 1 8 8 -p max -b midline
# where are the tiles? (overlaps are brighter)
zarrsmith fuse -i /path/to/2026-10-14_103957 -z acq_tiles.ome.zarr -rds 1 8 8 -p max -b sum
# many mosaics from a CSV file
zarrsmith fuse --batch mosaics.csv
The fusion options:
Flag |
Meaning |
|---|---|
|
|
|
downsampling while reading (block mean): one value or |
|
|
|
|
|
steepness of the |
|
tile channels and groups (e.g. |
|
the field to fuse (groups of touching tiles, |
|
only fuse these tiles, and fit the output to them: stacks such as |
|
tiles to leave blank (the output keeps its size): |
|
timepoints to fuse (default: all); more than one gives an output with a |
|
timepoint whose tiles set the geometry of every timepoint (default: the first), or |
|
Opera: do not apply Harmony’s flat-field correction (applied by default, see Opera) |
|
axis along which |
|
output dtype |
|
tiles read in parallel processes (default 4); not to be confused with |
|
folder for the temporary fused level 0 (a local disk is faster) |
|
replace an existing output, once the fusion has succeeded |
Every output option of convert is available too, applied to the fused output. Two read differently for a mosaic: -cs is given in C Z Y X order (C Y X for projections, after T for several timepoints), and -s/--subset crops the fused output (z/y/x in output voxels, after -rds) and selects channels (c), e.g. "z=0:100;y=200:900;c=1"; timepoints are chosen with -tp. -si loads one scene of a Zeiss mosaic, ignored for the others.
The batch CSV has the columns input, microscope, output, plus any of the output columns of convert --batch and of the fusion columns downsample, projection, blend, sigmoid_steepness, channels, groups, fields, tiles, skip_tiles, timepoints, reference_timepoint, midline_axis, out_dtype, read_workers, temp_dir, overwrite. Leave a cell empty for the default; lists are space separated. A row asking for tiles from several fields is not fused; the other rows still run, and the rows that were not fused are listed at the end. The napari Mosaic Fusion widget writes such rows with Append to batch CSV.
input,microscope,output,downsample,projection,blend,num_levels,shards
/path/to/acquisition_1,luxendo,/path/to/acq1_3D.ome.zarr,4 8 8,none,sigmoid,3,auto
/path/to/acquisition_1,luxendo,/path/to/acq1_MIP.ome.zarr,1 8 8,max,midline,,none
Correct the chromatic shift
chromatic-shift measures the Z offset between the channels of an OME-Zarr image on the sample itself and writes a corrected copy with the same chunks, shards, compression and metadata as the input (see Chromatic shift correction):
# measure, save the report and write the corrected image
zarrsmith chromatic-shift -i brain.ome.zarr -z brain_csc.ome.zarr -r shift.json
# only measure
zarrsmith chromatic-shift -i brain.ome.zarr -r shift.json
# apply known shifts (one per channel), or the shifts of an earlier report
zarrsmith chromatic-shift -i brain.ome.zarr -z brain_csc.ome.zarr -sf 0 104.4
zarrsmith chromatic-shift -i other.ome.zarr -z other_csc.ome.zarr -sf shift.json
# many images from a CSV file
zarrsmith chromatic-shift --batch images.csv
Flag |
Meaning |
|---|---|
|
input OME-Zarr image |
|
corrected OME-Zarr image; leave out to only measure |
|
save the estimate report (JSON) |
|
skip the estimate: one shift per channel in the Z unit, or a JSON report |
|
reference channel, as an index or a name (default 0) |
|
timepoint the shift is measured on, an index along the |
|
largest shift searched, in the Z unit (default: 10% of the stack depth) |
|
coarse level, refine level ( |
|
exit with an error, writing only the report, when the estimate has warnings |
|
|
|
|
|
also write image subgroups / labels ( |
|
replace an existing output and report |
|
write threads |
In a pipeline (e.g. a Nextflow process), use -r to keep the report next to the output and --fail_on_warning so that a doubtful estimate (search limit reached, no usable crop) fails the step instead of producing a wrongly corrected image.
The batch CSV has the columns input, output (empty: only measure), plus any of report, shifts, reference_channel, timepoint, max_shift, coarse_level, refine_level, n_regions, crop_yx, min_z_normal, min_correlation, threshold, extent, order, include_groups, include_labels, overwrite, num_workers, fail_on_warning. Leave a cell empty for the default; shifts are space separated.
input,output,report,reference_channel,max_shift
/path/to/a.ome.zarr,/path/to/a_csc.ome.zarr,/path/to/a_csc.json,cFos-647,150
/path/to/b.ome.zarr,,/path/to/b_shift.json,0,
Old command names
The commands used to have other names. They still work, with their original options, and print a one-line notice with the new name:
Old |
New |
|---|---|
|
|
|
|
|
|
|
|
Batch CSV files written before the rename (with a read_downsample column) still run.