lecodes-assets 0.2.0 → 0.2.1

package/src/retarget/rig.ts

@@ -0,0 +1,542 @@
+// A rig — the minimum both sides of a retarget need: a bone hierarchy, its rest pose, and a way to
+// sample an animated pose at a time. Built from either an FBX scene (the clip donor) or a glTF
+// Document (the model being animated), so the retargeter never sees the difference.
+//
+// Rotations are carried as quaternions composed up the chain rather than extracted from world
+// matrices. That is only valid while every scale in the chain is uniform — `checkUniformScale`
+// enforces it, because a non-uniform scale makes "the world rotation of this bone" meaningless.
+//
+// The pose a rig is MEASURED AGAINST is its BIND pose (inverse of the skin's inverse-bind matrices),
+// not the TRS sitting on its nodes. Those two are the same in a clean export, but an FBX carrying
+// baked clips routinely stores whatever pose the exporter last evaluated — the polyperfect wolf's
+// node pose is 0.37 m away from its bind pose on a 1.5 m animal. Measuring a retarget delta from
+// that is measuring from nothing, so `bind` is what the retargeter anchors on and node TRS is only
+// the fallback for bones no skin binds (leaf tips, helpers).
+import type { Document } from '@gltf-transform/core'
+import { readFbx, f32 } from '../fbx/read'
+import { readFileSync } from 'node:fs'
+
+export type Quat = [number, number, number, number]   // x, y, z, w
+export type Vec3 = [number, number, number]
+
+export const qmul = (a: Quat, b: Quat): Quat => [
+  a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+  a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+  a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+  a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+]
+export const qinv = (q: Quat): Quat => [ -q[0], -q[1], -q[2], q[3] ]   // unit quaternions only
+const qconj = qinv
+export const qnorm = (q: Quat): Quat => {
+  const l = Math.hypot(q[0], q[1], q[2], q[3]) || 1
+  return [ q[0] / l, q[1] / l, q[2] / l, q[3] / l ]
+}
+export const qslerp = (a: Quat, b: Quat, t: number): Quat => {
+  let d = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]
+  let e = b
+  if (d < 0) { d = -d; e = [ -b[0], -b[1], -b[2], -b[3] ] }
+  if (d > 0.9995) return qnorm([ a[0] + (e[0] - a[0]) * t, a[1] + (e[1] - a[1]) * t, a[2] + (e[2] - a[2]) * t, a[3] + (e[3] - a[3]) * t ])
+  const th = Math.acos(d), s = Math.sin(th)
+  const wa = Math.sin((1 - t) * th) / s, wb = Math.sin(t * th) / s
+  return [ a[0] * wa + e[0] * wb, a[1] * wa + e[1] * wb, a[2] * wa + e[2] * wb, a[3] * wa + e[3] * wb ]
+}
+/** Rotate a vector by a quaternion. */
+const sub = (a: Vec3, b: Vec3): Vec3 => [ a[0] - b[0], a[1] - b[1], a[2] - b[2] ]
+const add = (a: Vec3, b: Vec3): Vec3 => [ a[0] + b[0], a[1] + b[1], a[2] + b[2] ]
+const scl = (a: Vec3, k: number): Vec3 => [ a[0] * k, a[1] * k, a[2] * k ]
+const len = (v: Vec3): number => Math.hypot(v[0], v[1], v[2])
+export const qrot = (q: Quat, v: Vec3): Vec3 => {
+  const [ x, y, z, w ] = q
+  const tx = 2 * (y * v[2] - z * v[1]), ty = 2 * (z * v[0] - x * v[2]), tz = 2 * (x * v[1] - y * v[0])
+  return [
+    v[0] + w * tx + y * tz - z * ty,
+    v[1] + w * ty + z * tx - x * tz,
+    v[2] + w * tz + x * ty - y * tx,
+  ]
+}
+
+export interface Pose { t: Vec3[]; r: Quat[]; s: Vec3[] }
+export interface Clip { name: string; duration: number; sample: (time: number) => Pose }
+
+/** The pose a retarget measures against: bind where a skin defines it, node rest elsewhere. */
+export interface BindPose {
+  worldRot: Quat[]; worldPos: Vec3[]; fromSkin: boolean[]
+  /** Uniform factor baked into the bind positions to bring the skin's bind space to node-world units (1 = none). */
+  scale: number
+  /** The same pose in local space — the base a clip is sampled onto, so bones a clip does not
+   *  animate fall back to BIND rather than to whatever pose the exporter left on the nodes. */
+  local: Pose
+}
+
+export interface Rig {
+  label: string
+  names: string[]
+  parents: number[]
+  /** Rest pose in local space, and the world rotation / position it produces. */
+  rest: Pose
+  restWorldRot: Quat[]
+  restWorldPos: Vec3[]
+  bind: BindPose
+  order: number[]              // topological: every parent before its children
+  index: Map<string, number>
+  clips: Clip[]
+}
+
+const buildOrder = (parents: number[]): number[] => {
+  const order: number[] = []
+  const done = new Set<number>()
+  const visit = (i: number): void => {
+    if (done.has(i)) return
+    if (parents[i] >= 0) visit(parents[i])
+    done.add(i); order.push(i)
+  }
+  parents.forEach((_, i) => visit(i))
+  return order
+}
+
+/** World rotation/position for a whole pose, honouring a uniform scale in the chain. */
+export const worldOf = (rig: Rig, pose: Pose): { rot: Quat[]; pos: Vec3[]; scale: number[] } => {
+  const rot: Quat[] = new Array(rig.names.length)
+  const pos: Vec3[] = new Array(rig.names.length)
+  const scale: number[] = new Array(rig.names.length)
+  for (const i of rig.order) {
+    const p = rig.parents[i]
+    if (p < 0) { rot[i] = qnorm(pose.r[i]); pos[i] = pose.t[i]; scale[i] = pose.s[i][0]; continue }
+    rot[i] = qnorm(qmul(rot[p], pose.r[i]))
+    const off = qrot(rot[p], [ pose.t[i][0] * scale[p], pose.t[i][1] * scale[p], pose.t[i][2] * scale[p] ])
+    pos[i] = [ pos[p][0] + off[0], pos[p][1] + off[1], pos[p][2] + off[2] ]
+    scale[i] = scale[p] * pose.s[i][0]
+  }
+  return { rot, pos, scale }
+}
+
+export type Mat4 = number[]   // column-major
+
+const matMul = (a: Mat4, b: Mat4): Mat4 => {
+  const o = new Array(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+const matCompose = (t: Vec3, q: Quat, s: Vec3): Mat4 => {
+  const [ x, y, z, w ] = q, x2 = x + x, y2 = y + y, z2 = z + z
+  const xx = x * x2, xy = x * y2, xz = x * z2, yy = y * y2, yz = y * z2, zz = z * z2, wx = w * x2, wy = w * y2, wz = w * z2
+  return [ (1 - (yy + zz)) * s[0], (xy + wz) * s[0], (xz - wy) * s[0], 0,
+           (xy - wz) * s[1], (1 - (xx + zz)) * s[1], (yz + wx) * s[1], 0,
+           (xz + wy) * s[2], (yz - wx) * s[2], (1 - (xx + yy)) * s[2], 0, t[0], t[1], t[2], 1 ]
+}
+/** Inverse of a rigid matrix with a uniform scale — all an IBM ever is. */
+const matInvRigid = (m: Mat4): Mat4 => {
+  const s2 = m[0] * m[0] + m[1] * m[1] + m[2] * m[2] || 1
+  const r: Mat4 = [ m[0] / s2, m[4] / s2, m[8] / s2, 0, m[1] / s2, m[5] / s2, m[9] / s2, 0, m[2] / s2, m[6] / s2, m[10] / s2, 0, 0, 0, 0, 1 ]
+  r[12] = -(r[0] * m[12] + r[4] * m[13] + r[8] * m[14])
+  r[13] = -(r[1] * m[12] + r[5] * m[13] + r[9] * m[14])
+  r[14] = -(r[2] * m[12] + r[6] * m[13] + r[10] * m[14])
+  return r
+}
+/** Rotation of a matrix as a quaternion, scale divided out first. */
+const matToQuat = (m: Mat4): Quat => {
+  const sx = Math.hypot(m[0], m[1], m[2]) || 1, sy = Math.hypot(m[4], m[5], m[6]) || 1, sz = Math.hypot(m[8], m[9], m[10]) || 1
+  const a = m[0] / sx, b = m[1] / sx, c = m[2] / sx
+  const d = m[4] / sy, e = m[5] / sy, f = m[6] / sy
+  const g = m[8] / sz, h = m[9] / sz, i = m[10] / sz
+  const tr = a + e + i
+  if (tr > 0) { const k = Math.sqrt(tr + 1) * 2; return qnorm([ (f - h) / k, (g - c) / k, (b - d) / k, k / 4 ]) }
+  if (a > e && a > i) { const k = Math.sqrt(1 + a - e - i) * 2; return qnorm([ k / 4, (d + b) / k, (g + c) / k, (f - h) / k ]) }
+  if (e > i) { const k = Math.sqrt(1 + e - a - i) * 2; return qnorm([ (d + b) / k, k / 4, (h + f) / k, (g - c) / k ]) }
+  const k = Math.sqrt(1 + i - a - e) * 2
+  return qnorm([ (g + c) / k, (h + f) / k, k / 4, (b - d) / k ])
+}
+
+/**
+ * Bind pose from inverse-bind matrices, filled in down the hierarchy for bones no skin binds.
+ * `ibmByNode` maps a node index to its 16 IBM floats.
+ *
+ * IBMs are authored in the MESH's space, which is not always the node-world space: a Maya "actor"
+ * export keeps the skeleton in metres while the mesh (and so every IBM) sits in a 100× smaller
+ * space with a ×100 mesh-node scale that glTF ignores for skinned meshes. The bind pose then lands
+ * 100× too small next to the rest pose. Bone LENGTHS are invariant under whatever junk rotations an
+ * exporter left on the nodes, so the ratio of total rest bone length to total bind bone length is
+ * a robust measure of that scale; it is baked into the bind positions (`scale` reports it).
+ */
+const buildBind = (parents: number[], order: number[], rest: Pose, ibmByNode: Map<number, number[]>, spaceByNode: Map<number, Mat4>): BindPose => {
+  const world: Mat4[] = new Array(parents.length)
+  const fromSkin: boolean[] = new Array(parents.length).fill(false)
+  // Rest world matrices, for the mesh-space fold below and the fill-in of unskinned nodes.
+  const restWorld: Mat4[] = new Array(parents.length)
+  for (const i of order) {
+    const local = matCompose(rest.t[i], rest.r[i], rest.s[i])
+    restWorld[i] = parents[i] >= 0 ? matMul(restWorld[parents[i]], local) : local
+  }
+  // inv(IBM) is the joint in the MESH's geometry space. That space is the world only when the node
+  // carrying the mesh sits at identity; an exporter that parks the Z-up→Y-up turn on a geometry
+  // helper node (Female Runner's `Humanoid_F`: helper −90°X, joints Y-up, IBMs Z-up) or a ×100 scale
+  // on the mesh node (Maya "actor" exports) leaves the raw bind turned/shrunk against the joints.
+  // Folding the mesh node's world transform in front is exact for those; it is kept only when it
+  // brings the bind CLOSER to the node rest pose (a rig whose mesh node carries an unrelated
+  // transform — glTF ignores it for skinned meshes — must not be turned by it).
+  let rawDist = 0, foldedDist = 0
+  const raw: Mat4[] = new Array(parents.length), folded: Mat4[] = new Array(parents.length)
+  for (const i of order) {
+    const ibm = ibmByNode.get(i)
+    if (!ibm) continue
+    raw[i] = matInvRigid(ibm)
+    const space = spaceByNode.get(i)
+    folded[i] = space ? matMul(space, raw[i]) : raw[i]
+    fromSkin[i] = true
+    rawDist += Math.hypot(raw[i][12] - restWorld[i][12], raw[i][13] - restWorld[i][13], raw[i][14] - restWorld[i][14])
+    foldedDist += Math.hypot(folded[i][12] - restWorld[i][12], folded[i][13] - restWorld[i][13], folded[i][14] - restWorld[i][14])
+  }
+  const useFolded = foldedDist <= rawDist
+  for (const i of order) if (fromSkin[i]) world[i] = useFolded ? folded[i] : raw[i]
+  // Accumulated (uniform) scale, taken from the rest pose — scale is not part of the bind problem.
+  const accum: number[] = new Array(parents.length).fill(1)
+  for (const i of order) accum[i] = (parents[i] >= 0 ? accum[parents[i]] : 1) * rest.s[i][0]
+  let restLen = 0, bindLen = 0
+  for (const i of order) {
+    const p = parents[i]
+    if (p < 0 || !fromSkin[i] || !fromSkin[p]) continue
+    restLen += Math.hypot(...rest.t[i]) * accum[p]
+    bindLen += Math.hypot(world[i][12] - world[p][12], world[i][13] - world[p][13], world[i][14] - world[p][14])
+  }
+  const scale = restLen > 0 && bindLen > 0 ? restLen / bindLen : 1
+  if (Math.abs(scale - 1) > 0.01) for (const i of order) if (fromSkin[i]) { world[i][12] *= scale; world[i][13] *= scale; world[i][14] *= scale }
+  for (const i of order) {
+    if (fromSkin[i]) continue
+    const local = matCompose(rest.t[i], rest.r[i], rest.s[i])
+    world[i] = parents[i] >= 0 ? matMul(world[parents[i]], local) : local
+  }
+  const worldRot = world.map(matToQuat)
+  const worldPos = world.map((m) => [ m[12], m[13], m[14] ] as Vec3)
+  const local: Pose = { t: [], r: [], s: rest.s.map((v) => [ ...v ] as Vec3) }
+  for (const i of order) {
+    const p = parents[i]
+    if (p < 0) { local.t[i] = [ ...worldPos[i] ] as Vec3; local.r[i] = worldRot[i]; continue }
+    const off: Vec3 = [ worldPos[i][0] - worldPos[p][0], worldPos[i][1] - worldPos[p][1], worldPos[i][2] - worldPos[p][2] ]
+    const rel = qrot(qconj(worldRot[p]), off)
+    const k = accum[p] || 1
+    local.t[i] = [ rel[0] / k, rel[1] / k, rel[2] / k ]
+    local.r[i] = qnorm(qmul(qconj(worldRot[p]), worldRot[i]))
+  }
+  return { worldRot, worldPos, fromSkin, local, scale: Math.abs(scale - 1) > 0.01 ? scale : 1 }
+}
+
+/** Rest world matrix of one node (parents composed), for the mesh-space fold in `buildBind`. */
+const restWorldOf = (parents: number[], rest: Pose, node: number): Mat4 => {
+  const chain: number[] = []
+  for (let a = node; a >= 0; a = parents[a]) chain.unshift(a)
+  let m: Mat4 | null = null
+  for (const i of chain) { const local = matCompose(rest.t[i], rest.r[i], rest.s[i]); m = m ? matMul(m, local) : local }
+  return m!
+}
+
+/**
+ * Assemble a Rig: topological order, the bind pose from inverse-bind matrices (`ibmByNode` — the
+ * bones a skin binds; the rest are filled in down the hierarchy), and the clips, which are built
+ * from the BIND local pose so a bone no clip animates falls back to bind rather than to whatever
+ * the exporter left on the node. The one constructor — FBX, glTF and Unreal rigs all come out of it.
+ */
+export const makeRig = (label: string, names: string[], parents: number[], rest: Pose, makeClips: (base: Pose) => Clip[], ibmByNode: Map<number, number[]>, spaceByNode: Map<number, Mat4> = new Map()): Rig => {
+  const order = buildOrder(parents)
+  const bind = buildBind(parents, order, rest, ibmByNode, spaceByNode)
+  const rig: Rig = {
+    label, names, parents, rest,
+    restWorldRot: [], restWorldPos: [],
+    bind,
+    order,
+    index: new Map(names.map((n, i) => [ n, i ])),
+    clips: makeClips(bind.local),
+  }
+  const w = worldOf(rig, rest)
+  rig.restWorldRot = w.rot
+  rig.restWorldPos = w.pos
+  return rig
+}
+
+/** How far a rig's bind pose sits from the TRS on its nodes — large means the node pose is junk. */
+export const bindVsRest = (rig: Rig): { worst: number; bone: string; skinned: number } => {
+  let worst = 0, bone = ''
+  for (let i = 0; i < rig.names.length; i++) {
+    if (!rig.bind.fromSkin[i]) continue
+    const a = rig.bind.worldPos[i], b = rig.restWorldPos[i]
+    const d = Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2])
+    if (d > worst) { worst = d; bone = rig.names[i] }
+  }
+  return { worst, bone, skinned: rig.bind.fromSkin.filter(Boolean).length }
+}
+
+/** Throws on a non-uniform scale — the quaternion chain above would silently lie. */
+export const checkUniformScale = (rig: Rig): void => {
+  for (let i = 0; i < rig.names.length; i++) {
+    const [ a, b, c ] = rig.rest.s[i]
+    if (Math.abs(a - b) > 1e-4 || Math.abs(b - c) > 1e-4) {
+      throw new Error(`${rig.label}: bone "${rig.names[i]}" has a non-uniform rest scale [${rig.rest.s[i]}] — retargeting needs uniform scales`)
+    }
+  }
+}
+
+// ---- FBX (the clip donor) -----------------------------------------------------------------------
+
+/** Sample one baked FBX track (times/values in the arena) at `time`. */
+const sampleTrack = (times: Float32Array, values: Float32Array, n: number, time: number, step = false): number[] => {
+  const last = times.length - 1
+  const at = (i: number): number[] => Array.from(values.subarray(i * n, i * n + n))
+  if (time <= times[0]) return at(0)
+  if (time >= times[last]) return at(last)
+  let i = 0
+  while (i < last && times[i + 1] < time) i++
+  if (step) return at(i)
+  const u = (time - times[i]) / (times[i + 1] - times[i] || 1)
+  const a = at(i), b = at(i + 1)
+  if (n === 4) return qslerp(a as Quat, b as Quat, u)
+  return a.map((v, k) => v + (b[k] - v) * u)
+}
+
+export const rigFromFbx = async (path: string, bytes: Uint8Array): Promise<Rig> => {
+  const scene = await readFbx(bytes)
+  const names = scene.nodes.map((n) => n.name)
+  const parents = scene.nodes.map((n) => n.parent)
+  const rest: Pose = {
+    t: scene.nodes.map((n) => [ ...n.t ] as Vec3),
+    r: scene.nodes.map((n) => [ ...n.r ] as Quat),
+    s: scene.nodes.map((n) => [ ...n.s ] as Vec3),
+  }
+  const ibmByNode = new Map<number, number[]>()
+  const spaceByNode = new Map<number, Mat4>()
+  scene.skins.forEach((skin, si) => {
+    const ibm = f32(scene, skin.ibm, skin.joints.length * 16)
+    // The node carrying this skin's mesh (ufbx parks a geometry transform on a helper child, which
+    // is then the node that has the mesh): its world is the IBMs' space.
+    const meshNode = scene.nodes.findIndex((n) => n.skin === si)
+    const space = meshNode >= 0 ? restWorldOf(parents, rest, meshNode) : null
+    skin.joints.forEach((node, j) => {
+      if (ibmByNode.has(node)) return
+      ibmByNode.set(node, Array.from(ibm.subarray(j * 16, j * 16 + 16)))
+      if (space) spaceByNode.set(node, space)
+    })
+  })
+  const makeClips = (base: Pose): Clip[] => scene.animations.filter((a) => a.tracks.length > 0).map((anim) => {
+    // Pre-resolve the arena views once; sample() is called per frame per clip.
+    const tracks = anim.tracks.map((tr) => {
+      const n = tr.path === 'rotation' ? 4 : 3
+      return { node: tr.node, path: tr.path, n, times: f32(scene, tr.times, tr.count), values: f32(scene, tr.values, tr.count * n) }
+    })
+    return {
+      name: anim.name,
+      duration: anim.duration,
+      sample: (time: number): Pose => {
+        const pose: Pose = { t: base.t.map((v) => [ ...v ] as Vec3), r: base.r.map((v) => [ ...v ] as Quat), s: base.s.map((v) => [ ...v ] as Vec3) }
+        for (const tr of tracks) {
+          const v = sampleTrack(tr.times, tr.values, tr.n, time)
+          if (tr.path === 'translation') pose.t[tr.node] = v as Vec3
+          else if (tr.path === 'rotation') pose.r[tr.node] = qnorm(v as Quat)
+          else pose.s[tr.node] = v as Vec3
+        }
+        return pose
+      },
+    }
+  })
+  return makeRig(path, names, parents, rest, makeClips, ibmByNode, spaceByNode)
+}
+
+// ---- glTF Document (the model being animated) ---------------------------------------------------
+
+export interface DocRig extends Rig { doc: Document; nodes: any[] }
+
+/** Clips from a glTF Document's animations, sampled the same way the FBX side is. */
+const clipsFromDocument = (doc: Document, nodes: any[], base: Pose): Clip[] => {
+  const idx = new Map(nodes.map((n, i) => [ n, i ]))
+  return doc.getRoot().listAnimations().map((anim) => {
+    const chans = anim.listChannels().map((ch) => {
+      const s = ch.getSampler()!
+      return {
+        node: idx.get(ch.getTargetNode()!)!,
+        path: ch.getTargetPath() as string,
+        step: s.getInterpolation() === 'STEP',
+        times: s.getInput()!.getArray() as Float32Array,
+        values: s.getOutput()!.getArray() as Float32Array,
+      }
+    }).filter((c) => c.node !== undefined)
+    let duration = 0
+    for (const c of chans) duration = Math.max(duration, c.times[c.times.length - 1] ?? 0)
+    return {
+      name: anim.getName(),
+      duration,
+      sample: (time: number): Pose => {
+        const pose: Pose = { t: base.t.map((v) => [ ...v ] as Vec3), r: base.r.map((v) => [ ...v ] as Quat), s: base.s.map((v) => [ ...v ] as Vec3) }
+        for (const c of chans) {
+          const n = c.path === 'rotation' ? 4 : 3
+          const v = sampleTrack(c.times, c.values as Float32Array, n, time, c.step)
+          if (c.path === 'translation') pose.t[c.node] = v as Vec3
+          else if (c.path === 'rotation') pose.r[c.node] = qnorm(v as Quat)
+          else if (c.path === 'scale') pose.s[c.node] = v as Vec3
+        }
+        return pose
+      },
+    }
+  })
+}
+
+export const rigFromDocument = (doc: Document, label: string): DocRig => {
+  const nodes = doc.getRoot().listNodes()
+  const idx = new Map(nodes.map((n, i) => [ n, i ]))
+  const names = nodes.map((n) => n.getName())
+  const parents = nodes.map((n) => { const p = n.getParentNode(); return p ? idx.get(p)! : -1 })
+  const rest: Pose = {
+    t: nodes.map((n) => [ ...n.getTranslation() ] as Vec3),
+    r: nodes.map((n) => [ ...n.getRotation() ] as Quat),
+    s: nodes.map((n) => [ ...n.getScale() ] as Vec3),
+  }
+  const ibmByNode = new Map<number, number[]>()
+  const spaceByNode = new Map<number, Mat4>()
+  for (const skin of doc.getRoot().listSkins()) {
+    const acc = skin.getInverseBindMatrices()
+    if (!acc) continue
+    // A converted FBX keeps the mesh on the (helper) node whose world is the IBMs' space; glTF
+    // ignores that transform for skinning, so it survives as the record of where the bind lives.
+    const meshNode = nodes.findIndex((n) => n.getSkin() === skin)
+    const space = meshNode >= 0 ? restWorldOf(parents, rest, meshNode) : null
+    skin.listJoints().forEach((joint, j) => {
+      const i = idx.get(joint)
+      if (i === undefined || ibmByNode.has(i)) return
+      ibmByNode.set(i, acc.getElement(j, []))
+      if (space) spaceByNode.set(i, space)
+    })
+  }
+  return { ...makeRig(label, names, parents, rest, (base) => clipsFromDocument(doc, nodes, base), ibmByNode, spaceByNode), doc, nodes }
+}
+
+export const loadRig = async (path: string): Promise<Rig> => rigFromFbx(path, new Uint8Array(readFileSync(path)))
+
+/** A skeleton with a skin somewhere — the kind the classifiers can read. */
+export const hasSkin = (rig: Rig): boolean => rig.bind.fromSkin.some(Boolean)
+
+const shortBoneName = (n: string): string => n.slice(n.search(/[^:|]*$/))
+
+/**
+ * Is `source` (a clip file, a model) the same skeleton as `rig` — the kind a clip can be copied
+ * onto bone by bone? Names must match (≥ 80 %), and the matched bones' LOCAL OFFSETS (the child in
+ * its parent's frame) must point the same way: that vector is fixed by the rig and survives any
+ * pose the exporter baked into the nodes, while local rotations do not (a mocap pack's clip files
+ * carry their first frame as the rest pose). Bones under 5 cm (fingers, eyes) are ignored. A rig
+ * of the same FAMILY (another Mixamo character: same joint frames, other proportions) stays within
+ * ~20°; a rig that merely shares the naming convention (two Unreal-style rigs) turns some joint —
+ * typically the root's — by 90°, and copying its clips would twist the character.
+ */
+export const sameSkeleton = (rig: Rig, source: Rig): { same: boolean; share: number; worstDeg: number; worstBone: string } => {
+  const short = new Map<string, number>()
+  rig.names.forEach((n, i) => { const s = shortBoneName(n); if (!short.has(s)) short.set(s, i) })
+  const map = source.names.map((n) => rig.index.get(n) ?? short.get(shortBoneName(n)) ?? -1)
+  const share = map.filter((j) => j >= 0).length / Math.max(1, source.names.length)
+  let worstDeg = 0, worstBone = ''
+  source.names.forEach((_, i) => {
+    const j = map[i]
+    if (j < 0) return
+    const ps = source.parents[i], pt = rig.parents[j]
+    if (ps < 0 || pt < 0 || map[ps] !== pt) return
+    const a = rig.rest.t[j], b = source.rest.t[i]
+    const la = Math.hypot(...a), lb = Math.hypot(...b)
+    if (la < 0.05 || lb < 0.05) return
+    const deg = Math.acos(Math.max(-1, Math.min(1, (a[0] * b[0] + a[1] * b[1] + a[2] * b[2]) / (la * lb)))) * 180 / Math.PI
+    if (deg > worstDeg) { worstDeg = deg; worstBone = source.names[i] }
+  })
+  return { same: share >= 0.8 && worstDeg < 45, share, worstDeg, worstBone }
+}
+
+/**
+ * Clips of a SKELETON-ONLY file (a mocap pack's clip FBX: nodes and curves, no mesh, no skin) bound
+ * to the rig they were animated on, by bone name — exact first, then the name without its
+ * `namespace:` prefix. The result is `rig` with those clips: each sample starts from the rig's
+ * bind and takes the clip's LOCAL ROTATION on every bone it names, so the rig's own bind pose,
+ * skin and classification carry the motion. Bone OFFSETS stay the rig's — a clip file's skeleton
+ * is not always the model's (Mixamo's skin-less downloads are ~9 % larger than the character they
+ * were made for, with the thighs 22° elsewhere; the legs would come out longer than the bind and
+ * every straight leg out of reach). The translations a clip ANIMATES (the hips' travel and bob,
+ * a root's travel) are taken from the clip scaled by `scale`: 1 when the two skeletons have the
+ * same bone lengths (a pack's own clip files — exact), else the factor that puts the lowest joint
+ * of the rebound rig over the clips on the rig's own ground (a locomotion clip touches the ground
+ * somewhere; no bone-length ratio says how high the hips ride when the proportions differ).
+ * Bones the clip does not name stay in bind; bones the clip names and the rig lacks are reported.
+ */
+export const rebindClips = (rig: Rig, source: Rig): { rig: Rig; bound: number; total: number; unbound: string[]; scale: number } => {
+  const short = new Map<string, number>()
+  rig.names.forEach((n, i) => { const s = shortBoneName(n); if (!short.has(s)) short.set(s, i) })
+  const map = source.names.map((n) => rig.index.get(n) ?? short.get(shortBoneName(n)) ?? -1)
+  const unbound = source.names.filter((_, i) => map[i] < 0)
+  const bound = map.filter((j) => j >= 0).length
+  const base = rig.bind.local, srcRest = source.rest
+  // Which translations the clips animate: a bone whose translation leaves its rest anywhere in a clip.
+  const animated = source.names.map(() => false)
+  for (const c of source.clips) for (let k = 0; k <= 8; k++) {
+    const p = c.sample((k / 8) * c.duration)
+    p.t.forEach((t, i) => { if (!animated[i] && len(sub(t, srcRest.t[i])) > 1e-6) animated[i] = true })
+  }
+  const sampleAt = (c: Clip, time: number, scale: number): Pose => {
+    const p = c.sample(time)
+    const out: Pose = { t: base.t.map((v) => [ ...v ] as Vec3), r: base.r.map((q) => [ ...q ] as Quat), s: base.s.map((v) => [ ...v ] as Vec3) }
+    map.forEach((j, i) => {
+      if (j < 0) return
+      out.r[j] = p.r[i]
+      if (animated[i]) out.t[j] = scl(p.t[i], scale)
+    })
+    return out
+  }
+  // Same skeleton (every still matched offset within 1 % of its length) → the clip's translations
+  // are the rig's, exactly. Otherwise solve for the scale that grounds the rebound rig.
+  let sameLengths = true, num = 0, den = 0
+  map.forEach((j, i) => {
+    if (j < 0 || animated[i] || source.parents[i] < 0 || rig.parents[j] < 0) return
+    const a = len(base.t[j]), b = len(srcRest.t[i])
+    num += a; den += b
+    if (Math.abs(a - b) > 0.01 * Math.max(a, b, 0.01)) sameLengths = false
+  })
+  let scale = 1
+  if (!sameLengths && source.clips.length) {
+    const skinned = rig.bind.fromSkin.some(Boolean) ? rig.bind.worldPos.filter((_, i) => rig.bind.fromSkin[i]) : rig.bind.worldPos
+    const ground = Math.min(...skinned.map((p) => p[1]))
+    const lowest = (s: number): number => {
+      let lo = Infinity
+      for (const c of source.clips) for (let k = 0; k < 16; k++) {
+        const w = worldOf(rig, sampleAt(c, (k / 15) * c.duration, s))
+        for (let i = 0; i < w.pos.length; i++) if (rig.bind.fromSkin[i] || !rig.bind.fromSkin.some(Boolean)) lo = Math.min(lo, w.pos[i][1])
+      }
+      return lo
+    }
+    let a = 0.5, b = 2, fa = lowest(a) - ground, fb = lowest(b) - ground
+    if (fa < 0 && fb > 0) {
+      for (let it = 0; it < 24; it++) { const m = (a + b) / 2, fm = lowest(m) - ground; if (fm < 0) { a = m; fa = fm } else { b = m; fb = fm } }
+      scale = (a + b) / 2
+    } else scale = den > 0 && num > 0 ? num / den : 1   // no ground contact to solve on: the bone-length ratio
+  }
+  const clips: Clip[] = source.clips.map((c) => ({ name: c.name, duration: c.duration, sample: (time: number): Pose => sampleAt(c, time, scale) }))
+  return { rig: { ...rig, clips }, bound, total: source.names.length, unbound, scale }
+}
+
+/**
+ * The same rig turned by a world rotation (its root nodes get `q` in front of them): every world
+ * orientation, position and sampled pose comes out rotated, nothing else changes. Used to turn a
+ * donor to face the way the target faces before a retarget.
+ */
+export const rotateRig = <T extends Rig>(rig: T, q: Quat): T => {
+  const roots = rig.parents.map((p, i) => (p < 0 ? i : -1)).filter((i) => i >= 0)
+  const turn = (pose: Pose): Pose => {
+    const out: Pose = { t: pose.t.map((v) => [ ...v ] as Vec3), r: pose.r.map((v) => [ ...v ] as Quat), s: pose.s }
+    for (const i of roots) { out.t[i] = qrot(q, pose.t[i]); out.r[i] = qnorm(qmul(q, pose.r[i])) }
+    return out
+  }
+  const bind: BindPose = {
+    ...rig.bind,
+    worldRot: rig.bind.worldRot.map((r) => qnorm(qmul(q, r))),
+    worldPos: rig.bind.worldPos.map((p) => qrot(q, p)),
+    local: turn(rig.bind.local),
+  }
+  const out: T = {
+    ...rig,
+    rest: turn(rig.rest),
+    bind,
+    clips: rig.clips.map((c) => ({ ...c, sample: (t: number) => turn(c.sample(t)) })),
+  }
+  const w = worldOf(out, out.rest)
+  out.restWorldRot = w.rot
+  out.restWorldPos = w.pos
+  return out
+}