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