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
about: Report a movement that doesn't render correctly or triggers joint range-of-motion warnings
4
+
title: '[MOVEMENT] '
5
+
labels: movement, bug
6
+
assignees: ''
7
+
8
+
---
9
+
10
+
**Which movement is having an issue?**
11
+
Name of the preset/movement: (e.g., deadlift, squat, waltz-box) or paste the shared link if it's a custom script.
12
+
13
+
**Describe the rendering or biomechanical issue**
14
+
Explain what is wrong with the visual animation or which joint warnings are triggered (e.g. "Knee flexion triggers warning at 95 degrees during descent").
15
+
16
+
**Provide the `.posecode` source**
17
+
If it's a custom movement or you modified an existing preset, paste the full `.posecode` script block here:
18
+
19
+
```posecode
20
+
# Paste code here
21
+
```
22
+
23
+
**What is the expected posture/movement?**
24
+
A brief description or link to medical/biomechanical standard data detailing how it should look or what the actual joint limit should be.
25
+
26
+
**Are you interested in sending a PR to fix this?**
27
+
-[ ] Yes (Check out CONTRIBUTING.md for details on adding/editing presets)
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
6
+
7
+
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
8
+
9
+
## Our Standards
10
+
11
+
Examples of behavior that contributes to a positive environment for our community include:
12
+
13
+
* Demonstrating empathy and kindness toward other people
14
+
* Being respectful of differing opinions, viewpoints, and experiences
15
+
* Giving and gracefully accepting constructive feedback
16
+
* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
17
+
* Focusing on what is best for the overall community, and not just for us as individuals
18
+
19
+
Examples of unacceptable behavior include:
20
+
21
+
* The use of sexualized language or imagery, and unwelcome sexual attention or advances
22
+
* Trolling, insulting or derogatory comments, and personal or political attacks
23
+
* Public or private harassment
24
+
* Publishing others' private information, such as a physical or email address, without their explicit permission
25
+
* Other conduct which could reasonably be considered inappropriate in a professional setting
26
+
27
+
## Enforcement Responsibilities
28
+
29
+
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
30
+
31
+
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
32
+
33
+
## Scope
34
+
35
+
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
36
+
37
+
## Enforcement
38
+
39
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **hello@posecode.org**. All complaints will be reviewed and investigated promptly and fairly.
40
+
41
+
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
42
+
43
+
## Attribution
44
+
45
+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][version].
Thank you for your interest in contributing to Posecode! We welcome contributions from developers, biomechanists, and creators.
4
+
5
+
To maintain a high-quality codebase, please review the contribution guidelines below.
6
+
7
+
---
8
+
9
+
## Workspace Architecture
10
+
11
+
Posecode is structured as an npm-based monorepo using **npm workspaces**:
12
+
13
+
-`packages/posecode-parser`: Text parser converting `.posecode` to validated, ROM-clamped IR (pure TypeScript).
14
+
-`packages/posecode-render`: 3D Forward Kinematics and CCD IK WebGL renderer (Three.js).
15
+
-`packages/posecode-embed`: Light `<posecode-player>` web component for embedding 3D figures in blogs/docs.
16
+
-`packages/posecode-share`: Permalink codec/compressor for creating short, shareable links.
17
+
-`packages/posecode-lsp`: Language Server Protocol implementation for editor autocompletion and diagnostic warnings.
18
+
-`packages/posecode-mcp`: Model Context Protocol server exposing parser, authoring guide, and renderer to LLM agents.
19
+
-`packages/posecode-eval`: Biomechanical scoring evaluations and headless regression testing.
20
+
-`playground`: The main interactive web sandbox (Vite + TypeScript).
21
+
22
+
---
23
+
24
+
## Local Development & Setup
25
+
26
+
### 1. Prerequisites
27
+
Ensure you have **Node.js 20+** installed.
28
+
29
+
### 2. Install Dependencies
30
+
Run the following command at the monorepo root to link all workspace packages:
31
+
```bash
32
+
npm install
33
+
```
34
+
35
+
### 3. Run the Playground
36
+
Start the local Vite dev server:
37
+
```bash
38
+
npm run dev
39
+
```
40
+
Open your browser to `http://localhost:5173`.
41
+
42
+
### 4. Build the Project
43
+
To compile the production build:
44
+
```bash
45
+
npm run build
46
+
```
47
+
48
+
---
49
+
50
+
## Testing & Quality Control
51
+
52
+
We run a strict set of checks on all PRs to ensure regressions are not introduced.
53
+
54
+
### Unit Tests
55
+
Run the unit test suite across all packages using Vitest:
56
+
```bash
57
+
npm test
58
+
```
59
+
60
+
### Biomechanical Invariant Evals
61
+
The fidelity scorecard headlessly solves FK and IK constraints for all example movements to verify biomechanical invariants (e.g., verifying that a deadlift maintains a flat back and matches vertical shins):
62
+
```bash
63
+
npm run eval
64
+
```
65
+
66
+
### Type Checking
67
+
Run compiler typechecks on all workspaces:
68
+
```bash
69
+
npm run typecheck
70
+
```
71
+
72
+
---
73
+
74
+
## How to Add a New Example Movement
75
+
76
+
To add a new movement preset to the catalog:
77
+
78
+
1.**Write the `.posecode` script**: Create a file named `spec/examples/<your-movement-id>.posecode` and write your movement steps.
79
+
2.**Import the script**: Open `playground/src/presets.ts` and add an import at the top of the file using the `?raw` loader:
4.**Regenerate Static Pages**: Statically generated pages must be updated before committing:
97
+
```bash
98
+
node scripts/generate-content-pages.mjs
99
+
```
100
+
5.**Verify Fidelity**: Run the eval suite to make sure the movement compiles warning-free and conforms to safety limits:
101
+
```bash
102
+
npm run eval
103
+
```
104
+
105
+
---
106
+
107
+
## Coding Conventions
108
+
109
+
-**TypeScript First**: All core library files must be written in strongly-typed TypeScript.
110
+
-**Framework-Agnostic Core**: Keep packages under `packages/` dependency-light and decoupled from frontend frameworks (like React or Vue) to maximize embeddability.
111
+
-**Range of Motion Clamping**: Never bypass the `posecode-parser` ROM bounds. All custom rigs or movements must adhere to healthy physical thresholds.
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
135
136
-
> ⚠️ Posecode's range-of-motion values are general literature data, not medical advice. Consult a qualified professional for physiotherapy or exercise prescription.
136
+
> Posecode's range-of-motion values are general literature data, not medical advice. Consult a qualified professional for physiotherapy or exercise prescription.
0 commit comments