spiral

Function

spiral(
    states: list[State],
    center: Point2D = Point2D(x=0, y=0),
    start_radius: float = 20,
    radius_step: float = 20,
    start_angle: float = 0,
    angle_step: float = 30,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0,
    element_rotation_offset_fn: Optional[Callable[[float], float]] = None
) -> list[State]

Arrange states in a spiral formation (Archimedean spiral).

Each element is placed at increasing radius and angle from the center. Preserves all other state attributes (color, scale, opacity, etc.) while only modifying x and y positions.

Parameters

states: List of states to arrange
cx: X coordinate of spiral center
cy: Y coordinate of spiral center
start_radius: Initial radius from center for first element
radius_step: Amount to increase radius for each subsequent element
start_angle: Initial angle in degrees for first element
angle_step: Amount to increase angle for each subsequent element (degrees)
alignment: How to align each element relative to the spiral. PRESERVE keeps original rotation, LAYOUT aligns tangent to spiral, UPRIGHT starts from vertical position.
element_rotation_offset: Additional rotation in degrees added to the alignment base.
element_rotation_offset_fn: Function that takes position angle (degrees) and returns rotation offset. If provided, this overrides element_rotation_offset parameter.

Returns

New list of states with spiral positions