circle_between_points

Function

circle_between_points(
    states: list[State],
    p1: Point2D,
    p2: Point2D,
    rotation: float = 0,
    clockwise: bool = True,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0,
    angles: list[float] | None = None,
    radius_fn: Optional[Callable[[int, float], float]] = None,
    element_rotation_offset_fn: Optional[Callable[[float], float]] = None
) -> list[State]

Arrange states in a circular formation with diameter defined by two points.

Alternative specification to circle() for users who think in terms of diameter endpoints. The circle's center will be at the midpoint between the two points, and the radius will be half the distance between them.

Parameters

states: List of states to arrange.
p1: First diameter endpoint.
p2: Second diameter endpoint. Center is at their midpoint, radius = distance / 2.
rotation: Rotation offset in degrees.
clockwise: If True, arrange clockwise; if False, counterclockwise.
alignment: How to align each element relative to the circle.
element_rotation_offset: Additional rotation in degrees added to the alignment base.
angles: Optional list of specific angles in degrees for each element.
radius_fn: Function that takes (index, default_radius) and returns custom radius.
element_rotation_offset_fn: Function that takes position angle and returns rotation offset.
Raises
ValueError: If points are identical (zero diameter)

Examples

# Circle with diameter from origin to (200, 0) - radius 100
    circle_between_points(states, 0, 0, 200, 0)

    # Circle with diagonal diameter
    circle_between_points(states, -100, -100, 100, 100)

    # Equivalent to circle() with center and radius:
    # circle_between_points(states, 0, 0, 200, 0)
    # == circle(states, cpos=Point2D(100, 0), cy=0, radius=100)