ellipse_in_bbox

Function

ellipse_in_bbox(
    states: list[State],
    center: Point2D,
    width: float,
    height: float,
    rotation: float = 0,
    clockwise: bool = True,
    start_angle: float = 0,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0,
    angles: Optional[List[float]] = None,
    element_rotation_offset_fn: Optional[Callable[[float], float]] = None
) -> list[State]

Arrange states in an elliptical formation within a bounding box.

Alternative specification to ellipse() for users who think in terms of bounding boxes rather than center + radii. The ellipse will be inscribed in the specified rectangle.

Parameters

states: List of states to arrange
x: X coordinate of bounding box top-left corner
y: Y coordinate of bounding box top-left corner
width: Width of bounding box
height: Height of bounding box
rotation: Rotation in degrees (0° = top, 90° = right)
clockwise: If True, arrange clockwise; if False, counterclockwise
start_angle: Starting angle in degrees for first element
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.
angles: Optional list of specific angles in degrees for each element. If provided, overrides automatic distribution.
element_rotation_offset_fn: Function that takes position angle (degrees) and returns rotation offset.

Returns

New list of states with elliptical positions Raises: ValueError: If width or height is zero or negative

Examples

# Ellipse in 400x200 box at origin
    ellipse_in_bbox(states, 0, 0, 400, 200)

    # Ellipse in square box (becomes circle)
    ellipse_in_bbox(states, -100, -100, 200, 200)

    # Rotated ellipse in rectangular box
    ellipse_in_bbox(states, 50, 50, 300, 150, rotation=45)

    # Equivalent to ellipse() with center and radii:
    # ellipse_in_bbox(states, 0, 0, 400, 200)
    # == ellipse(states, center=Point2D(), rx=200, ry=100)