lecodes-assets 0.2.0 → 2.4.10

package/src/retarget/heading.ts

@@ -0,0 +1,238 @@
+// 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
+  /** the clip is a LOOP (its last frame is its first, a cycle on): the travel direction is smoothed PERIODICALLY —
+   *  the sequence continued past either end by the loop's own turn — so the curve is the clean ramp the motion is.
+   *  Clamped at the ends like a one-shot, a 0.6 s arc loop lost ~7° at each end of its 38° (the Gaussian's
+   *  truncated half averages the inside only) and the engine turned the node by 23° a pass, the travel by 38:
+   *  she crabbed 15° a cycle (ArcL4 on Kachujin, 2026-09-05). No leading / tail / pinned-end rules: a loop has
+   *  no standing phase. */
+  loop?: boolean
+}
+
+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 }
+  }
+  if (opts.loop) return loopHeading(ux, uz, w, n, dt, sigma, fps)
+  // 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°).
+  // (…and only when the END the caller asks for actually lies a turn away from the travel's line at the last fast
+  // frame: `endAt` is given for EVERY generated clip since 2026-09-05, a straight stop's included, and its pelvis
+  // turns ~40° into the stance as well — that alone made a straight stop's tail follow the pelvis to 54° and back)
+  const tail = new Uint8Array(n)
+  const travelAtFast = lastFast >= 0 ? Math.atan2(ux[lastFast]!, uz[lastFast]!) * 180 / Math.PI : 0
+  const endTurns = opts.endAt !== undefined && Math.abs(wrap180(opts.endAt - travelAtFast)) >= minTurn
+  if (endTurns && 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
+  // A FINAL STOP'S TAIL: after the last frame of confident motion (w ≥ 0.95, `moving`) with no such frame after it,
+  // the body only creeps and steps into its stance at 0.6–2 m/s in whatever direction the settle takes — that is
+  // not travel, and read as travel it turned a straight stop's course 5.5° (KM_STM on Kachujin, 2026-09-05: the
+  // node turned while she stood, the feet visibly rotating, and every following start began 5.5° off). The tail
+  // HOLDS the heading of the last confident frame; `endAt` (below) then brings it to where the clip must end.
+  // A pivot-tail (a turn stop cut in its pivot, `tail[]`) keeps its pelvis-graded rule.
+  let lastMoving = -1
+  for (let k = 0; k < n; k++) if (w[k]! >= 0.95) lastMoving = k
+  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 }
+    if (lastMoving >= 0 && k > lastMoving && !pivot[k]) { deg[k] = prev; 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++
+    // a clip that ENDS MOVING (a start, a run turn) has no standing tail to blend over: pinned on its last frame
+    // alone the difference was a 1–3° step in one frame, right at the seam into the run. Spread it over the
+    // last 0.5 s of motion instead.
+    if (k0 >= n - 1) k0 = Math.max(first > 0 ? first : 0, n - 1 - Math.round(0.5 / dt))
+    // …and the end is taken NEAREST ON THE CIRCLE: a 135 that went the long way round (−225) asked to end at
+    // +135 must not be handed 360° of extra turn over its tail
+    const c = wrap180(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) }
+  }
+  // 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 }
+}
+
+/** A LOOP's heading: the unwrapped travel angle, continued past either end by the loop's turn (the period is
+ *  n − 1 frames — the last frame repeats the first), Gaussian-smoothed over that periodic sequence. A loop that
+ *  does not turn (a straight run, |turn| < 5°) is pinned to 0 like a one-shot: its wobble is the gait's sway. */
+const loopHeading = (ux: Float64Array, uz: Float64Array, w: Float64Array, n: number, dt: number, sigma: number, fps: number): HeadingCurve => {
+  const period = n - 1
+  // the raw angle per frame, unwrapped from the previous (a still frame keeps the previous angle)
+  const ang = new Float64Array(n)
+  for (let k = 0; k < n; k++) {
+    const has = Math.hypot(ux[k]!, uz[k]!) > 1e-6
+    const a = has ? Math.atan2(ux[k]!, uz[k]!) * 180 / Math.PI : 0
+    ang[k] = k === 0 ? a : ang[k - 1]! + (has ? wrap180(a - ang[k - 1]!) : 0)
+  }
+  // the loop's turn: the angle a cycle on is the angle now plus this (the last frame IS the first, so its
+  // direction is the first's turned by the loop; the raw end-to-end difference says how much)
+  const turn = ang[n - 1]! - ang[0]!
+  if (Math.abs(turn) < 5) return { fps, deg: new Array(n).fill(0) }
+  const at = (j: number): { a: number, w: number } => {
+    let cyc = 0
+    while (j < 0) { j += period; cyc-- }
+    while (j >= period) { j -= period; cyc++ }
+    return { a: ang[j]! + cyc * turn, w: w[j]! }
+  }
+  const r = Math.max(1, Math.round(3 * sigma / dt))
+  const deg: number[] = new Array(n).fill(0)
+  // (the sequence is unwrapped and continued continuously, so this is a plain weighted mean of angles)
+  for (let k = 0; k < n; k++) {
+    let s = 0, sw = 0
+    for (let i = -r; i <= r; i++) {
+      const c = Math.exp(-0.5 * (i * dt / sigma) ** 2)
+      const p = at(k + i)
+      s += c * p.w * p.a; sw += c * p.w
+    }
+    deg[k] = sw > 1e-6 ? s / sw : ang[k]!
+  }
+  // the last frame is the first, a turn on — exactly, so the engine's seam (heading(end) − heading(0)) is the turn
+  deg[n - 1] = deg[0]! + turn
+  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
+}