Skip to content

abczarr.ome.config

Describes an OME-Zarr multiscale image to write.

An ImageConfig is to OME-Zarr metadata what an ArrayConfig is to a Zarr array: a high-level, human-facing description that lowers to the exact typed metadata a group carries. It holds the axes, the voxel geometry, and how the pyramid was built, and produces OME-NGFF multiscales metadata for any requested version.

Three coordinate spaces sit behind the config::

voxel (array index) --scale+translation--> intrinsic --transforms--> model

scale and translation place each resolution level's array indices into a single intrinsic space shared by every level. transforms (or the voxel_to_world shortcut) map that intrinsic space onto a model space, a world or anatomical frame. One config lowers to both the stable 0.5 shape and the 0.6 preview.

Classes

ImageConfig 

ImageConfig(axes: Sequence[str | Mapping[str, Any] | Sequence[Any] | Axis] | Mapping[str, Any], scale: float | int | Sequence[float] | Mapping[str, float] | None = None, translation: float | int | Sequence[float] | Mapping[str, float] | None = None, intrinsic_name: str = 'intrinsic', model_name: str = 'model', transforms: Sequence[Any] | Mapping[str | tuple[str, str], Any] = (), voxel_to_world: Any = None, name: str | None = None, ome_version: str = 'stable', factor: float | int | Sequence[float] | Mapping[str, float] = 2, strategy: str | int = 'edge')

A high-level description of an OME-Zarr multiscale image.

The axes and the voxel geometry are set once. The config then lowers to typed OME metadata for any version through to_ome, producing both the stable 0.5 shape and the 0.6 preview.

Parameters:

Name Type Description Default
axes sequence or mapping

The array's axes, one per dimension. A sequence lists each axis as a name ("x"), a (name, type) or (name, type, unit) tuple, a {"name", "type", "unit"} dict, or a typed Axis. A mapping keys each axis by its name, in order, and gives a type string, a dict of the remaining fields, or None. An axis name matches a v3 array's dimension_names. A missing type is inferred from the name: x, y, and z are space, t is time, c is channel, and any other name is space.

 required
scale number, sequence, or mapping

The voxel-to-intrinsic diagonal scale (physical size of one voxel). One value for all axes, a value per axis, or a mapping keyed by axis name or type (name wins). Defaults to 1.

 None
translation number, sequence, or mapping

The voxel-to-intrinsic translation, same shapes as scale. Defaults to 0.

 None
intrinsic_name str

The name of the intrinsic coordinate system every level maps into.

 'intrinsic'
model_name str

The default name of the model system the transforms map onto.

 'model'
transforms sequence or mapping

The transforms from the intrinsic system to a model system. A sequence lists each transform as a numpy affine matrix, which maps the intrinsic system to model_name, or as a typed OME transformation, which carries its own input and output systems. A mapping instead names the systems in its key. A string key is a model system name, and the transform maps intrinsic_name to it. An (input, output) tuple key names both systems. The key sets the input and output systems, overriding any that a typed transform of its own carries.

 ()
voxel_to_world array - like or CoordinateTransformation

A shortcut for images with a single voxel-to-world affine, in place of separate scale/translation and transforms. The composed voxel-to-world transform equals this matrix exactly. When scale is not given, it is derived from this matrix.

 None
name str

The multiscale's name.

 None
ome_version str

The version to lower to: "stable" (the latest released version), "latest" (the newest, including previews), or an explicit version such as "0.6rc0".

 'stable'
factor number, sequence, or mapping

The per-axis downsampling factor between levels, same shapes as scale. Defaults to 2.

 2
strategy (edge, center, window)

How a level's placement is worked out from the downsampling. The "edge" and "center" strategies need the level shapes. The "window" strategy, or an int window size, needs only the factors.

 "edge"

Attributes

axes class-attribute instance-attribute 
axes: Axes = field()
scale class-attribute instance-attribute 
scale: PerAxis | None = field(default=None)
translation class-attribute instance-attribute 
translation: PerAxis | None = field(default=None)
intrinsic_name class-attribute instance-attribute 
intrinsic_name: str = field(default='intrinsic')
model_name class-attribute instance-attribute 
model_name: str = field(default='model')
transforms class-attribute instance-attribute 
transforms: Transforms = field(factory=tuple)
voxel_to_world class-attribute instance-attribute 
voxel_to_world: Any = field(default=None)
name class-attribute instance-attribute 
name: str | None = field(default=None)
ome_version class-attribute instance-attribute 
ome_version: str = field(default='stable')
factor class-attribute instance-attribute 
factor: PerAxis = field(default=2)
strategy class-attribute instance-attribute 
strategy: str | int = field(default='edge')

Methods:

resolved_version 
resolved_version(version: str | None = None) -> str

The concrete OME version this config lowers to.

The method resolves version, or ome_version when version is None. "stable" is the latest released version, "latest" is the newest version including previews, and any other value is taken as an explicit version string.

Parameters:

Name Type Description Default
version str

An override for ome_version.

 None

Returns:

Type Description
str

The resolved version string.
to_ome 
to_ome(*, version: str | None = None, policy: ConversionPolicy = 'warn', level_shapes: Sequence[Sequence[int]] | None = None, level_paths: Sequence[str] | None = None) -> OME

Lowers this config to typed OME-Zarr metadata.

The result carries the intrinsic and model coordinate systems, one dataset per resolution level mapping the array onto the intrinsic system, and the intrinsic-to-model transforms, all for the resolved version.

Parameters:

Name Type Description Default
version str

An override for ome_version (see resolved_version).

 None
policy (lossy, warn, strict)

How to treat information an older target version cannot hold. "warn" (the default) drops the information and issues one warning. "strict" raises an error instead. "lossy" drops the information silently.

 "lossy"
level_shapes sequence of shape

The array shape of each resolution level, finest first. Required by the "edge" and "center" strategies for more than one level. When omitted, "edge"/"center" emit level 0 only.

 None
level_paths sequence of str

The array path of each level. Defaults to "0", "1", and so on.

 None

Returns:

Type Description
OME

The typed metadata for the resolved version, ready to assign to a group's ome.

Raises:

Type Description
ValueError

If a per-axis quantity does not match the axes, or a strategy is asked for more levels than it can build without shapes.
apply 
apply(group: Any, **kwargs: Any) -> OME

Sets a group's OME metadata from this config.

The metadata is produced by lowering the config with to_ome, and the result is assigned to group's ome. Keyword arguments are passed through to to_ome.

Parameters:

Name Type Description Default
group ZarrNode

The group to write the metadata to.

 required
**kwargs Any

Passed through to to_ome.

 {}

Returns:

Type Description
OME

The metadata that was written.

Functions:

axis 

axis(name: str, type: str | None = None, unit: str | None = None) -> Axis

Builds a 0.6 Axis from a name.

The axis type is inferred from name when not given: x, y, and z are space, t is time, c is channel, and anything else is space. A known type gives back the matching axis subclass, a SpaceAxis and so on.

Parameters:

Name Type Description Default
name str

The axis name, such as "x".

 required
type str

The axis type. Inferred from name when omitted.

 None
unit str

The axis's physical unit, such as "micrometer".

 None

Returns:

Type Description
Axis

The typed axis.
!!! example 
>>> from abczarr.ome import axis
>>> axis("x", unit="micrometer").type
'space'
>>> axis("t").type
'time'