acia.viz#

Module for general visualization functionality

acia.viz.draw_scale_bar(image_iterator, xy_position, size_of_pixel, bar_width, bar_height, color=(255, 255, 255), font_size=25, font_path='/opt/hostedtoolcache/Python/3.10.21/x64/lib/python3.10/site-packages/matplotlib/mpl-data/fonts/ttf/DejaVuSans.ttf', background_color=None, background_margin_pixel=3)[source]#

Draws a scale bar on all images of an image sequence or iterable image array

Parameters:

  • image_iterator – image sequence or iterator over images

  • xy_position (tuple[int, int]) – lower left xy position of the scale bar

  • size_of_pixel (_type_) – metric size of a pixel (e.g. 0.007 * ureg.micrometer)

  • bar_width (_type_) – width of the scale bar (e.g. 5 * ureg.micrometer)

  • short_title (str, optional) – Short title of the unit to be displayed. Defaults to “μm”.

  • color (tuple, optional) – Color of scale bar and text. Defaults to (255, 255, 255).

  • font_size (int, optional) – text font size. Defaults to 25.

  • font_path (str, optional) – text font. Defaults to “/usr/share/fonts/truetype/dejavu/DejaVuSerif.ttf”.

  • background_color – color for a potential background rectangle (e.g. (0, 0, 0)). Defaults to None (no background drawn).

  • background_margin_pixel – pixels of margin for the background rectangle

Yields:

np.ndarray | LocalImage – Image in numpy format or LocalImage (depending on the input format)

acia.viz.draw_time(image_iterator, xy_position, time_step, color=(255, 255, 255), font_size=25, font_path='/opt/hostedtoolcache/Python/3.10.21/x64/lib/python3.10/site-packages/matplotlib/mpl-data/fonts/ttf/DejaVuSans.ttf', background_color=None, background_margin_pixel=3)[source]#

Draw time onto images

Parameters:

  • image_iterator (_type_) – image sequence or iterator over images

  • xy_position (tuple[int, int]) – lower left xy position of the time text

  • time_step (_type_) – time step between images (e.g. 15 * ureg.minute or “15 minute”)

  • color (_type) – Color of the time text. Defaults to (255, 255, 255) which is white.

  • font_size (int, optional) – text font size. Defaults to 25.

  • font_path (str, optional) – text font. Defaults to “/usr/share/fonts/truetype/dejavu/DejaVuSerif.ttf”.

  • background_color – color for a potential background rectangle (e.g. (0, 0, 0)). Defaults to None (no background drawn).

  • background_margin_pixel – pixels of margin for the background rectangle

Yields:

_type_ – _description_

class acia.viz.VideoExporter[source]#

Bases: object

Wrapper for opencv video writer. Simplifies usage

__init__(filename, framerate, codec='MJPG')[source]#
write(image)[source]#
close()[source]#
class acia.viz.VideoExporter2[source]#

Bases: object

Wrapper for opencv video writer. Simplifies usage

__init__(filename, framerate, codec='mjpeg', ffmpeg_params=None)[source]#
Parameters:
static default_vp9(filename, framerate)[source]#
Parameters:
static fast_vp9(filename, framerate)[source]#
Parameters:
static default_h264(filename, framerate)[source]#
Parameters:
static default_h265(filename, framerate)[source]#
Parameters:
static default_mjpg(filename, framerate)[source]#
Parameters:
write(image)[source]#
close()[source]#
acia.viz.render_segmentation(imageSource, overlay, cell_color=(255, 255, 0))[source]#

Render a video of the time-lapse including the segmentaiton information.

Parameters:

  • imageSource (ImageSequenceSource) – Your time-lapse source object.

  • Overlay ([type]) – Your source of RoIs for the image (e.g. cells).

  • cell_color – rgb color of the cell outlines

  • overlay (Overlay)

Return type:

ImageSequenceSource

acia.viz.render_cell_centers(image_source, overlay, center_color=(255, 255, 0), center_size=3)[source]#

Render a image sequence of the time-lapse with the cell centers.

Parameters:

  • imageSource (ImageSequenceSource) – Your time-lapse source object.

  • overlay (Overlay, optional) – Your source of RoIs for the image (e.g. cells).

  • center_color (tuple, optional) – RGB color of the cell center circle. Defaults to (255, 255, 0).

  • center_size (int, optional) – Radius of the cell center circle (in pixels). Defaults to 3.

  • image_source (ImageSequenceSource | ndarray)

Raises:

ValueError – If we recognize unsupported image type or format

Returns:

ImageSequenceSource – The rendered image sequence

Return type:

ImageSequenceSource

acia.viz.render_tracking(image_source, overlay, tracking_graph)[source]#

Render the tracking to an image source

Parameters:

  • image_source (ImageSequenceSource) – Image source

  • overlay (Overlay) – overla of cell detections (for center points)

  • tracking_graph (nx.DiGraph) – the tracking graph where every cell detection is a node in the graph.

Returns:

ImageSequenceSource – Rendered image source

Return type:

ImageSequenceSource

acia.viz.render_video(image_source, filename, framerate=10, codec='libx264', pixelformat='yuv420p', macro_block_size=2, ffmpeg_params=None)[source]#

Render video

Parameters:

  • image_source (ImageSequenceSource) – sequence of images

  • filename (str) – video filename

  • framerate (int) – framerate of the video

  • codec (str) – the codec for video encoding

  • pixelformat (str) – output pixel format. “yuv420p” is required by most browsers/players (e.g. Firefox rejects other chroma subsampling).

  • macro_block_size (int) – frame dimensions are padded up to a multiple of this value. imageio’s own default of 16 stretches typical (already-even) frame sizes noticeably; 2 is the minimum yuv420p allows and avoids that visible distortion.

  • ffmpeg_params (list[str] | None) – extra output ffmpeg arguments, applied in addition to “-movflags +faststart” (which moves the moov atom to the front of the file so it plays back in browsers instead of failing to load).

Return type:

None

acia.viz.render_scalebar(image_source, xy_position, size_of_pixel, bar_width, bar_height, color=(255, 255, 255), font_size=25, font_path='/opt/hostedtoolcache/Python/3.10.21/x64/lib/python3.10/site-packages/matplotlib/mpl-data/fonts/ttf/DejaVuSans.ttf', background_color=None, background_margin_pixel=3, show_text=True)[source]#

Draws a scale bar on all images of an image sequence or iterable image array

Parameters:

  • image_source (Overlay) – image sequence or iterator over images

  • xy_position (tuple[int, int]) – lower left xy position of the scale bar

  • size_of_pixel (pint.Quantity) – metric size of a pixel (e.g. 0.007 * ureg.micrometer)

  • bar_width (pint.Quantity) – width of the scalebar (e.g. 5 * ureg.micrometer). Also the text over the bar.

  • bar_height (pint.Quantity) – height of the scalebar.

  • color (tuple, optional) – Color of the scalebar and text. Defaults to (255, 255, 255).

  • font_size (int, optional) – font size of the text. Defaults to 25.

  • font_path (_type_, optional) – path to the font. Defaults to default_font.

  • background_color (tuple[int, int, int], optional) – Color of the background. None draws no background. Defaults to None.

  • background_margin_pixel (int, optional) – Margin of the background box. Defaults to 3.

  • show_text (bool, optional) – If true shows the bar width as text above the bar. Defaults to True.

Returns:

ImageSequenceSource – Rendered image sequence

Return type:

ImageSequenceSource

acia.viz.render_time(image_source, xy_position, timepoints, time_format='{H:02}h {M:02}m', color=(255, 255, 255), font_size=25, font_path='/opt/hostedtoolcache/Python/3.10.21/x64/lib/python3.10/site-packages/matplotlib/mpl-data/fonts/ttf/DejaVuSans.ttf', background_color=None, background_margin_pixel=3)[source]#

Draw time onto images

Parameters:

  • image_source (ImageSequenceSource) – image sequence of the time-lapse

  • xy_position (tuple[int]) – lower left xy position of the formatted time text

  • timepoints (list[pint.Quantity | timedelta]) – timepoints of the individual frames

  • time_format (str, optional) – Timeformat for rendering the time to the images. Defaults to “{H:02}h {M:02}m”.

  • color (tuple, optional) – Color of the time text. Defaults to (255, 255, 255).

  • font_size (int, optional) – Fontsize of the time text. Defaults to 25.

  • font_path (_type_, optional) – Path to the rendering font. Defaults to default_font.

  • background_color (tuple[int, int, int], optional) – Color of the background box. None does not draw any background box. Defaults to None.

  • background_margin_pixel (int, optional) – Margin of the background box. Defaults to 3.

Returns:

ImageSequenceSource – Rendered image sequence

Return type:

ImageSequenceSource

acia.viz.colorize_instance_mask(instance_mask, background_color=(0, 0, 0), seed=42, color_lut=None)[source]#

Convert instance mask to an RGB image with random colors per instance (no loop).

Parameters:

  • instance_mask (np.ndarray) – 2D array of shape (H, W) with integer instance IDs.

  • background_color (tuple) – RGB color for background (default black).

  • seed (int) – Random seed for consistent coloring.

  • color_lut (np.ndarray) – Ix3 lookup map for instance colors (I)

Returns:

np.ndarray – Colored mask of shape (H, W, 3), dtype=uint8.

Return type:

ndarray

acia.viz.get_mask(self, height, width, binary_mask=True)[source]#

Turn the individual overlays into masks. For every time point we create a mask of all contours.

returns: List of masks (np.array[bool])

height: height of the image width: width of the image

Return type:

ndarray

acia.viz.render_overlay_frame(image, overlay, frame_idx, alpha=0.8)[source]#

Render segmentation overlay on a single frame image with alpha blending.

This helper function applies a segmentation overlay to a single frame image, blending the colorized instance mask with the original image using alpha transparency. Used by Jupyter widget callbacks for interactive overlay rendering.

Parameters:

  • image (np.ndarray) – Single frame image in HxW or HxWxC format (uint8 or uint16).

  • overlay (Overlay) – Overlay object containing contours for the current frame (typically from overlay.time_iterator()).

  • frame_idx (int) – Frame index for reference (not directly used, for compatibility).

  • alpha (float, optional) – Alpha blending weight for the original image. Default 0.8 means 80% original image, 20% overlay. Valid range: 0.0-1.0.

Returns:

np.ndarray –

Blended image with overlay applied, dtype uint8, shape HxWx3 (RGB).

Where the overlay has no data (background), returns the original image unchanged.

Return type:

ndarray

acia.viz.render_segmentation_mask(source, overlay, alpha=0.8, *, colors=None, palette=None, cmap='viridis', default_color=(120, 120, 120))[source]#

Render cell segmentation masks, colored randomly (default) or from a table.

Parameters:

  • source (ImageSequenceSource) – the time-lapse sequence source.

  • overlay (Overlay) – the corresponding overlay. WARNING: all instances need to be based on masks!

  • alpha (float, optional) – weight of the original image in the blend – 1.0 keeps the frame unchanged, 0.0 shows solid mask color. Defaults to 0.8.

  • colors – optional per-cell coloring, matched to contours by id – a pandas.Series indexed by contour id (i.e. one column of a property table), a dict {id: value}, or a single-column DataFrame. Each value becomes a color: an (r, g, b) triple is used directly, a number is mapped through cmap (continuous), anything else is categorical (one distinct color per category, from palette or a qualitative colormap). None (default) keeps the original random per-instance colors.

  • palette (dict | None) – optional {category: (r, g, b)} mapping for categorical colors (its keys double as the color legend).

  • cmap (str) – matplotlib colormap name used for numeric colors.

  • default_color (tuple[int, int, int]) – color for cells absent from colors (or with NaN).

Returns:

THWCSequenceSource – TxHxWx3 sequence

Return type:

THWCSequenceSource

acia.viz.render_tracking_mask(source, overlay, alpha=0.8, show_label_numbers=False, seed=42)[source]#

Render tracking and use the label colors for the masks

Parameters:

  • source (ImageSequenceSource) – the time-lapse sequence source

  • overlay (Overlay) – the corresponding overlay. WARNING: all instances need to be based on masks!

  • alpha (float, optional) – The opacity of the masked image. Defaults to 0.8.

Returns:

THWCSequenceSource – TxHxWx3 sequence

Return type:

THWCSequenceSource

acia.viz.compute_lineage_y(G, time_feature='t')[source]#

Assign a y-position to each node using a tidy tree layout.

Parameters#

Gnx.DiGraph

The lineage graph.

time_featurestr

The node attribute that encodes time.

Returns#

assigned_ydict

Mapping from node to y-coordinate (float).

Parameters:
Return type:

dict[Any, float]

acia.viz.extract_lineage_plotdata(G, assigned_y, time_feature='t', label_name=None, orientation='horizontal')[source]#

Collect all node and edge positions and hover info for plotting.

Parameters:
Return type:

dict[str, Any]

acia.viz.plot_cell_lineage(G, time_feature='t', orientation='horizontal', show_label=True, label_name=None, node_marker='o', node_ms=6, line_color='blue', line_lw=2, mark_births=False, birth_color='red', birth_marker=None, birth_ms=12, mark_ends=False, end_color='orange', end_marker='s', end_ms=10, ax=None, interactive_tooltip=False, node_color_by=None, node_edge_color='none', node_cmap='viridis', node_na_color='#bbbbbb', show_colorbar=True, show_legend=True, colorbar_title=None)[source]#

Draw a cell lineage tree as a static matplotlib plot.

Parameters:
acia.viz.plotly_cell_lineage(G, time_feature='t', orientation='horizontal', show_label=True, label_name=None, node_marker='circle', node_ms=10, line_color='blue', line_width=2, mark_births=False, birth_color='red', birth_marker=None, birth_ms=16, mark_ends=False, end_color='orange', end_marker='square', end_ms=14, figure_title='Cell Lineage', fig_height=500, fig_width=1000, node_color_by=None, node_colorscale='Viridis', node_na_color='lightgray', show_colorbar=True, show_legend=True, colorbar_title=None, time_axis_label=None)[source]#

Plot a cell lineage tree as an interactive Plotly chart. Node hover shows all features as a readable (monospace) “pseudo-table”.

time_axis_label overrides the title on whichever axis encodes time_feature (x when horizontal, y when vertical). When it is None (the default), the title is auto-derived: f"Time [{unit}]" when the graph carries a graph["time_unit"] (as stamped by the tracker when the source was time-calibrated), else plain "Time".

Parameters:
acia.viz.tracklet_graph_to_segments(tracklet_graph)[source]#

Reshape a tracklet graph into a “one line per cell cycle” segment graph.

plotly_cell_lineage()/plot_cell_lineage() (and their shared layout helpers compute_lineage_y()/extract_lineage_plotdata()) only require a graph where every node carries a unique id and a scalar time_feature attribute – they know nothing about tracklets. This function bridges that gap by turning each tracklet node n (with start_frame/end_frame int attributes, as produced by e.g. acia.tracking.formats.read_ctc_tracklet_graph()) into two point nodes, so a tracklet becomes a single line segment from its start to its end and a division becomes a branch from a parent segment’s end-point to each child segment’s start-point.

Parameters:

tracklet_graph (DiGraph) – one node per tracklet, keyed by an arbitrary hashable label (e.g. the CTC integer label), with start_frame/ end_frame int attributes; edges parent -> child encode a division.

Return type:

DiGraph

When the tracklet graph carries real time on its nodes – start_time/ end_time float attributes plus a graph["time_unit"], as stamped by acia.tracking.annotate_tracklet_times() at tracking time – those are forwarded to the point nodes’ "time" attribute (and the unit copied to segments.graph["time_unit"]), so the lineage lays out on a real-time axis with no extra input. Otherwise only "frame" is carried.

Returns:

A new networkx.DiGraph where each input node n becomes (n, "start") and (n, "end"), each carrying a "frame" int attribute (start_frame/end_frame respectively) and, when the input carried real time, a "time" float attribute. One intra-tracklet edge (n, "start") -> (n, "end") per tracklet, and one inter-tracklet edge (n, "end") -> (child, "start") for every division edge n -> child in the input. Suitable for plotly_cell_lineage(segments, time_feature="frame") (or time_feature="time" when the input carried real time).

Parameters:

tracklet_graph (DiGraph)

Return type:

DiGraph

acia.viz.plot_tracklet_lineage(tracklet_graph, **kwargs)[source]#

Render a tracklet graph as a lineage tree with one line per cell cycle.

One-line convenience wrapper hiding tracklet_graph_to_segments() behind a single call to plotly_cell_lineage(). time_feature is selected automatically – "time" when the tracklet graph carries real time (start_time/end_time, as stamped by acia.tracking.annotate_tracklet_times()), else "frame" – and is not caller-overridable; a caller who also passes time_feature= gets Python’s own “got multiple values for keyword argument” TypeError, which is the correct, sufficient failure mode here. When real time is present, the axis is auto-labelled from the graph’s time_unit.

Parameters:
Returns:

The plotly.graph_objects.Figure produced by plotly_cell_lineage().