VSceneComposite

Spatial composition of multiple scenes.

VSceneComposite stacks multiple scenes horizontally or vertically with automatic scaling to align dimensions. Scenes maintain aspect ratio.

Constructor

VSceneComposite(
    scenes: list[ComposableScene],
    direction: Literal['horizontal', 'vertical'] = 'horizontal',
    gap: float = 0.0,
    origin: Origin | None = None,
    background: Color | None = None
) -> None

Initialize a composite of scenes.

Parameters

scenes: List of VScene, VSceneSequence, or VSceneComposite to compose
direction: Stack direction - "horizontal" or "vertical"
gap: Gap between scenes in pixels (default: 0.0)
origin: Override origin mode (default: use first scene's origin)
background: Background color to fill gaps (default: first scene's background)
Raises
ValueError: If scenes list is empty or direction is invalid

Methods

to_drawing

to_drawing(
    frame_time: float = 0.0,
    render_scale: float = 1.0,
    width: float | None = None,
    height: float | None = None
) -> Drawing

Render the composite at a specific time point.

Parameters

frame_time: Time point to render (0.0 to 1.0).
render_scale: Scale factor for rendering. Applied when width/height not provided.
width: Override output width. Defaults to total_width * render_scale.
height: Override output height. Defaults to total_height * render_scale.
Raises
ValueError: If frame_time is outside [0.0, 1.0]

to_svg

to_svg(
    frame_time: float = 0.0,
    render_scale: float = 1.0,
    width: float | None = None,
    height: float | None = None,
    filename: str | None = None,
    log: bool = True
) -> str

Render the composite to SVG at a specific time point.

Parameters

frame_time: Time point to render (0.0 to 1.0).
render_scale: Scale factor for rendering.
width: Override output width.
height: Override output height.
filename: Optional filename to save SVG to.
log: Whether to log the save operation.

Properties

background: Get the composite background color.
direction: Get the stack direction.
gap: Get the gap between scenes.
height: Get the composite height.
origin: Get the composite origin mode (from first scene or override).
scenes: Get the list of composed scenes.
width: Get the composite width.