@babylonjs/core 9.3.1 → 9.3.2

package/XR/features/WebXRBodyTracking.d.ts

@@ -0,0 +1,952 @@
+import { WebXRAbstractFeature } from "./WebXRAbstractFeature.js";
+import { type WebXRSessionManager } from "../webXRSessionManager.js";
+import { type AbstractMesh } from "../../Meshes/abstractMesh.js";
+import { Quaternion } from "../../Maths/math.vector.js";
+import { type Nullable } from "../../types.js";
+import { type IDisposable, type Scene } from "../../scene.js";
+import { Observable } from "../../Misc/observable.js";
+import { TransformNode } from "../../Meshes/transformNode.js";
+import { type Node } from "../../node.js";
+/**
+ * All 83 body joint names as defined by the WebXR Body Tracking specification.
+ * @see https://immersive-web.github.io/body-tracking/#xrbody-interface
+ */
+export declare enum WebXRBodyJoint {
+    /** The center of the hips / pelvis */
+    HIPS = "hips",
+    /** Lower spine (lumbar) */
+    SPINE_LOWER = "spine-lower",
+    /** Middle spine (thoracic) */
+    SPINE_MIDDLE = "spine-middle",
+    /** Upper spine */
+    SPINE_UPPER = "spine-upper",
+    /** Chest */
+    CHEST = "chest",
+    /** Neck */
+    NECK = "neck",
+    /** Head */
+    HEAD = "head",
+    /** Left shoulder */
+    LEFT_SHOULDER = "left-shoulder",
+    /** Left scapula */
+    LEFT_SCAPULA = "left-scapula",
+    /** Left upper arm */
+    LEFT_ARM_UPPER = "left-arm-upper",
+    /** Left forearm (lower arm) */
+    LEFT_ARM_LOWER = "left-arm-lower",
+    /** Left hand wrist twist (forearm twist) */
+    LEFT_HAND_WRIST_TWIST = "left-hand-wrist-twist",
+    /** Right shoulder */
+    RIGHT_SHOULDER = "right-shoulder",
+    /** Right scapula */
+    RIGHT_SCAPULA = "right-scapula",
+    /** Right upper arm */
+    RIGHT_ARM_UPPER = "right-arm-upper",
+    /** Right forearm (lower arm) */
+    RIGHT_ARM_LOWER = "right-arm-lower",
+    /** Right hand wrist twist (forearm twist) */
+    RIGHT_HAND_WRIST_TWIST = "right-hand-wrist-twist",
+    /** Left palm center */
+    LEFT_HAND_PALM = "left-hand-palm",
+    /** Left wrist */
+    LEFT_HAND_WRIST = "left-hand-wrist",
+    /** Left thumb metacarpal */
+    LEFT_HAND_THUMB_METACARPAL = "left-hand-thumb-metacarpal",
+    /** Left thumb proximal phalanx */
+    LEFT_HAND_THUMB_PHALANX_PROXIMAL = "left-hand-thumb-phalanx-proximal",
+    /** Left thumb distal phalanx */
+    LEFT_HAND_THUMB_PHALANX_DISTAL = "left-hand-thumb-phalanx-distal",
+    /** Left thumb tip */
+    LEFT_HAND_THUMB_TIP = "left-hand-thumb-tip",
+    /** Left index finger metacarpal */
+    LEFT_HAND_INDEX_METACARPAL = "left-hand-index-metacarpal",
+    /** Left index finger proximal phalanx */
+    LEFT_HAND_INDEX_PHALANX_PROXIMAL = "left-hand-index-phalanx-proximal",
+    /** Left index finger intermediate phalanx */
+    LEFT_HAND_INDEX_PHALANX_INTERMEDIATE = "left-hand-index-phalanx-intermediate",
+    /** Left index finger distal phalanx */
+    LEFT_HAND_INDEX_PHALANX_DISTAL = "left-hand-index-phalanx-distal",
+    /** Left index finger tip */
+    LEFT_HAND_INDEX_TIP = "left-hand-index-tip",
+    /** Left middle finger metacarpal */
+    LEFT_HAND_MIDDLE_METACARPAL = "left-hand-middle-metacarpal",
+    /** Left middle finger proximal phalanx */
+    LEFT_HAND_MIDDLE_PHALANX_PROXIMAL = "left-hand-middle-phalanx-proximal",
+    /** Left middle finger intermediate phalanx */
+    LEFT_HAND_MIDDLE_PHALANX_INTERMEDIATE = "left-hand-middle-phalanx-intermediate",
+    /** Left middle finger distal phalanx */
+    LEFT_HAND_MIDDLE_PHALANX_DISTAL = "left-hand-middle-phalanx-distal",
+    /** Left middle finger tip */
+    LEFT_HAND_MIDDLE_TIP = "left-hand-middle-tip",
+    /** Left ring finger metacarpal */
+    LEFT_HAND_RING_METACARPAL = "left-hand-ring-metacarpal",
+    /** Left ring finger proximal phalanx */
+    LEFT_HAND_RING_PHALANX_PROXIMAL = "left-hand-ring-phalanx-proximal",
+    /** Left ring finger intermediate phalanx */
+    LEFT_HAND_RING_PHALANX_INTERMEDIATE = "left-hand-ring-phalanx-intermediate",
+    /** Left ring finger distal phalanx */
+    LEFT_HAND_RING_PHALANX_DISTAL = "left-hand-ring-phalanx-distal",
+    /** Left ring finger tip */
+    LEFT_HAND_RING_TIP = "left-hand-ring-tip",
+    /** Left little finger metacarpal */
+    LEFT_HAND_LITTLE_METACARPAL = "left-hand-little-metacarpal",
+    /** Left little finger proximal phalanx */
+    LEFT_HAND_LITTLE_PHALANX_PROXIMAL = "left-hand-little-phalanx-proximal",
+    /** Left little finger intermediate phalanx */
+    LEFT_HAND_LITTLE_PHALANX_INTERMEDIATE = "left-hand-little-phalanx-intermediate",
+    /** Left little finger distal phalanx */
+    LEFT_HAND_LITTLE_PHALANX_DISTAL = "left-hand-little-phalanx-distal",
+    /** Left little finger tip */
+    LEFT_HAND_LITTLE_TIP = "left-hand-little-tip",
+    /** Right palm center */
+    RIGHT_HAND_PALM = "right-hand-palm",
+    /** Right wrist */
+    RIGHT_HAND_WRIST = "right-hand-wrist",
+    /** Right thumb metacarpal */
+    RIGHT_HAND_THUMB_METACARPAL = "right-hand-thumb-metacarpal",
+    /** Right thumb proximal phalanx */
+    RIGHT_HAND_THUMB_PHALANX_PROXIMAL = "right-hand-thumb-phalanx-proximal",
+    /** Right thumb distal phalanx */
+    RIGHT_HAND_THUMB_PHALANX_DISTAL = "right-hand-thumb-phalanx-distal",
+    /** Right thumb tip */
+    RIGHT_HAND_THUMB_TIP = "right-hand-thumb-tip",
+    /** Right index finger metacarpal */
+    RIGHT_HAND_INDEX_METACARPAL = "right-hand-index-metacarpal",
+    /** Right index finger proximal phalanx */
+    RIGHT_HAND_INDEX_PHALANX_PROXIMAL = "right-hand-index-phalanx-proximal",
+    /** Right index finger intermediate phalanx */
+    RIGHT_HAND_INDEX_PHALANX_INTERMEDIATE = "right-hand-index-phalanx-intermediate",
+    /** Right index finger distal phalanx */
+    RIGHT_HAND_INDEX_PHALANX_DISTAL = "right-hand-index-phalanx-distal",
+    /** Right index finger tip */
+    RIGHT_HAND_INDEX_TIP = "right-hand-index-tip",
+    /** Right middle finger metacarpal */
+    RIGHT_HAND_MIDDLE_METACARPAL = "right-hand-middle-metacarpal",
+    /** Right middle finger proximal phalanx */
+    RIGHT_HAND_MIDDLE_PHALANX_PROXIMAL = "right-hand-middle-phalanx-proximal",
+    /** Right middle finger intermediate phalanx */
+    RIGHT_HAND_MIDDLE_PHALANX_INTERMEDIATE = "right-hand-middle-phalanx-intermediate",
+    /** Right middle finger distal phalanx */
+    RIGHT_HAND_MIDDLE_PHALANX_DISTAL = "right-hand-middle-phalanx-distal",
+    /** Right middle finger tip */
+    RIGHT_HAND_MIDDLE_TIP = "right-hand-middle-tip",
+    /** Right ring finger metacarpal */
+    RIGHT_HAND_RING_METACARPAL = "right-hand-ring-metacarpal",
+    /** Right ring finger proximal phalanx */
+    RIGHT_HAND_RING_PHALANX_PROXIMAL = "right-hand-ring-phalanx-proximal",
+    /** Right ring finger intermediate phalanx */
+    RIGHT_HAND_RING_PHALANX_INTERMEDIATE = "right-hand-ring-phalanx-intermediate",
+    /** Right ring finger distal phalanx */
+    RIGHT_HAND_RING_PHALANX_DISTAL = "right-hand-ring-phalanx-distal",
+    /** Right ring finger tip */
+    RIGHT_HAND_RING_TIP = "right-hand-ring-tip",
+    /** Right little finger metacarpal */
+    RIGHT_HAND_LITTLE_METACARPAL = "right-hand-little-metacarpal",
+    /** Right little finger proximal phalanx */
+    RIGHT_HAND_LITTLE_PHALANX_PROXIMAL = "right-hand-little-phalanx-proximal",
+    /** Right little finger intermediate phalanx */
+    RIGHT_HAND_LITTLE_PHALANX_INTERMEDIATE = "right-hand-little-phalanx-intermediate",
+    /** Right little finger distal phalanx */
+    RIGHT_HAND_LITTLE_PHALANX_DISTAL = "right-hand-little-phalanx-distal",
+    /** Right little finger tip */
+    RIGHT_HAND_LITTLE_TIP = "right-hand-little-tip",
+    /** Left upper leg (thigh) */
+    LEFT_UPPER_LEG = "left-upper-leg",
+    /** Left lower leg (shin) */
+    LEFT_LOWER_LEG = "left-lower-leg",
+    /** Left foot ankle twist */
+    LEFT_FOOT_ANKLE_TWIST = "left-foot-ankle-twist",
+    /** Left foot ankle */
+    LEFT_FOOT_ANKLE = "left-foot-ankle",
+    /** Left foot subtalar */
+    LEFT_FOOT_SUBTALAR = "left-foot-subtalar",
+    /** Left foot transverse */
+    LEFT_FOOT_TRANSVERSE = "left-foot-transverse",
+    /** Left foot ball */
+    LEFT_FOOT_BALL = "left-foot-ball",
+    /** Right upper leg (thigh) */
+    RIGHT_UPPER_LEG = "right-upper-leg",
+    /** Right lower leg (shin) */
+    RIGHT_LOWER_LEG = "right-lower-leg",
+    /** Right foot ankle twist */
+    RIGHT_FOOT_ANKLE_TWIST = "right-foot-ankle-twist",
+    /** Right foot ankle */
+    RIGHT_FOOT_ANKLE = "right-foot-ankle",
+    /** Right foot subtalar */
+    RIGHT_FOOT_SUBTALAR = "right-foot-subtalar",
+    /** Right foot transverse */
+    RIGHT_FOOT_TRANSVERSE = "right-foot-transverse",
+    /** Right foot ball */
+    RIGHT_FOOT_BALL = "right-foot-ball"
+}
+/**
+ * Parent index for each joint in {@link BodyJointReferenceArray} order.
+ * -1 means "root" (no parent).  Used to convert world-space XR poses to
+ * local-space transforms suitable for skeleton bones.
+ *
+ * Hierarchy follows the WebXR Body Tracking specification and standard
+ * humanoid anatomy.
+ */
+export declare const BodyJointParentIndex: number[];
+/**
+ * Logical body parts for convenient grouping of joints.
+ */
+export declare enum BodyPart {
+    /** Torso / spine (hips through head) */
+    TORSO = "torso",
+    /** Left arm (shoulder through wrist twist) */
+    LEFT_ARM = "left-arm",
+    /** Right arm (shoulder through wrist twist) */
+    RIGHT_ARM = "right-arm",
+    /** Left hand (palm through finger tips) */
+    LEFT_HAND = "left-hand",
+    /** Right hand (palm through finger tips) */
+    RIGHT_HAND = "right-hand",
+    /** Left leg (upper leg through foot ball) */
+    LEFT_LEG = "left-leg",
+    /** Right leg (upper leg through foot ball) */
+    RIGHT_LEG = "right-leg"
+}
+/**
+ * A dictionary mapping each {@link WebXRBodyJoint} to a bone name in a rigged body mesh.
+ *
+ * When you supply a rigged mesh to {@link WebXRTrackedBody.setBodyMesh}, provide
+ * a mapping so the feature knows which skeleton bone to drive for each joint.
+ *
+ * @example
+ * ```typescript
+ * const rigMapping: XRBodyMeshRigMapping = {
+ *   "hips": "Bip01_Pelvis",
+ *   "spine-lower": "Bip01_Spine",
+ *   "head": "Bip01_Head",
+ *   // …remaining joints…
+ * };
+ * ```
+ */
+export type XRBodyMeshRigMapping = {
+    [jointName in WebXRBodyJoint]?: string;
+};
+/**
+ * Represents the XRBodySpace native interface as defined by the spec.
+ * An XRBodySpace is an XRSpace that additionally exposes a jointName.
+ * @see https://immersive-web.github.io/body-tracking/#xrjointspace-interface
+ */
+interface XRBodySpace extends XRSpace {
+    readonly jointName: string;
+}
+/**
+ * Represents the native XRBody interface as defined by the spec.
+ * An XRBody is an iterable map of XRBodyJoint → XRBodySpace.
+ * @see https://immersive-web.github.io/body-tracking/#xrbody-interface
+ */
+interface XRBody {
+    readonly size: number;
+    get(key: string): XRBodySpace | undefined;
+    forEach(callbackfn: (value: XRBodySpace, key: string, map: XRBody) => void): void;
+    [Symbol.iterator](): IterableIterator<[string, XRBodySpace]>;
+    entries(): IterableIterator<[string, XRBodySpace]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<XRBodySpace>;
+}
+declare global {
+    interface XRFrame {
+        body?: XRBody;
+    }
+}
+/**
+ * Configuration options for the WebXR body tracking feature.
+ */
+export interface IWebXRBodyTrackingOptions {
+    /**
+     * A pre-existing rigged body mesh to drive with tracked joint poses.
+     * If provided, skeleton bones will be linked to tracked joints automatically.
+     * The mesh should contain a skeleton whose bones can be mapped via `rigMapping`.
+     */
+    bodyMesh?: AbstractMesh;
+    /**
+     * A mapping from {@link WebXRBodyJoint} names to skeleton bone names.
+     * Required when the skeleton's bone names do not match the WebXR joint names.
+     * If omitted and a body mesh is provided, the feature assumes bones are
+     * named identically to the WebXR joint names (e.g. `"hips"`, `"left-arm-upper"`, etc.).
+     */
+    rigMapping?: XRBodyMeshRigMapping;
+    /**
+     * Scale factor applied to the local-space position of every joint.
+     *
+     * This uniformly scales the distances between parent and child joints,
+     * allowing you to fit XR body tracking data to meshes that are larger or
+     * smaller than the tracked user.
+     *
+     * - `1.0` (default): no scaling — real-world proportions.
+     * - `> 1.0`: stretches the skeleton (makes it taller / wider).
+     * - `< 1.0`: compresses the skeleton.
+     *
+     * Only affects local joint offsets, not the root (hips) position.
+     */
+    jointScaleFactor?: number;
+    /**
+     * Preserve bind-pose local translations for mapped bones and only retarget rotations.
+     *
+     * When `false` (default), mapped bones are translated directly to the tracked joint
+     * positions. This reproduces the tracked skeleton exactly, but can distort avatars whose
+     * proportions differ from the tracked user.
+     *
+     * When `true`, mapped child bones keep their bind-pose local translation offsets while
+     * still using the tracked joint rotations. This is the typical retargeting mode for
+     * driving arbitrary skinned characters without forcing them to the tracked skeleton's
+     * segment lengths.
+     */
+    preserveBindPoseBonePositions?: boolean;
+    /**
+     * Apply a per-bone orientation offset so the avatar bone basis matches the XR joint basis.
+     *
+     * When enabled, WebXR joint rotations are corrected using the bone's bind-space child axis.
+     * This is useful for rigs whose bone local axes do not match the anatomical axes used by
+     * the WebXR body-tracking joint orientations.
+     */
+    useBoneOrientationOffsets?: boolean;
+    /**
+     * Rotation applied in each tracked joint's local frame to re-base the
+     * XR joint axes. Some runtimes (e.g., some Meta Quest builds) emit body
+     * joint poses whose +Z axis points along the bone (parent → child), while
+     * most avatar rigs expect +Y along the bone. Setting this to
+     * `Quaternion.RotationAxis(Vector3.Right(), -Math.PI / 2)` converts
+     * "+Z-along-bone" joint data to "+Y-along-bone" before retargeting.
+     *
+     * Applied as a pre-multiply on each joint's world matrix:
+     * `M' = R × M`, which, under Babylon's row-vector convention
+     * (`v_world = v_local × M`), effectively re-bases the joint-local axes.
+     *
+     * Default `undefined` = identity (no re-basing).
+     */
+    jointLocalRotationOffset?: Quaternion;
+    /**
+     * Per–XR-joint override for the "aim child" joint used when
+     * {@link useBoneOrientationOffsets} is enabled.
+     *
+     * By default the aim direction for a mapped bone is computed against its
+     * nearest mapped descendant in the skeleton. For rigs whose XR-mapped
+     * spine chain has very short segments (e.g. WebXR's `hips`→`spine-lower`
+     * is typically only ~1 cm), the aim direction becomes noise-dominated and
+     * can produce a large incorrect rotation for the parent bone.
+     *
+     * Use this map to redirect a specific XR joint's aim target to a farther
+     * XR joint whose relative position is stable. Both the source and target
+     * joint must be present in {@link rigMapping} (i.e. mapped to a bone on the
+     * skeleton).
+     *
+     * Example for a Mixamo-style rig where hips, spine, spine1, spine2 and
+     * neck are all mapped:
+     * ```ts
+     * aimChildOverrides: {
+     *   [WebXRBodyJoint.HIPS]: WebXRBodyJoint.SPINE_UPPER,   // skip spine-lower/middle
+     *   [WebXRBodyJoint.SPINE_LOWER]: WebXRBodyJoint.NECK,   // long stable segment
+     *   [WebXRBodyJoint.SPINE_MIDDLE]: WebXRBodyJoint.NECK,
+     * }
+     * ```
+     */
+    aimChildOverrides?: Partial<Record<WebXRBodyJoint, WebXRBodyJoint>>;
+    /**
+     * Convenience flag for Mixamo-rigged characters.
+     *
+     * When set to `true`, the feature automatically applies:
+     * - {@link MixamoRigMapping} as the `rigMapping` (skipping any explicit
+     *   `rigMapping` you provide).
+     * - {@link MixamoAimChildOverrides} as `aimChildOverrides` (skipping any
+     *   explicit `aimChildOverrides` you provide).
+     * - Turns on {@link useBoneOrientationOffsets} by default (you can still
+     *   override to `false`).
+     *
+     * The Mixamo `mixamorig:` bone-name prefix is detected automatically by
+     * inspecting the skeleton, so the same mapping works regardless of whether
+     * the bones have been renamed to strip the prefix (common when re-exporting).
+     */
+    isMixamoModel?: boolean;
+}
+/**
+ * Default rig mapping for Mixamo-rigged humanoid characters.
+ *
+ * Maps each supported {@link WebXRBodyJoint} to the corresponding Mixamo bone
+ * name, **without** the `mixamorig:` prefix. When the feature applies this
+ * mapping, it auto-detects whether the skeleton uses the `mixamorig:` prefix
+ * and prepends it as needed, so the same table works for both prefixed and
+ * unprefixed exports.
+ *
+ * @example
+ * ```ts
+ * xr.featuresManager.enableFeature(WebXRFeatureName.BODY_TRACKING, "latest", {
+ *     bodyMesh: myMixamoMesh,
+ *     isMixamoModel: true,
+ * });
+ * ```
+ *
+ * Or, if you want to extend or customize it:
+ * ```ts
+ * import { MixamoRigMapping } from "@babylonjs/core";
+ * const rigMapping: XRBodyMeshRigMapping = { ...MixamoRigMapping, [WebXRBodyJoint.NECK]: "MyNeckBone" };
+ * ```
+ */
+export declare const MixamoRigMapping: XRBodyMeshRigMapping;
+/**
+ * Default aim-child overrides for Mixamo-rigged humanoids.
+ *
+ * Redirects the short / noisy XR spine segments to longer, stable ones so that
+ * {@link IWebXRBodyTrackingOptions.useBoneOrientationOffsets} produces clean
+ * torso rotations. In WebXR data, `hips`→`spine-lower` is typically only ~1 cm
+ * apart — too short to give a stable aim direction — so we reroute Mixamo's
+ * Hips/Spine/Spine1 bones to aim at `spine-upper` / `neck` instead.
+ */
+export declare const MixamoAimChildOverrides: Partial<Record<WebXRBodyJoint, WebXRBodyJoint>>;
+/**
+ * Resolve the Mixamo rig mapping for a given body mesh, auto-detecting the
+ * `mixamorig:` bone-name prefix. Falls back to the unprefixed names.
+ * @param bodyMesh The rigged Mixamo body mesh.
+ * @returns An {@link XRBodyMeshRigMapping} whose bone names include the
+ *          detected prefix (if any).
+ * @internal
+ */
+export declare function _ResolveMixamoRigMapping(bodyMesh: AbstractMesh): XRBodyMeshRigMapping;
+/**
+ * Represents a tracked body during a WebXR session.
+ *
+ * This class manages the bridge between the WebXR body pose data and the
+ * Babylon.js scene graph.  It creates a set of {@link TransformNode}s — one per
+ * body joint — whose transforms are updated every frame from the XR runtime.
+ * When a rigged body mesh is attached, its skeleton bones are linked to these
+ * transform nodes, causing the mesh to follow the user's body automatically.
+ *
+ * Coordinate-system handling:
+ * - WebXR delivers poses in a right-handed system.
+ * - By default, Babylon.js uses a left-handed system.
+ * - The class converts the data in-place (negating the Z components of every
+ *   4 × 4 joint matrix) before decomposing into Babylon transforms.
+ * - If the mesh was authored in a right-handed tool (the common case for glTF),
+ *   the bone transforms are un-flipped so the skeleton interprets them correctly.
+ */
+export declare class WebXRTrackedBody implements IDisposable {
+    /**
+     * Fired when the body mesh is changed via {@link setBodyMesh}.
+     */
+    readonly onBodyMeshSetObservable: Observable<WebXRTrackedBody>;
+    private _scene;
+    /**
+     * One {@link TransformNode} per joint.  These receive the WebXR matrix data
+     * every frame and serve as link targets for skeleton bones.
+     */
+    private _jointTransforms;
+    /**
+     * Flat Float32Array that receives transform matrices directly from the
+     * WebXR API (via `fillPoses`). 16 floats per joint × 83 joints = 1 328 floats.
+     */
+    private _jointTransformMatrices;
+    /**
+     * Copy of the raw RHS XR matrices (before LHS conversion).
+     * Used to compute bone-local transforms for glTF skeletons that
+     * operate in RHS space.
+     */
+    private _jointTransformMatricesRHS;
+    /**
+     * Cached array of XRBodySpace objects extracted from the XRBody, kept in the
+     * same order as {@link BodyJointReferenceArray}.
+     */
+    private _jointSpaces;
+    /** Temporary matrix: this joint's XR world-space matrix. */
+    private _tempJointMatrix;
+    /** Temporary matrix: parent joint's XR world-space matrix. */
+    private _tempParentMatrix;
+    /** Temporary matrix: computed bone-local matrix. */
+    private _tempLocalMatrix;
+    /** Temporary vector for scale extracted from decompose. */
+    private _tempScaleVector;
+    /** Temporary quaternion for decompose. */
+    private _tempRotQuat;
+    /** Temporary position vector for decompose. */
+    private _tempPosVec;
+    /** Temporary quaternion for alternate rotation calculations. */
+    private _tempRotQuat2;
+    /** Temporary vector for desired child direction. */
+    private _tempDirection;
+    /** Temporary vector for joint-local child direction. */
+    private _tempLocalDirection;
+    /** Cached desired final positions for mapped joints. */
+    private _desiredFinalPositions;
+    /**
+     * For each joint index, the joint index of the nearest mapped SKELETON
+     * ancestor bone.  -1 when the bone has no mapped ancestor (root level).
+     * Precomputed in {@link setBodyMesh} by walking the skeleton hierarchy.
+     */
+    private _jointParentJointIdx;
+    /** Tracks which joint indices have a linked bone (for step 4b). */
+    private _jointHasBone;
+    /** Bone → XR joint index lookup, built in {@link setBodyMesh}. */
+    private _boneToJointIdx;
+    /** Original bind-pose local matrices for mapped bones. */
+    private _mappedBoneBindLocals;
+    /** Nearest mapped child bone for each mapped bone. */
+    private _mappedChildBones;
+    /** Bind-space local child direction for each mapped bone. */
+    private _bindLocalAimDirections;
+    /**
+     * XR joint index to aim each mapped bone at. This can be a mapped joint
+     * (same as `_boneToJointIdx.get(aimChildBone)`) or an **unmapped** XR
+     * joint whose tracked position is nonetheless useful for aim correction —
+     * e.g. `LEFT_HAND_MIDDLE_METACARPAL` for `mixamorig:LeftHand`, which has
+     * no mapped finger descendant but whose tracked position still defines
+     * "where the hand is pointing".
+     */
+    private _boneAimTargetJointIdx;
+    /**
+     * Per-mapped-bone bind-pose world rotation in mesh-local space
+     * (decomposed from `bone.getFinalMatrix()` at bind time). Used by the
+     * delta-from-bind retarget path (axis-convention-invariant).
+     */
+    private _bindBoneWorldRotMeshLocal;
+    /**
+     * Bind-pose tracked joint rotation in mesh-local space per mapped joint.
+     * Captured on the first tracked frame (or on demand via
+     * {@link captureTrackedBind}). `null` until captured.
+     */
+    private _trackedBindDesiredFinalRot;
+    /** Bind-pose tracked joint position (mesh-local), captured alongside rotation. */
+    private _trackedBindDesiredFinalPos;
+    /** True once a tracked-bind snapshot has been taken. */
+    private _hasTrackedBind;
+    /**
+     * When `true` (default), the first tracked frame after the feature
+     * attaches is used as the "rest" pose for delta-from-bind retargeting.
+     * Set to `false` to require an explicit {@link captureTrackedBind} call.
+     */
+    autoCaptureBindOnFirstFrame: boolean;
+    /** Scratch quaternion for retarget delta composition. */
+    private _tempDeltaQuat;
+    private _tempBoneWorldRot;
+    private _tempParentNewWorldRotInv;
+    private _tempTrackedCurRot;
+    private _tempTrackedCurPos;
+    private _tempBindLocalScale;
+    private _tempBindLocalPos;
+    /**
+     * Per-bone cache of the current frame's computed world rotation.
+     * Entries are pooled across frames (values are reused via `copyFrom`)
+     * to avoid allocating a fresh Quaternion per mapped bone per frame.
+     * A bone is considered "populated this frame" iff it has been visited
+     * by the current retarget pass (tracked via `_computedBoneNewWorldRotFrameId`).
+     */
+    private _computedBoneNewWorldRot;
+    /** Per-bone marker: frame id at which the pooled rotation above was last set. */
+    private _computedBoneNewWorldRotFrameId;
+    private _currentRetargetFrameId;
+    /** Scratch quaternion reused for the parent-world accumulation loop. */
+    private _tempParentAccumRot;
+    /** Scratch quaternion reused for the parent-world intermediate product. */
+    private _tempParentAccumTmp;
+    /** The skeleton reference for iterating bones in parent-first order. */
+    private _skeleton;
+    /** Cached inverse of the skeleton mesh's world matrix. */
+    private _meshWorldMatrixInverse;
+    /** Cached inverse of the skeleton mesh pose matrix when initial skinning is used. */
+    private _initialSkinMatrixInverse;
+    /**
+     * Pre-allocated desiredFinal matrices (one per joint slot).
+     * `desiredFinal[i] = strip(xrWorld[i] × inv(meshWorld))` — the bone's
+     * target skeleton-space final matrix with parasitic scale removed.
+     */
+    private _desiredFinals;
+    /**
+     * Standalone TransformNodes created for unmapped skinned bones.
+     * These TNs are initialized to the bone's bind-pose local and linked
+     * so that `prepare()` reads deterministic values rather than the
+     * original glTF scene-graph TNs (which we don't control).
+     */
+    private _unmappedBoneNodes;
+    /** The mesh that owns the skeleton (used for world-matrix inverse). */
+    private _skeletonMesh;
+    /** The body mesh root (topmost parent), used to parent the mesh to the camera. */
+    private _bodyMeshRoot;
+    /** The rigged body mesh, if any. */
+    private _bodyMesh;
+    /** Scale factor for local joint offsets. */
+    private _jointScaleFactor;
+    /** Whether mapped bones should keep their bind-pose local translations. */
+    private readonly _preserveBindPoseBonePositions;
+    /** Whether mapped bones should correct WebXR joint rotations using bind-space orientation offsets. */
+    private readonly _useBoneOrientationOffsets;
+    /** Per–XR-joint override mapping for aim children (used with _useBoneOrientationOffsets). */
+    private _aimChildOverrides;
+    /**
+     * Runtime-mutable rotation applied in each tracked joint's local frame to
+     * re-base XR joint axes (e.g., "+Z-along-bone" → "+Y-along-bone").
+     * `null` = identity / disabled.
+     */
+    jointLocalRotationOffset: Nullable<Quaternion>;
+    /** Cached 4×4 matrix form of {@link jointLocalRotationOffset} for the fast path. */
+    private _jointLocalRotationOffsetMatrix;
+    /** Temporary matrix used when applying {@link jointLocalRotationOffset}. */
+    private _tempOffsetAppliedMatrix;
+    /**
+     * When true, bypass skeleton.prepare() and write skin matrices directly.
+     * This is a diagnostic flag to help isolate rendering issues. When the
+     * standard pipeline (TN → bone → prepare → skin matrices) produces
+     * unexpected results, enabling this writes `absInvBind × final` directly
+     * into the skeleton's transform matrix buffer.
+     * @internal
+     */
+    _directSkinWrite: boolean;
+    /**
+     * Debug info string from the last `updateFromXRFrame` call.
+     * Useful for diagnosing tracking failures on-device.
+     * @internal
+     */
+    _lastDebugInfo: string;
+    /**
+     * Get the current body mesh (if any).
+     */
+    get bodyMesh(): Nullable<AbstractMesh>;
+    /**
+     * Get or set the scale factor for local joint offsets.
+     * @see {@link IWebXRBodyTrackingOptions.jointScaleFactor}
+     */
+    get jointScaleFactor(): number;
+    set jointScaleFactor(value: number);
+    /**
+     * Returns the array of transform nodes representing each body joint.
+     * The order matches {@link WebXRBodyTracking.AllBodyJoints}; use
+     * {@link getJointTransform} or {@link getBodyPartTransforms} for
+     * name-based lookup.
+     *
+     * Note: when a body mesh is attached, these transform nodes are also
+     * used as the skeleton's link targets for mapped joints. In that case
+     * the values held by mapped-joint nodes are skeleton-local (parent bone's
+     * frame), not XR world-space. Unmapped-joint nodes always hold world-space
+     * pose. If you need world-space poses for every joint regardless of
+     * mapping, sample the bone matrices directly via the attached skeleton.
+     */
+    get jointTransforms(): readonly TransformNode[];
+    /**
+     * Get the transform node for a specific body joint.
+     * @param jointName The name of the body joint (from {@link WebXRBodyJoint}).
+     * @returns The transform node corresponding to that joint, or `undefined` if not found.
+     */
+    getJointTransform(jointName: WebXRBodyJoint): TransformNode | undefined;
+    /**
+     * Get all joint transform nodes that belong to a given body part.
+     * @param part The body part to query.
+     * @param result Optional pre-allocated array to fill (avoids per-call allocation).
+     *   The array is cleared and populated with the results.
+     * @returns An array of TransformNodes for that body part.
+     */
+    getBodyPartTransforms(part: BodyPart, result?: TransformNode[]): TransformNode[];
+    /**
+     * Construct a new tracked body instance.
+     * @param scene The Babylon.js scene.
+     * @param bodyMesh Optional rigged body mesh to attach immediately.
+     * @param rigMapping Optional mapping from WebXR joint names to skeleton bone names.
+     * @param jointScaleFactor Scale factor for local joint offsets (default 1.0).
+     * @param preserveBindPoseBonePositions Whether mapped bones should keep bind-pose local translations.
+     * @param useBoneOrientationOffsets Whether mapped bones should correct XR joint rotations using bind-space offsets.
+     * @param aimChildOverrides Per–XR-joint override for the aim child used with `useBoneOrientationOffsets`.
+     * @param jointLocalRotationOffset Optional rotation re-basing each XR joint's local frame (e.g. Z-along-bone → Y-along-bone).
+     */
+    constructor(scene: Scene, bodyMesh?: AbstractMesh, rigMapping?: XRBodyMeshRigMapping, jointScaleFactor?: number, preserveBindPoseBonePositions?: boolean, useBoneOrientationOffsets?: boolean, aimChildOverrides?: Partial<Record<WebXRBodyJoint, WebXRBodyJoint>>, jointLocalRotationOffset?: Quaternion);
+    /**
+     * Attach (or replace) a rigged body mesh.
+     *
+     * The mesh's skeleton bones are linked to the internal transform nodes
+     * that receive WebXR tracking data each frame.  If the mesh has a skeleton,
+     * the `rigMapping` (or a direct name match) is used to bind each bone.
+     *
+     * @param bodyMesh The rigged mesh to drive.
+     * @param rigMapping An optional mapping from {@link WebXRBodyJoint} to bone name.
+     *   If omitted, bones are expected to be named after the WebXR joint names.
+     */
+    setBodyMesh(bodyMesh: AbstractMesh, rigMapping?: XRBodyMeshRigMapping): void;
+    /**
+     * Update joint transforms from the current XR frame.
+     *
+     * This method is called once per frame by the feature class.  Internally it:
+     * 1. Extracts all XRBodySpaces from the XRBody.
+     * 2. Fills the transform-matrix buffer via `fillPoses()` (or per-joint fallback).
+     * 3. Converts from WebXR right-handed to Babylon left-handed coordinates.
+     * 4. Decomposes each matrix into the corresponding TransformNode.
+     * 5. Parents the body mesh root to the XR camera so it tracks correctly.
+     *
+     * @param xrFrame The current XRFrame.
+     * @param referenceSpace The XRReferenceSpace to resolve poses against.
+     * @param xrCameraParent The parent node of the XR camera (used for parenting).
+     * @returns `true` if valid tracking data was processed, `false` otherwise.
+     */
+    updateFromXRFrame(xrFrame: XRFrame, referenceSpace: XRReferenceSpace, xrCameraParent: Nullable<Node>): boolean;
+    /**
+     * Replay a pre-captured joint matrix set through the retargeting
+     * pipeline as if it had just been delivered by an XR frame.
+     *
+     * Useful for headset-less testing: call with a snapshot captured via
+     * {@link snapshotFrame} (the `jointMatricesRHS` array, or `jointMatricesLHS`
+     * already flipped). The matrices are assumed to be RHS unless
+     * `isAlreadyLhs=true`, in which case the RHS→LHS flip step is skipped.
+     *
+     * @param rawMatrices Float32Array of BODY_JOINT_COUNT × 16 (= 1328) floats.
+     * @param isAlreadyLhs Set to `true` if matrices are already LHS-converted.
+     */
+    replayRawJointMatrices(rawMatrices: Float32Array | number[], isAlreadyLhs?: boolean): void;
+    /**
+     * Run steps 2.5 → 5 of the retargeting pipeline using whatever is
+     * currently in `_jointTransformMatrices` (as if the WebXR API just
+     * filled it for the current frame).
+     * @param xrCameraParent Parent node of the XR camera (used to parent the body mesh root during live XR).
+     * @param skipRhsToLhs If true, skip the RHS→LHS flip (matrices are already in the scene's handedness).
+     */
+    private _processTrackedJointMatrices;
+    /**
+     * Capture the current tracked-joint desired-final rotations and positions
+     * as the "rest pose" for delta-from-bind retargeting.
+     *
+     * Delta-from-bind is the production retarget path: every subsequent
+     * frame is interpreted as a rotation delta from this snapshot, which
+     * makes retargeting invariant to the XR-joint axis convention and to
+     * any skeletal-proportion differences between the tracked user and the
+     * avatar.
+     *
+     * Call this after the user assumes a known rest pose (e.g. T-pose,
+     * A-pose, arms-at-sides). By default the feature auto-captures on the
+     * first tracked frame — disable via {@link autoCaptureBindOnFirstFrame}.
+     */
+    captureTrackedBind(): void;
+    /**
+     * Clear any captured bind, reverting subsequent frames to the fallback
+     * direct-retarget path (or re-triggering auto-capture on the next frame).
+     */
+    clearTrackedBind(): void;
+    /** Internal: copy current desiredFinals into the tracked-bind slots. */
+    private _captureTrackedBindFromDesiredFinals;
+    /**
+     * Delta-from-bind retarget: axis-convention-invariant.
+     *
+     * For each mapped bone in skeleton order (parents first):
+     *   let j = joint mapped to this bone
+     *   deltaMeshLocalRot  = bindTracked[j]⁻¹ × currentTracked[j]     (right-side in row-vector)
+     *   newBoneWorldRot    = bindBoneWorldRot × deltaMeshLocalRot
+     *   newBoneLocalRot    = newBoneWorldRot × parentNewBoneWorldRot⁻¹
+     *
+     * Positions: root bone receives tracked world delta (so the avatar
+     * translates with the user). All other mapped bones keep their rig's
+     * bind-pose local translation to preserve segment lengths.
+     * @param scaleFactor Additional scale applied to joint local positions.
+     */
+    private _retargetDeltaFromBind;
+    /**
+     * Legacy direct-retarget path (pre-bind-capture). Kept as fallback.
+     * @param useInitialSkinMatrix Skeleton needs initial-skin-matrix chaining for the root.
+     * @param useBoneOrientationOffsets Apply aim-direction correction per mapped bone.
+     * @param scaleFactor Additional scale applied to joint local positions.
+     * @param computedWorldRotations Optional map used by the aim-correction path for parent lookups.
+     */
+    private _retargetDirect;
+    /**
+     * Capture a snapshot of the current frame's raw XR joint matrices and
+     * skeleton metadata.  Returns a JSON string that can be used offline to
+     * replay / debug bone-local computation without a headset.
+     *
+     * The snapshot includes:
+     * - `jointMatricesRHS` – 83 × 16 raw RHS matrices (before LHS conversion)
+     * - `jointMatricesLHS` – 83 × 16 LHS-converted matrices (after step 3)
+     * - `meshWorldMatrix` – 16 floats, the skeleton mesh's world matrix (if any)
+     * - `jointHasBone` – boolean[83], which joints are mapped to bones
+     * - `jointParentJointIdx` – number[83], mapped ancestor for each joint
+     * - `useRightHandedSystem` – scene handedness setting
+     * - `jointNames` – the 83 joint names in order
+     *
+     * @returns A JSON string with the snapshot data.
+     */
+    snapshotFrame(): string;
+    /**
+     * Capture a snapshot and copy it to the system clipboard.
+     * Logs to the console on success or failure.
+     * @returns A promise that resolves when the copy completes.
+     */
+    snapshotFrameToClipboardAsync(): Promise<void>;
+    /**
+     * Dispose of this tracked body and its resources.
+     * @param disposeMesh If `true`, the body mesh and its skeleton are disposed as well.
+     */
+    dispose(disposeMesh?: boolean): void;
+}
+/**
+ * WebXR Body Tracking feature.
+ *
+ * This feature tracks the user's full-body pose using the
+ * [WebXR Body Tracking Module](https://immersive-web.github.io/body-tracking/),
+ * which exposes 83 articulated joints covering the torso, arms, hands, legs and feet.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * // Enable body tracking when creating the default XR experience:
+ * const xr = await scene.createDefaultXRExperienceAsync();
+ * const bodyTracking = xr.baseExperience.featuresManager.enableFeature(
+ *     WebXRFeatureName.BODY_TRACKING,
+ *     "latest",
+ *     {
+ *         bodyMesh: myRiggedBodyMesh,
+ *         rigMapping: {
+ *             "hips": "Bip01_Pelvis",
+ *             "spine-lower": "Bip01_Spine",
+ *             // … one entry per joint you want to drive …
+ *         },
+ *     } as IWebXRBodyTrackingOptions,
+ * );
+ *
+ * // React to tracking changes:
+ * bodyTracking.onBodyTrackingStartedObservable.add((trackedBody) => {
+ *     console.log("Body tracking started");
+ * });
+ * bodyTracking.onBodyTrackingFrameUpdateObservable.add((trackedBody) => {
+ *     // The tracked body's joint transforms are already up-to-date.
+ * });
+ * ```
+ *
+ * ## How It Works
+ *
+ * 1. The feature requests the `"body-tracking"` native WebXR feature at session start.
+ * 2. Each frame, if `XRFrame.body` is available, joint poses are filled into a
+ *    flat Float32Array via the batch `fillPoses()` API (with a per-joint fallback).
+ * 3. The 4 × 4 matrices are converted from WebXR right-handed coordinates to
+ *    Babylon.js left-handed coordinates in-place (unless the scene is RHS).
+ * 4. Each matrix is decomposed and written to a TransformNode; skeleton bones
+ *    linked to those nodes animate the rigged mesh automatically.
+ *
+ * ## Coordinate System
+ *
+ * WebXR data arrives in a **right-handed** coordinate system.  Babylon.js
+ * defaults to **left-handed**.  The conversion is handled automatically:
+ * - Joint matrices are flipped in-place (Z-negation of specific matrix elements).
+ * - For meshes authored in a right-handed tool (glTF, Blender, etc.), the bone
+ *   data is un-flipped so the skeleton interprets poses correctly.
+ * - If you use `scene.useRightHandedSystem = true`, no conversion is applied.
+ *
+ * @see https://immersive-web.github.io/body-tracking/
+ */
+export declare class WebXRBodyTracking extends WebXRAbstractFeature {
+    /** Configuration options for the body tracking feature. */
+    readonly options: IWebXRBodyTrackingOptions;
+    /**
+     * The module's name, used when enabling the feature on the features manager.
+     * Value: `"xr-body-tracking"`.
+     */
+    static readonly Name: "xr-body-tracking";
+    /**
+     * The (Babylon) version of this module.
+     * This is an integer representing the implementation version.
+     * This number does not correspond to the WebXR specs version.
+     */
+    static readonly Version = 1;
+    /**
+     * Observable fired when body tracking starts (i.e. the first frame where
+     * `XRFrame.body` returns valid data).
+     */
+    readonly onBodyTrackingStartedObservable: Observable<WebXRTrackedBody>;
+    /**
+     * Observable fired when body tracking is lost (i.e. `XRFrame.body` becomes
+     * `null` or returns no valid poses after previously tracking).
+     */
+    readonly onBodyTrackingEndedObservable: Observable<void>;
+    /**
+     * Observable fired every frame that has valid body tracking data.
+     * At the point of notification, all joint transforms are up-to-date.
+     */
+    readonly onBodyTrackingFrameUpdateObservable: Observable<WebXRTrackedBody>;
+    /**
+     * Observable fired when the body mesh has been set via {@link setBodyMesh}
+     * or during initial configuration.
+     */
+    readonly onBodyMeshSetObservable: Observable<WebXRTrackedBody>;
+    /** The current tracked body, or null when not tracking. */
+    private _trackedBody;
+    /** True while we have an active body tracking session. */
+    private _isTracking;
+    /** Observer for world scale changes, so the body mesh can be rescaled. */
+    private _worldScaleObserver;
+    /**
+     * Debug info from the feature-level frame loop.
+     * Shows why `_onXRFrame` did or did not call `updateFromXRFrame`.
+     * @internal
+     */
+    _lastFrameDebugInfo: string;
+    /**
+     * Get the currently tracked body, if any.
+     */
+    get trackedBody(): Nullable<WebXRTrackedBody>;
+    /**
+     * Returns `true` while body tracking data is actively being received.
+     */
+    get isTracking(): boolean;
+    /**
+     * Construct a new WebXRBodyTracking feature.
+     * @param _xrSessionManager The XR session manager.
+     * @param options Configuration options.
+     */
+    constructor(_xrSessionManager: WebXRSessionManager, 
+    /** Configuration options for the body tracking feature. */
+    options?: IWebXRBodyTrackingOptions);
+    /**
+     * Attach a rigged body mesh (or replace the current one) at any time.
+     *
+     * This is a convenience method that forwards to the underlying
+     * {@link WebXRTrackedBody.setBodyMesh}.  The body does not need to be
+     * already tracking for this to work — the mesh will be applied once
+     * tracking begins.
+     *
+     * @param bodyMesh The rigged mesh to drive.
+     * @param rigMapping Optional mapping from {@link WebXRBodyJoint} names to bone names.
+     */
+    setBodyMesh(bodyMesh: AbstractMesh, rigMapping?: XRBodyMeshRigMapping): void;
+    /**
+     * Attach the feature.
+     * Called by the features manager when the XR session initialises.
+     *
+     * Body tracking is a draft WebXR spec.  Some UAs (e.g. Meta Quest) provide
+     * body data on `XRFrame.body` but do not list `"body-tracking"` in
+     * `session.enabledFeatures`.  To handle this, we temporarily clear
+     * {@link xrNativeFeatureName} before calling the base `attach()` so the
+     * enabled-features check is skipped, then restore it afterwards.
+     * @returns `true` if attachment succeeded.
+     */
+    attach(): boolean;
+    /**
+     * Detach the feature.
+     * Called by the features manager when the XR session ends.
+     * @returns `true` if detachment succeeded.
+     */
+    detach(): boolean;
+    /**
+     * Dispose this feature and all resources.
+     */
+    dispose(): void;
+    /**
+     * Called every XR frame by the base class.
+     * Reads body joint data from the XR runtime and updates transforms.
+     * @param xrFrame The current XRFrame.
+     */
+    protected _onXRFrame(xrFrame: XRFrame): void;
+    /**
+     * Returns the complete ordered list of body joint names tracked by this feature.
+     * Useful for iterating over all joints or building UI.
+     */
+    static get AllBodyJoints(): readonly WebXRBodyJoint[];
+    /**
+     * Capture a single-frame snapshot of all 83 joints and copy it to the
+     * clipboard.  Call this from a playground button or the console while
+     * wearing the headset:
+     *
+     * ```typescript
+     * bodyTracking.snapshotFrameToClipboard();
+     * ```
+     *
+     * The JSON can later be loaded offline to replay the bone-local
+     * computation without a headset.
+     * @returns A promise that resolves when the copy completes, or rejects
+     *   if no body is currently tracked.
+     */
+    snapshotFrameToClipboardAsync(): Promise<void>;
+}
+export {};