Skip to content

streaming.pipeline#

zen_api_utils.streaming.pipeline #

Headless ZEN-API pixel streaming and OME-Zarr writing pipeline.

The module exposes reusable async functions and retains a command-line entry point for the example launcher and the installed package console script.

Classes:

Functions:

IncompleteAcquisitionError #

IncompleteAcquisitionError(zarr_path: Path, received_frames: int, expected_frames: int, report_path: Path)

Bases: RuntimeError

Expected acquisition frames are missing; partial output is retained.

generate_omezarr_pyramids #

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

Append Y/X pyramid levels after acquisition without rewriting level 0.

stream_to_omezarr async #

stream_to_omezarr(zenapi_config: str | Path, experiment_name: str, output_dir: str | Path, dtype: dtype | None = None, start_experiment_from_script: bool = False, czi_name: str = 'zenapi_stream', overwrite_czi: bool = True, channel_index: int | None = None, overwrite_zarr: bool = True, compression: str | None = 'blosc-zstd', spatial_shard_size_chunks: int | None = 2, inactivity_timeout: float = _STATUS_POLL_TIMEOUT) -> Path

Stream ZEN pixel data into an OME-ZARR file.

Parameters:

  • zenapi_config (str | Path) –

    Path to the ZEN-API gateway config.ini.

  • experiment_name (str) –

    ZEN experiment name (without .czexp).

  • output_dir (str | Path) –

    Folder where the OME-ZARR will be created.

  • dtype (dtype | None, default: None ) –

    Pixel data type (must match the experiment output).

  • start_experiment_from_script (bool, default: False ) –

    If True, start the experiment via API. If False, the user starts the experiment from the ZEN UI.

  • czi_name (str, default: 'zenapi_stream' ) –

    CZI output name when starting experiment from script.

  • overwrite_czi (bool, default: True ) –

    Allow overwriting an existing CZI.

  • channel_index (int | None, default: None ) –

    Optional channel filter index (None = all channels).

  • overwrite_zarr (bool, default: True ) –

    Overwrite an existing OME-ZARR at the output path.

  • compression (str | None, default: 'blosc-zstd' ) –

    Compression for ZARR ('blosc-zstd', 'blosc-lz4', 'zstd', 'none', or None).

  • spatial_shard_size_chunks (int | None, default: 2 ) –

    Number of chunks per Y/X shard, or None to disable Zarr v3 sharding.

  • inactivity_timeout (float, default: _STATUS_POLL_TIMEOUT ) –

    Maximum wait for another matching frame. Missing expected coordinates fail the acquisition.

Returns:

  • Path –

    Path to the created OME-ZARR directory.

Raises:

  • IncompleteAcquisitionError –

    Expected frames are missing. Partial data and a completion report are retained, without finalization.

stream_to_omezarr_with_config async #

stream_to_omezarr_with_config(ecfg: ExperimentConfig, inactivity_timeout: float = _STATUS_POLL_TIMEOUT) -> Path

Stream ZEN pixel data into OME-ZARR using exported experiment dimensions.

Export the selected experiment before opening channel subscriptions. The first matching frame supplies its pixel size and live dimensions; subsequent frames are written with bounded out-of-order buffering.

Parameters:

  • ecfg (ExperimentConfig) –

    Writer and experiment settings. Exported metadata replaces dimension hints without mutating this configuration object.

  • inactivity_timeout (float, default: _STATUS_POLL_TIMEOUT ) –

    Maximum wait for another matching frame.

Returns:

  • Path –

    Path to the created OME-ZARR directory.

Raises:

  • IncompleteAcquisitionError –

    Expected frames are missing. Partial data and a completion report are retained, without finalization.

parse_args #

parse_args() -> argparse.Namespace

Parse command-line arguments.

main #

main() -> None

Entry point: parse arguments, run the appropriate streaming mode, and open the viewer.