laban-rig.git · README.md

revision fc813fbf6ee5e1554e429fb8bf91ffb33f310308 · complete file
# Canonical Humanoid Rig (ARKit + Laban) – Package

**Version:** 1.0.0  
**Date:** 2025-12-08

This package defines a **canonical humanoid rig description** that

- is directly **compatible with Apple's ARKit/iPhone mocap skeleton** (`ARSkeletonDefinition.defaultBody3D`),
- abstracts that skeleton into a **notation-agnostic JSON schema**,
- provides a **Laban-friendly grouping** of joints into body parts (TRUNK, ARM_LEFT, etc.),
- is designed to be easily mapped into common 3D / animation formats (USD/USDC/USDZ, FBX, glTF, BVH),
- is written to be **read and followed by an LLM** in other environments.

The package contains three files:

1. **README.md** – this document (high-level explanation and usage hints).
2. **canonical_rig.json** – a JSON file containing:
   - a validation **schema** for the canonical skeleton description, and
   - an **example skeleton instance** using a small, analysis-oriented subset of ARKit joints.
3. **EXTENSIBILITY.md** – guidelines on how to extend this rig description for:
   - more joints (hands, fingers, face),  
   - other source skeletons (e.g. Mixamo, Unreal Mannequin, SMPL, BVH),  
   - other analysis systems (e.g. Labanotation, Laban Movement Analysis, Effort categories).

---

## Concept in One Paragraph

The canonical rig is defined as an **abstract skeleton** composed of joints with the following attributes:

- `id` – a stable, human-readable canonical identifier (e.g. `"pelvis"`, `"spine_upper"`),
- `name` – the native name in the *source* skeleton (e.g. ARKit's `"hips_joint"`),
- `parentId` – the canonical parent joint,
- `side` – `"CENTER"`, `"LEFT"`, or `"RIGHT"`,
- `role` – a semantic role (e.g. `PELVIS`, `SPINE_UPPER`, `KNEE`, `WRIST`),
- `labanPart` – a coarse Laban body-region (e.g. `TRUNK`, `ARM_LEFT`, `FOOT_RIGHT`),
- `restTransform` – a 4×4 local matrix in the bind pose (or `null` if handled elsewhere).

LLMs and tools can use this description to **translate between**:

- **iPhone mocap data** (ARKit joint transforms),
- **procedural or symbolic movement descriptions** (e.g. “right arm forward-high for 0.5s”),
- **Laban-style movement notation**, which works on body segments (arm, leg, trunk, head),
- **engine-specific rigs** (Unity, Unreal, Blender, etc.), by mapping the canonical `id` to engine bones.

---

## How to Use this Package with an LLM

### 1. Provide the context

When you want to instruct an LLM (in another environment) to understand or use this rig:

1. Upload / paste **`canonical_rig.json`** to that environment, or copy its contents into a prompt.
2. Optionally upload **`EXTENSIBILITY.md`** if you want the LLM to customize or expand the rig.

You can say something like:

> “Here is a JSON file describing our canonical humanoid rig based on ARKit and Laban.  
> Please read it and then follow its schema when producing any skeleton descriptions,  
> rig mappings, or procedural movement specifications.”

### 2. Mapping ARKit data into the canonical rig

Given an `ARBodyAnchor` from Apple’s ARKit:

- `jointNames[i]` → should match the `name` field in the example skeleton.
- `jointModelTransforms[i]` → the transform for that joint in the character’s model space.

The LLM or tool should:

1. Build a lookup `name → canonical id` from the `joints` array.
2. For each ARKit joint:
   - Find the matching `joints[k]` record.
   - Attach the transform to that canonical joint id in a “pose frame” structure of your choice.

This yields a rig-agnostic, Laban-aware representation of the pose.

### 3. Mapping from the canonical rig into engines or files

You can embed the canonical skeleton in:

- **USD/USDC/USDZ**: map each joint `id` or `name` to a skeleton joint name in `UsdSkel`, adding `role` and `labanPart` as custom metadata.
- **FBX**: use the same joint names in the node hierarchy; attach extras for `role` and `labanPart`.
- **glTF**: store joints as nodes; use `extras` to store the canonical metadata.
- **BVH**: define a reduced hierarchy and maintain a mapping table `bvhName → canonical id` for analysis.

The key principle: **do not lose the canonical ids or semantic tags**. They are what make Laban-style reasoning portable.

---

## Relationship to Laban Notation

- Laban works primarily with **body segments** (e.g. “right arm”, “left leg”, “trunk”).  
- The canonical rig groups individual joints into **LabanPart** categories:
  - `TRUNK`, `HEAD_NECK`, `ARM_LEFT`, `ARM_RIGHT`, `LEG_LEFT`, `LEG_RIGHT`, `FOOT_LEFT`, `FOOT_RIGHT`, etc.
- For movement analysis, you typically use segments such as:
  - `pelvis → neck_top` for the trunk,
  - `shoulder_right → wrist_right` for the right arm,
  - `hip_left → ankle_left` for the left leg, etc.

These segments can then be classified into **Laban directions and levels** (forward/backward, left/right, high/middle/low) and movement durations, which are notated symbolically in Labanotation.

The canonical rig does **not** encode Laban symbols directly, but it **provides the structural information** needed to compute or realize them.

---

## File Overview (Quick Reference)

- **`canonical_rig.json`**
  - `skeletonSchema` – JSON Schema for validating canonical skeleton descriptions.
  - `exampleSkeleton` – a minimal, analysis-oriented skeleton instance with ~20 joints.

- **`EXTENSIBILITY.md`**
  - How to add more joints (fingers, face).
  - How to adapt the canonical schema to other skeleton sources.
  - How to keep Laban and ARKit compatibility when extending.

This package is intentionally minimal and text-based so it can be embedded in prompts, version-controlled, and shared as a foundation for further research or tooling.