Napari

We add support to Napari software by providing conversion helpers and viewer instanciers to visualize ByoTrack data within Napari.

Note

This requires Napari to be installed and accessible in the python environment.

byotrack.napari.utils.detections_to_napari_segmentation(detections_sequence: Sequence[byotrack.Detections]) → np.ndarray

Convert detections data to a segmentation array compatible with Napari labels layer.

Parameters:

detections_sequence (Sequence[byotrack.Detections]) – Sequence of T detections (one per frame). All detections are expected to share the same spatial shape.

Returns:

Instance segmentation video built by stacking each frame segmentation.

Shape: (T, [D, ]H, W), dtype: uint16

Return type:

np.ndarray

byotrack.napari.utils.detections_to_napari_points(detections_sequence: Sequence[byotrack.Detections]) → np.ndarray

Convert detections data to a points array compatible with Napari points layer.

Parameters:

detections_sequence (Sequence[byotrack.Detections]) – Sequence of T detections (one per frame).

Returns:

Points with their frame index prepended to their position ([t, [k, ]i, j]).

Shape: (N, dim + 1), dtype: float32, where N is the total number of detections.

Return type:

np.ndarray

byotrack.napari.utils.tracks_to_napari_tracks(tracks: Collection[byotrack.Track]) → tuple[np.ndarray, dict[int, list[int]], np.ndarray]

Convert tracks data to Napari tracks layer format (points, graph, lineage_ids).

NaN positions (undetected frames within a track) are dropped from the resulting points.

Parameters:

tracks (Collection[byotrack.Track]) – Tracks to convert.

Returns:

(points, graph, lineage_ids)

points (np.ndarray): Points with track identifier and frame index prepended to their

position ([identifier, t, [k, ]i, j]), as expected by Napari’s add_tracks. Shape: (N, dim + 2), dtype: float32

graph (dict[int, list[int]]): Mapping of each track identifier to the list of its parent

track identifiers (split and merge events), as expected by Napari’s add_tracks.

lineage_ids (np.ndarray): Lineage identifier of each point in points, shared by all tracks

that are connected (through splits/merges) in the same lineage tree. Shape: (N,), dtype: uint16

Return type:

tuple

byotrack.napari.utils.precompute_optical_flow(video: Sequence[np.ndarray] | np.ndarray, optflow: byotrack.OpticalFlow) → tuple[list[np.ndarray], list[np.ndarray]]

Precompute bidirectional optical flow maps between each pair of consecutive frames.

Parameters:

• video (Sequence[np.ndarray] | np.ndarray) – Sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C)

• optflow (byotrack.OpticalFlow) – Optical flow algorithm used to preprocess frames and compute the flow maps.

Returns:

(forward_flows, backward_flows)

forward_flows (list[np.ndarray]): Flow map from frame t to frame t+1, for each of the

T - 1 consecutive frame pairs.

backward_flows (list[np.ndarray]): Flow map from frame t+1 to frame t, for each of the

T - 1 consecutive frame pairs.

Return type:

tuple

byotrack.napari.viewer.add_video(viewer: napari.Viewer, video: Sequence[np.ndarray] | np.ndarray, *, anisotropy: tuple[float, float, float] = (1.0, 1.0, 1.0), rgb=True, lazy: bool = False) → None

Add a video to a Napari viewer.

Parameters:

• viewer (napari.Viewer) – Napari viewer to add the video to.

• video (Sequence[np.ndarray] | np.ndarray) – Sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C)

• anisotropy (tuple[float, float, float]) – Spatial anisotropy ([Z, ]Y, X) used to scale the layer. Default: (1.0, 1.0, 1.0)

• rgb (bool) – If True and the video has 3 or 4 channels, add it as a single RGB(A) layer. Otherwise, add one grayscale layer per channel. Default: True

• lazy (bool) – If True, frames are read from video on demand (one frame at a time) instead of loading the whole video into memory upfront. Requires video to be a byotrack.Video. Please be aware, that for advanced napari usage (e.g. swapped temporal axis), this may fail. Default: False

byotrack.napari.viewer.add_detections(viewer: napari.Viewer, detections_sequence: Sequence[byotrack.DetectionsLike] = (), *, anisotropy: tuple[float, float, float] = (1.0, 1.0, 1.0), detections_mode: Literal['segmentation', 'points'] = 'segmentation', detection_size=10.0, lazy: bool = False) → None

Add detections to a Napari viewer.

Parameters:

• viewer (napari.Viewer) – Napari viewer to add the detections to.

• detections_sequence (Sequence[byotrack.DetectionsLike]) – Sequence of T detections (one per frame, sorted in time). Default: () (No detections)

• anisotropy (tuple[float, float, float]) – Spatial anisotropy ([Z, ]Y, X) used to scale the layer. Default: (1.0, 1.0, 1.0)

• detections_mode (Literal["segmentation", "points"]) – Whether to display detections as an instance segmentation (labels layer) or as points (points layer). Default: “segmentation”

• detection_size (float) – Size of the points, when detections_mode is “points”. Default: 10.0

• lazy (bool) – If True in “segmentation” mode, detections are read from detections_sequence on demand (one frame at a time) instead of loading the whole segmentation into memory upfront. Please be aware, that for advanced napari usage (e.g. label edition, swapped temporal axis), this may fail. Default: False

byotrack.napari.viewer.add_tracks(viewer: napari.Viewer, tracks: Collection[byotrack.Track], *, anisotropy: tuple[float, float, float] = (1.0, 1.0, 1.0), track_width=5.0) → None

Add tracks to a Napari viewer.

Adds a points layer for the tracked points at the current frame, and a tracks layer showing the trails of each track (including splits and merges).

Parameters:

• viewer (napari.Viewer) – Napari viewer to add the tracks to.

• tracks (Collection[byotrack.Track]) – Tracks to display.

• anisotropy (tuple[float, float, float]) – Spatial anisotropy ([Z, ]Y, X) used to scale the layer. Default: (1.0, 1.0, 1.0)

• track_width (float) – Size of the tracked points and width of the track trails. Default: 5.0

byotrack.napari.viewer.add_optical_flow(viewer: napari.Viewer, video: Sequence[np.ndarray] | np.ndarray, optflow: byotrack.OpticalFlow, *, grid_step: int = 20, display_grid: bool = True, size: int = 5, anisotropy: tuple[float, float, float] = (1.0, 1.0, 1.0), forward_flows: Sequence[np.ndarray] = (), backward_flows: Sequence[np.ndarray] = ()) → None

Add an optical flow grid visualization to a Napari viewer.

Displays a deformable grid of points (and optionally the edges linking them) that is warped by the optical flow as the temporal slider is scrubbed, forward or backward. If the flow maps are not (fully) precomputed, they are first pre-computed with _precompute_optical_flow.

Press ‘g’ to reset the grid to a uniform distribution at the current frame.

Parameters:

• viewer (napari.Viewer) – Napari viewer to add the visualization to.

• video (Sequence[np.ndarray] | np.ndarray) – Sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C)

• optflow (byotrack.OpticalFlow) – Optical flow algorithm used to (pre)compute and apply the flow.

• grid_step (int) – Spacing (in scaled/world units) between two consecutive grid control points. Default: 20

• display_grid (bool) – If True, also draw the edges linking the grid points (wireframe). Note that this may slow down the visualization with large grids. Default: True

• size (int) – Size of the grid points. Default: 5

• anisotropy (tuple[float, float, float]) – Spatial anisotropy ([Z, ]Y, X) used to scale the layers. Default: (1.0, 1.0, 1.0)

• forward_flows (Sequence[np.ndarray]) – Precomputed flow maps from frame t to frame t+1, for each of the T - 1 consecutive frame pairs. If shorter than video, all flows are recomputed. Default: () (Flows are computed from video)

• backward_flows (Sequence[np.ndarray]) – Precomputed flow maps from frame t+1 to frame t, for each of the T - 1 consecutive frame pairs. If shorter than video, all flows are recomputed. Default: () (Flows are computed from video)

byotrack.napari.viewer.visualize(video: Sequence[np.ndarray] | np.ndarray = (), detections_sequence: Sequence[byotrack.DetectionsLike] = (), tracks: Collection[byotrack.Track] = (), *, anisotropy: tuple[float, float, float] = (1.0, 1.0, 1.0), rgb=True, lazy: bool = False, detections_mode: Literal['segmentation', 'points'] = 'segmentation', detection_size=10.0, track_width=5.0, run=True) → napari.Viewer

Open a Napari viewer to visualize a video, detections and/or tracks.

Any combination of video, detections_sequence and tracks can be given (at least one is required). When several are given, they are expected to share the same dimension (2D or 3D).

Parameters:

• video (Sequence[np.ndarray] | np.ndarray) – Optional sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C) Default: () (No video)

• detections_sequence (Sequence[byotrack.DetectionsLike]) – Optional sequence of T detections (one per frame, sorted in time). Default: () (No detections)

• tracks (Collection[byotrack.Track]) – Optional tracks. Default: () (No tracks)

• anisotropy (tuple[float, float, float]) – Spatial anisotropy ([Z, ]Y, X) used to scale the layers. Default: (1.0, 1.0, 1.0)

• rgb (bool) – If True and the video has 3 or 4 channels, add it as a single RGB(A) layer. Otherwise, add one grayscale layer per channel. Default: True

• lazy (bool) – If True, video frames and detections are read on demand instead of loading the whole video into memory upfront. Requires video to be a byotrack.Video. See add_video, add_detections. Please be aware, that for advanced napari usage (e.g. label edition, swapped temporal axis), this may fail. Default: False

• detections_mode (Literal["segmentation", "points"]) – Whether to display detections as an instance segmentation (labels layer) or as points (points layer). Default: “segmentation”

• detection_size (float) – Size of the points, when detections_mode is “points”. Default: 10.0

• track_width (float) – Size of the tracked points and width of the track trails. Default: 5.0

• run (bool) – If True, blocks and starts the Napari Qt event loop (napari.run()). Default: True

Returns:

The created Napari viewer.

Return type:

napari.Viewer

byotrack.napari.viewer.visualize_flow_deformation(video: Sequence[np.ndarray] | np.ndarray, optflow: byotrack.OpticalFlow, *, anisotropy: tuple[float, float, float] = (1.0, 1.0, 1.0), grid_step: int = 20, display_grid: bool = True, size: int = 5, forward_flows: Sequence[np.ndarray] = (), backward_flows: Sequence[np.ndarray] = (), rgb=True, run=True) → napari.Viewer

Open a Napari viewer to visualize a video together with its optical flow deformation grid.

Parameters:

• video (Sequence[np.ndarray] | np.ndarray) – Sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C)

• optflow (byotrack.OpticalFlow) – Optical flow algorithm used to (pre)compute and apply the flow.

• grid_step (int) – Spacing (in scaled/world units) between two consecutive grid control points. Default: 20

• display_grid (bool) – If True, also draw the edges linking the grid points (wireframe). Default: True

• size (int) – Size of the grid points. Default: 5

• anisotropy (tuple[float, float, float]) – Spatial anisotropy ([Z, ]Y, X) used to scale the layers. Default: (1.0, 1.0, 1.0)

• forward_flows (Sequence[np.ndarray]) – Precomputed flow maps from frame t to frame t+1, for each of the T - 1 consecutive frame pairs. If shorter than video, all flows are recomputed. Default: () (Flows are computed from video)

• backward_flows (Sequence[np.ndarray]) – Precomputed flow maps from frame t+1 to frame t, for each of the T - 1 consecutive frame pairs. If shorter than video, all flows are recomputed. Default: () (Flows are computed from video)

• rgb (bool) – If True and the video has 3 or 4 channels, add it as a single RGB(A) layer. Otherwise, add one grayscale layer per channel. Default: True

• run (bool) – If True, blocks and starts the Napari Qt event loop (napari.run()). Default: True

Returns:

The created Napari viewer.

Return type:

napari.Viewer