Skip to content

streaming.omezarr#

zen_api_utils.streaming.omezarr #

Classes:

Functions:

ExperimentConfig dataclass #

ExperimentConfig(experiment_name: str, czi_name: str, start_from_script: bool, overwrite_czi: bool, time_points: int, channels: int, z_planes: int, z_spacing: float, tiles: int, scenes: int, output_dir: str, dtype: str, compression: str | None, overwrite_zarr: bool, channel_index: int | None, zenapi_config: str, positions: tuple[dict[str, object], ...] = (), use_hcs_layout: bool = True, keep_source_tiles: bool = False, spatial_shard_size_chunks: int | None = 2, max_pending_frames: int = 4096)

Parsed experiment configuration.

load_experiment_config #

load_experiment_config(config_path: str | Path) -> ExperimentConfig

Load experiment configuration from an INI file.

Parameters:

  • config_path (str | Path) –

    Path to the experiment config INI file.

Returns:

start_experiment async #

start_experiment(exp_name: str, czi_name: str, overwrite: bool = False, zenapi_config: str | Path = 'config.ini') -> tuple[str, Path]

Start a ZEN experiment via the ZEN-API.

Parameters:

  • exp_name (str) –

    Experiment name (without .czexp extension).

  • czi_name (str) –

    Desired CZI output name (without .czi extension).

  • overwrite (bool, default: False ) –

    Allow overwriting an existing CZI.

  • zenapi_config (str | Path, default: 'config.ini' ) –

    Path to the ZEN-API config file.

Returns:

  • tuple[str, Path] –

    Tuple of (experiment_id, czi_path).

start_loaded_experiment async #

start_loaded_experiment(service: ExperimentServiceStub, experiment_id: str, czi_name: str, overwrite: bool = False) -> Path

Start an already loaded experiment without changing its identity.

Parameters:

  • service (ExperimentServiceStub) –

    Connected ZEN experiment service.

  • experiment_id (str) –

    ID obtained before arming pixel subscriptions.

  • czi_name (str) –

    Output name without the CZI extension.

  • overwrite (bool, default: False ) –

    Allow replacement of an existing CZI file.

Returns:

  • Path –

    Path to the experiment's CZI output.

build_progress_bar #

build_progress_bar(current: int, total: int | None, width: int = 40) -> str

Render a text progress bar string.

Parameters:

  • current (int) –

    Current frame number (1-based).

  • total (int | None) –

    Total expected frames, or None if unknown.

  • width (int, default: 40 ) –

    Character width of the bar.

Returns:

  • str –

    Formatted progress bar string.

open_in_ndv_viewer #

open_in_ndv_viewer(zarr_path: Path) -> None

Open an OME-ZARR dataset in the ndv viewer.

Reads axis names (T, C, Z, Y, X) and per-axis scales from the OME-ZARR 0.5 metadata stored in zarr.json and wraps the highest-resolution array as a dask-backed xr.DataArray with physically-spaced coordinates so that ndv shows correct proportions (including Z depth) and labelled sliders.

Requires optional dependencies: ndv, zarr, dask, xarray. If any are missing the function logs a warning and returns silently.

Parameters:

  • zarr_path (Path) –

    Path to the .ome.zarr directory.

open_in_napari_viewer #

open_in_napari_viewer(zarr_path: Path) -> None

Open an OME-ZARR dataset in the napari viewer.

Uses the napari-ome-zarr plugin to read the dataset with full OME-ZARR metadata support (channels, scales, axis labels).

Requires optional dependencies: napari and napari-ome-zarr. If any are missing the function logs a warning and returns silently.

Parameters:

  • zarr_path (Path) –

    Path to the .ome.zarr directory.

read_omezarr_axis_names #

read_omezarr_axis_names(zarr_path: Path) -> tuple[str, ...] | None

Read axis names from the first OME-ZARR 0.5 image metadata.

OME-ZARR 0.5 (zarr v3) stores the multiscales metadata inside zarr.json → attributes.ome.multiscales, unlike OME-ZARR 0.4 which used .zattrs.

Parameters:

  • zarr_path (Path) –

    Path to the .ome.zarr directory.

Returns:

  • tuple[str, ...] | None –

    Tuple of uppercase axis names (e.g. ('T', 'C', 'Z', 'Y', 'X')),

  • tuple[str, ...] | None –

    or None if the metadata cannot be read.

read_omezarr_axis_scales #

read_omezarr_axis_scales(zarr_path: Path) -> dict[str, float] | None

Read scale factors from the first OME-ZARR 0.5 image metadata.

The scale transform is stored in zarr.json → attributes.ome.multiscales[0].datasets[0].coordinateTransformations as a list entry with {"type": "scale", "scale": [s0, s1, ...]}. The scale values are ordered to match the axes list.

Parameters:

  • zarr_path (Path) –

    Path to the .ome.zarr directory.

Returns:

  • dict[str, float] | None –

    Dict mapping uppercase axis name to its scale factor,

  • dict[str, float] | None –

    or None if the metadata cannot be read.

find_image_paths #

find_image_paths(zarr_path: str | Path) -> list[Path]

Find regular or HCS image groups containing multiscales metadata.

generate_pyramids #

generate_pyramids(zarr_path: str | Path, pyramid_levels: int, spatial_shard_size_chunks: int | None = 2) -> None

Append Y/X pyramid levels without rewriting level 0.