# motion
continuous spatial movement: circular motion, LFO-driven panning, chaotic wander, or path-following.

## introduction
The motion domain resides in the spatial layer and enriches static placements by assigning each source a precomputed, continuous trajectory through the sound field.
It operates after `position` (static anchor) and before `diffusion` (spatial spread), generating time-varying coordinates for each voice or partial.
All motion forms are deterministic-once parameters `a` and `b` are fixed, the full path is known prior to playback, with no runtime randomness or feedback.

## overview
Each form defines a unique movement paradigm over a normalized time span:
### 0. `circular_orbit`
- Behavior: moves the source in a circular or elliptical orbit around a center point
- Analogy: a rotating speaker or a carousel ride
- Parameters:
  - `a`: rotation speed (0 → 0 Hz … 1 → Nyquist-rate LFO)
  - `b`: orbit shape (0 = perfect circle → 1 = highly eccentric ellipse)
### 1. `lfo_pan`
- Behavior: oscillates the pan position with a low-frequency oscillator
- Analogy: a pendulum swinging left and right
- Parameters:
  - `a`: LFO rate (0 → 0.01 Hz … 1 → 10 Hz)
  - `b`: modulation depth (0 = no movement → 1 = full stereo traverse)
### 2. `path_follow`
- Behavior: traverses a user-defined static path (line, curve, or bezier spline)
- Analogy: an object rolling along a drawn track
- Parameters:
  - `a`: path selector/phase (0 → start of path … 1 → end of path)
  - `b`: traversal speed (0 → static at start → 1 → completes path in one cycle)
### 3. `chaos_wander`
- Behavior: applies a chaotic or noise-based algorithm (e.g., logistic map, Perlin noise) to pan coordinates
- Analogy: leaves blown randomly by the wind
- Parameters:
  - `a`: complexity parameter (0 → near-linear drift → 1 → deep chaos)
  - `b`: wander amplitude (0 = no movement → 1 = full stereo width)

## parameter behavior summary
- circular\_orbit
  - `a`: angular velocity of the orbit
  - `b`: ellipse eccentricity (radius ratio)
- lfo\_pan
  - `a`: oscillation frequency
  - `b`: pan excursion range
- path\_follow
  - `a`: phase along the predefined curve
  - `b`: speed scaling of the traversal
- chaos\_wander
  - `a`: nonlinearity strength (chaos vs. linear drift)
  - `b`: maximum positional deviation

## why these were chosen
- Comprehensive dynamics: covers cyclical, periodic, path-based, and chaotic movements-four archetypal motion paradigms.
- Irreducible forms: no form can emulate another's behavior without external data or extra parameters.
- Two-parameter clarity: split between tempo/speed and shape/extent in each case, preserving parametric purity.
- Fully precomputed trajectories: aligns with the system's deterministic, additive ethos, ensuring every spatial coordinate is known in advance.

## what is not included
- Reactive or event-triggered moves: handled by structural or onset domains.
- Audio-rate movement or micro-modulation: those would violate the “no post-processing” rule.
- 3D spatialization curves or listener-tracking: outside current 2D pan-field scope.
- Dynamic diffusion or blurring: delegated to the `diffusion` domain.

## conclusion
The motion domain provides a succinct yet powerful set of four continuous movement forms-circular, LFO, path-based, and chaotic-each fully defined by two parameters.
Together, they enable complex, deterministically repeatable spatial trajectories that expand the project's remit from static placement to rich, time-varying sound motion, without sacrificing the overarching goals of parametric purity and precomputed structure.