wave

Function

wave(
    states: list[State],
    amplitude: float = 20,
    wavelength: float = 100,
    spacing: float = 50,
    phase: float = 0,
    middle_x: float = 0,
    middle_y: float = 0,
    rotation: float = 0,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0,
    distances: Optional[List[float]] = None
) -> list[State]

Arrange elements along a sine wave.

Creates a new list of states with elements positioned along a sine wave, following the same base-line logic as line_layout but with wave displacement perpendicular to the line direction. Preserves all other state attributes (color, scale, opacity, etc.) while only modifying x, y positions and optionally rotation.

Parameters

states: List of states to arrange
amplitude: Height of the wave peaks
wavelength: Distance between wave peaks
spacing: Distance between adjacent elements along the base line
phase: Phase shift of the wave in radians
middle_x: X coordinate of the center point
middle_y: Y coordinate of the center point
rotation: Angle of the base line in degrees (0° = horizontal right)
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 spacing calculation. List length should match states length.

Returns

New list of states with wave positions

Examples

# Basic horizontal wave
    states = [CircleState(), CircleState(), CircleState()]
    wave_layout(states, amplitude=30, wavelength=200)

    # Diagonal wave with custom spacing
    wave_layout(states, rotation=45, spacing=40, amplitude=20)

    # Wave with custom distances
    wave_layout(states, distances=[-100, -50, 0, 50, 100])