posecode-parser

posecode-parser

Parses .posecode, a small text language for describing human movement, into a validated, range-of-motion-clamped intermediate representation (IR).

Part of Posecode: a kinematic-motion protocol LLMs can write, rendered as an animated 3D figure in the browser. See the language spec for the full grammar.

Install

npm install posecode-parser

Usage

import { parse } from "posecode-parser";

const { ir, warnings, errors } = parse(`
  posecode exercise "Body-weight squat"
    rig humanoid
    pose start = standing

    step "Descend" 1.6s settle:
      hips: flex 80
      knees: flex 95
      ground-lock: feet

    repeat 8
`);

if (errors.length === 0 && ir) {
  // Pass `ir` to posecode-render to animate it, or inspect it directly.
}

Append : to a built-in start pose to customize it with sparse, ROM-clamped joint targets. The composed pose is used both at load and when the animation loops:

  pose start = standing:
    shoulders: flex 20
    elbow_left: flex 35

A document may contain only one pose start declaration; duplicates are reported as errors rather than replacing an earlier built-in pose or block.

Validate a movement library

The parser includes a zero-config validator for local files and directories:

npx posecode-parser@latest validate ./movements
npx posecode-parser@latest validate --strict ./movements

The command recurses through directories, prints file-and-line diagnostics, and exits non-zero for parse errors. --strict also fails on ROM-clamp warnings; --json emits machine-readable results for CI.

Timing modes

Canonical modes are flow, settle, drive, snap, and linear. The v0.1 aliases ease-in, ease-out, and ease-in-out remain accepted so existing movement files keep working.

parse() never throws: malformed or out-of-range documents come back as structured errors/warnings instead. Every joint angle in ir is clamped to Posecode's configured range-of-motion bounds, so a hallucinated knee: flex 200 renders at the configured 144° ceiling with a warning. These rig constraints are not a clinical safety assessment of the full movement.

License

Apache-2.0