lecodes-assets 0.1.2 → 0.2.1

package/src/retarget/inPlace.ts

@@ -0,0 +1,130 @@
+// In-place conversion of a retargeted clip: the root's horizontal travel (and, on request, its
+// turn) is taken OFF the animation — the root stays where and how the model rests, so the character
+// stands on its capsule whatever window of a take the clip is — and handed back as per-key profiles
+// the game commands its capsule and heading with.
+//
+// Runs on the glTF document AFTER `retarget()` — so the retarget saw the real motion (foot contacts,
+// planting, the travel in the report) and only the playback loses it. Root MOTION stays available
+// through the report / `extras.lecodes.travel`; here the extras gain `inPlace: true`.
+
+import type { Document } from "@gltf-transform/core"
+
+export interface InPlaceResult {
+  /** the keyframe times of the root's translation track, seconds */
+  times: number[]
+  /** the horizontal displacement that was removed, per key: [dx, dz] from the root's rest position */
+  travel: [ number, number ][]
+  /** the horizontal speed per key, m/s (central differences over the keys) */
+  speed: number[]
+  /** with `yaw`: the root's heading per key, degrees, cumulative from the first key (+ = a turn to
+   *  the left, about +Y) — the turn a `rootRotation: 'yaw'` retarget put on the root; empty otherwise */
+  yaw: number[]
+}
+
+export interface InPlaceOptions {
+  /** also flatten the root's ROTATION track to the node's rest rotation and return its yaw profile
+   *  (a turn-in-place / turn-start clip: the game turns the node by the profile, the clip stays put) */
+  yaw?: boolean
+}
+
+type Q = [ number, number, number, number ]
+const qmul = (a: Q, b: Q): Q => [
+  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],
+]
+const qinv = (q: Q): Q => [ -q[0], -q[1], -q[2], q[3] ]
+/** heading of the +Z axis after `q`, radians about +Y */
+const headingOf = (q: Q): number => Math.atan2(2 * (q[0] * q[2] + q[3] * q[1]), 1 - 2 * (q[0] * q[0] + q[1] * q[1]))
+
+/**
+ * Hold the root's x/z at the node's REST translation for the named animation (and its rotation at
+ * the rest rotation with `yaw`). Returns the travel / turn that was removed (null when the animation
+ * has no root translation track — nothing to do).
+ */
+export const makeInPlace = (doc: Document, animationName: string, rootNodeName: string, opts: InPlaceOptions = {}): InPlaceResult | null => {
+  const anim = doc.getRoot().listAnimations().find((a) => a.getName() === animationName)
+  if (!anim) throw new Error(`makeInPlace: no animation "${animationName}"`)
+  const channel = anim.listChannels().find((c) => c.getTargetPath() === "translation" && c.getTargetNode()?.getName() === rootNodeName)
+  if (!channel) return null
+  const node = channel.getTargetNode()!
+  const [ rx, , rz ] = node.getTranslation()
+  const sampler = channel.getSampler()!
+  const input = sampler.getInput()!, output = sampler.getOutput()!
+  const times = Array.from(input.getArray() as ArrayLike<number>)
+  const values = new Float32Array(output.getArray()! as ArrayLike<number>)
+  const travel: [ number, number ][] = []
+  for (let k = 0; k < times.length; k++) {
+    travel.push([ values[k * 3]! - rx, values[k * 3 + 2]! - rz ])
+    values[k * 3] = rx
+    values[k * 3 + 2] = rz
+  }
+  output.setArray(values)
+  const speed = times.map((_, k) => {
+    const a = Math.max(0, k - 1), b = Math.min(times.length - 1, k + 1)
+    const dt = times[b]! - times[a]!
+    return dt > 0 ? Math.hypot(travel[b]![0] - travel[a]![0], travel[b]![1] - travel[a]![1]) / dt : 0
+  })
+
+  // the turn: the rotation track relative to the rest rotation is a pure yaw (retarget rootRotation
+  // 'yaw'); read it per translation key, then hold the track at rest
+  const yaw: number[] = []
+  if (opts.yaw) {
+    const rc = anim.listChannels().find((c) => c.getTargetPath() === "rotation" && c.getTargetNode() === node)
+    if (rc) {
+      const rs = rc.getSampler()!
+      const rt = Array.from(rs.getInput()!.getArray() as ArrayLike<number>)
+      const rv = new Float32Array(rs.getOutput()!.getArray()! as ArrayLike<number>)
+      const rest = node.getRotation() as Q
+      const at = (t: number): Q => {
+        let i = 0
+        while (i < rt.length - 2 && rt[i + 1]! <= t) i++
+        const t0 = rt[i]!, t1 = rt[i + 1] ?? t0, u = t1 > t0 ? Math.min(1, Math.max(0, (t - t0) / (t1 - t0))) : 0
+        const a = Array.from(rv.subarray(i * 4, i * 4 + 4)) as Q, b = rt.length > i + 1 ? Array.from(rv.subarray(i * 4 + 4, i * 4 + 8)) as Q : a
+        const s = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3] < 0 ? -1 : 1
+        const q: Q = [ a[0] + (s * b[0] - a[0]) * u, a[1] + (s * b[1] - a[1]) * u, a[2] + (s * b[2] - a[2]) * u, a[3] + (s * b[3] - a[3]) * u ]
+        const n = Math.hypot(...q) || 1
+        return [ q[0] / n, q[1] / n, q[2] / n, q[3] / n ]
+      }
+      let acc = 0, prev = 0
+      for (let k = 0; k < times.length; k++) {
+        const h = headingOf(qmul(at(times[k]!), qinv(rest)))
+        if (k > 0) { let d = h - prev; d = Math.atan2(Math.sin(d), Math.cos(d)); acc += d }
+        prev = h
+        yaw.push(acc * 180 / Math.PI)
+      }
+      const base = yaw[0] ?? 0
+      for (let k = 0; k < yaw.length; k++) yaw[k] = yaw[k]! - base
+      for (let k = 0; k < rt.length; k++) { rv[k * 4] = rest[0]; rv[k * 4 + 1] = rest[1]; rv[k * 4 + 2] = rest[2]; rv[k * 4 + 3] = rest[3] }
+      rs.getOutput()!.setArray(rv)
+    }
+  }
+
+  const extras = anim.getExtras() as Record<string, unknown>
+  const lecodes = { ...((extras.lecodes as Record<string, unknown>) ?? {}), inPlace: true }
+  anim.setExtras({ ...extras, lecodes })
+  return { times, travel, speed, yaw }
+}
+
+/** A per-key series resampled at `hz`, from t = 0 to the last key (linear between keys). */
+const resample = (times: number[], series: number[], hz: number): number[] => {
+  const end = times[times.length - 1] ?? 0
+  const n = Math.ceil(end * hz)
+  const out: number[] = []
+  for (let k = 0; k <= n; k++) {
+    const t = Math.min(end, k / hz)
+    let i = 0
+    while (i < times.length - 2 && times[i + 1]! <= t) i++
+    const t0 = times[i]!, t1 = times[i + 1] ?? t0
+    const u = t1 > t0 ? (t - t0) / (t1 - t0) : 0
+    out.push(series[i]! + ((series[i + 1] ?? series[i]!) - series[i]!) * u)
+  }
+  return out
+}
+
+/** The removed travel's speed resampled at `hz`, from t = 0 to the last key (linear between keys). */
+export const speedProfile = (r: InPlaceResult, hz = 30): number[] => resample(r.times, r.speed, hz)
+
+/** The removed turn resampled at `hz` — degrees since t = 0 (empty unless `makeInPlace` ran with `yaw`). */
+export const yawProfile = (r: InPlaceResult, hz = 30): number[] => (r.yaw.length ? resample(r.times, r.yaw, hz) : [])