acia.viz.compose#

Compose image sequences into a single sequence – side by side, stacked, gridded.

The one primitive here, ComposedSequenceSource, tiles several child ImageSequenceSources along one axis and is itself an ImageSequenceSource. Because the operation is closed over the source type, it nests: two horizontal composites stacked vertically make a 2x2 grid with no extra code. Composition is lazy – each output frame is built on demand from the corresponding child frames, so no full second copy of a movie is held in memory (relevant given how heavy video rendering already is).

Typical use – a before/after comparison video:

before = render_segmentation_mask(source.to_rgb(), overlay_before)
after = render_segmentation_mask(source.to_rgb(), overlay_after)
comparison = compose_sequences(
    [before, after], axis="horizontal",
    titles=["before", "after"], gap=4,
)
render_video(comparison, "compare.mp4")

label_sequence() (the titling primitive) is itself implemented via compose_sequences() – a title band is just a constant sub-sequence stacked vertically on top of the panel – which is why the whole thing is “composed once”.

class acia.viz.compose.ComposedSequenceSource[source]#

Bases: ImageSequenceSource

Lazily tile several child sequences along one axis into one sequence.

Each output frame is composed on demand: the k-th child’s frame is placed into a shared canvas along axis ("horizontal" -> panels left-to-right, "vertical" -> top-to-bottom), padded on the perpendicular axis to the largest panel (positioned by align) and separated by gap pixels. The result is an ImageSequenceSource, so it can itself be a child of another composition (grids via nesting).

Parameters:

  • sources – the child sequences (at least one).

  • axis – "horizontal" (side by side) or "vertical" (stacked).

  • gap – pixels of separation between adjacent panels (0 = flush).

  • gap_color – RGB fill for the gap strips (only drawn when it differs from pad_color).

  • align – perpendicular placement of shorter panels – "start", "center" (default), or "end".

  • pad_color – RGB fill for the canvas / perpendicular padding.

  • n_frames – reconcile differing child lengths by the "min" (truncate, default) or "max" (hold each panel’s last frame) length. A warning is logged when child lengths differ.

Time/pixel calibration is inherited from the first child.

__init__(sources, *, axis='horizontal', gap=0, gap_color=(0, 0, 0), align='center', pad_color=(0, 0, 0), n_frames='min')[source]#
Parameters:
get_frame(frame)[source]#
Parameters:

frame (int)

Return type:

BaseImage

property num_channels: int#
property size_c: int#
property size_t: int#
property size_h: int#
property size_w: int#
acia.viz.compose.label_sequence(source, title, *, height=28, bg_color=(30, 30, 30), text_color=(255, 255, 255), font_size=None)[source]#

Prepend a titled caption band above every frame of source.

The band is a constant sub-sequence stacked on top of the panel via compose_sequences(), so the result is itself composable (e.g. several labelled panels can be placed side by side).

Parameters:

  • source (ImageSequenceSource) – the sequence to caption.

  • title (str) – caption text, drawn centered on the band.

  • height (int) – band height in pixels.

  • bg_color (tuple[int, int, int]) – RGB band background.

  • text_color (tuple[int, int, int]) – RGB text color.

  • font_size (int | None) – text size; defaults to ~60% of height.

Returns:

A ComposedSequenceSource of [band, source] stacked vertically, height pixels taller than source.

Return type:

ComposedSequenceSource

acia.viz.compose.compose_sequences(sources, *, axis='horizontal', titles=None, gap=0, gap_color=(0, 0, 0), align='center', pad_color=(0, 0, 0), n_frames='min')[source]#

Tile several image sequences into one – side by side or stacked.

A thin front-end over ComposedSequenceSource that additionally captions each panel when titles is given (via label_sequence()). See ComposedSequenceSource for the layout parameters.

Parameters:

  • sources (Sequence[ImageSequenceSource]) – the child sequences (at least one).

  • axis (Literal['horizontal', 'vertical']) – "horizontal" (side by side) or "vertical" (stacked).

  • titles (Sequence[str] | None) – optional per-panel captions; must match sources in length. Each source is wrapped with label_sequence() before tiling.

  • gap (int) – pixels between adjacent panels.

  • gap_color (tuple[int, int, int]) – RGB fill for the gap strips.

  • align (Literal['start', 'center', 'end']) – perpendicular placement of shorter panels.

  • pad_color (tuple[int, int, int]) – RGB fill for the canvas / perpendicular padding.

  • n_frames (Literal['min', 'max']) – "min" (truncate) or "max" (hold last frame) length reconciliation for unequal-length children.

Returns:

A composed ComposedSequenceSource, ready for acia.viz.render_video() or further composition.

Return type:

ComposedSequenceSource