bioio_conversion.converters.OmeZarrConverter

class bioio_conversion.converters.OmeZarrConverter(*, source: str, destination: str | None = None, scenes: int | List[int] | None = None, name: str | None = None, level_shapes: Sequence[int] | Sequence[Sequence[int]] | None = None, chunk_shape: Sequence[int] | Sequence[Sequence[int]] | None = None, shard_shape: Sequence[int] | Sequence[Sequence[int]] | None = None, compressor: BloscCodec | Codec | None = None, zarr_format: int | None = None, image_name: str | None = None, channels: List[Channel] | None = None, rdefs: Dict[str, Any] | None = None, creator_info: Dict[str, Any] | None = None, root_transform: Dict[str, Any] | None = None, axes_names: List[str] | None = None, axes_types: List[str] | None = None, axes_units: List[str | None] | None = None, physical_pixel_size: List[float] | None = None, num_levels: int | None = None, downsample_z: bool = False, memory_target: int | None = None, start_t_src: int | None = None, start_t_dest: int | None = None, tbatch: int | None = None, dtype: str | dtype | None = None, n_workers: int | None = None, shard_limit_bytes: int = 4294967296)[source]

OmeZarrConverter handles conversion of any BioImage‐supported format (TIFF, CZI, etc.) into OME-Zarr stores. Supports exporting one, many, or all scenes from a multi-scene file.

__init__(*, source: str, destination: str | None = None, scenes: int | List[int] | None = None, name: str | None = None, level_shapes: Sequence[int] | Sequence[Sequence[int]] | None = None, chunk_shape: Sequence[int] | Sequence[Sequence[int]] | None = None, shard_shape: Sequence[int] | Sequence[Sequence[int]] | None = None, compressor: BloscCodec | Codec | None = None, zarr_format: int | None = None, image_name: str | None = None, channels: List[Channel] | None = None, rdefs: Dict[str, Any] | None = None, creator_info: Dict[str, Any] | None = None, root_transform: Dict[str, Any] | None = None, axes_names: List[str] | None = None, axes_types: List[str] | None = None, axes_units: List[str | None] | None = None, physical_pixel_size: List[float] | None = None, num_levels: int | None = None, downsample_z: bool = False, memory_target: int | None = None, start_t_src: int | None = None, start_t_dest: int | None = None, tbatch: int | None = None, dtype: str | dtype | None = None, n_workers: int | None = None, shard_limit_bytes: int = 4294967296) → None[source]

Initialize an OME-Zarr converter with flexible scene selection, pyramid construction, and chunk-sizing.

Parameters:
sourcestr

Path to the input image (any format supported by BioImage).

destinationOptional[str]

Directory in which to write the .ome.zarr output(s). If None, the converter will use the current working directory

scenesOptional[Union[int, List[int]]]

Which scene(s) to export: - None → export all scenes - int → a single scene index - List[int] → those specific scene indices

nameOptional[str]

Base name for output files (defaults to the source stem). When exporting multiple scenes, each file name is suffixed with the scene’s name.

level_shapesOptional[List[Tuple[int, …]]]

Explicit per-level, per-axis absolute shapes (level 0 first). Each tuple length must match the native axis count. If provided, convenience options like num_levels and downsample_z are ignored.

chunk_shapeOptional[Union[Tuple[int, …], Tuple[Tuple[int, …], …]]]

Explicit chunk shape for the written arrays (applies to both Zarr v2 and v3) — a single tuple applied to all levels, or per-level tuples, in the array’s axis order (e.g. (1, 1, 1, 512, 512) for TCZYX). The writer validates it against each level’s shape. When provided under v3 it also disables the auto-shard calculation, since the shard layout is derived from the chunk shape.

shard_shapeOptional[Union[Tuple[int, …], Tuple[Tuple[int, …], …]]]

Explicit shard shape (Zarr v3 only). When provided, disables the v3 auto-shard calculation.

compressorOptional[Union[zarr.codecs.BloscCodec, numcodecs.abc.Codec]]

Compression codec. For v2 use numcodecs.Blosc; for v3 use zarr.codecs.BloscCodec.

zarr_formatOptional[int]

Target Zarr array format (2 or 3). Defaults to 3 when None.

image_nameOptional[str]

Image name to record in multiscales metadata. Defaults to the output base.

channelsOptional[List[Channel]]

Optional OMERO-style channel metadata. Only used when a 'c' axis exists. If omitted, minimal channel models are derived from the reader.

rdefsOptional[Dict[str, Any]]

Optional OMERO rendering defaults.

creator_infoOptional[Dict[str, Any]]

Optional “creator” metadata block (e.g., tool/version).

root_transformOptional[Dict[str, Any]]

Optional multiscale root coordinate transformation.

axes_namesOptional[List[str]]

Axis names to write; defaults to the native axis names from the reader.

axes_typesOptional[List[str]]

Axis types (e.g., ["time","channel","space",...]). Writer validates.

axes_unitsOptional[List[Optional[str]]]

Physical units per axis. Writer validates.

physical_pixel_sizeOptional[List[float]]

Physical scale at level 0 per axis. If omitted, values are derived from BioImage.scale for present axes.

num_levelsOptional[int]

Number of pyramid levels (including level 0) to generate via a simple XY half-pyramid. When set, overrides the v3 atlas-based auto-pyramid:

  • 1 = only level 0

  • 2 = level 0 + one XY half

  • 3 = level 0 + two XY halves, etc.

Ignored if level_shapes is provided.

downsample_zbool, default = False

Also halve Z at each level when building the num_levels pyramid. Ignored if level_shapes is provided.

memory_targetOptional[int]

Chunk budget in bytes. For zarr_format=3 this is passed as chunk_limit_bytes to the auto-chunk/shard layout; for other formats it drives multiscale_chunk_size_from_memory_target. Has no effect when chunk_shape is set explicitly. Default: 16 MiB.

start_t_srcOptional[int]

Source T index at which to begin reading from the BioImage. Default: use writer default.

start_t_destOptional[int]

Destination T index at which to begin writing into the store. Default: use writer default.

tbatchOptional[int]

Number of timepoints to transfer. If None, the converter writes as many as available in both source and destination.

dtypeOptional[Union[str, np.dtype]]

Override output data type; defaults to the reader’s dtype.

n_workersOptional[int]

Number of worker processes for shard writes (auto-layout path). If None (default), derived from the cores actually available to the process. One process per core, floored at 1.

shard_limit_bytesint

Maximum uncompressed size of a level-0 shard. Default: 4 GiB.

Methods

__init__(*, source[, destination, scenes, ...])

Initialize an OME-Zarr converter with flexible scene selection, pyramid construction, and chunk-sizing.

convert()