ellipse

Function

ellipse(
    states: list[State],
    rx: float = 100,
    ry: float = 50,
    rotation: float = 0,
    center: Point2D = Point2D(x=0, y=0),
    clockwise: bool = True,
    start_angle: float = 0,
    angles: Optional[List[float]] = None,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0,
    element_rotation_offset_fn: Optional[Callable[[float], float]] = None
) -> list[State]

Arrange states in an elliptical formation.

Positions elements around an ellipse, either evenly distributed or at specific angles. Preserves all other state attributes (color, scale, opacity, etc.) while only modifying x and y positions.

Parameters

states: List of states to arrange
rx: Horizontal radius of the ellipse
ry: Vertical radius of the ellipse
rotation: Rotation in degrees (0° = top, 90° = right)
cx: X coordinate of ellipse center
cy: Y coordinate of ellipse center
clockwise: If True, arrange clockwise; if False, counterclockwise. Only used when angles is None.
angles: Optional list of specific angles in degrees for each element. If provided, overrides automatic distribution and clockwise parameter. List length should match states length.
alignment: How to align each element relative to the ellipse. PRESERVE keeps original rotation, LAYOUT aligns tangent to ellipse, 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 elliptical positions