workouts/Exercise Library/SYSTEM.md

Exercise Visual System

Exercise visuals are produced by an articulated 2D rig: one shared stick body posed per exercise by joint angles. Nothing is drawn by hand — a body profile plus a motion script resolve through forward kinematics into every frame, so figures are always in proportion, and the whole library can be re-proportioned (male/female), flipped, rotated in-plane, or re-themed by changing data, never artwork.

The rig

• body.json — proportion profiles. Each profile is a table of bone lengths: headR, neck, spine1/spine2 (two chained segments so the spine can curve), upperArm/foreArm, thigh/shin, plus leftOffset (the small offset that separates left-limb attachments visually). neutral is the default; add profiles to add figures.
• <Exercise>/motion.json — the exercise script: key frames of absolute joint angles (degrees, y-up: 0=forward/right, 90=up, 180=back/left, -90=down), a root pelvis position, and timing.

{
  "name": "Bird Dog",
  "primary": 2,                    // 1-based frame used for visual.svg
  "working": ["arm_r", "leg_l"],   // parts drawn in the accent color
  "hide": [],                      // limbs fully occluded in this view
  "frames": [
    {
      "hold": 0.5,                 // seconds held at this key frame
      "tween": 0.8,                // seconds animating to the NEXT frame
      "root": [190, 106],          // pelvis, canvas coords
      "spine": [171, 171],         // pelvis→mid, mid→neck angles
      "neck": 187, "gaze": 205,    // head direction; nose tick direction
      "arm_r": [-90, -90],         // upper-arm, forearm angles
      "arm_l": [-90, -90],
      "leg_r": [-83, 0],           // thigh, shin angles
      "leg_l": [-83, 0],
      "pins": {"hand_r": [105, 152], "hand_l": [111, 154]}
    }
  ]
}

• Pins (IK) — a planted hand/foot names a target point (hand_r/hand_l/foot_r/foot_l); the renderer solves the two-bone chain analytically so the extremity holds that point exactly, using the authored angles only to pick the elbow/knee bend direction. A pin active in two consecutive key frames stays planted throughout the tween (plank forearms, side-plank support arm); a pin present in only one frame releases naturally (bird-dog arm lifting off).
• Tweening happens in angle space (shortest path), so limbs swing in natural arcs and bone lengths never distort. The last frame tweens back to the first (looping). Asymmetric timing carries technique: leg raises lower slowly (tween 1.4 s down, 0.6 s up).
• The same math is the plan for the app: a small SwiftUI renderer consumes body.json + motion.json and tweens angles on the lower half of the exercise screen (the paged timer flow occupies only the top half).

The visual language

• Right vs left limb — the one rule that never bends: the figure's right-side limbs are dark (#3a3f4b), its left-side limbs are light (#a9afba) and drawn behind the body. Working limbs keep the split: right = teal #0d9488, left = light teal #86cfc5. Every render embeds a small R — / L — legend, so opposite-limb moves (bird dog, dead bug) are visibly opposite: one dark-teal limb, one light-teal limb.
• Facing / front-of-torso — the head carries a nose tick (gaze angle); the belly is on that side. Prone noses point at the floor, supine at the ceiling. The head is drawn last, filled opaque, so overhead arms pass behind the face.
• Spine — rendered as a smooth curve through pelvis → mid → neck; teal when the trunk is the working part.
• Canvas 320×180, ground line at y = 152. Limbs listed in hide are fully occluded in this view and not drawn.

Rendering

cd "Exercise Library"
python3 render.py                 # all exercises: frames/*.svg, preview.gif, visual.svg
python3 render.py "Bird Dog"      # one exercise
python3 render.py --sheet         # + contact-sheet.png of every key frame
python3 render.py --demo          # + demo-sheet.png: profile / flip / theme variants
python3 render.py --figure=female # render with another body profile
python3 render.py --flip          # mirror the figure (faces the other way)
python3 render.py --export        # copy body.json + <Name>.motion.json app resources

render.py needs only Pillow (for GIFs/sheets; the SVGs have no dependency). The library lives at the repo root, outside every target's source folders — same-named files per entry (info.md, visual.svg) would collide in Xcode's flat resource copy, so the library itself never enters the app bundle. Only the --export copies ship: body.json plus uniquely-named <Name>.motion.json files in Workouts/Resources/ExerciseMotions/, consumed by the in-app SwiftUI renderer (Workouts/ExerciseFigure/). Re-run python3 render.py --export after editing any motion; the library stays the source of truth.