clearex.visualization.pipeline

Napari visualization workflow for canonical ClearEx analysis stores.

Functions

run_compile_movie_analysis(*, zarr_path, ...)

Compile rendered PNG frames into movie files with ffmpeg.

run_display_pyramid_analysis(*, zarr_path, ...)

Prepare reusable display pyramids and stored display contrast metadata.

run_render_movie_analysis(*, zarr_path, ...)

Render smooth frame sequences from captured napari keyframes.

run_visualization_analysis(*, zarr_path, ...)

Run napari visualization on canonical ClearEx analysis data.

Classes

BuiltNapariScene(viewer, renderer_info, ...)

Live napari viewer scene returned by the shared scene builder.

CompileMovieSummary(component, ...)

Summary metadata for one compile-movie run.

DisplayPyramidSummary(component, ...)

Summary metadata for one display-pyramid preparation run.

NapariLayerPayload(axis_labels_tczyx, ...)

Payload describing napari layer metadata and calibration.

PreparedVisualizationScene(...)

Prepared visualization context reusable across viewer entrypoints.

RenderMovieSummary(component, ...)

Summary metadata for one render-movie run.

ResolvedVolumeLayer(component, ...)

Resolved visualization layer configuration for one source component.

VisualizationSummary(component, ...[, ...])

Summary metadata for one visualization run.
class clearex.visualization.pipeline.VisualizationSummary(component, source_component, source_components, position_index, selected_positions, show_all_positions, overlay_points_count, launch_mode, viewer_pid, keyframe_manifest_path=None, keyframe_count=0, renderer=None, viewer_ndisplay_requested=3, viewer_ndisplay_effective=3, display_mode_fallback_reason=None)

Bases: object

Summary metadata for one visualization run.

Variables:

  • component (str) – Output component path inside the Zarr store.

  • source_component (str) – Source image component rendered in napari.

  • source_components (tuple[str, ...]) – Ordered source levels used for multiscale rendering.

  • position_index (int) – Reference position index from the p axis. When show_all_positions is False this is the single selected position. When True this is the first rendered position.

  • selected_positions (tuple[int, ...]) – Rendered position indices from the p axis.

  • show_all_positions (bool) – Whether all positions were rendered in one napari scene.

  • overlay_points_count (int) – Number of particle points overlaid in the viewer.

  • launch_mode (str) – Effective launch mode: in_process or subprocess.

  • viewer_pid (int, optional) – Spawned viewer process ID when subprocess launch mode is used.

  • keyframe_manifest_path (str, optional) – JSON path used to persist interactive keyframe selections.

  • keyframe_count (int) – Number of captured keyframes written to the manifest.

  • renderer (dict[str, Any], optional) – OpenGL renderer probe payload captured from napari context.

Parameters:

  • component (str) –

  • source_component (str) –

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

  • position_index (int) –

  • selected_positions (tuple[int, ...]) –

  • show_all_positions (bool) –

  • overlay_points_count (int) –

  • launch_mode (str) –

  • viewer_pid (Optional[int]) –

  • keyframe_manifest_path (Optional[str]) –

  • keyframe_count (int) –

  • renderer (Optional[Dict[str, Any]]) –

  • viewer_ndisplay_requested (int) –

  • viewer_ndisplay_effective (int) –

  • display_mode_fallback_reason (Optional[str]) –

component: str
source_component: str
source_components: tuple[str, ...]
position_index: int
selected_positions: tuple[int, ...]
show_all_positions: bool
overlay_points_count: int
launch_mode: str
viewer_pid: Optional[int]
keyframe_manifest_path: Optional[str] = None
keyframe_count: int = 0
renderer: Optional[Dict[str, Any]] = None
viewer_ndisplay_requested: int = 3
viewer_ndisplay_effective: int = 3
display_mode_fallback_reason: Optional[str] = None
class clearex.visualization.pipeline.RenderMovieSummary(component, visualization_component, keyframe_manifest_path, render_manifest_path, output_directory, rendered_levels, frame_count, fps)

Bases: object

Summary metadata for one render-movie run.

Parameters:

  • component (str) –

  • visualization_component (str) –

  • keyframe_manifest_path (str) –

  • render_manifest_path (str) –

  • output_directory (str) –

  • rendered_levels (tuple[int, ...]) –

  • frame_count (int) –

  • fps (int) –

component: str
visualization_component: str
keyframe_manifest_path: str
render_manifest_path: str
output_directory: str
rendered_levels: tuple[int, ...]
frame_count: int
fps: int
class clearex.visualization.pipeline.CompileMovieSummary(component, render_component, render_manifest_path, output_directory, rendered_level, output_format, compiled_files, fps)

Bases: object

Summary metadata for one compile-movie run.

Parameters:

  • component (str) –

  • render_component (str) –

  • render_manifest_path (str) –

  • output_directory (str) –

  • rendered_level (int) –

  • output_format (str) –

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

  • fps (int) –

component: str
render_component: str
render_manifest_path: str
output_directory: str
rendered_level: int
output_format: str
compiled_files: tuple[str, ...]
fps: int
class clearex.visualization.pipeline.DisplayPyramidSummary(component, source_component, source_components, channel_count, contrast_limits_by_channel, reused_existing_levels)

Bases: object

Summary metadata for one display-pyramid preparation run.

Variables:

  • component (str) – Latest output metadata group path for the task.

  • source_component (str) – Source component used to prepare the display pyramid.

  • source_components (tuple[str, ...]) – Ordered multiscale components registered for later visualization.

  • channel_count (int) – Number of source channels summarized for display contrast.

  • contrast_limits_by_channel (tuple[tuple[float, float], ...]) – Stored per-channel contrast limits derived from the fixed display percentiles.

  • reused_existing_levels (bool) – Whether the task reused existing levels instead of writing new ones.

Parameters:

  • component (str) –

  • source_component (str) –

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

  • channel_count (int) –

  • contrast_limits_by_channel (tuple[tuple[float, float], ...]) –

  • reused_existing_levels (bool) –

component: str
source_component: str
source_components: tuple[str, ...]
channel_count: int
contrast_limits_by_channel: tuple[tuple[float, float], ...]
reused_existing_levels: bool
class clearex.visualization.pipeline.NapariLayerPayload(axis_labels_tczyx, scale_tczyx, image_metadata, points_metadata)

Bases: object

Payload describing napari layer metadata and calibration.

Variables:

  • axis_labels_tczyx (tuple[str, str, str, str, str]) – Display axis labels for rendered arrays in (t, c, z, y, x) order.

  • scale_tczyx (tuple[float, float, float, float, float]) – Physical/index scaling factors for rendered arrays in (t, c, z, y, x) order.

  • image_metadata (dict[str, Any]) – Metadata payload attached to the napari image layer.

  • points_metadata (dict[str, Any]) – Metadata payload attached to the napari points layer.

Parameters:

  • axis_labels_tczyx (tuple[str, str, str, str, str]) –

  • scale_tczyx (tuple[float, float, float, float, float]) –

  • image_metadata (Dict[str, Any]) –

  • points_metadata (Dict[str, Any]) –

axis_labels_tczyx: tuple[str, str, str, str, str]
scale_tczyx: tuple[float, float, float, float, float]
image_metadata: Dict[str, Any]
points_metadata: Dict[str, Any]
class clearex.visualization.pipeline.ResolvedVolumeLayer(component, source_components, layer_type, channels, visible, opacity, blending, colormap, rendering, name, multiscale_policy, multiscale_status)

Bases: object

Resolved visualization layer configuration for one source component.

Variables:

  • component (str) – Base component path rendered by this layer.

  • source_components (tuple[str, ...]) – Ordered component paths for multiscale rendering, including base level.

  • layer_type (str) – Napari layer type: image or labels.

  • channels (tuple[int, ...]) – Requested channel indices. Empty means all available channels.

  • visible (bool, optional) – Explicit visibility override, or None to use napari defaults.

  • opacity (float, optional) – Explicit opacity override in [0, 1], or None for defaults.

  • blending (str) – Optional napari blending mode override.

  • colormap (str) – Optional colormap override for image layers.

  • rendering (str) – Optional rendering-style override for image layers.

  • name (str) – Optional layer base-name override.

  • multiscale_policy (str) – Layer multiscale policy: inherit, require, or off.

  • multiscale_status (str) – Effective multiscale outcome: off, existing, or single_scale.

Parameters:

  • component (str) –

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

  • layer_type (str) –

  • channels (tuple[int, ...]) –

  • visible (Optional[bool]) –

  • opacity (Optional[float]) –

  • blending (str) –

  • colormap (str) –

  • rendering (str) –

  • name (str) –

  • multiscale_policy (str) –

  • multiscale_status (str) –

component: str
source_components: tuple[str, ...]
layer_type: str
channels: tuple[int, ...]
visible: Optional[bool]
opacity: Optional[float]
blending: str
colormap: str
rendering: str
name: str
multiscale_policy: str
multiscale_status: str
class clearex.visualization.pipeline.PreparedVisualizationScene(normalized_parameters, volume_layers, selected_positions, reference_position_index, points_by_position, point_properties_by_position, total_overlay_points, source_component, source_components, viewer_ndisplay_requested, viewer_ndisplay_effective, display_mode_fallback_reason, napari_payload, position_affines_tczyx, spatial_calibration)

Bases: object

Prepared visualization context reusable across viewer entrypoints.

Parameters:

  • normalized_parameters (Dict[str, Any]) –

  • volume_layers (tuple[clearex.visualization.pipeline.ResolvedVolumeLayer, ...]) –

  • selected_positions (tuple[int, ...]) –

  • reference_position_index (int) –

  • points_by_position (Dict[int, ndarray]) –

  • point_properties_by_position (Dict[int, Dict[str, ndarray]]) –

  • total_overlay_points (int) –

  • source_component (str) –

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

  • viewer_ndisplay_requested (int) –

  • viewer_ndisplay_effective (int) –

  • display_mode_fallback_reason (Optional[str]) –

  • napari_payload (NapariLayerPayload) –

  • position_affines_tczyx (Dict[int, ndarray]) –

  • spatial_calibration (SpatialCalibrationConfig) –

normalized_parameters: Dict[str, Any]
volume_layers: tuple[clearex.visualization.pipeline.ResolvedVolumeLayer, ...]
selected_positions: tuple[int, ...]
reference_position_index: int
points_by_position: Dict[int, ndarray]
point_properties_by_position: Dict[int, Dict[str, ndarray]]
total_overlay_points: int
source_component: str
source_components: tuple[str, ...]
viewer_ndisplay_requested: int
viewer_ndisplay_effective: int
display_mode_fallback_reason: Optional[str]
napari_payload: NapariLayerPayload
position_affines_tczyx: Dict[int, ndarray]
spatial_calibration: SpatialCalibrationConfig
class clearex.visualization.pipeline.BuiltNapariScene(viewer, renderer_info, manifest_path, primary_source_component, primary_source_components, serialized_volume_layers, axis_labels_tczyx, scale_tczyx)

Bases: object

Live napari viewer scene returned by the shared scene builder.

Parameters:

  • viewer (Any) –

  • renderer_info (Dict[str, Any]) –

  • manifest_path (Optional[Path]) –

  • primary_source_component (str) –

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

  • serialized_volume_layers (list[Dict[str, Any]]) –

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

  • scale_tczyx (tuple[float, ...]) –

viewer: Any
renderer_info: Dict[str, Any]
manifest_path: Optional[Path]
primary_source_component: str
primary_source_components: tuple[str, ...]
serialized_volume_layers: list[Dict[str, Any]]
axis_labels_tczyx: tuple[str, ...]
scale_tczyx: tuple[float, ...]
clearex.visualization.pipeline.run_display_pyramid_analysis(*, zarr_path, parameters, client=None, progress_callback=None, run_id=None)

Prepare reusable display pyramids and stored display contrast metadata.

Parameters:

  • zarr_path (Union[str, Path]) –

  • parameters (Mapping[str, Any]) –

  • client (Optional[Any]) –

  • progress_callback (Optional[Callable[[int, str], None]]) –

  • run_id (Optional[str]) –

Return type:

DisplayPyramidSummary

clearex.visualization.pipeline.run_visualization_analysis(*, zarr_path, parameters, progress_callback=None, run_id=None)

Run napari visualization on canonical ClearEx analysis data.

Parameters:

  • zarr_path (str or pathlib.Path) – Path to canonical analysis-store Zarr object.

  • parameters (mapping[str, Any]) – Visualization parameters.

  • progress_callback (callable, optional) – Progress callback invoked as callback(percent, message).

  • run_id (str, optional) – Optional provenance run identifier.

Returns:

Summary including source selection and viewer-launch metadata.

Return type:

VisualizationSummary

Raises:

ValueError – If source component is missing or selected position is out of bounds.

clearex.visualization.pipeline.run_render_movie_analysis(*, zarr_path, parameters, progress_callback=None, run_id=None)

Render smooth frame sequences from captured napari keyframes.

Parameters:

  • zarr_path (str or pathlib.Path) – Canonical analysis-store path.

  • parameters (mapping[str, Any]) – Render-movie parameter mapping.

  • progress_callback (callable, optional) – Optional callback receiving (percent, message) progress updates.

  • run_id (str, optional) – Provenance run identifier when available.

Returns:

Summary of rendered frame sets and latest metadata paths.

Return type:

RenderMovieSummary

Raises:

  • ValueError – If required visualization metadata or keyframes are missing.

  • RuntimeError – If a render subprocess fails.

clearex.visualization.pipeline.run_compile_movie_analysis(*, zarr_path, parameters, progress_callback=None, run_id=None)

Compile rendered PNG frames into movie files with ffmpeg.

Parameters:

  • zarr_path (str or pathlib.Path) – Canonical analysis-store path.

  • parameters (mapping[str, Any]) – Compile-movie parameter mapping.

  • progress_callback (callable, optional) – Optional callback receiving (percent, message) progress updates.

  • run_id (str, optional) – Provenance run identifier when available.

Returns:

Summary of encoded movie outputs and latest metadata paths.

Return type:

CompileMovieSummary

Raises:

  • ValueError – If the render manifest or selected frame set is missing or invalid.

  • RuntimeError – If ffmpeg fails through the compile helpers.