@franzenzenhofer/asanakit 0.1.0 → 0.2.0

package/docs/AUTHORING.md

@@ -1,39 +1,84 @@
 # Authoring poses
 
-A pose is a YAML file. Nothing is drawn imperatively: you describe a body, and asanakit
-solves and renders it. This guide is written to be followed by a person or by a model.
+A pose is a YAML file. Nothing is drawn imperatively: you describe a body in 3D, and
+asanakit solves and renders it - as an SVG/PNG from any camera, as an interactive 3D
+viewer, or as a GLB model. This guide is written to be followed by a person or by a model.
 
 ## The coordinate system
 
-Angles are **degrees**, measured **counter-clockwise from the +x axis**:
+The figure stands at the origin in anatomical neutral, **facing +z**, with **+x its own
+left** and **+y up**. It is one unit tall (sole to crown). The ground is the plane `y = 0`.
 
-```
-            90  (up)
-             |
-  180 -------+------- 0   (right, and the way a side-view figure faces)
-             |
-           -90  (down)
-```
-
-The figure is one unit tall (sole to crown). The ground is `y = 0`.
+All rotations are **degrees**.
 
 ## The two ways to angle a bone
 
 | Block | Meaning | Use it for |
 |---|---|---|
-| `joints:` | rotation **relative to the parent bone**, from anatomical neutral (standing, arms down) | small deviations from standing |
-| `world:` | the bone's **absolute direction** on the page | everything else |
+| `joints:` | rotation **relative to the parent bone**, about the joint's own anatomical axes | small deviations from standing; twists |
+| `world:` | the bone's **absolute direction** in space | everything else |
+
+### `world`: absolute directions
+
+```yaml
+world:
+  thighL: { azimuth: 0, elevation: -55 }     # down and forward
+  spine:  { azimuth: 0, elevation: 40 }      # leaning forward, 40° above horizontal
+  upperArmR: { azimuth: -90, elevation: 0 }  # straight out to the figure's right
+```
+
+- `azimuth` - which way the bone points on the compass of the body: `0` = the figure's
+  facing direction (+z), `90` = the figure's **left**, `-90` its right, `180` backward.
+- `elevation` - how far it rises: `90` = straight up, `0` = horizontal, `-90` = straight down.
+- `twist` (optional) - rotation about the aimed bone.
+
+"The front thigh points forward and 55° down" is something you can reason about and check
+by eye. Chaining five relative rotations is not. **`world` is what you want almost always.**
 
-`world` is what you want almost always. "The front thigh points down and back at -125°"
-is something you can reason about and check by eye. Chaining five relative rotations is not.
+A bone listed in `world` ignores its parent's rotation. Its **children still hang off
+it**, so pinning the thigh and then flexing the knee with `joints: {shinL: 40}` works
+exactly as you would expect.
 
-A bone listed in `world` ignores its rest angle and its parent's rotation. Its **children
-still hang off it**, so pinning the thigh and then flexing the knee with `joints: {shinL: 40}`
-works exactly as you would expect.
+> **The single most common mistake:** you tip the figure with `root.pitch` and forget
+> that every unpinned limb rotates with it. Tip the root to fold forward, and the legs
+> swing up into the air. **If you set root angles, pin the legs in `world`.**
 
-> **The single most common mistake:** you tilt the pelvis with `root.rotation` and forget
-> that every unpinned limb rotates with it. Tilt the pelvis to fold forward, and the legs
-> swing up into the air. **If you set `root.rotation`, pin the legs in `world`.**
+### `joints`: anatomical rotations
+
+A bare number is pure **flexion** - the joint bending the way anatomy names it:
+
+```yaml
+joints:
+  forearmL: 90          # elbow bends 90° (forward - the only way an elbow goes)
+  shinR: 60             # knee bends 60° (backward - the only way a knee goes)
+```
+
+The object form adds the other two anatomical axes:
+
+```yaml
+joints:
+  upperArmL: { abduct: 90 }              # arm straight out to the side
+  thighR:    { flex: 45, abduct: 30, twist: 20 }
+```
+
+- `flex` - forward bend for hips/arms/spine, backward for knees, toes-up for ankles.
+- `abduct` - away from the midline, on either side. Center bones lean toward the figure's left.
+- `twist` - about the bone: positive is **external rotation** (toes/palms turn outward);
+  for center bones, turning toward the figure's left.
+
+The signs are per-side anatomical, so a mirrored pose is literally the same numbers with
+L and R swapped - which is what `mirror: true` does.
+
+### The root
+
+```yaml
+root:
+  yaw: 90       # turn the whole figure toward its left
+  pitch: 40     # tip it forward (90 = horizontal, face down)
+  roll: -65     # cartwheel it sideways (negative drops the LEFT side)
+  position: [0, 0, 0]
+  scale: 1
+```
 
 ## Bones you can angle
 
@@ -43,10 +88,9 @@ clavicleL/R  upperArmL/R  forearmL/R  handL/R
 hipL/R  thighL/R  shinL/R  footL/R
 ```
 
-`root.rotation` aims the pelvis (90 = upright). Rotating a bone rotates everything below it.
-
-Positive `shinL` **flexes the knee** (heel toward the buttock). Positive `forearmL` flexes
-the elbow. Neither joint bends the other way, and the validator will tell you so.
+Rotating a bone rotates everything below it. Feet rest pointing forward, dropped 20°
+toward the floor; a **flat standing foot wants `world: { azimuth: …, elevation: 0 }`**
+or a matching dorsiflexion.
 
 ## Landmarks you can point at
 
@@ -58,17 +102,33 @@ shoulderL/R elbowL/R wristL/R handTipL/R
 hipJointL/R kneeL/R ankleL/R toeL/R
 ```
 
-## Views
+## The camera
+
+The pose is 3D; a picture of it needs a viewpoint:
+
+```yaml
+camera: side                              # or front | back | left | right | three-quarter | top
+camera: { azimuth: 30, elevation: 15 }    # or any orbit angle
+```
+
+This is only the pose's **default**. `--camera` on the CLI overrides it, and every camera
+shows the same body: `asanakit render pose --camera back` needs nothing re-authored.
+Camera azimuth 0 looks at the figure's front; positive azimuth walks toward the figure's
+left; `side` is the classic profile with the figure facing picture-right.
 
-| view | what it means |
-|---|---|
-| `front` | the figure faces you. Left and right limbs **mirror**: `upperArmL: 90` and `upperArmR: 90` raise both arms outward. |
-| `side` | profile, facing **+x** (to the right). Limbs **do not mirror** - both arms swing the same way, because you see both from the same side. The left/right offset becomes depth and nearly vanishes. |
-| `back` | like `front`. |
-| `three-quarter` | between the two. |
+`mirror: true` swaps which limb does what (the other side of an asymmetric asana).
+Sequences use it to render the "second side".
+
+## Physics, when necessary
+
+```yaml
+physics: settle
+```
 
-Set `flip: true` to face the other way. Set `mirror: true` to swap which limb does what
-(the other side of an asymmetric asana). Sequences apply both to render "second side".
+drops the solved figure onto the ground plane with a real physics engine (Rapier) and
+lets it rest on its true support instead of the naive lowest-point shift. Opt-in per pose,
+or ad hoc with `--settle`. The authored pose is preserved exactly; only the figure's
+position and orientation change.
 
 ## Contact points: the thing that keeps you honest
 
@@ -83,17 +143,18 @@ is hovering 9 cm above it. **Every pose must declare its contact points.**
 ## The loop
 
 ```bash
-npx tsx src/cli/index.ts lint my-pose                       # anatomy + contact check
-npx tsx src/cli/index.ts render my-pose -o out/p.png -w 500 -h 500 --scale 500
+asanakit lint my-pose                                    # anatomy + contact check
+asanakit render my-pose -o out/p.png -w 500 -h 500
+asanakit view my-pose --open                             # orbit it in 3D
 ```
 
-Then **look at the PNG**. Lint proves the pose is physically possible; only your eye proves
-it is the right posture. Iterate until both agree.
+Then **look at it - from more than one angle**. Lint proves the pose is physically
+possible; only your eye proves it is the right posture. Iterate until both agree.
 
 ## A complete example
 
 ```yaml
-asanakit: 1
+asanakit: 2
 id: adho-mukha-svanasana
 name: Downward-Facing Dog
 sanskrit: Adho Mukha Śvānāsana
@@ -107,27 +168,27 @@ drishti: nabi-chakra
 cues:
   - Lift the sit bones, lengthen the spine
 contact: [toeL, toeR, handTipL, handTipR]
+camera: side
 figure:
-  view: side
   grounded: true
   root:
-    rotation: -48        # pelvis aims down-and-forward: the torso ramps to the hands
+    pitch: 138                                   # pelvis aims down-and-forward: the torso ramps to the hands
   world:
-    thighL: -125         # legs ramp down-and-back to the feet
-    thighR: -125
-    shinL: -125          # straight leg: shin collinear with thigh
-    shinR: -125
-    footL: -20
-    footR: -20
-    spine: -48
-    neck: -48
-    head: -48            # head hangs between the arms, in line with the spine
-    upperArmL: -50       # arms continue the line of the spine to the floor
-    upperArmR: -50
-    forearmL: -50
-    forearmR: -50
-    handL: -8            # palm flat
-    handR: -8
+    thighL: { azimuth: 180, elevation: -55 }     # legs ramp down-and-back to the feet
+    thighR: { azimuth: 180, elevation: -55 }
+    shinL: { azimuth: 180, elevation: -55 }      # straight leg: shin collinear with thigh
+    shinR: { azimuth: 180, elevation: -55 }
+    footL: { azimuth: 0, elevation: -20 }
+    footR: { azimuth: 0, elevation: -20 }
+    spine: { azimuth: 0, elevation: -48 }
+    neck: { azimuth: 0, elevation: -48 }
+    head: { azimuth: 0, elevation: -48 }         # head hangs between the arms, in line with the spine
+    upperArmL: { azimuth: 0, elevation: -50 }    # arms continue the line of the spine to the floor
+    upperArmR: { azimuth: 0, elevation: -50 }
+    forearmL: { azimuth: 0, elevation: -50 }
+    forearmR: { azimuth: 0, elevation: -50 }
+    handL: { azimuth: 0, elevation: -8 }         # palm flat
+    handR: { azimuth: 0, elevation: -8 }
 props:
   - type: mat
 muscles:
@@ -137,7 +198,7 @@ muscles:
 
 ## Reference
 
-- `asanakit vocab` prints every joint, landmark, muscle, style and view name.
+- `asanakit vocab` prints every joint, landmark, muscle, style and camera name.
 - `asanakit schema` prints the JSON Schema for the format.
 - Props: `mat`, `ground`, `block`, `strap`, `wall`, `surfboard`, `wave`.
 - Annotations: `angle`, `line`, `plumb`, `arrow`, `label`, `point`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@franzenzenhofer/asanakit",
-  "version": "0.1.0",
-  "description": "Programmatic stick-figure and anatomical infographic engine for yoga and surf postures. Declarative pose format, deterministic SVG/PNG output, CLI-first, AI-driveable.",
+  "version": "0.2.0",
+  "description": "Programmatic stick-figure and body-posture visualization engine for yoga and surf. Declarative 3D pose format, deterministic any-angle SVG/PNG, interactive three.js viewer, GLB export, Rapier physics settling. CLI-first, AI-driveable.",
   "keywords": [
     "yoga",
     "surf",
@@ -15,7 +15,14 @@
     "skeleton",
     "kinematics",
     "cli",
-    "typescript"
+    "typescript",
+    "3d",
+    "three.js",
+    "gltf",
+    "glb",
+    "physics",
+    "rapier",
+    "camera"
   ],
   "license": "MIT",
   "author": "Franz Enzenhofer",
@@ -40,6 +47,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./physics": {
+      "types": "./dist/physics/index.d.ts",
+      "default": "./dist/physics/index.js"
     }
   },
   "files": [
@@ -50,9 +61,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli/index.js",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli/index.js && tsx scripts/build-viewer.ts",
     "dev": "tsx src/cli/index.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p viewer-src/tsconfig.json",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run",
@@ -63,6 +74,7 @@
     "prepublishOnly": "npm run verify"
   },
   "dependencies": {
+    "@dimforge/rapier3d-compat": "^0.19.3",
     "@resvg/resvg-js": "^2.6.2",
     "commander": "^14.0.1",
     "culori": "^4.0.2",
@@ -70,6 +82,7 @@
     "d3-shape": "^3.2.0",
     "gl-matrix": "^3.4.4",
     "svgo": "^4.0.2",
+    "three": "0.185.1",
     "xmlbuilder2": "^4.0.3",
     "yaml": "^2.8.1",
     "zod": "^4.1.12"
@@ -79,7 +92,9 @@
     "@types/d3-path": "^3.1.1",
     "@types/d3-shape": "^3.1.8",
     "@types/node": "^24.9.2",
+    "@types/three": "^0.185.1",
     "@vitest/coverage-v8": "^3.2.4",
+    "esbuild": "^0.28.1",
     "eslint": "^9.38.0",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",

package/poses/surf/bottom-turn.pose.yaml

@@ -1,4 +1,4 @@
-asanakit: 1
+asanakit: 2
 id: bottom-turn
 name: Bottom Turn
 english: Bottom Turn
@@ -6,42 +6,42 @@ discipline: surf
 family: turning
 difficulty: 4
 description: The turn at the base of the wave that sets up everything after it. The surfer compresses deep, drives the weight through the heels and the rail, and reaches the inside arm toward the wave face while the eyes go back up to the lip.
-tags: [surf, turning, rail, power]
+tags: [ surf, turning, rail, power ]
 cues:
   - Compress low and drive from the heels
   - Look where you want to go - back up at the lip
-contact: [toeL, toeR]
+contact: [ toeL, toeR ]
 figure:
-  view: side
   grounded: true
   root:
-    rotation: 55
+    pitch: 35
   world:
-    spine: 45
-    neck: 68
-    head: 82
-    thighL: -25
-    shinL: -100
-    footL: -15
-    thighR: -60
-    shinR: -145
-    footR: -10
-    upperArmL: -5
-    forearmL: 15
-    handL: 20
-    upperArmR: -150
-    forearmR: -140
-    handR: -135
+    spine: { azimuth: 0, elevation: 45 }
+    neck: { azimuth: 0, elevation: 68 }
+    head: { azimuth: 0, elevation: 82 }
+    thighL: { azimuth: 0, elevation: -25 }
+    shinL: { azimuth: 180, elevation: -80 }
+    footL: { azimuth: 0, elevation: -15 }
+    thighR: { azimuth: 0, elevation: -60 }
+    shinR: { azimuth: 180, elevation: -35 }
+    footR: { azimuth: 0, elevation: -10 }
+    upperArmL: { azimuth: 0, elevation: -5 }
+    forearmL: { azimuth: 0, elevation: 15 }
+    handL: { azimuth: 0, elevation: 20 }
+    upperArmR: { azimuth: 180, elevation: -30 }
+    forearmR: { azimuth: 180, elevation: -40 }
+    handR: { azimuth: 180, elevation: -45 }
 props:
   - type: wave
     amplitude: 0.45
     length: 3.4
     y: -0.2
   - type: surfboard
-    under: [ankleL, ankleR]
+    under: [ ankleL, ankleR ]
     rotation: 10
     length: 1.15
-    offset: [0, -0.1]
+    offset: [ 0, -0.1 ]
 muscles:
-  engaged: [quadriceps, gluteus, obliques, erectorSpinae, adductors]
-  stretched: [hipFlexors, latissimus]
+  engaged: [ quadriceps, gluteus, obliques, erectorSpinae, adductors ]
+  stretched: [ hipFlexors, latissimus ]
+camera: side

package/poses/surf/cutback.pose.yaml

@@ -1,4 +1,4 @@
-asanakit: 1
+asanakit: 2
 id: cutback
 name: Cutback
 english: Cutback
@@ -6,42 +6,42 @@ discipline: surf
 family: turning
 difficulty: 4
 description: The turn that takes the surfer back to the power source. Out on the shoulder the board is swung around by the torso - the chest and both arms lead the rotation back toward the breaking part of the wave, the weight settles over the tail and the front leg extends.
-tags: [surf, turning, rotation, flow]
+tags: [ surf, turning, rotation, flow ]
 cues:
   - Turn your chest and arms first, the board follows
   - Weight back over the tail to pivot, not the nose
-contact: [toeL, toeR]
+contact: [ toeL, toeR ]
 figure:
-  view: side
   grounded: true
   root:
-    rotation: 82
+    pitch: 8
   world:
-    spine: 100
-    neck: 118
-    head: 145
-    thighL: -45
-    shinL: -105
-    footL: -20
-    thighR: -85
-    shinR: -135
-    footR: -15
-    upperArmL: -178
-    forearmL: -172
-    handL: -170
-    upperArmR: 132
-    forearmR: 158
-    handR: 162
+    spine: { azimuth: 180, elevation: 80 }
+    neck: { azimuth: 180, elevation: 62 }
+    head: { azimuth: 180, elevation: 35 }
+    thighL: { azimuth: 0, elevation: -45 }
+    shinL: { azimuth: 180, elevation: -75 }
+    footL: { azimuth: 0, elevation: -20 }
+    thighR: { azimuth: 0, elevation: -85 }
+    shinR: { azimuth: 180, elevation: -45 }
+    footR: { azimuth: 0, elevation: -15 }
+    upperArmL: { azimuth: 180, elevation: -2 }
+    forearmL: { azimuth: 180, elevation: -8 }
+    handL: { azimuth: 180, elevation: -10 }
+    upperArmR: { azimuth: 180, elevation: 48 }
+    forearmR: { azimuth: 180, elevation: 22 }
+    handR: { azimuth: 180, elevation: 18 }
 props:
   - type: wave
     amplitude: 0.42
     length: 3.4
     y: -0.22
   - type: surfboard
-    under: [ankleL, ankleR]
+    under: [ ankleL, ankleR ]
     rotation: 4
     length: 1.15
-    offset: [0, -0.1]
+    offset: [ 0, -0.1 ]
 muscles:
-  engaged: [obliques, erectorSpinae, gluteus, quadriceps, deltoid]
-  stretched: [pectoralis, hamstrings]
+  engaged: [ obliques, erectorSpinae, gluteus, quadriceps, deltoid ]
+  stretched: [ pectoralis, hamstrings ]
+camera: side

package/poses/surf/duck-dive.pose.yaml

@@ -1,4 +1,4 @@
-asanakit: 1
+asanakit: 2
 id: duck-dive
 name: Duck Dive
 english: Duck Dive
@@ -6,32 +6,31 @@ discipline: surf
 family: prone
 difficulty: 3
 description: How a shortboarder gets under a broken wave. Both arms straighten and drive the nose deep under the water, the head follows it down, and one knee then punches into the tail to sink the whole board while the wave passes overhead.
-tags: [surf, prone, paddling, defensive, shortboard]
+tags: [ surf, prone, paddling, defensive, shortboard ]
 cues:
   - Straight arms - push the nose down, do not pull it toward you
   - Knee into the tail only once the nose is already under
-contact: [handTipL, handTipR]
+contact: [ handTipL, handTipR ]
 figure:
-  view: side
   grounded: true
   root:
-    rotation: -30
+    pitch: 120
   world:
-    spine: -38
-    neck: -34
-    head: -30
-    upperArmL: -56
-    forearmL: -56
-    handL: -56
-    upperArmR: -50
-    forearmR: -50
-    handR: -50
-    thighL: 168
-    shinL: 142
-    footL: 150
-    thighR: -175
-    shinR: 95
-    footR: 70
+    spine: { azimuth: 0, elevation: -38 }
+    neck: { azimuth: 0, elevation: -34 }
+    head: { azimuth: 0, elevation: -30 }
+    upperArmL: { azimuth: 0, elevation: -56 }
+    forearmL: { azimuth: 0, elevation: -56 }
+    handL: { azimuth: 0, elevation: -56 }
+    upperArmR: { azimuth: 0, elevation: -50 }
+    forearmR: { azimuth: 0, elevation: -50 }
+    handR: { azimuth: 0, elevation: -50 }
+    thighL: { azimuth: 180, elevation: 12 }
+    shinL: { azimuth: 180, elevation: 38 }
+    footL: { azimuth: 180, elevation: 30 }
+    thighR: { azimuth: 180, elevation: -5 }
+    shinR: { azimuth: 180, elevation: 85 }
+    footR: { azimuth: 0, elevation: 70 }
 props:
   - type: wave
     amplitude: 0.5
@@ -39,9 +38,10 @@ props:
     y: 0.55
     facing: left
   - type: surfboard
-    at: [0.023, 0.108]
+    at: [ 0.023, 0.108 ]
     rotation: -32
     length: 1.35
 muscles:
-  engaged: [triceps, deltoid, latissimus, rectusAbdominis, hipFlexors]
-  stretched: [pectoralis, quadriceps]
+  engaged: [ triceps, deltoid, latissimus, rectusAbdominis, hipFlexors ]
+  stretched: [ pectoralis, quadriceps ]
+camera: side

package/poses/surf/noseride.pose.yaml

@@ -1,4 +1,4 @@
-asanakit: 1
+asanakit: 2
 id: noseride
 name: Noseride
 english: Noseride
@@ -6,32 +6,29 @@ discipline: surf
 family: trim
 difficulty: 4
 description: The longboard reward. With the tail held in the wave the surfer walks to the front of the board and stands tall and still on the nose, legs long, arms loose, doing as little as possible while the board trims along the face.
-tags: [surf, longboard, trim, nose, style]
+tags: [ surf, longboard, trim, nose, style ]
 cues:
   - Stand tall and quiet - do nothing and let the board trim
   - Stay behind the tail's hold, never lunge at the nose
-contact: [toeL, toeR]
+contact: [ toeL, toeR ]
 figure:
-  view: side
   grounded: true
-  root:
-    rotation: 90
   world:
-    spine: 95
-    neck: 90
-    head: 88
-    thighL: -80
-    shinL: -95
-    footL: -15
-    thighR: -100
-    shinR: -112
-    footR: -12
-    upperArmL: -60
-    forearmL: -50
-    handL: -45
-    upperArmR: -112
-    forearmR: -102
-    handR: -100
+    spine: { azimuth: 180, elevation: 85 }
+    neck: { azimuth: 0, elevation: 90 }
+    head: { azimuth: 0, elevation: 88 }
+    thighL: { azimuth: 0, elevation: -80 }
+    shinL: { azimuth: 180, elevation: -85 }
+    footL: { azimuth: 0, elevation: -15 }
+    thighR: { azimuth: 180, elevation: -80 }
+    shinR: { azimuth: 180, elevation: -68 }
+    footR: { azimuth: 0, elevation: -12 }
+    upperArmL: { azimuth: 0, elevation: -60 }
+    forearmL: { azimuth: 0, elevation: -50 }
+    handL: { azimuth: 0, elevation: -45 }
+    upperArmR: { azimuth: 180, elevation: -68 }
+    forearmR: { azimuth: 180, elevation: -78 }
+    handR: { azimuth: 180, elevation: -80 }
 props:
   - type: wave
     amplitude: 0.3
@@ -39,10 +36,11 @@ props:
     y: -0.18
     breaking: false
   - type: surfboard
-    under: [ankleL, ankleR]
+    under: [ ankleL, ankleR ]
     rotation: -2
     length: 1.7
-    offset: [-0.5, -0.1]
+    offset: [ -0.5, -0.1 ]
 muscles:
-  engaged: [gastrocnemius, tibialisAnterior, quadriceps, erectorSpinae]
-  stretched: [hamstrings, pectoralis]
+  engaged: [ gastrocnemius, tibialisAnterior, quadriceps, erectorSpinae ]
+  stretched: [ hamstrings, pectoralis ]
+camera: side