line

Function

line(
    states: list[State],
    spacing: float = 100,
    rotation: float = 0,
    center: Point2D = Point2D(x=0, y=0),
    distances: list[float] | None = None,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0
) -> list[State]

Arrange states in a straight line formation.

Positions elements along a straight line with configurable spacing, rotation, and center point. For odd numbers of elements, one element is placed at the center. For even numbers, elements are distributed symmetrically around the center point. Preserves all other state attributes (color, scale, opacity, etc.) while only modifying x and y positions.

Parameters

states: List of states to arrange
spacing: Distance between adjacent elements. Only used when distances is None.
rotation: Angle of the line in degrees (0° = horizontal right, 90° = vertical down)
center: Center point of the line
distances: Optional list of specific distances from center for each element. If provided, overrides automatic distribution and spacing parameter. Positive values = forward along line, negative = backward along line. List length should match states length.
alignment: How to align each element relative to the line. PRESERVE keeps original rotation, LAYOUT aligns parallel to line, UPRIGHT starts from vertical position.
element_rotation_offset: Additional rotation in degrees added to the alignment base.

Examples

# Even spacing (automatic distribution)
    line(states, spacing=50, rotation=0)

    # Explicit distances from center
    line(states, distances=[-100, -20, 50, 150])

    # Elements aligned with line direction
    line(states, rotation=45, alignment=ElementAlignment.LAYOUT)