@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/humanoid/body.ts

@@ -0,0 +1,663 @@
+/**
+ * The procedural humanoid BODY: entirely procedural three.js geometry
+ * (capsules + one pelvis box via `CapsuleGeometry`/`BoxGeometry`, merged with
+ * `BufferGeometryUtils.mergeGeometries` into ONE `SkinnedMesh`). No imported
+ * mesh anywhere. Promoted from the accepted Phase-1 PoC
+ * (`packages/engine/e2e/humanoid-skin-proof/procedural-body.ts`) and
+ * parameterized by body dimensions — with all-default dims the output is
+ * bit-identical to the PoC body.
+ *
+ * Skin binding is **analytic per-segment with smooth 2-bone joint blending**:
+ * every body part is generated along one bone segment (proximal joint →
+ * distal joint, both known a priori from the rest pose), so each vertex's
+ * normalized position `t` along the bone axis is exact — no nearest-bone
+ * search, no heuristic falloff radius. Vertices in the interior of a segment
+ * bind 100% to that segment's bone; vertices inside a blend zone at either
+ * end split weight smoothstep-wise with the adjacent bone, reaching 50/50 at
+ * (and past) the joint itself. This is the standard cure for the two classic
+ * rigid-binding artifacts: gaps/interpenetration at elbows/knees (fixed by
+ * the overshoot + 50/50 blend across the joint) and hard shading creases
+ * (fixed by the smoothstep ramp). Because the blend zone is derived from the
+ * ACTUAL joint positions of the (possibly rescaled) skeleton, weights stay
+ * correct as body proportions change. Two influences per vertex is enough
+ * for a capsule-limb body; the vertex format still uses the standard 4-wide
+ * skinIndex/skinWeight attributes, zero-padded, exactly as GLTF skins do.
+ */
+
+import * as THREE from 'three';
+import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
+import type { BuiltSkeleton } from './skeleton';
+
+/** Which dimension multiplier a part's radius follows. `foot` parts scale by
+ *  heightFactor ONLY, so ground clearance (set by the skeleton re-ground
+ *  step, which knows nothing about radii) is never violated by a thick body. */
+type RadiusGroup = 'torso' | 'limb' | 'head' | 'foot';
+
+/** One procedural body part, generated along the bone segment `from`→`to`. */
+interface SegmentSpec {
+  /** The bone this part binds to (owns the segment; usually === `from`). */
+  bone: string;
+  /** Proximal joint (t = 0). */
+  from: string;
+  /** Distal joint (t = 1) — an existing child bone name. */
+  to: string;
+  /** Capsule radius, metres at reference scale (multiplied by the part's
+   *  radius-group dim before use). */
+  radius: number;
+  /** Radius-group multiplier this part follows. */
+  group: RadiusGroup;
+  /** Blend partner near t=0 (typically the parent bone). Omit = rigid end. */
+  proximalBlend?: string;
+  /** Blend partner near t=1 (typically the `to` bone). Omit = rigid end. */
+  distalBlend?: string;
+  /** Extend the capsule past the proximal / distal joint, metres at reference
+   *  scale — overlaps the neighbouring part so blended joints never show gaps. */
+  overshootFrom?: number;
+  overshootTo?: number;
+  /** Per-part vertex color (visualizes the segment map + blend zones). */
+  color: number;
+}
+
+const C = {
+  torso: 0x4f8fba,
+  pelvis: 0x3a6ea5,
+  head: 0xd9a066,
+  neck: 0xc98b5e,
+  armL: 0xe07b39,
+  foreL: 0xf0a860,
+  armR: 0x4fae6a,
+  foreR: 0x7fd196,
+  hand: 0xd9c8b4,
+  thigh: 0x8a5fb0,
+  shin: 0xb08ad0,
+  foot: 0x555f6e,
+  toe: 0x6d7885,
+} as const;
+
+/** The full body map. Radii/overshoots are metres at reference scale, tuned
+ *  to the reference rig's T-pose proportions (~1.83 m tall). */
+const SEGMENTS: readonly SegmentSpec[] = [
+  // Torso column — three short, fat, overlapping capsules following the
+  // spine chain, each blending into its neighbours.
+  {
+    bone: 'mixamorigSpine',
+    from: 'mixamorigSpine',
+    to: 'mixamorigSpine1',
+    radius: 0.135,
+    group: 'torso',
+    proximalBlend: 'mixamorigHips',
+    distalBlend: 'mixamorigSpine1',
+    overshootFrom: 0.03,
+    overshootTo: 0.02,
+    color: C.torso,
+  },
+  {
+    bone: 'mixamorigSpine1',
+    from: 'mixamorigSpine1',
+    to: 'mixamorigSpine2',
+    radius: 0.145,
+    group: 'torso',
+    proximalBlend: 'mixamorigSpine',
+    distalBlend: 'mixamorigSpine2',
+    overshootFrom: 0.02,
+    overshootTo: 0.02,
+    color: C.torso,
+  },
+  {
+    bone: 'mixamorigSpine2',
+    from: 'mixamorigSpine2',
+    to: 'mixamorigNeck',
+    radius: 0.14,
+    group: 'torso',
+    proximalBlend: 'mixamorigSpine1',
+    distalBlend: 'mixamorigNeck',
+    overshootFrom: 0.02,
+    overshootTo: 0.01,
+    color: C.torso,
+  },
+  // Neck + head.
+  {
+    bone: 'mixamorigNeck',
+    from: 'mixamorigNeck',
+    to: 'mixamorigHead',
+    radius: 0.048,
+    group: 'head',
+    proximalBlend: 'mixamorigSpine2',
+    distalBlend: 'mixamorigHead',
+    overshootFrom: 0.02,
+    overshootTo: 0.02,
+    color: C.neck,
+  },
+  {
+    bone: 'mixamorigHead',
+    from: 'mixamorigHead',
+    to: 'mixamorigHeadTop_End',
+    radius: 0.105,
+    group: 'head',
+    proximalBlend: 'mixamorigNeck',
+    color: C.head,
+  },
+  // Left arm chain (shoulder → upper arm → forearm → hand).
+  {
+    bone: 'mixamorigLeftShoulder',
+    from: 'mixamorigLeftShoulder',
+    to: 'mixamorigLeftArm',
+    radius: 0.062,
+    group: 'torso',
+    proximalBlend: 'mixamorigSpine2',
+    distalBlend: 'mixamorigLeftArm',
+    overshootFrom: 0.02,
+    color: C.torso,
+  },
+  {
+    bone: 'mixamorigLeftArm',
+    from: 'mixamorigLeftArm',
+    to: 'mixamorigLeftForeArm',
+    radius: 0.052,
+    group: 'limb',
+    proximalBlend: 'mixamorigLeftShoulder',
+    distalBlend: 'mixamorigLeftForeArm',
+    overshootFrom: 0.015,
+    overshootTo: 0.01,
+    color: C.armL,
+  },
+  {
+    bone: 'mixamorigLeftForeArm',
+    from: 'mixamorigLeftForeArm',
+    to: 'mixamorigLeftHand',
+    radius: 0.044,
+    group: 'limb',
+    proximalBlend: 'mixamorigLeftArm',
+    distalBlend: 'mixamorigLeftHand',
+    overshootFrom: 0.01,
+    overshootTo: 0.01,
+    color: C.foreL,
+  },
+  {
+    bone: 'mixamorigLeftHand',
+    from: 'mixamorigLeftHand',
+    to: 'mixamorigLeftHandMiddle1',
+    radius: 0.04,
+    group: 'limb',
+    proximalBlend: 'mixamorigLeftForeArm',
+    overshootTo: 0.05,
+    color: C.hand,
+  },
+  // Right arm chain.
+  {
+    bone: 'mixamorigRightShoulder',
+    from: 'mixamorigRightShoulder',
+    to: 'mixamorigRightArm',
+    radius: 0.062,
+    group: 'torso',
+    proximalBlend: 'mixamorigSpine2',
+    distalBlend: 'mixamorigRightArm',
+    overshootFrom: 0.02,
+    color: C.torso,
+  },
+  {
+    bone: 'mixamorigRightArm',
+    from: 'mixamorigRightArm',
+    to: 'mixamorigRightForeArm',
+    radius: 0.052,
+    group: 'limb',
+    proximalBlend: 'mixamorigRightShoulder',
+    distalBlend: 'mixamorigRightForeArm',
+    overshootFrom: 0.015,
+    overshootTo: 0.01,
+    color: C.armR,
+  },
+  {
+    bone: 'mixamorigRightForeArm',
+    from: 'mixamorigRightForeArm',
+    to: 'mixamorigRightHand',
+    radius: 0.044,
+    group: 'limb',
+    proximalBlend: 'mixamorigRightArm',
+    distalBlend: 'mixamorigRightHand',
+    overshootFrom: 0.01,
+    overshootTo: 0.01,
+    color: C.foreR,
+  },
+  {
+    bone: 'mixamorigRightHand',
+    from: 'mixamorigRightHand',
+    to: 'mixamorigRightHandMiddle1',
+    radius: 0.04,
+    group: 'limb',
+    proximalBlend: 'mixamorigRightForeArm',
+    overshootTo: 0.05,
+    color: C.hand,
+  },
+  // Left leg chain (thigh → shin → foot → toes).
+  {
+    bone: 'mixamorigLeftUpLeg',
+    from: 'mixamorigLeftUpLeg',
+    to: 'mixamorigLeftLeg',
+    radius: 0.078,
+    group: 'limb',
+    proximalBlend: 'mixamorigHips',
+    distalBlend: 'mixamorigLeftLeg',
+    overshootFrom: 0.035,
+    overshootTo: 0.01,
+    color: C.thigh,
+  },
+  {
+    bone: 'mixamorigLeftLeg',
+    from: 'mixamorigLeftLeg',
+    to: 'mixamorigLeftFoot',
+    radius: 0.058,
+    group: 'limb',
+    proximalBlend: 'mixamorigLeftUpLeg',
+    distalBlend: 'mixamorigLeftFoot',
+    overshootFrom: 0.01,
+    overshootTo: 0.01,
+    color: C.shin,
+  },
+  {
+    bone: 'mixamorigLeftFoot',
+    from: 'mixamorigLeftFoot',
+    to: 'mixamorigLeftToeBase',
+    radius: 0.05,
+    group: 'foot',
+    proximalBlend: 'mixamorigLeftLeg',
+    distalBlend: 'mixamorigLeftToeBase',
+    overshootFrom: 0.01,
+    color: C.foot,
+  },
+  {
+    bone: 'mixamorigLeftToeBase',
+    from: 'mixamorigLeftToeBase',
+    to: 'mixamorigLeftToe_End',
+    radius: 0.042,
+    group: 'foot',
+    proximalBlend: 'mixamorigLeftFoot',
+    color: C.toe,
+  },
+  // Right leg chain.
+  {
+    bone: 'mixamorigRightUpLeg',
+    from: 'mixamorigRightUpLeg',
+    to: 'mixamorigRightLeg',
+    radius: 0.078,
+    group: 'limb',
+    proximalBlend: 'mixamorigHips',
+    distalBlend: 'mixamorigRightLeg',
+    overshootFrom: 0.035,
+    overshootTo: 0.01,
+    color: C.thigh,
+  },
+  {
+    bone: 'mixamorigRightLeg',
+    from: 'mixamorigRightLeg',
+    to: 'mixamorigRightFoot',
+    radius: 0.058,
+    group: 'limb',
+    proximalBlend: 'mixamorigRightUpLeg',
+    distalBlend: 'mixamorigRightFoot',
+    overshootFrom: 0.01,
+    overshootTo: 0.01,
+    color: C.shin,
+  },
+  {
+    bone: 'mixamorigRightFoot',
+    from: 'mixamorigRightFoot',
+    to: 'mixamorigRightToeBase',
+    radius: 0.05,
+    group: 'foot',
+    proximalBlend: 'mixamorigRightLeg',
+    distalBlend: 'mixamorigRightToeBase',
+    overshootFrom: 0.01,
+    color: C.foot,
+  },
+  {
+    bone: 'mixamorigRightToeBase',
+    from: 'mixamorigRightToeBase',
+    to: 'mixamorigRightToe_End',
+    radius: 0.042,
+    group: 'foot',
+    proximalBlend: 'mixamorigRightFoot',
+    color: C.toe,
+  },
+];
+
+/** The head capsule's reference radius — `generate.ts` feeds this (× headSize)
+ *  to the skeleton height normalization as the crown padding. */
+export const HEAD_CAPSULE_RADIUS =
+  SEGMENTS.find((s) => s.bone === 'mixamorigHead')?.radius ?? 0.105;
+
+/** Body dimension multipliers, resolved by `generate.ts` from the params. */
+export interface HumanoidBodyDims {
+  /** The skeleton's uniform height factor — every base metre scales by this. */
+  heightFactor: number;
+  limbThickness: number;
+  torsoGirth: number;
+  headSize: number;
+  hipWidth: number;
+}
+
+export const smoothstep = (x: number): number => {
+  const t = Math.min(1, Math.max(0, x));
+  return t * t * (3 - 2 * t);
+};
+
+/** Blend-zone length as a fraction of a segment (≈10 cm at reference scale,
+ *  clamped to 20–50% of the segment) — shared verbatim by the body generator
+ *  and `skinToHumanoid` so clothing gets the SAME joint blend as the body. */
+export const blendZone = (len: number, heightFactor: number): number =>
+  Math.min(0.5, Math.max(0.2, (0.1 * heightFactor) / len));
+
+/** World rest position of a named bone (scene must have updated matrices). */
+function jointPos(rig: BuiltSkeleton, name: string): THREE.Vector3 {
+  const bone = rig.byName.get(name);
+  if (!bone) throw new Error(`humanoid: unknown bone '${name}'`);
+  return new THREE.Vector3().setFromMatrixPosition(bone.matrixWorld);
+}
+
+/** name → skinIndex row, cached per rig (reviewer note: the former O(n)
+ *  findIndex per call was fine for 22 parts, not for per-prop/per-vertex use). */
+const boneIndexCache = new WeakMap<BuiltSkeleton, Map<string, number>>();
+
+function boneIndex(rig: BuiltSkeleton, name: string): number {
+  let map = boneIndexCache.get(rig);
+  if (!map) {
+    map = new Map(rig.bones.map((b, i) => [b.name, i]));
+    boneIndexCache.set(rig, map);
+  }
+  const i = map.get(name);
+  if (i === undefined) throw new Error(`humanoid: unknown bone '${name}'`);
+  return i;
+}
+
+/** Fill vertex colors with a flat per-part color. */
+function paint(geo: THREE.BufferGeometry, color: number): void {
+  const n = geo.attributes['position']!.count;
+  const c = new THREE.Color(color);
+  const arr = new Float32Array(n * 3);
+  for (let i = 0; i < n; i++) arr.set([c.r, c.g, c.b], i * 3);
+  geo.setAttribute('color', new THREE.BufferAttribute(arr, 3));
+}
+
+/**
+ * Compute skinIndex/skinWeight for a segment geometry: per-vertex projection
+ * onto the joint axis → smoothstep 2-bone blend inside the end zones. The
+ * blend zone length adapts to the segment (≈10 cm at reference scale,
+ * clamped to 20–50% of the segment) so short torso links still blend and
+ * long thighs stay mostly rigid.
+ */
+function skinSegment(
+  geo: THREE.BufferGeometry,
+  rig: BuiltSkeleton,
+  spec: SegmentSpec,
+  p0: THREE.Vector3,
+  p1: THREE.Vector3,
+  heightFactor: number,
+): void {
+  const primary = boneIndex(rig, spec.bone);
+  const proximal = spec.proximalBlend ? boneIndex(rig, spec.proximalBlend) : -1;
+  const distal = spec.distalBlend ? boneIndex(rig, spec.distalBlend) : -1;
+  const axis = p1.clone().sub(p0);
+  const len = axis.length();
+  const axisN = axis.clone().divideScalar(len);
+  const blend = blendZone(len, heightFactor);
+
+  const pos = geo.attributes['position']!;
+  const n = pos.count;
+  const skinIndex = new Uint16Array(n * 4);
+  const skinWeight = new Float32Array(n * 4);
+  const v = new THREE.Vector3();
+  for (let i = 0; i < n; i++) {
+    v.fromBufferAttribute(pos as THREE.BufferAttribute, i);
+    const t = v.sub(p0).dot(axisN) / len; // may exceed [0,1] via overshoot
+    let other = primary;
+    let w2 = 0;
+    if (proximal >= 0 && t < blend) {
+      // 50/50 exactly at (and beyond) the joint, ramping to 100% primary.
+      other = proximal;
+      w2 = 0.5 * (1 - smoothstep(t / blend));
+    } else if (distal >= 0 && t > 1 - blend) {
+      other = distal;
+      w2 = 0.5 * smoothstep((t - (1 - blend)) / blend);
+    }
+    skinIndex.set([primary, other, 0, 0], i * 4);
+    skinWeight.set([1 - w2, w2, 0, 0], i * 4);
+  }
+  geo.setAttribute('skinIndex', new THREE.BufferAttribute(skinIndex, 4));
+  geo.setAttribute('skinWeight', new THREE.BufferAttribute(skinWeight, 4));
+}
+
+/** Capsule spanning exactly `p0 - dir*overshootFrom` → `p1 + dir*overshootTo`. */
+function capsuleBetween(
+  p0: THREE.Vector3,
+  p1: THREE.Vector3,
+  radius: number,
+  overshootFrom: number,
+  overshootTo: number,
+): THREE.BufferGeometry {
+  const dir = p1.clone().sub(p0).normalize();
+  const a = p0.clone().addScaledVector(dir, -overshootFrom);
+  const b = p1.clone().addScaledVector(dir, overshootTo);
+  const span = a.distanceTo(b);
+  const cyl = Math.max(0.01, span - 2 * radius);
+  const geo = new THREE.CapsuleGeometry(radius, cyl, 6, 16);
+  geo.deleteAttribute('uv'); // untextured; keeps merged attribute sets identical
+  const quat = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), dir);
+  const mid = a.clone().add(b).multiplyScalar(0.5);
+  geo.applyMatrix4(new THREE.Matrix4().compose(mid, quat, new THREE.Vector3(1, 1, 1)));
+  return geo;
+}
+
+/** The pelvis is the one non-capsule part: a box centred between the hips
+ *  and the upper-leg roots, rigidly bound to `mixamorigHips` (the thigh
+ *  capsules overshoot up into it and carry the blending). */
+function buildPelvis(rig: BuiltSkeleton, dims: HumanoidBodyDims): THREE.BufferGeometry {
+  const hips = jointPos(rig, 'mixamorigHips');
+  const upL = jointPos(rig, 'mixamorigLeftUpLeg');
+  const upR = jointPos(rig, 'mixamorigRightUpLeg');
+  const centerY = (hips.y + (upL.y + upR.y) / 2) / 2;
+  const f = dims.heightFactor;
+  const geo = new THREE.BoxGeometry(
+    0.3 * f * dims.hipWidth,
+    0.17 * f,
+    0.19 * f * dims.torsoGirth,
+    2,
+    2,
+    2,
+  );
+  geo.deleteAttribute('uv');
+  geo.translate(hips.x, centerY, hips.z);
+  paint(geo, C.pelvis);
+  const hipsIndex = boneIndex(rig, 'mixamorigHips');
+  const n = geo.attributes['position']!.count;
+  const skinIndex = new Uint16Array(n * 4);
+  const skinWeight = new Float32Array(n * 4);
+  for (let i = 0; i < n; i++) {
+    skinIndex[i * 4] = hipsIndex;
+    skinWeight[i * 4] = 1;
+  }
+  geo.setAttribute('skinIndex', new THREE.BufferAttribute(skinIndex, 4));
+  geo.setAttribute('skinWeight', new THREE.BufferAttribute(skinWeight, 4));
+  return geo;
+}
+
+/** One merged-body part's vertex range + the bones its weights may reference —
+ *  the segment-adjacency contract the unit tests verify. */
+export interface HumanoidBodyPart {
+  name: string;
+  /** skinIndex values every non-zero-weight influence in the range must use. */
+  boneIndices: readonly number[];
+  vertexStart: number;
+  vertexCount: number;
+}
+
+export interface HumanoidBody {
+  mesh: THREE.SkinnedMesh;
+  skeleton: THREE.Skeleton;
+  vertexCount: number;
+  parts: readonly HumanoidBodyPart[];
+}
+
+function radiusMultiplier(group: RadiusGroup, dims: HumanoidBodyDims): number {
+  switch (group) {
+    case 'torso':
+      return dims.torsoGirth;
+    case 'limb':
+      return dims.limbThickness;
+    case 'head':
+      return dims.headSize;
+    case 'foot':
+      return 1;
+  }
+}
+
+/**
+ * Build the whole body as ONE merged `SkinnedMesh` in the rig root's space
+ * (the skeleton's rest pose), and bind it. Callers must have called
+ * `updateMatrixWorld(true)` on the armature's parent after adding the bone
+ * hierarchy, so every bone's `matrixWorld` is its rest pose —
+ * `new THREE.Skeleton(bones)` captures the inverse bind matrices from
+ * exactly those.
+ */
+export function buildHumanoidBody(
+  rig: BuiltSkeleton,
+  dims: HumanoidBodyDims,
+  material?: THREE.Material,
+): HumanoidBody {
+  const geos: THREE.BufferGeometry[] = [buildPelvis(rig, dims)];
+  const parts: HumanoidBodyPart[] = [];
+  let vertexCursor = geos[0]!.attributes['position']!.count;
+  parts.push({
+    name: 'pelvis',
+    boneIndices: [boneIndex(rig, 'mixamorigHips')],
+    vertexStart: 0,
+    vertexCount: vertexCursor,
+  });
+  const f = dims.heightFactor;
+  for (const spec of SEGMENTS) {
+    const p0 = jointPos(rig, spec.from);
+    const p1 = jointPos(rig, spec.to);
+    const radius = spec.radius * f * radiusMultiplier(spec.group, dims);
+    const geo = capsuleBetween(
+      p0,
+      p1,
+      radius,
+      (spec.overshootFrom ?? 0) * f,
+      (spec.overshootTo ?? 0) * f,
+    );
+    paint(geo, spec.color);
+    skinSegment(geo, rig, spec, p0, p1, f);
+    const count = geo.attributes['position']!.count;
+    const boneIndices = [boneIndex(rig, spec.bone)];
+    if (spec.proximalBlend) boneIndices.push(boneIndex(rig, spec.proximalBlend));
+    if (spec.distalBlend) boneIndices.push(boneIndex(rig, spec.distalBlend));
+    parts.push({ name: spec.bone, boneIndices, vertexStart: vertexCursor, vertexCount: count });
+    vertexCursor += count;
+    geos.push(geo);
+  }
+  const merged = mergeGeometries(geos, false);
+  if (!merged) throw new Error('humanoid: mergeGeometries failed');
+  for (const g of geos) g.dispose();
+
+  const mat =
+    material ??
+    new THREE.MeshStandardMaterial({
+      vertexColors: true,
+      roughness: 0.75,
+      metalness: 0.05,
+    });
+  const mesh = new THREE.SkinnedMesh(merged, mat);
+  mesh.name = 'ProceduralHumanoidBody';
+  mesh.castShadow = true;
+  // An animated skinned mesh moves far outside its static rest-pose bounds.
+  mesh.frustumCulled = false;
+
+  const skeleton = new THREE.Skeleton(rig.bones);
+  mesh.updateMatrixWorld(true);
+  mesh.bind(skeleton, mesh.matrixWorld.clone());
+  return {
+    mesh,
+    skeleton,
+    vertexCount: merged.attributes['position']!.count,
+    parts,
+  };
+}
+
+// --- Segment-binding exposure (package-internal, consumed by compose.ts) ----
+
+/** One skin-binding segment of the standard body, resolved against a concrete
+ *  rest pose: the analytic per-segment data `skinToHumanoid` shares with the
+ *  body generator so arbitrary clothing geometry deforms EXACTLY like the
+ *  body part underneath it. Not part of the public module surface. */
+export interface HumanoidBindingSegment {
+  /** Primary bone row (the skinIndex value). */
+  bone: number;
+  /** Blend-partner rows near t=0 / t=1 (-1 = rigid end). */
+  proximal: number;
+  distal: number;
+  /** Proximal joint rest position, model-space metres. */
+  p0: THREE.Vector3;
+  /** Unit axis p0→p1 (p1 = distal joint) and the joint-to-joint length. */
+  axis: THREE.Vector3;
+  len: number;
+  /** Normalized blend-zone length (the body's own `blendZone` value). */
+  blend: number;
+  /** The body part's surface radius, metres — nearest-segment selection
+   *  measures distance to the SURFACE so loose clothing picks the part it
+   *  visually covers, not merely the closest bone axis. */
+  radius: number;
+}
+
+/**
+ * Resolve the body's segment map (plus one synthetic rigid pelvis segment —
+ * the pelvis box binds 100% to Hips, and belts/skirts must get the same
+ * anchor to stay congruent with it) against a concrete rest pose.
+ * Parameterized on lookups rather than `BuiltSkeleton` because the compose
+ * path recovers rest joints from `Skeleton.boneInverses` (bones may be
+ * mid-animation by then), while the generator reads live rest matrices.
+ * `jointAt` must return a FRESH Vector3 per call (results are mutated here).
+ */
+export function computeBindingSegments(
+  jointAt: (name: string) => THREE.Vector3,
+  indexOf: (name: string) => number,
+  dims: HumanoidBodyDims,
+): HumanoidBindingSegment[] {
+  const f = dims.heightFactor;
+  const segments: HumanoidBindingSegment[] = [];
+
+  // Axis LATERALLY along the hip-to-hip line (not hips→legs): a capsule
+  // there is the closest round proxy for the pelvis box, and — unlike a
+  // short vertical axis with a wide radius — it does not bulge spherically
+  // down between the thighs and steal inner-thigh vertices from the legs.
+  const upLegL = jointAt('mixamorigLeftUpLeg');
+  const upLegR = jointAt('mixamorigRightUpLeg');
+  const pelvisAxis = upLegR.clone().sub(upLegL);
+  const pelvisLen = Math.max(pelvisAxis.length(), 1e-6);
+  segments.push({
+    bone: indexOf('mixamorigHips'),
+    proximal: -1,
+    distal: -1,
+    p0: upLegL,
+    axis: pelvisAxis.divideScalar(pelvisLen),
+    len: pelvisLen,
+    blend: 0,
+    radius: 0.1 * f * dims.hipWidth,
+  });
+
+  for (const spec of SEGMENTS) {
+    const p0 = jointAt(spec.from);
+    const p1 = jointAt(spec.to);
+    const axis = p1.sub(p0);
+    const len = Math.max(axis.length(), 1e-6);
+    segments.push({
+      bone: indexOf(spec.bone),
+      proximal: spec.proximalBlend ? indexOf(spec.proximalBlend) : -1,
+      distal: spec.distalBlend ? indexOf(spec.distalBlend) : -1,
+      p0,
+      axis: axis.divideScalar(len),
+      len,
+      blend: blendZone(len, f),
+      radius: spec.radius * f * radiusMultiplier(spec.group, dims),
+    });
+  }
+  return segments;
+}