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).

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.

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.”

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.

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.

• 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.

• 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.