docs/CHOREOGRAPHY_GUIDE.md

# Reachy Mini Choreography Guide

This guide provides physics rules and artistic principles for creating custom movements. Referenced by `get_choreography_guide` tool and used when creating sequences via `execute_sequence`.

## 1. Physical Constraints

### Head Movement
| Axis | Range | Sign Convention |
|------|-------|-----------------|
| **Roll** (Tilt L/R) | ±45° | Positive = Tilt Right |
| **Pitch** (Up/Down) | ±45° | **Negative = Look UP**, Positive = Look DOWN |
| **Yaw** (Turn L/R) | ±65° | Positive = Robot's Left |

### Body Rotation
| Axis | Range | Notes |
|------|-------|-------|
| **body_yaw** | ±160° | Full rotation works! 170° = facing away |

### Antennas
| Parameter | Range | Notes |
|-----------|-------|-------|
| **Both** | ±90° | 0° = vertical/neutral |
| **Individual** | ±90° | Use `left_antenna_amplitude` / `right_antenna_amplitude` in `generate_motion` |

**Expressiveness:**
- *Forward (+)*: Alert, interested, angry (if rigid)
- *Backward (-)*: Sad, scared, aerodynamic
- *Asymmetric*: Confused, playful (one up, one down)

## 2. Timing & Smoothness

| Speed | Duration | Use Case |
|-------|----------|----------|
| Fast | 0.2-0.3s | Small twitches, excitement |
| Normal | 0.5-1.0s | Looking around |
| Slow | 1.5s+ | Breathing, sad movements |

**Rules:**
- Use minimum-jerk / S-curve easing for smooth motion
- Head motions ≤ 4 Hz overall
- Antenna flicks ≤ 0.12s each
- Design for 80% of limits unless user asks for "big/extreme"

### Velocity Limits (Soft)
| Component | Max Speed |
|-----------|-----------|
| Head yaw | 120°/s |
| Head pitch | 90°/s |
| Head roll | 90°/s |
| Body yaw | 90°/s |

## 3. Using `generate_motion`

For continuous procedural animations, use `generate_motion` with these motion types:

| Type | Best For | Key Parameters |
|------|----------|----------------|
| `nod` | Yes/agreement | `pitch_amplitude=12-20°`, `tempo=1.5-3.0 Hz` |
| `shake` | No/disagreement | `yaw_amplitude=14-22°`, `tempo=1.5-2.5 Hz` |
| `sway` / `groove` | Dancing | `yaw_amplitude=10-16°`, `roll_amplitude=6-12°`, `tempo=0.8-1.6 Hz` |
| `spiral` / `figure8` | Playful loops | `yaw=16-24°`, `pitch=8-14°`, `tempo=0.6-1.2 Hz` |
| `bounce` | Energetic | `z_offset=6-12mm`, `tempo=1.3-2.2 Hz` |
| `peek` | Peek-a-boo style | Duck + peek side to side |
| `dizzy` | Wobbly circles | Small `yaw=18°`, `pitch=8°`, `roll=6-10°` |

### Advanced Parameters
- **Drift**: `z_drift=0.02` for rising "snake charmer" effect
- **Start offset**: `z_start_offset=-0.02` + `z_drift=0.02` for crouch→rise
- **Antenna control**: `left_antenna_amplitude`, `right_antenna_amplitude` for individual control
- **Body swivel**: `body_yaw_amplitude` for dancing turns

## 4. Choreography Patterns

### "The Breath" (Idle/Calm)
Gentle, slow pitch movement with slight antenna swaying.
```
goto_pose(pitch=5, duration=2.0)   # Inhale/Up
goto_pose(pitch=0, duration=2.0)   # Exhale
```

### "The Scan" (Searching)
Head stays level (pitch 0), yaw sweeps, antennas alert.
```
goto_pose(yaw=-30, duration=1.0)  # Look left
goto_pose(yaw=30, duration=1.0)   # Look right
```

### "The Jiggle" (Excitement)
Use `generate_motion` for rapid oscillation:
```
generate_motion(motion_type="groove", roll_amplitude=8, tempo=2.0, duration=1.0)
```

## 5. Safety Rules

1. **Collision avoidance**: If pitch < -20° (looking down hard), keep antennas < 20°
2. **Speed limits**: Required speed ≈ Δangle / duration. If exceeding limits, increase duration
3. **Coupling**: If `body_yaw_amplitude > 20°`, halve head yaw amplitude
4. **Clamp to hard caps**: System will scale amplitudes proportionally if needed