VElementGroup

Element transform group with complete SVG transform capabilities.

Uses chainable builder pattern for animation construction. All methods return new instances (immutable pattern).

Constructor

VElementGroup(
    elements: list[VElement] | None = None,
    group_easing: Callable[[float], float] | None = None,
    _builder: BuilderState | None = None,
    _clip_elements: list[VElement] | None = None,
    _mask_element: VElement | None = None,
    _attribute_easing: dict[str, EasingFunction] | None = None,
    _attribute_keystates: AttributeKeyStatesDict | None = None
) -> None

Initialize an element group with builder pattern.

Parameters

elements: Optional initial list of child elements
group_easing: Optional easing function applied to the group's animation time

Methods

add_element

add_element(child: 'VElement') -> 'VElementGroup'

Add a child element to the group. Returns new VElementGroup.

add_elements

add_elements(elements: list['VElement']) -> 'VElementGroup'

Add multiple child elements to the group. Returns new VElementGroup.

attributes

attributes(
    easing_dict: dict[str, EasingFunction] | None = None,
    interpolation_dict: dict[str, Any] | None = None,
    keystates_dict: AttributeKeyStatesDict | None = None
) -> T

Set element-level attribute configuration.

Parameters

easing_dict: Per-field easing functions {field_name: easing_func}
interpolation_dict: Per-field path functions {field_name: path_func}
keystates_dict: Per-field keystate timelines {field_name: [values]}

Returns

New instance with attributes set

clear_elements

clear_elements()

Remove all child elements from the group. Returns new VElementGroup.

clip

clip(velement: 'VElement') -> 'VElementGroup'

Add a clip element. Can be called multiple times. Returns new VElementGroup.

default_transition

default_transition(
    easing_dict: dict[str, EasingFunction] | None = None,
    interpolation_dict: dict[str, Any] | None = None,
    morphing: 'MorphingConfig | None' = None,
    state_interpolation: Callable | None = None
) -> T

Set default transition parameters for all subsequent segments.

Parameters

easing_dict: Per-field easing functions to use as default
interpolation_dict: Per-field path functions to use as default
morphing: Morphing configuration to use as default
state_interpolation: Optional callable (start_state, end_state, t) -> State that bypasses all per-field interpolation. t is raw segment t (0→1).

Returns

New instance with default transition set

get_elements

get_elements()

Get the list of child elements.

get_frame

get_frame(t: float) -> VElementGroupState | None

Get the interpolated state at a specific time.

is_animatable

is_animatable()

Check if this group can be animated.

is_empty

is_empty()

Check if the group has no child elements.

keystate

keystate(
    state: State | list[State],
    at: float | None = None,
    render_index: int | None = 0
) -> T

Add a keystate at the specified time.

Parameters

state: State for this keystate, or a 2-element list [incoming_state, outgoing_state] for dual-state keystates. When using dual-state: - state[0]: interpolation target coming IN - state[1]: interpolation source going OUT
at: Time position (0.0-1.0), or None for auto-timing
render_index: Which state to render at exactly this time (0 or 1, default 0). Only applicable for dual-state keystates.

Returns

New instance with keystate added

keystates

keystates(
    states: Sequence[State],
    between: list[float] | None = None,
    extend: bool = False,
    at: list[float] | None = None
) -> T

Add multiple keystates with automatic timing.

Parameters

states: List of states to add
between: Time range [start, end] for the states (default [0.0, 1.0])
extend: If True and time range doesn't cover [0,1], extend with copies of first/last state at 0.0/1.0
at: Exact times for each state (overrides between if both given)

Returns

New instance with keystates added

mask

mask(velement: 'VElement') -> 'VElementGroup'

Set the mask element. Returns new VElementGroup.

remove_element

remove_element(child: 'VElement') -> 'VElementGroup'

Remove a child element from the group. Returns new VElementGroup.

render

render()

Render the element group in its initial state.

render_at_frame_time

render_at_frame_time(t: float, drawing: Drawing | None = None) -> Group | None

Render the element transform group at a specific animation time.

render_state

render_state(
    state: VElementGroupState,
    drawing: Drawing | None = None
) -> Group | None

Render a pre-computed state directly (avoids re-interpolation).

transition

transition(
    easing_dict: dict[str, EasingFunction] | None = None,
    interpolation_dict: dict[str, Any] | None = None,
    morphing_config: 'MorphingConfig | None' = None,
    linear_angle_interpolation: bool = False,
    state_interpolation: Callable | None = None
) -> T

Configure the transition between the previous and next keystate.

Parameters

easing_dict: Per-field easing functions for this segment
interpolation_dict: Per-field interpolation functions {field_name: func} - Point2D: (p1, p2, t) -> Point2D - Rotation: (r1, r2, t) -> float
morphing_config: Morphing configuration for vertex state transitions
linear_angle_interpolation: If True, rotation interpolates linearly without angle wrapping
state_interpolation: Optional callable (start_state, end_state, t) -> State that bypasses all per-field interpolation. t is raw segment t (0→1).

Returns

New instance with transition configured