wave_between_points

Function

wave_between_points(
    states: list[State],
    x1: float,
    y1: float,
    x2: float,
    y2: float,
    amplitude: float = 50,
    wavelength: float = 200,
    phase: float = 0,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0,
    distances: Optional[List[float]] = None,
    element_rotation_offset_fn: Optional[Callable[[float], float]] = None
) -> list[State]

Arrange states along a sine wave from point A to point B.

Alternative specification to wave() for users who think in terms of endpoints. Distributes states evenly from start to end point along a wave pattern, with the wave oscillating perpendicular to the line between the points.

Parameters

states: List of states to arrange
x1: X coordinate of wave base line start point
y1: Y coordinate of wave base line start point
x2: X coordinate of wave base line end point
y2: Y coordinate of wave base line end point
amplitude: Height of the wave peaks
wavelength: Distance between wave peaks
phase: Phase shift of the wave in radians
alignment: How to align each element relative to the wave base line. PRESERVE keeps original rotation, LAYOUT aligns parallel to base line, UPRIGHT starts from vertical position.
element_rotation_offset: Additional rotation in degrees added to the alignment base.
distances: Optional list of specific distances from center for each element. If provided, overrides automatic distribution.
element_rotation_offset_fn: Optional function to calculate rotation offset dynamically. Not used currently, reserved for future compatibility.

Returns

New list of states with wave positions Raises: ValueError: If start and end points are identical (zero-length base line)

Examples

# Horizontal wave from origin to (200, 0)
    wave_between_points(states, 0, 0, 200, 0, amplitude=30, wavelength=100)

    # Diagonal wave
    wave_between_points(states, -100, -100, 100, 100, amplitude=20)

    # Vertical wave with custom wavelength
    wave_between_points(states, 50, 0, 50, 200, amplitude=40, wavelength=150)

    # Equivalent to wave() with center and rotation:
    # wave_between_points(states, 0, 0, 200, 0, amplitude=30)
    # == wave(states, middle_pos=Point2D(100, 0), middle_y=0, rotation=0, amplitude=30, spacing=~50)