lecodes-assets 0.1.2 → 0.2.1

package/src/props.ts

@@ -0,0 +1,137 @@
+// Props out of multi-variant files. Asset-store packs ship every LOD, colour set and arrangement of
+// a prop in ONE FBX (`Barrel_v1.FBX` = 15 meshes: Barrel_v1_LD1, _LD2, _S1, _rusty…); a game wants
+// one of them per GLB, sitting on the ground at the origin. `keepNodes` carves the named subtrees
+// out of a Document and re-origins what is left (X/Z centred on its footprint, Y = 0 at the lowest
+// vertex) so a `Model.load` lands the prop exactly where the node is; `splitDoc` does that for every
+// top-level node at once (one Document each). Static geometry only — skinned meshes keep their
+// skeleton's frame and are left where they are.
+
+import { Logger, type Document, type Node } from "@gltf-transform/core"
+import { cloneDocument, prune, unpartition } from "@gltf-transform/functions"
+
+/** prune() narrates what it removed through the document's logger — not news for a deliberate cut. */
+export const quiet = (doc: Document): Document => doc.setLogger(new Logger(Logger.Verbosity.SILENT))
+
+export type Vec3 = [number, number, number]
+export type NodeInfo = { name: string, depth: number, meshes: number, tris: number, size: Vec3, children: number }
+
+const IDENTITY = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+const mul = (a: number[], b: number[]): number[] => {
+  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 xf = (m: number[], x: number, y: number, z: number): Vec3 =>
+  [ m[0] * x + m[4] * y + m[8] * z + m[12], m[1] * x + m[5] * y + m[9] * z + m[13], m[2] * x + m[6] * y + m[10] * z + m[14] ]
+
+type Bounds = { lo: Vec3, hi: Vec3, tris: number, meshes: number }
+const emptyBounds = (): Bounds => ({ lo: [ Infinity, Infinity, Infinity ], hi: [ -Infinity, -Infinity, -Infinity ], tris: 0, meshes: 0 })
+const grow = (b: Bounds, p: Vec3): void => { for (let k = 0; k < 3; k++) { if (p[k] < b.lo[k]) b.lo[k] = p[k]; if (p[k] > b.hi[k]) b.hi[k] = p[k] } }
+
+/** World-space bounds of a subtree (node transforms applied; skinned primitives measured as-is). */
+export const subtreeBounds = (node: Node, parentWorld: number[] = IDENTITY, into: Bounds = emptyBounds()): Bounds => {
+  const world = mul(parentWorld, Array.from(node.getMatrix()))
+  const mesh = node.getMesh()
+  if (mesh) {
+    into.meshes++
+    for (const prim of mesh.listPrimitives()) {
+      const pos = prim.getAttribute("POSITION")
+      if (!pos) continue
+      const idx = prim.getIndices()
+      into.tris += idx ? idx.getCount() / 3 : pos.getCount() / 3
+      const a = pos.getArray()!
+      for (let i = 0; i < a.length; i += 3) grow(into, xf(world, a[i], a[i + 1], a[i + 2]))
+    }
+  }
+  for (const c of node.listChildren()) subtreeBounds(c, world, into)
+  return into
+}
+
+const sizeOf = (b: Bounds): Vec3 => (b.lo[0] === Infinity ? [ 0, 0, 0 ] : [ b.hi[0] - b.lo[0], b.hi[1] - b.lo[1], b.hi[2] - b.lo[2] ])
+
+/** The scene's nodes down to `depth` levels with mesh counts and world sizes — what `--keep` takes. */
+export const listNodes = (doc: Document, depth = 1): NodeInfo[] => {
+  const out: NodeInfo[] = []
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]
+  if (!scene) return out
+  const walk = (n: Node, d: number, parentWorld: number[]): void => {
+    const b = subtreeBounds(n, parentWorld)
+    out.push({ name: n.getName(), depth: d, meshes: b.meshes, tris: b.tris, size: sizeOf(b), children: n.listChildren().length })
+    if (d + 1 < depth) {
+      const world = mul(parentWorld, Array.from(n.getMatrix()))
+      for (const c of n.listChildren()) walk(c, d + 1, world)
+    }
+  }
+  for (const c of scene.listChildren()) walk(c, 0, IDENTITY)
+  return out
+}
+
+export type KeepResult = { kept: string[], missing: string[], size: Vec3, offset: Vec3 }
+
+/**
+ * Keep only the named nodes (any depth; their ancestors stay as the path to them, their descendants
+ * stay with them), drop everything else, then re-origin: the kept geometry's footprint centre goes to
+ * X/Z = 0 and its lowest point to Y = 0 (`ground: false` keeps the file's own placement).
+ */
+export const keepNodes = async (doc: Document, names: string[], opts: { ground?: boolean } = {}): Promise<KeepResult> => {
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]
+  if (!scene) throw new Error("the file has no scene")
+  const wanted = new Set(names)
+  const found = new Set<string>()
+  const keep = new Set<Node>()
+  // a node survives if it is wanted, sits under a wanted node, or leads to one
+  const mark = (n: Node, underKept: boolean): boolean => {
+    const self = wanted.has(n.getName())
+    if (self) found.add(n.getName())
+    let leads = false
+    for (const c of n.listChildren()) if (mark(c, underKept || self)) leads = true
+    const survives = self || underKept || leads
+    if (survives) keep.add(n)
+    return survives
+  }
+  for (const c of scene.listChildren()) mark(c, false)
+  const doomed: Node[] = []
+  scene.traverse((n) => { if (!keep.has(n)) doomed.push(n) })
+  // children first: disposing a parent detaches its subtree, which is fine, but keeps the order obvious
+  for (const n of doomed.reverse()) n.dispose()
+  const missing = names.filter((n) => !found.has(n))
+
+  const b = emptyBounds()
+  for (const c of scene.listChildren()) subtreeBounds(c, IDENTITY, b)
+  const offset: Vec3 = [ 0, 0, 0 ]
+  if (opts.ground !== false && b.lo[0] !== Infinity) {
+    offset[0] = -(b.lo[0] + b.hi[0]) / 2; offset[1] = -b.lo[1]; offset[2] = -(b.lo[2] + b.hi[2]) / 2
+    for (const c of scene.listChildren()) {
+      const t = c.getTranslation()
+      c.setTranslation([ t[0] + offset[0], t[1] + offset[1], t[2] + offset[2] ])
+    }
+  }
+  await quiet(doc).transform(prune(), unpartition())
+  return { kept: [ ...found ], missing, size: sizeOf(b), offset }
+}
+
+/** One Document per top-level node, each re-origined (see `keepNodes`). Names are de-duplicated with ` (2)`. */
+export const splitDoc = async (doc: Document, opts: { ground?: boolean } = {}): Promise<{ name: string, doc: Document, size: Vec3 }[]> => {
+  const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]
+  if (!scene) return []
+  const out: { name: string, doc: Document, size: Vec3 }[] = []
+  const seen = new Map<string, number>()
+  for (const top of scene.listChildren()) {
+    const name = top.getName() || "node"
+    const n = (seen.get(name) ?? 0) + 1
+    seen.set(name, n)
+    // keepNodes picks by NAME — a duplicate top-level name gets its siblings too; give it a unique one first
+    const unique = n > 1 ? `${name} (${n})` : name
+    const copy = cloneDocument(doc)
+    const copyScene = copy.getRoot().getDefaultScene() ?? copy.getRoot().listScenes()[0]
+    const twin = copyScene.listChildren()[scene.listChildren().indexOf(top)]
+    twin.setName(`__split__${unique}`)
+    const r = await keepNodes(copy, [ `__split__${unique}` ], opts)
+    twin.setName(name)
+    out.push({ name: unique, doc: copy, size: r.size })
+  }
+  return out
+}
+
+/** File-system friendly stem for a node name (`Barrel_v1 (2)` → `Barrel_v1-2`). */
+export const fileStem = (name: string): string => name.replace(/\s*\((\d+)\)$/, "-$1").replace(/[^\w.-]+/g, "_").replace(/^_+|_+$/g, "") || "node"

package/src/retarget/automap.ts

@@ -0,0 +1,276 @@
+// Automatic bone map for a quadruped retarget — from SKELETON SHAPE, not names.
+//
+// Bone names are unreliable across rigs (`backleg0`, `Knee_L`, `actor:skin_backKnee_L`, `joint17`),
+// but every quadruped skeleton has the same shape: a centreline from the tail through the pelvis
+// and chest to the head, four lateral chains hanging down to the ground, ears/jaw/eyes branching off
+// the head. `classify` reads that structure off the bind pose of one rig — root, spine, neck, head,
+// tail, legs (side + end), ears, jaw — and `autoMap` pairs the two structures chain by chain,
+// matching bones within a chain by normalized arc length (a 6-bone spine against a 3-bone spine maps
+// its ends exactly and the middle to the nearest donor bone; leftover target bones stay unmapped and
+// become bridges in the retarget). The result is a starting map the user reads and corrects, with a
+// report of what was and was not recognised — never a silent guess.
+import type { Rig, Vec3 } from './rig'
+import type { BoneMap } from './retarget'
+
+export interface LegInfo { side: 'L' | 'R'; end: 'front' | 'back'; chain: number[] }   // hip → … → ball of foot
+
+export interface Skeleton {
+  root: number
+  forward: Vec3                  // horizontal unit vector, tail → head
+  lateral: Vec3                  // unit vector to the rig's LEFT (+x when facing +z)
+  size: number                   // largest bounding extent
+  spine: number[]                // root … chest (inclusive both ends; length 1 when root == chest)
+  chest: number
+  neck: number[]                 // first bone after chest … head (inclusive)
+  head: number | null
+  jaw: number | null
+  ears: [number, number] | null  // [left, right]
+  tail: number[]                 // first tail bone … tip
+  legs: LegInfo[]
+  notes: string[]
+}
+
+const sub = (a: Vec3, b: Vec3): Vec3 => [ a[0] - b[0], a[1] - b[1], a[2] - b[2] ]
+const dot = (a: Vec3, b: Vec3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+const len = (v: Vec3): number => Math.hypot(v[0], v[1], v[2])
+
+/** Structure of one rig from its bind pose. Works on skinned joints only. */
+export const classify = (rig: Rig): Skeleton => {
+  const notes: string[] = []
+  const skinned = (i: number): boolean => rig.bind.fromSkin[i]
+  const pos = rig.bind.worldPos
+  const children: number[][] = rig.names.map(() => [])
+  rig.parents.forEach((p, i) => { if (p >= 0) children[p].push(i) })
+  const skids = (i: number): number[] => {
+    // Skinned descendants reachable without crossing another skinned joint.
+    const out: number[] = []
+    const q = [ ...children[i] ]
+    while (q.length) { const c = q.shift()!; if (skinned(c)) out.push(c); else q.push(...children[c]) }
+    return out
+  }
+  const sparent = (i: number): number => { let p = rig.parents[i]; while (p >= 0 && !skinned(p)) p = rig.parents[p]; return p }
+
+  // Root: the skinned joint with no skinned ancestor (the first one in topological order).
+  const root = rig.order.find((i) => skinned(i) && sparent(i) < 0)
+  if (root === undefined) throw new Error(`${rig.label}: no skinned joints`)
+  const joints = rig.order.filter(skinned)
+
+  // Bounds and body frame. Forward = the principal horizontal axis, pointing to the end where the
+  // high joints are (head, ears, neck); lateral = up × forward.
+  let lo: Vec3 = [ Infinity, Infinity, Infinity ], hi: Vec3 = [ -Infinity, -Infinity, -Infinity ]
+  for (const i of joints) for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k], pos[i][k]); hi[k] = Math.max(hi[k], pos[i][k]) }
+  const size = Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) || 1
+  const height = hi[1] - lo[1] || size
+  const cx = joints.reduce((a, i) => a + pos[i][0], 0) / joints.length, cz = joints.reduce((a, i) => a + pos[i][2], 0) / joints.length
+  let sxx = 0, sxz = 0, szz = 0
+  for (const i of joints) { const x = pos[i][0] - cx, z = pos[i][2] - cz; sxx += x * x; sxz += x * z; szz += z * z }
+  // Largest-eigenvector of the 2×2 covariance [[sxx, sxz], [sxz, szz]].
+  const theta = 0.5 * Math.atan2(2 * sxz, sxx - szz)
+  let forward: Vec3 = [ Math.cos(theta), 0, Math.sin(theta) ]
+  const top = [ ...joints ].sort((a, b) => pos[b][1] - pos[a][1]).slice(0, Math.max(1, Math.ceil(joints.length * 0.1)))
+  const topProj = top.reduce((a, i) => a + dot(sub(pos[i], [ cx, 0, cz ]), forward), 0) / top.length
+  if (topProj < 0) forward = [ -forward[0], 0, -forward[2] ]
+  const lateral: Vec3 = [ forward[2], 0, -forward[0] ]   // up × forward = (0,1,0) × (fx,0,fz) = (fz, 0, -fx)
+  const fwd = (i: number): number => dot(sub(pos[i], pos[root]), forward)
+  const lat = (i: number): number => dot(sub(pos[i], pos[root]), lateral)
+  const centre = (i: number): boolean => Math.abs(lat(i)) < 0.03 * size
+
+  // Legs: chains that hang down from the body to the ground, off the centreline.
+  const legs: LegInfo[] = []
+  {
+    const leaves = joints.filter((i) => skids(i).length === 0)
+    const feet = leaves.filter((i) => pos[i][1] - lo[1] < 0.2 * height && Math.abs(lat(i)) > 0.03 * size)
+    const taken = new Set<number>()
+    for (const f of feet) {
+      // Up to the first centreline joint (the attach point on the body): that is the leg's extent.
+      const chain: number[] = []
+      let b = f
+      while (b >= 0 && !centre(b)) { chain.unshift(b); b = sparent(b) }
+      if (b < 0 || chain.length < 3) continue
+      if (chain.some((i) => taken.has(i))) continue   // toes of a leg already found
+      // Ball of the foot: the first joint from the hip at the chain's lowest level.
+      const lowest = Math.min(...chain.map((i) => pos[i][1]))
+      const ball = chain.findIndex((i) => pos[i][1] - lowest < 0.04 * height)
+      const leg = chain.slice(0, Math.max(2, ball) + 1)
+      for (const i of leg) taken.add(i)
+      legs.push({ side: lat(leg[0]) > 0 ? 'L' : 'R', end: 'back', chain: leg })
+    }
+    // Front/back by where the leg attaches along the body. Two or four legs expected.
+    legs.sort((a, b) => fwd(a.chain[0]) - fwd(b.chain[0]))
+    if (legs.length >= 4) { legs[legs.length - 1].end = 'front'; legs[legs.length - 2].end = 'front' }
+    else if (legs.length === 3) { legs[2].end = 'front'; notes.push('three legs found — check the map') }
+    else if (legs.length === 2) {
+      // A biped, or a quadruped whose other pair was not recognised.
+      const mid = (fwd(legs[0].chain[0]) + fwd(legs[1].chain[0])) / 2
+      const bodyMid = (Math.min(...joints.map(fwd)) + Math.max(...joints.map(fwd))) / 2
+      if (mid > bodyMid) for (const l of legs) l.end = 'front'
+      notes.push('two legs found')
+    } else if (!legs.length) notes.push('no legs recognised')
+  }
+
+  // Chest: the lowest common ancestor of the front legs (or of all legs when there is no front pair).
+  const ancestors = (i: number): number[] => { const out: number[] = []; for (let a = i; a >= 0; a = sparent(a)) out.push(a); return out }
+  const lca = (list: number[]): number => {
+    if (!list.length) return root
+    let common = ancestors(list[0])
+    for (const i of list.slice(1)) { const set = new Set(ancestors(i)); common = common.filter((a) => set.has(a)) }
+    return common[0] ?? root
+  }
+  const front = legs.filter((l) => l.end === 'front')
+  let chest = front.length ? lca(front.map((l) => sparent(l.chain[0]))) : root
+  // The hip attach of the back legs should be at/near the root; if the root sits far behind the
+  // pelvis (a long "root bone"), the spine still starts at the root.
+  const pathUp = (from: number, to: number): number[] => { const out: number[] = []; for (let a = from; a >= 0; a = sparent(a)) { out.unshift(a); if (a === to) break } return out }
+  if (!ancestors(chest).includes(root)) chest = root
+  const spine = pathUp(chest, root)
+  if (spine[0] !== root) { notes.push('chest is not below the root — spine left as root only'); spine.splice(0, spine.length, root) }
+
+  // Neck/head: from the chest, the centreline path that keeps going forward. The head is the last
+  // joint on it that has side branches (ears/eyes/jaw); otherwise the path's end.
+  const legJoints = new Set(legs.flatMap((l) => l.chain))
+  const tail: number[] = []
+  const neck: number[] = []
+  let head: number | null = null, jaw: number | null = null, ears: [number, number] | null = null
+  {
+    const frontKids = (i: number): number[] => skids(i).filter((c) => !legJoints.has(c) && centre(c) && fwd(c) > fwd(i) - 0.01 * size)
+    let cur = chest
+    const path: number[] = []
+    for (let guard = 0; guard < 64; guard++) {
+      const ks = frontKids(cur).sort((a, b) => fwd(b) - fwd(a))
+      if (!ks.length) break
+      cur = ks[0]; path.push(cur)
+    }
+    if (path.length) {
+      // Head: the furthest joint on the path that branches; jaw/ears hang off it.
+      let h = path.length - 1
+      while (h > 0 && skids(path[h]).length < 2) h--
+      if (skids(path[h]).length < 2) h = path.length - 1
+      head = path[h]
+      neck.push(...path.slice(0, h + 1))
+      const kids = skids(head)
+      const pair = kids.filter((c) => Math.abs(lat(c)) > 0.02 * size)
+      const left = pair.filter((c) => lat(c) > 0).sort((a, b) => pos[b][1] - pos[a][1]), right = pair.filter((c) => lat(c) < 0).sort((a, b) => pos[b][1] - pos[a][1])
+      if (left.length && right.length) ears = [ left[0], right[0] ]   // the highest lateral pair: ears
+      const centreKids = kids.filter((c) => !pair.includes(c))
+      // Jaw (or snout): a centreline child heading forward and DOWN, with its own chain preferably.
+      const j = centreKids.filter((c) => pos[c][1] < pos[head!][1] - 0.01 * size && fwd(c) > fwd(head!)).sort((a, b) => skids(b).length - skids(a).length)[0]
+      if (j !== undefined) jaw = j
+    } else notes.push('no neck/head found forward of the chest')
+
+    // Tail: from the root (or a joint right next to it), the centreline path heading backward. The
+    // first tail bone often sits ON the root, so a candidate counts by where its subtree goes.
+    const subtreeFwd = (i: number): number => { let s = 0, c = 0; const q = [ i ]; while (q.length) { const j = q.shift()!; s += fwd(j); c++; q.push(...skids(j)) } return s / c }
+    const backKids = (i: number): number[] => skids(i).filter((c) => !legJoints.has(c) && !spine.includes(c) && !neck.includes(c) && centre(c) && subtreeFwd(c) < fwd(i) - 0.01 * size)
+    let start = root
+    let ks = backKids(start)
+    if (!ks.length && spine.length > 1) { start = spine[1]; ks = backKids(start) }
+    cur = start
+    for (let guard = 0; guard < 64 && ks.length; guard++) {
+      cur = ks.sort((a, b) => fwd(a) - fwd(b))[0]
+      tail.push(cur)
+      ks = backKids(cur)
+    }
+  }
+
+  return { root, forward, lateral, size, spine, chest, neck, head, jaw, ears, tail, legs, notes }
+}
+
+export interface AutoMapResult {
+  map: BoneMap
+  root: string
+  legs: string[]
+  target: Skeleton
+  donor: Skeleton
+  lines: string[]            // human-readable pairing report
+}
+
+/**
+ * Map two classified skeletons onto each other. Chains pair by role; bones inside a chain pair by
+ * normalized arc length, ends exact, each donor bone used at most once per chain (extra target bones
+ * are left out → bridges).
+ */
+export const autoMap = (target: Rig, donor: Rig): AutoMapResult => {
+  const T = classify(target), D = classify(donor)
+  const map: BoneMap = {}
+  const lines: string[] = []
+  const name = (rig: Rig, i: number): string => rig.names[i]
+
+  const arc = (rig: Rig, chain: number[], anchor: number): number[] => {
+    // Cumulative length from the chain's anchor joint (the joint it hangs off) through each bone,
+    // normalized so the chain's end is 1. A one-bone chain is therefore [1]: it IS the end.
+    const out: number[] = []
+    let acc = 0, prev = anchor
+    for (const c of chain) { acc += len(sub(rig.bind.worldPos[c], rig.bind.worldPos[prev])); out.push(acc); prev = c }
+    const total = acc || 1
+    return out.map((v) => v / total)
+  }
+  // Name hints: bones whose names share an anatomical token (knee/Knee_L, backAnkle/Ankle) pair for
+  // less — names are unreliable across rigs, but when they do agree they beat arc length.
+  const TOKENS = [ 'scapula', 'shoulder', 'elbow', 'wrist', 'finger', 'hand', 'hip', 'thigh', 'knee', 'shin', 'calf', 'ankle', 'toe', 'foot', 'spine', 'chest', 'neck', 'head', 'jaw', 'ear', 'eye', 'tail', 'rump' ]
+  // "frontHip/frontKnee/frontAnkle/frontToes/frontRump" is one rig family's name for the front leg:
+  // translate to the forelimb words so they meet Shoulder/Elbow/Wrist/Fingers/Scapula.
+  const FRONT: Record<string, string> = { hip: 'shoulder', thigh: 'shoulder', knee: 'elbow', shin: 'wrist', ankle: 'wrist', toe: 'finger', foot: 'hand', rump: 'scapula' }
+  const tokensOf = (s: string): Set<string> => {
+    const l = s.toLowerCase()
+    const found = TOKENS.filter((t) => l.includes(t))
+    return new Set(/front|fore/.test(l) ? found.map((t) => FRONT[t] ?? t) : found)
+  }
+  const nameBonus = (t: number, d: number): number => {
+    const a = tokensOf(name(target, t)), b = tokensOf(name(donor, d))
+    for (const x of a) if (b.has(x)) return 0.2
+    return 0
+  }
+  const pairChain = (role: string, tc: number[], dc: number[], tAnchor: number, dAnchor: number): void => {
+    if (!tc.length || !dc.length) { if (tc.length || dc.length) lines.push(`  ${role}: ${tc.length ? 'donor' : 'target'} has none — skipped`); return }
+    const tu = arc(target, tc, tAnchor), du = arc(donor, dc, dAnchor)
+    // Monotone alignment of the two chains (sequence alignment on arc length): pairing costs the
+    // arc-length gap, skipping a bone on either side costs GAP, the two ENDS always pair (foot,
+    // head, tail tip). Extra target bones are left out and become bridges in the retarget.
+    const GAP = 0.12
+    const cost = (k: number, j: number): number => Math.abs(tu[k - 1] - du[j - 1]) - nameBonus(tc[k - 1], dc[j - 1])
+    const nt = tc.length - 1, nd = dc.length - 1   // ends handled separately
+    const Dp: number[][] = Array.from({ length: nt + 1 }, () => new Array(nd + 1).fill(0))
+    for (let k = 1; k <= nt; k++) Dp[k][0] = k * GAP
+    for (let j = 1; j <= nd; j++) Dp[0][j] = j * GAP
+    for (let k = 1; k <= nt; k++) for (let j = 1; j <= nd; j++) {
+      Dp[k][j] = Math.min(Dp[k - 1][j - 1] + cost(k, j), Dp[k - 1][j] + GAP, Dp[k][j - 1] + GAP)
+    }
+    const pairs: [number, number][] = []
+    for (let k = nt, j = nd; k > 0 && j > 0;) {
+      if (Math.abs(Dp[k][j] - (Dp[k - 1][j - 1] + cost(k, j))) < 1e-12) { pairs.unshift([ tc[k - 1], dc[j - 1] ]); k--; j-- }
+      else if (Dp[k][j] === Dp[k - 1][j] + GAP) k--
+      else j--
+    }
+    pairs.push([ tc[tc.length - 1], dc[dc.length - 1] ])
+    for (const [ t, d ] of pairs) map[name(target, t)] = name(donor, d)
+    lines.push(`  ${role}: ${pairs.map(([ t, d ]) => `${name(target, t)}←${name(donor, d)}`).join(', ')}${tc.length > pairs.length ? `  (+${tc.length - pairs.length} target bone(s) bridged)` : ''}`)
+  }
+  const sparentOf = (rig: Rig) => (i: number): number => { let p = rig.parents[i]; while (p >= 0 && !rig.bind.fromSkin[p]) p = rig.parents[p]; return p }
+  const tsp = sparentOf(target), dsp = sparentOf(donor)
+
+  // The root pairs with the root; the rest of the spine hangs off it.
+  map[name(target, T.root)] = name(donor, D.root)
+  lines.push(`  root: ${name(target, T.root)}←${name(donor, D.root)}`)
+  pairChain('spine', T.spine.slice(1), D.spine.slice(1), T.root, D.root)
+  pairChain('neck/head', T.neck, D.neck, T.chest, D.chest)
+  if (T.jaw !== null && D.jaw !== null) { map[name(target, T.jaw)] = name(donor, D.jaw); lines.push(`  jaw: ${name(target, T.jaw)}←${name(donor, D.jaw)}`) }
+  if (T.ears && D.ears) { map[name(target, T.ears[0])] = name(donor, D.ears[0]); map[name(target, T.ears[1])] = name(donor, D.ears[1]); lines.push(`  ears: ${name(target, T.ears[0])}←${name(donor, D.ears[0])}, ${name(target, T.ears[1])}←${name(donor, D.ears[1])}`) }
+  if (T.tail.length && D.tail.length) pairChain('tail', T.tail, D.tail, tsp(T.tail[0]), dsp(D.tail[0]))
+  else if (T.tail.length || D.tail.length) lines.push(`  tail: ${T.tail.length ? 'donor' : 'target'} has none — skipped`)
+  const legNames: string[] = []
+  for (const tl of T.legs) {
+    const dl = D.legs.find((l) => l.side === tl.side && l.end === tl.end)
+    if (!dl) { lines.push(`  leg ${tl.end}-${tl.side}: donor has none — skipped`); continue }
+    pairChain(`leg ${tl.end}-${tl.side}`, tl.chain, dl.chain, tsp(tl.chain[0]), dsp(dl.chain[0]))
+    legNames.push(name(target, tl.chain[tl.chain.length - 1]))
+  }
+  for (const n of [ ...T.notes.map((s) => `target: ${s}`), ...D.notes.map((s) => `donor: ${s}`) ]) lines.push(`  ⚠ ${n}`)
+  return { map, root: name(target, T.root), legs: legNames, target: T, donor: D, lines }
+}
+
+/** One-line summary of a classified skeleton, for the CLI. */
+export const describeSkeleton = (rig: Rig, s: Skeleton): string => {
+  const n = (i: number | null): string => (i === null ? '-' : rig.names[i])
+  return `root ${n(s.root)} · spine ${s.spine.length} · neck ${s.neck.length} · head ${n(s.head)} · jaw ${n(s.jaw)} · ears ${s.ears ? `${n(s.ears[0])}/${n(s.ears[1])}` : '-'} · tail ${s.tail.length} · legs ${s.legs.map((l) => `${l.end[0]}${l.side}:${l.chain.length}`).join(' ')} · facing [${s.forward.map((x) => x.toFixed(2)).join(',')}]`
+}
+

package/src/retarget/ghost.ts

@@ -0,0 +1,23 @@
+// A rig's "ghost": the skeleton alone, posed by ONE of its clips — what a viewport overlays on a
+// retargeted character to compare the transfer against the original. Meshes, skins, materials
+// and the other clips go; the node tree (names = bone names) and the chosen animation stay.
+import type { Document } from '@gltf-transform/core'
+import { prune } from '@gltf-transform/functions'
+
+export const ghostSkeleton = async (doc: Document, clip: number): Promise<Document> => {
+  const root = doc.getRoot()
+  for (const n of root.listNodes()) { n.setMesh(null); n.setSkin(null) }
+  for (const m of root.listMeshes()) { for (const p of m.listPrimitives()) p.dispose(); m.dispose() }
+  for (const s of root.listSkins()) s.dispose()
+  root.listAnimations().forEach((a, i) => { if (i !== clip) a.dispose() })
+  await doc.transform(prune())
+  // One degenerate triangle at the origin: glTF viewers built around meshes (OGL's GLTFLoader) refuse
+  // a file with none, and a mesh-less load leaves the node tree without a scene graph to animate.
+  const pos = doc.createAccessor('ghost_pos').setType('VEC3').setArray(new Float32Array(9))
+  const prim = doc.createPrimitive().setAttribute('POSITION', pos)
+  const mesh = doc.createMesh('ghost_mesh').addPrimitive(prim)
+  const node = doc.createNode('ghost_mesh').setMesh(mesh)
+  const scene = root.listScenes()[0] ?? doc.createScene('ghost')
+  scene.addChild(node)
+  return doc
+}

package/src/retarget/heading.ts

@@ -0,0 +1,171 @@
+// The clip's HEADING curve — where the character FACES, for the node's turn under root rotation and
+// for the game's course. Degrees, + = toward +X (the character's left when she faces +Z), 0 = the
+// clip's own +Z at frame 0.
+//
+// Neither the body nor the travel alone will do (worked out with the owner, 2026-09-03):
+//   - a pelvis carries the STANCE: Kachujin's idle stands 43° off the direction her straight start
+//     runs, so every start's pelvis turns 46–49° more than the heading, a stop's pelvis twists back
+//     by as much while she is no longer turning, and a right-45 start's pelvis barely moves at all;
+//   - the travel cannot tell which way ROUND the body turned before it moved, and it cannot see a
+//     strafe (a face held forward while the body goes sideways).
+// So: while the body MOVES, the heading is the smoothed direction of the root's travel, unwrapped
+// to the nearest turn from the previous frame; while it STANDS after having moved, the heading holds;
+// in the LEADING standing phase (a start that turns on the spot) it goes from 0 to the first moving
+// heading following the PELVIS' turn — its sense and its shape (a body that spun the long way round
+// gets its −270, not a +90) — or a smooth ramp when the pelvis did not turn (the right-45 case). A
+// SLOW window in the middle (a pivot the body runs out of again) follows the pelvis too, and the
+// travel takes over in proportion to the frame's moving weight, so a 180 pivot turns the heading
+// through the pivot instead of stepping it the frame the body moves again. A clip tagged `strafe`
+// keeps 0 throughout: the face stays where the animator put it.
+
+export type HeadingCurve = { fps: number, deg: number[] }
+
+export interface HeadingOptions {
+  /** the face stays forward whatever the travel does (a strafe, a backpedal) */
+  strafe?: boolean
+  /** speed below which a frame says nothing about the heading (m/s, default 0.6 — a turn on the spot sways the
+   *  root at 0.4–0.8 m/s in every direction before the body goes) */
+  still?: number
+  /** speed at which a frame counts fully (m/s, default 1.5) */
+  moving?: number
+  /** the Gaussian's sigma on the travel direction, seconds (default 0.15 — under half a running step) */
+  sigma?: number
+  /** the pelvis must have turned this much (degrees) by the first moving frame for its curve to shape the
+   *  leading phase (default 30) */
+  minTurn?: number
+  /** through a PIVOT (a slow window the body runs out of again) the heading leaves the travel's line for the
+   *  pelvis' as the speed drops from this (m/s, default 3.5 — a run's pace) to `still`, and comes back the
+   *  same way; a final stop keeps the travel's line */
+  pivotSpeed?: number
+  /** the heading the clip must END at (degrees, + = left): a generated STOP THAT TURNS ends in an idle pose pinned
+   *  facing the turn, while the pelvis rule alone ends at the turn plus the idle-vs-run stance twist (~40° on
+   *  Kachujin). The difference is blended in from the frame the body first stands after its last fast frame to
+   *  the last frame — the head (the turn's own frames) is left as the turn bakes it. */
+  endAt?: number
+}
+
+const wrap180 = (d: number): number => { while (d > 180) d -= 360; while (d < -180) d += 360; return d }
+
+/** `root`: the root's position per frame ([x, y, z], metres); `pelvisYaw`: the pelvis' world yaw per
+ *  frame, RADIANS (atan2 of its forward's x over z); `dt` the frame step (seconds). */
+export const headingCurve = (root: ArrayLike<number>[], pelvisYaw: ArrayLike<number>, dt: number, opts: HeadingOptions = {}): HeadingCurve => {
+  const n = Math.min(root.length, pelvisYaw.length)
+  const fps = dt > 0 ? 1 / dt : 30
+  if (n < 2 || dt <= 0 || opts.strafe) return { fps, deg: new Array(Math.max(1, n)).fill(0) }
+  const still = opts.still ?? 0.6, moving = opts.moving ?? 1.5, sigma = opts.sigma ?? 0.15, minTurn = opts.minTurn ?? 30, pivotSpeed = opts.pivotSpeed ?? 3.5
+  // per frame: the horizontal velocity (central difference) as a unit vector and its moving weight
+  const ux = new Float64Array(n), uz = new Float64Array(n), w = new Float64Array(n), wp = new Float64Array(n)
+  for (let k = 0; k < n; k++) {
+    const a = Math.max(0, k - 1), b = Math.min(n - 1, k + 1)
+    const vx = (root[b]![0]! - root[a]![0]!) / ((b - a) * dt), vz = (root[b]![2]! - root[a]![2]!) / ((b - a) * dt)
+    const s = Math.hypot(vx, vz)
+    w[k] = Math.max(0, Math.min(1, (s - still) / Math.max(1e-6, moving - still)))
+    wp[k] = Math.max(0, Math.min(1, (s - still) / Math.max(1e-6, pivotSpeed - still)))
+    if (s > 1e-6) { ux[k] = vx / s; uz[k] = vz / s }
+  }
+  // the pelvis yaw since frame 0, unwrapped (degrees)
+  const pelvis = new Float64Array(n)
+  for (let k = 1; k < n; k++) pelvis[k] = pelvis[k - 1]! + wrap180((pelvisYaw[k]! - pelvisYaw[k - 1]!) * 180 / Math.PI)
+  // the travel direction, Gaussian-smoothed over the weighted unit vectors; hold while standing
+  const r = Math.max(1, Math.round(3 * sigma / dt))
+  const kern: number[] = []
+  for (let i = -r; i <= r; i++) kern.push(Math.exp(-0.5 * (i * dt / sigma) ** 2))
+  const deg: number[] = new Array(n).fill(0)
+  let prev = 0, prevK = -1, off = 0
+  let first = w.findIndex((v) => v >= 0.95)
+  if (first < 0) first = w.findIndex((v) => v >= 0.05)
+  // a PIVOT: a stretch between two FAST frames (at `pivotSpeed`, a run's pace — the braking into the pivot
+  // starts from there) that dips to standing (w < 0.05) — the run-to-run 180 all but stops for ~0.2 s and
+  // runs back. Through it the heading follows the PELVIS, graded by speed; a start's leading phase and a
+  // stop's braking (no fast frame on the other side) keep their own rules
+  const pivot = new Uint8Array(n)
+  let lastFast = -1
+  for (let k = 0; k < n; k++) {
+    if (wp[k]! < 0.95) continue
+    if (lastFast >= 0 && k - lastFast > 1) { let dips = false; for (let j = lastFast + 1; j < k; j++) if (w[j]! < 0.05) { dips = true; break }; if (dips) for (let j = lastFast + 1; j < k; j++) pivot[j] = 1 }
+    lastFast = k
+  }
+  // …and a STOP THAT TURNS (`endAt` given — the caller knows the clip ends facing a turn): the stretch after the
+  // last fast frame when the clip ends standing and the pelvis went on turning through it (≥ minTurn) — a
+  // run-to-run turn's stop, cut in the pivot. No fast frame on the other side, but the heading must leave the
+  // travel's line for the pelvis' the same graded way, or it steps 180° the frame the body moves again (the step
+  // back into the stance). Gated on `endAt` on purpose: a STRAIGHT stop's pelvis also turns ~40° into the idle's
+  // stance, and this rule would bake that twist into its course (it did — every straight stop drifted 40°).
+  const tail = new Uint8Array(n)
+  if (opts.endAt !== undefined && lastFast >= 0 && lastFast < n - 1 && w[n - 1]! < 0.05 && Math.abs(pelvis[n - 1]! - pelvis[lastFast]!) >= minTurn) for (let j = lastFast + 1; j < n; j++) pivot[j] = tail[j] = 1
+  for (let k = 0; k < n; k++) {
+    if (w[k]! < 0.05) { deg[k] = pivot[k] && prevK >= 0 ? pelvis[k]! + off : prev; prev = deg[k]!; continue }
+    let sx = 0, sz = 0, sw = 0
+    for (let i = -r; i <= r; i++) {
+      const j = k + i
+      if (j < 0 || j >= n) continue
+      const c = kern[i + r]! * w[j]!
+      sx += c * ux[j]!; sz += c * uz[j]!; sw += c
+    }
+    let h = prev
+    if (sw > 0.05 && Math.hypot(sx, sz) > 1e-6) {
+      const a = Math.atan2(sx, sz) * 180 / Math.PI
+      // the first moving frame unwraps NEAREST TO THE PELVIS' TURN (the sense the body chose); after
+      // that, nearest to the PELVIS' CURRENT YAW plus the stance offset seen at that first frame — a
+      // run that turns about (AA_Running_Turn_180: the travel flips within a frame or two while the
+      // pelvis turns through 180 over the whole clip) must unwrap the way the body went, and neither
+      // the previous heading nor the pelvis' turn since the previous frame can tell (it baked +190
+      // for a pelvis that turned -180). The offset absorbs the stance twist (up to ~50 deg), well
+      // under the 180 that separates the two candidates.
+      const ref = k === first && Math.abs(pelvis[first]!) >= minTurn ? pelvis[first]!
+        : prevK >= 0 ? pelvis[k]! + off : prev
+      // …and through a PIVOT the travel's say is the speed's: the heading leaves the travel's line for the
+      // pelvis' as the body brakes into the pivot and returns the same way, not by a 180 step the frame
+      // the body moves again (the node snapped 180 in one frame there and the body visibly shifted — the
+      // run-to-run 180; the pelvis leads the travel by ~60 deg into a pivot, so any switch between the two
+      // references is a step unless it is graded by speed). A final stop keeps the travel's line.
+      // (in a stop's tail the body creeps and steps back: its smoothed travel is the mean of directions that
+      // disagree — the travel's say is scaled by that mean's length, its confidence, so a creeping body's
+      // garbage direction cannot nick the curve; the run-to-run turns keep their tuned shape untouched)
+      const conf = tail[k] ? Math.min(1, Math.hypot(sx, sz) / sw) : 1
+      h = ref + (pivot[k] && k !== first ? wp[k]! * conf : 1) * wrap180(a - ref)
+      if (k === first) off = h - pelvis[first]!
+    }
+    deg[k] = h
+    prev = h
+    prevK = k
+  }
+  // the LEADING standing phase: from 0 to the first moving heading — shaped by the pelvis' own turn when
+  // it turned (a turn on the spot: the sense and the pace are the body's), a smooth ramp when it did not
+  if (first > 1) {
+    const target = deg[first]!
+    const bodyTurn = pelvis[first]!
+    for (let k = 0; k < first; k++) {
+      let e: number
+      if (Math.abs(bodyTurn) >= minTurn) e = Math.max(0, Math.min(1, pelvis[k]! / bodyTurn))
+      else { const u = k / first; e = u * u * (3 - 2 * u) }
+      deg[k] = target * e
+    }
+  }
+  // the END pINNED (`endAt`): the difference to it blended in from the first standing frame after the last fast
+  // frame (the pivot's bottom — the turn's own frames before it stay as the turn bakes them) to the last frame
+  if (opts.endAt !== undefined && n > 1) {
+    let k0 = lastFast >= 0 ? lastFast + 1 : 0
+    while (k0 < n - 1 && w[k0]! >= 0.05) k0++
+    const c = opts.endAt - deg[n - 1]!
+    const span = Math.max(1, n - 1 - k0)
+    for (let k = k0; k < n; k++) { const u = Math.min(1, (k - k0) / span); deg[k] = deg[k]! + c * u * u * (3 - 2 * u) }
+    deg[n - 1] = opts.endAt
+  }
+  // a clip that does not turn (a run loop, an idle, a stop, a straight start) is pinned to 0 outright: its
+  // wobble is the gait's sway, and integrated by root rotation it drifted the node +-1..3 deg per run
+  const maxAbs = deg.reduce((m, v) => Math.max(m, Math.abs(v!)), 0)
+  if (Math.abs(deg[n - 1]!) < 5 && maxAbs < 8) deg.fill(0)
+  for (let k = 0; k < n; k++) deg[k] = Math.round(deg[k]! * 100) / 100
+  return { fps, deg }
+}
+
+/** The curve's value at `t` (seconds), linearly interpolated; past the end, the last value. */
+export const headingAt = (h: HeadingCurve, t: number): number => {
+  const f = t * h.fps
+  const i = Math.floor(f)
+  if (i < 0) return h.deg[0] ?? 0
+  if (i >= h.deg.length - 1) return h.deg[h.deg.length - 1] ?? 0
+  const u = f - i
+  return h.deg[i]! + (h.deg[i + 1]! - h.deg[i]!) * u
+}