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: list[float] | None = 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.

Examples

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

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

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