You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -22,69 +29,81 @@ as a tiny human-readable language that renders to an animated 3D figure in the b
22
29
23
30
---
24
31
25
-
## Why
26
-
27
-
Ask an LLM to explain a push-up and it can only give you prose or a flat image.
28
-
The model *knows* the biomechanics ("elbows flex, shoulders abduct on the
29
-
descent"), it just has no syntax to express it that a renderer can read.
30
-
Diffusion-based text-to-motion models exist, but they're heavy, expensive, and
31
-
give you no fine control over the anatomical phases.
32
-
33
-
Posecode takes the opposite, lightweight approach (see [the research](#background)):
34
-
35
-
- The LLM writes a small **`.posecode`** document: semantic phases, not 3D matrices.
36
-
- A **client-side** parser + Three.js renderer animates it. Generation is a
37
-
fraction of a cent of text; rendering runs at 60fps on a phone.
38
-
- Every angle is **hard-clamped to a healthy range of motion**, so a model
39
-
hallucinating "knee flex 200°" can't produce an anatomically impossible joint.
40
-
41
-
```posecode
42
-
posecode exercise "Body-weight squat"
43
-
rig humanoid
44
-
pose start = standing
45
-
46
-
step "Descend" 1.6s ease-in-out:
47
-
hips: flex 80
48
-
knees: flex 95
49
-
ankles: dorsiflex 14
50
-
ground-lock: feet
51
-
cue "Sit the hips back, chest proud, knees track over the toes"
52
-
53
-
step "Drive up" 1.2s ease-out:
54
-
hips: flex 0
55
-
knees: flex 0
56
-
ankles: dorsiflex 0
57
-
ground-lock: feet
58
-
cue "Drive through the heels to stand tall"
59
-
60
-
repeat 8
32
+
## Why Posecode?
33
+
34
+
Ask an LLM to explain a physical movement, and it will give you unstructured prose or a static, flat diagram. But large language models already *understand* the biomechanics of movement (e.g., "elbows flex, shoulders abduct on the descent of a push-up"). They just lack a standardized syntax to express it in a way that a computer can render dynamically.
35
+
36
+
### Why not diffusion text-to-motion models?
37
+
38
+
While neural network-based text-to-motion models exist, they are impractical for consumer web applications:
39
+
-**Resource Intensive**: They require heavy, expensive GPU hosting, making real-time generation and scaling cost-prohibitive.
40
+
-**No Fine Control**: They output black-box 3D coordinate trajectories, making it impossible to adjust anatomical phases, joint limits, or speed programmatically.
41
+
-**Safety Hazards**: There are no safety boundaries, meaning the model can easily render joint extensions that are anatomically impossible or physically dangerous.
42
+
43
+
### The Posecode Approach
44
+
45
+
Posecode takes the opposite, lightweight approach:
46
+
-**Text-Driven**: The LLM writes a tiny **`.posecode`** text document specifying semantic joint angles and phase times—generation costs a fraction of a cent.
47
+
-**Unbelievably Fast**: A client-side parser and WebGL renderer animate the figure at 60 FPS directly in the browser—even on low-end mobile devices.
48
+
-**Anatomically Safe**: Every joint rotation is **clamped to clinical range-of-motion limits** from standard physiotherapy tables. Hallucinations like `knee: flex 200` are safely capped with warnings.
49
+
50
+
---
51
+
52
+
## The Idea in 30 Seconds
53
+
54
+
A `.posecode` file describes human movements as a sequence of timed steps with targeted joint movements and range-of-motion rules:
*See the [Embed Package README](packages/posecode-embed/README.md) for customizing autoplay, controls, speed, and styling.*
64
86
87
+
### 💻 Core Libraries (For custom JS/TS apps)
88
+
Build custom rendering or parsing logic directly in your own applications:
65
89
```bash
66
-
npm install
67
-
npm run dev # opens the playground (Vite) at http://localhost:5173
68
-
npm test# parser + renderer + eval test suites
69
-
npm run eval# fidelity scorecard: geometric invariants over every example
90
+
# Parser only (converts text to range-of-motion clamped IR)
91
+
npm install posecode-parser
92
+
93
+
# WebGL 3D Renderer (built on Three.js)
94
+
npm install posecode-render
70
95
```
71
96
72
-
In the playground: pick an example, watch it animate, edit the text live, and
73
-
hit **Copy LLM prompt** to get a system prompt that teaches ChatGPT/Claude to
74
-
write Posecode for you, or wire up the [MCP server](packages/posecode-mcp) so
75
-
your agent authors, validates, and renders movements natively.
97
+
---
76
98
77
99
## How Posecode stays honest
78
100
79
101
Two safety layers ship with the language:
80
102
81
-
-**ROM clamping**: every angle is hard-clamped to healthy range-of-motion
82
-
tables before rendering; a hallucinated `knee: flex 200` renders at its
83
-
ceiling with a warning, never an impossible joint.
84
-
-**Fidelity evals**: [`posecode-eval`](packages/posecode-eval) re-runs the
85
-
real parser → FK → ground-lock pipeline headlessly and scores geometric
86
-
invariants ("a deadlift pitches the torso ≥ 50° with vertical shins"). Every
87
-
example must pass every invariant in CI.
103
+
-**ROM clamping**: every angle is hard-clamped to healthy range-of-motion tables before rendering; a hallucinated `knee: flex 200` renders at its ceiling with a warning, never an impossible joint.
104
+
-**Fidelity evals**: [`posecode-eval`](packages/posecode-eval) re-runs the real parser → FK → ground-lock pipeline headlessly and scores geometric invariants ("a deadlift pitches the torso ≥ 50° with vertical shins"). Every example must pass every invariant in CI.
105
+
106
+
---
88
107
89
108
## Packages
90
109
@@ -97,40 +116,29 @@ Two safety layers ship with the language:
|[`playground`](playground)| Live editor + 3D viewport + warnings + the LLM prompt + shareable links. |
99
118
100
-
The protocol and both libraries are **MIT-licensed**: the open core. See
101
-
[`spec/SPEC.md`](spec/SPEC.md) for the full language and
102
-
[`spec/llm-authoring.md`](spec/llm-authoring.md) for the authoring prompt.
103
-
For where Posecode spreads fastest and the per-domain go-to-market plan, see
104
-
[`docs/market-research.md`](docs/market-research.md); for the engine roadmap,
105
-
[`ROADMAP.md`](ROADMAP.md).
119
+
The protocol and both libraries are **MIT-licensed**: the open core. See [`spec/SPEC.md`](spec/SPEC.md) for the full language and [`spec/llm-authoring.md`](spec/llm-authoring.md) for the authoring prompt.
120
+
For where Posecode spreads fastest and the per-domain go-to-market plan, see [`docs/market-research.md`](docs/market-research.md); for the engine roadmap, [`ROADMAP.md`](ROADMAP.md).
121
+
122
+
---
106
123
107
124
## Scope (v0.1)
108
125
109
-
✅ Single-person movement across fitness, physio, desk, dance, education & rehab ·
This project follows a design study, *"Kinematic Motion Definition Protocols for Large Language Models"*, which argues for a semantic DSL over diffusion models, specifies ROM-based safety constraints from clinical normative data, and lays out the open-core commercialization path. The spec cross-references its sections (§4 DSL, §5 biomechanics, §6 client rendering, §7 strategy).
135
+
136
+
> ⚠️ Posecode's range-of-motion values are general literature data, not medical advice. Consult a qualified professional for physiotherapy or exercise prescription.
126
137
127
-
> ⚠️ Posecode's range-of-motion values are general literature data, not medical
128
-
> advice. Consult a qualified professional for physiotherapy or exercise
129
-
> prescription.
138
+
---
130
139
131
140
## Feedback & Support
132
141
133
142
We'd love to hear your feedback! You can reach us in two ways:
134
143
-**Email**: Send us an email at [hello@posecode.org](mailto:hello@posecode.org?subject=Posecode%20Feedback).
135
144
-**GitHub Issues**: If you found a bug or have a feature request, please [open a GitHub Issue](https://github.com/posecode-dev/posecode/issues).
0 commit comments