clearex.visualization.napari

Functions

`annotate_frame_with_component_legend`(...[, ...])	Annotate a screenshot with a component title and layer legend.
`create_viewer`(*[, dimensions, show])	Create and return a new napari viewer instance.
`get_viewer_perspective`(viewer)	Get the current camera perspective and time step from a napari viewer.
`load_tracks`(data_path)	Load detections and tracks for napari visualization.
`lut_strip_for_layer`(layer[, width, height, ...])	Render a compact LUT preview strip for a napari image layer.
`make_black_background_transparent`(frame_rgba_u8)	Set alpha=0 where the RGB is near-black (<= thresh in all channels).
`make_component_movie_frames`(viewer, data, ...)	Render a per-component turntable animation sequence to disk.
`representative_rgba_from_image_layer`(layer)	Estimate a representative RGBA display color for an image layer.
`representative_text_rgba_for_layer`(layer[, ...])	Pick a readable RGBA text color from a layer colormap.
`save_frame`(viewer, out_path, comp, groups[, ...])	Capture and annotate a single viewer frame.
`set_viewer_size_for_layer`(viewer, layer_name)	Resize napari viewer and canvas to match a layer's lateral extent.
`spin_azimuth`(viewer[, n_frames, seconds, ...])	Animate a full azimuth sweep around the current scene.
`update_viewer`(viewer[, angles, zoom, ...])	Update the napari viewer's camera perspective and time step.

clearex.visualization.napari.load_tracks(data_path)

Load detections and tracks for napari visualization.

This helper reads two CSV files written by the crop_analysis pipeline located under <data_path>/crop_analysis/: detections.csv and tracks.csv. The detections table must contain the columns t, z, y, x and may include per-detection properties such as amp and int. The tracks table is expected to be a comma-separated numeric table with either 4 columns (2D: t, y, x) or 5 columns (3D: t, z, y, x).

Parameters:

data_path (str or os.PathLike) – Path to the dataset folder that contains the crop_analysis subdirectory with the expected CSV files.

Returns:

detection_data (numpy.ndarray) – Array of per-detection coordinates with shape (N, 4) and columns [t, z, y, x].
detection_data_2D (numpy.ndarray) – Array of per-detection coordinates projected to 2D with shape (N, 3) and columns [t, y, x].
tracks_data (numpy.ndarray) – Track table after removing masked (invalid) rows. Shape is (M, 4) or (M, 5) depending on whether tracks are 2D or 3D.
tracks_data_2d (numpy.ndarray) – Track table converted to 2D by removing the z column (if present).
properties (dict) – Dictionary of per-detection properties (e.g. {'amp': array, 'int': array}).

Raises:

FileNotFoundError – If either detections.csv or tracks.csv are missing.
KeyError – If required columns are missing from detections.csv.

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray, Dict[str, ndarray]]

Notes

The function will raise a KeyError if the expected detection columns t, z, y, x are not present. The tracks loader is tolerant of single-row files (np.loadtxt returns a 1-D array in that case) and will reshape as needed.

clearex.visualization.napari.create_viewer(*, dimensions=3, show=True)

Create and return a new napari viewer instance.

Parameters:

dimensions (int, optional) – Number of spatial dimensions for the viewer (2 or 3), by default 3.
show (bool, optional) – Whether to display the viewer window immediately, by default True.

Returns:

A new napari viewer instance.

Return type:

napari.Viewer

clearex.visualization.napari.set_viewer_size_for_layer(viewer, layer_name, match_native_pixels=True, scale=1, extra_width=200, extra_height=50)

Resize napari viewer and canvas to match a layer’s lateral extent.

Parameters:

viewer (napari.Viewer) – The napari viewer instance to resize.
layer_name (str) – Name of an image layer already added to the viewer.
match_native_pixels (bool, optional) – If True, make canvas at least as many pixels as the image XY dims. Default is True.
scale (int, optional) – Integer scale multiplier to enlarge further. Default is 1.
extra_width (int, optional) – Allowance for sidebars/window decoration in pixels. Default is 200.
extra_height (int, optional) – Allowance for window decoration in pixels. Default is 50.

Returns:

Target canvas dimensions (width, height) if successful, or None if sizing could not be applied to the inner canvas.

Return type:

Optional[Tuple[int, int]]

Raises:

ValueError – If the layer has fewer than 2 spatial dimensions.

clearex.visualization.napari.update_viewer(viewer, angles=None, zoom=None, center=None, time=None)

Update the napari viewer’s camera perspective and time step.

Parameters:

viewer (napari.Viewer) – The napari viewer instance to update.
angles (Tuple[float, float, float] | None) – Camera rotation angles (azimuth, elevation, roll) in degrees.
zoom (float | None) – Camera zoom level.
center (Tuple[float, float, float] | None) – Camera center point coordinates (z, y, x).
time (int | None) – Time step index to set in the viewer dimensions.

Return type:

None

clearex.visualization.napari.get_viewer_perspective(viewer)

Get the current camera perspective and time step from a napari viewer.

Parameters:

viewer (napari.Viewer) – The napari viewer instance to query.

Returns:

angle (Tuple[float, float, float]) – Camera rotation angles (azimuth, elevation, roll) in degrees.
zoom (float) – Camera zoom level.
center (Tuple[float, float, float]) – Camera center point coordinates (z, y, x).
step (List[int]) – Current dimension step indices.
time (int) – Time step index (first element of step).

Return type:

Tuple[Tuple[float, float, float], float, Tuple[float, float, float], List[int], int]

clearex.visualization.napari.spin_azimuth(viewer, n_frames=180, seconds=6.0, save_dir=None, prefix='az_spin')

Animate a full azimuth sweep around the current scene.

Parameters:

viewer (napari.Viewer) – Viewer whose camera should orbit around the scene.
n_frames (int, default=180) – Number of rendered camera positions across the 360 degree sweep.
seconds (float, default=6.0) – Total sweep duration in seconds.
save_dir (str or os.PathLike, optional) – Directory where PNG frames are written. If omitted, frames are not saved to disk.
prefix (str, default="az_spin") – Filename prefix used when saving frames.

Returns:

Active timer driving the animation.

Return type:

qtpy.QtCore.QTimer

clearex.visualization.napari.lut_strip_for_layer(layer, width=140, height=10, alpha=0.6)

Render a compact LUT preview strip for a napari image layer.

Parameters:

layer (napari.layers.Layer) – Layer whose colormap should be visualized.
width (int, default=140) – Output strip width in pixels.
height (int, default=10) – Output strip height in pixels.
alpha (float, default=0.6) – Alpha multiplier applied to the generated strip.

Returns:

RGBA lookup-table image with shape (height, width, 4).

Return type:

numpy.ndarray

clearex.visualization.napari.representative_text_rgba_for_layer(layer, u=0.85, alpha=0.85)

Pick a readable RGBA text color from a layer colormap.

Parameters:

layer (napari.layers.Layer) – Layer whose display colormap should be sampled.
u (float, default=0.85) – Position along the normalized colormap range used for sampling.
alpha (float, default=0.85) – Output alpha in the 0..1 range.

Returns:

RGBA color in 8-bit integer form.

Return type:

tuple of int

clearex.visualization.napari.representative_rgba_from_image_layer(layer, q=0.90, sample_max=200_000, fallback_x=0.85)

Estimate a representative RGBA display color for an image layer.

Parameters:

layer (napari.layers.Layer) – Layer whose display mapping should be sampled.
q (float, default=0.90) – Quantile of normalized in-range intensities used for colormap lookup.
sample_max (int, default=200000) – Maximum number of pixels sampled from the layer.
fallback_x (float, default=0.85) – Fallback normalized position used when the layer has no finite in-range pixels.

Returns:

RGBA tuple in the 0..1 range, or None when the layer has no colormap.

Return type:

tuple of float or None

clearex.visualization.napari.make_black_background_transparent(frame_rgba_u8, thresh=2)

Set alpha=0 where the RGB is near-black (<= thresh in all channels). This makes the “empty” canvas transparent for PowerPoint/figures.

Parameters:

frame_rgba_u8 (ndarray) –
thresh (int) –

Return type:

ndarray

clearex.visualization.napari.annotate_frame_with_component_legend(frame_rgba_u8, viewer, component, label_names, x=20, y=20, title_rgba=(255, 255, 255, 255), box_rgba=(0, 0, 0, 140), draw_lut=True, transparent_background=False, bg_thresh=2, z_idx=None)

Annotate a screenshot with a component title and layer legend.

Parameters:

frame_rgba_u8 (numpy.ndarray) – Input frame in RGB/RGBA form.
viewer (napari.Viewer) – Viewer used to resolve layer colors and LUT previews.
component (str) – Name of the component being rendered.
label_names (list of str) – Layer names shown in the legend.
x (int, default=20) – Left pixel coordinate of the legend box.
y (int, default=20) – Top pixel coordinate of the legend box.
title_rgba (tuple of int, default=(255, 255, 255, 255)) – RGBA color for the title text.
box_rgba (tuple of int, default=(0, 0, 0, 140)) – RGBA fill color for the legend background.
draw_lut (bool, default=True) – If True, draw a short LUT strip beside each label.
transparent_background (bool, default=False) – If True, near-black pixels are made transparent before annotation.
bg_thresh (int, default=2) – Threshold used when making black backgrounds transparent.
z_idx (int, optional) – Z index to print beneath the title.

Returns:

Annotated RGBA frame.

Return type:

numpy.ndarray

clearex.visualization.napari.save_frame(viewer, out_path, comp, groups, transparent_background=True, z_idx=None)

Capture and annotate a single viewer frame.

Parameters:

viewer (napari.Viewer) – Viewer to capture.
out_path (str) – Destination PNG path.
comp (str) – Component name shown in the legend.
groups (dict) – Mapping of component name to displayed label names.
transparent_background (bool, default=True) – If True, remove black background pixels before saving.
z_idx (int, optional) – Z index to print in the legend.

Returns:

Writes the annotated frame to disk.

Return type:

None

clearex.visualization.napari.make_component_movie_frames(viewer, data, groups, out_dir, components, frames_per_component=90, transition_frames=12, anchor_labels=('Nuclei',), anchor_opacity=0.20, hide_when_zero=True, initial_angles=None, initial_zoom=None, initial_center=None)

Render a per-component turntable animation sequence to disk.

Parameters:

viewer (napari.Viewer) – Viewer containing the layers to animate.
data (dict) – Mapping of layer name to configuration dictionaries containing opacity metadata.
groups (dict) – Mapping of component name to the layer names that define that component.
out_dir (str) – Output directory that will receive a frames subdirectory.
components (list of str) – Ordered list of components to render.
frames_per_component (int, default=90) – Number of orbit frames rendered for each component.
transition_frames (int, default=12) – Number of fade frames inserted between components.
anchor_labels (tuple of str, default=("Nuclei",)) – Labels kept dimly visible throughout the sequence.
anchor_opacity (float, default=0.20) – Opacity used for anchor labels.
hide_when_zero (bool, default=True) – If True, layers reaching zero opacity are hidden.
initial_angles (tuple of float, optional) – Initial camera angles (elevation, azimuth, roll).
initial_zoom (float, optional) – Initial camera zoom.
initial_center (tuple of float, optional) – Initial camera center.

Returns:

Path to the directory containing rendered frame PNGs.

Return type:

str