streaming

zen_api_utils.streaming

Headless ZEN API pixel-streaming and OME-Zarr helpers.

Modules:

• acquisition –

  Streaming-facing imports for shared acquisition metadata.

• frames –

  Decode and validate ZEN pixel-stream payloads.

• geometry –

  Coordinate-based geometry for streamed image tiles.

• metrics –

  Pure throughput metrics for ZEN pixel-stream measurements.

• omezarr –
• pipeline –

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

• receiver –

  Asynchronous helpers for ZEN pixel-stream consumers.

Classes:

• AcquisitionChannel –

  An active acquisition channel.

• AcquisitionDimensions –

  Acquisition axes known before pixel streaming starts.

• ExperimentAcquisition –

  Small typed snapshot of the acquisition settings used by streaming.

• PlacedTile –

  Tile geometry resolved against a scene mosaic canvas.

• SceneGeometry –

  Shape and physical origin of a rasterized scene mosaic.

• TileGeometry –

  Physical geometry for one streamed image tile.

• IntervalResult –

  Throughput accumulated over one reporting interval.

Functions:

• decode_frame –

  Decode a row-major grayscale payload with a caller-supplied dtype.

• decode_pixel_payload –

  Decode a ZEN payload using its protocol pixel type metadata.

• runtime_grayscale_dtype –

  Return and validate the dtype reported by a streamed grayscale frame.

• assemble_channel_scene_mosaics –

  Merge (scene, time, tile, z, image) records into an STZYX array.

• calculate_scene_geometry –

  Calculate mosaic placement from arbitrary tile center positions.

• calculate_interval –

  Calculate rates for an interval using monotonic nanosecond timestamps.

AcquisitionChannel dataclass

AcquisitionChannel(name: str | None, pixel_type: str | None)

An active acquisition channel.

AcquisitionDimensions dataclass

AcquisitionDimensions(time_points: int, channels: int, z_planes: int, scenes: int, z_spacing: float = 1.0, tiles: int = 1, pixel_width: int | None = None, pixel_height: int | None = None)

Acquisition axes known before pixel streaming starts.

ExperimentAcquisition dataclass

ExperimentAcquisition(experiment_name: str | None, dimensions: AcquisitionDimensions, channels_info: tuple[AcquisitionChannel, ...], positions: tuple[dict[str, object], ...], split_scenes_in_separate_files: bool)

Small typed snapshot of the acquisition settings used by streaming.

Attributes:

• well_ids (tuple[str, ...]) –

  Unique sample-carrier well IDs in acquisition order.

• well_count (int) –

  Number of sample-carrier wells used for acquisition.

• position_count (int) –

  Number of active acquisition positions/scenes.

well_ids property

well_ids: tuple[str, ...]

Unique sample-carrier well IDs in acquisition order.

well_count property

well_count: int

Number of sample-carrier wells used for acquisition.

position_count property

position_count: int

Number of active acquisition positions/scenes.

PlacedTile dataclass

PlacedTile(tile: TileGeometry, y_offset: int, x_offset: int, translation_y: float, translation_x: float)

Tile geometry resolved against a scene mosaic canvas.

SceneGeometry dataclass

SceneGeometry(height: int, width: int, origin_y: float, origin_x: float, scale_y: float, scale_x: float, tiles: tuple[PlacedTile, ...])

Shape and physical origin of a rasterized scene mosaic.

TileGeometry dataclass

TileGeometry(scene_index: int, tile_index: int, position_index: int, center_x: float, center_y: float, position_z: float, scale_x: float, scale_y: float, height: int, width: int)

Physical geometry for one streamed image tile.

IntervalResult dataclass

IntervalResult(elapsed_seconds: float, interval_seconds: float, total_frames: int, interval_frames: int, total_bytes: int, interval_bytes: int, frames_per_second: float, mebibytes_per_second: float, megapixels_per_second: float, mean_reshape_microseconds: float)

Throughput accumulated over one reporting interval.

decode_frame

decode_frame(raw_data: bytes, dtype: dtype, width: int, height: int) -> np.ndarray

Decode a row-major grayscale payload with a caller-supplied dtype.

decode_pixel_payload

decode_pixel_payload(raw_data: bytes, width: int, height: int, pixel_type: PixelType) -> np.ndarray

Decode a ZEN payload using its protocol pixel type metadata.

runtime_grayscale_dtype

runtime_grayscale_dtype(pixel_type: PixelType, payload_size: int, width: int, height: int) -> np.dtype

Return and validate the dtype reported by a streamed grayscale frame.

assemble_channel_scene_mosaics

assemble_channel_scene_mosaics(channel_frames: list[tuple[int, int, int, int, ndarray]], tile_geometries: dict[tuple[int, int], TileGeometry]) -> np.ndarray

Merge (scene, time, tile, z, image) records into an STZYX array.

calculate_scene_geometry

calculate_scene_geometry(tiles: list[TileGeometry]) -> SceneGeometry

Calculate mosaic placement from arbitrary tile center positions.

calculate_interval

calculate_interval(measurement_start_ns: int, interval_start_ns: int, now_ns: int, total_frames: int, interval_frames: int, total_bytes: int, interval_bytes: int, interval_pixels: int, interval_reshape_ns: int) -> IntervalResult

Calculate rates for an interval using monotonic nanosecond timestamps.