Input formats

Bootstrapper reads Zarr format 2, including OME-NGFF 0.4. Your data gives the prepare examples.

Paths

Give one array path, such as data.zarr/raw/s0 or the OME-Zarr level image.ome.zarr/0.

Image files

bs prepare --raw takes a tif stack or a folder of 2D images, with --voxel-size. It converts an image such as stack.tif into <round>/stack.zarr/raw, and the round reads that array. Except for the voxel size, the conversion uses the defaults of bs utils convert:

• The array is uint8, z y x, with offset 0.
• The brightest voxel scales to 255.
• Every file with an extension in a folder is one section, in sorted name order.
• An RGB section keeps only its first channel.

Labels and masks must be Zarr arrays. To convert a label tif, keep its IDs with -d uint64:

bs utils convert -i labels.tif -o data.zarr/labels \
  -d uint64 -vs 40 8 8

With a type other than uint32 or uint64, such as the default uint8, bs utils convert scales the IDs.

Layouts

Labels and masks have the voxel size of the raw. Labels lie inside the raw, and a training mask lies inside its labels. An array does not have to cover the whole raw.

Native arrays

Target masks for segment and refine, and seeds, are native z y x arrays. bs prepare refuses an OME-Zarr target mask. The bs utils commands and refine ops read native arrays.

Native metadata

Write geometry attributes on each input array before preparing a round, in nm and z y x order:

{
  "voxel_size": [40, 4, 4],
  "offset": [80, 12, 16],
  "axis_names": ["z", "y", "x"],
  "units": ["nm", "nm", "nm"]
}

• The voxel size and offset are whole nanometers.
• The offset is a multiple of the voxel size.
• A raw with channels uses "axis_names": ["c^", "z", "y", "x"].

bs prepare asks for --voxel-size when a raw has none. The answer does not replace the stored metadata that the model scripts read.

OME-Zarr

The parent image group's multiscales metadata gives the axes, scale and translation of each level. You do not need --voxel-size.

Axes and channels

The supported axis orders are z y x, c z y x, t z y x and t c z y x. Each spatial axis has a unit: angstrom, nanometer, micrometer or millimeter. A missing unit, unsupported axis order or malformed metadata stops the reader with an error.

Rounding to whole nanometers

1. The reader composes a level's transformations and converts them to nanometers.
2. It rounds the scale and translation separately to the nearest whole nanometer. A tie goes to the even number, as Python's round does: 2.5 nm becomes 2 nm.
3. A value more than 1e-6 nm from its rounded value gives a warning.
4. The scale must stay positive, and the translation must be a multiple of the voxel size. A scale that rounds to 0 nm gives an error.

Rounding changes only the geometry that Bootstrapper uses. The source metadata and voxel data stay unchanged.

Warning: image.ome.zarr/0: OME scale 4.6 167.68 5.24 nm rounds to 5 168 5 nm; bootstrapper uses whole nanometers. See docs/inputs.md.

Voxel grid

An offset off the rounded grid gives an error. The reader does not move the image onto the grid. An offset on the original grid can fall off the rounded grid. For example, scale 4.6 nm and translation 9.2 nm (two voxels) round to 5 nm and 9 nm. Since 9 is not a multiple of 5, this image needs resampling before Bootstrapper can read it.

Conflicting attributes

OME metadata controls the image geometry. A level's voxel_size or offset attribute must agree with the OME value within 1e-6 nm, before or after rounding. Otherwise, the reader stops with an error. For an OME scale of 4.6 nm, an attribute of 4.6 or 5 agrees, and 4.7 does not.

Conversion

OME-NGFF 0.5 uses Zarr format 3, which Bootstrapper does not read. Export again as OME-NGFF 0.4, or convert to a native array.

The script below reads the selected volume into memory and overwrites its destination, so give it a new destination. An image with an offset off its voxel grid needs resampling. A change to its attributes alone moves the image off its registration.

import sys
import zarr

src = zarr.open_array(sys.argv[1], mode="r")
pixels = src[0, 0]  # Select time 0 and channel 0.
dst = zarr.open_array(sys.argv[2], mode="w", zarr_format=2,
                      shape=pixels.shape, chunks=src.chunks[-3:],
                      dtype=pixels.dtype)
dst[:] = pixels
dst.attrs.update(voxel_size=[50, 8, 8], offset=[100, 80, 80],
                 axis_names=["z", "y", "x"], units=["nm"] * 3)

uv run --no-project --with "zarr>=3" python -I convert_input.py \
  image_v05.ome.zarr/0 converted.zarr/raw

Existing rounds

A round folder contains copies of the model scripts, and an update of Bootstrapper does not change them. In a stock copied train.py or predict.py, replace:

from funlib.persistence import open_ds

with:

from bootstrapper.inputs import open_ds

The new import reads OME-Zarr inputs. Fresh copies from bs prepare also check that labels and masks are z y x. bs prepare copies the scripts again only into a setup folder that has no train.py.