lecodes-assets 0.2.0 → 0.2.1

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "lecodes-assets",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "LeCodes asset pipeline: FBX → GLB (ufbx), clip merging by bone name, texture embedding, GLB doctor (bone cap, texture normalize, KTX2).",
   "type": "module",
   "bin": {
     "lecodes-assets": "dist/cli.js"
   },
   "exports": {
-    ".": { "types": "./src/index.ts", "default": "./dist/index.js" },
-    "./cli": { "types": "./src/cli.ts", "default": "./dist/cli.js" }
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./src/cli.ts",
+      "default": "./dist/cli.js"
+    },
+    "./fbx/*": "./src/fbx/*.ts",
+    "./retarget/*": "./src/retarget/*.ts",
+    "./unreal/*": "./src/unreal/*.ts"
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "engines": {

package/src/bvh/fromDocument.ts

@@ -0,0 +1,136 @@
+// glTF document → BVH: one clip of a skeleton (a rig the BVH reader made, or any rig whose nodes ARE
+// the joints) written in the layout Kimodo reads back (`kimodo_convert x.bvh x.npz
+// --bvh_standard_tpose`): a zero `Root` with six channels over the root joint (six channels), every
+// other joint three ZYX rotation channels, no End Sites, centimetres, the rest pose = the nodes'
+// rest translations (their offsets) with identity rotations — i.e. the file's rest is whatever the
+// document's rest is (the standard T-pose for a rig read from Kimodo's `--bvh_standard_tpose` export).
+// The clip is resampled at `fps` (nlerp between keys).
+
+import type { Document, Node } from "@gltf-transform/core"
+
+type Quat = [number, number, number, number]
+type Vec3 = [number, number, number]
+
+export type BvhWriteOptions = {
+  /** the clip to write (default: the document's first) */
+  clip?: string
+  /** frames per second of the output (default 30 — Kimodo's rate) */
+  fps?: number
+  /** metres per BVH unit (default 0.01: centimetres) */
+  unit?: number
+  /** the wrapper root's name over the skeleton root (default "Root"); "" = none, the skeleton root is the BVH root */
+  wrapperRoot?: string
+}
+
+const nlerp = (a: Quat, b: Quat, t: number): Quat => {
+  const d = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]
+  const s = d < 0 ? -1 : 1
+  const q: Quat = [ a[0] + (s * b[0] - a[0]) * t, a[1] + (s * b[1] - a[1]) * t, a[2] + (s * b[2] - a[2]) * t, a[3] + (s * b[3] - a[3]) * t ]
+  const n = Math.hypot(q[0], q[1], q[2], q[3]) || 1
+  return [ q[0] / n, q[1] / n, q[2] / n, q[3] / n ]
+}
+
+/** Z·Y·X Euler angles (degrees, in channel order Zrotation Yrotation Xrotation) of a unit quaternion:
+ *  R = Rz(γ)·Ry(β)·Rx(α) → β = asin(−R20), α = atan2(R21, R22), γ = atan2(R10, R00). */
+const eulerZYX = (q: Quat): [number, number, number] => {
+  const [ x, y, z, w ] = q
+  const r00 = 1 - 2 * (y * y + z * z), r10 = 2 * (x * y + z * w), r20 = 2 * (x * z - y * w)
+  const r21 = 2 * (y * z + x * w), r22 = 1 - 2 * (x * x + y * y)
+  const b = Math.asin(Math.max(-1, Math.min(1, -r20)))
+  const D = 180 / Math.PI
+  if (Math.abs(r20) > 0.999999) {
+    // gimbal lock: fold everything into γ
+    const r01 = 2 * (x * y - z * w), r11 = 1 - 2 * (x * x + z * z)
+    return [ Math.atan2(-r01, r11) * D, b * D, 0 ]
+  }
+  return [ Math.atan2(r10, r00) * D, b * D, Math.atan2(r21, r22) * D ]
+}
+
+const f = (v: number): string => {
+  const s = (Math.abs(v) < 5e-7 ? 0 : v).toFixed(6)
+  return s.replace(/\.?0+$/, "") || "0"
+}
+
+export const documentToBvh = (doc: Document, opts: BvhWriteOptions = {}): { text: string, report: { clip: string, joints: number, frames: number, fps: number } } => {
+  const fps = opts.fps ?? 30
+  const U = opts.unit ?? 0.01
+  const root = doc.getRoot()
+  const anim = opts.clip ? root.listAnimations().find((a) => a.getName() === opts.clip) : root.listAnimations()[0]
+  if (!anim) throw new Error(opts.clip ? `no clip "${opts.clip}" (have ${root.listAnimations().map((a) => a.getName()).join(", ")})` : "no animation in the document")
+
+  // the skeleton: the joints of the first skin if there is one, else every node under the scene
+  const skin = root.listSkins()[0]
+  const joints = skin ? skin.listJoints() : root.listNodes().filter((n) => !n.getMesh())
+  const jointSet = new Set(joints)
+  const skelRoots = joints.filter((n) => { const p = n.getParentNode(); return !p || !jointSet.has(p) })
+  if (skelRoots.length !== 1) throw new Error(`the skeleton must have one root joint (found ${skelRoots.map((n) => n.getName()).join(", ") || "none"})`)
+  const skelRoot = skelRoots[0]
+
+  // tracks: per joint, the sampler for rotation / translation
+  const tracks = new Map<Node, { rot?: { t: Float32Array, v: Float32Array }, pos?: { t: Float32Array, v: Float32Array } }>()
+  for (const ch of anim.listChannels()) {
+    const node = ch.getTargetNode(), s = ch.getSampler()
+    if (!node || !s || !jointSet.has(node)) continue
+    const t = s.getInput()?.getArray() as Float32Array | undefined, v = s.getOutput()?.getArray() as Float32Array | undefined
+    if (!t || !v) continue
+    const rec = tracks.get(node) ?? {}
+    if (ch.getTargetPath() === "rotation") rec.rot = { t, v }
+    else if (ch.getTargetPath() === "translation") rec.pos = { t, v }
+    tracks.set(node, rec)
+  }
+  let duration = 0
+  for (const r of tracks.values()) for (const k of [ r.rot, r.pos ]) if (k) duration = Math.max(duration, k.t[k.t.length - 1])
+  const frames = Math.max(1, Math.round(duration * fps) + 1)
+
+  const sample = (t: Float32Array, v: Float32Array, n: number, time: number, mix: (a: number[], b: number[], k: number) => number[]): number[] => {
+    if (time <= t[0]) return Array.from(v.subarray(0, n))
+    const last = t.length - 1
+    if (time >= t[last]) return Array.from(v.subarray(last * n, last * n + n))
+    let i = 0
+    while (i < last && t[i + 1] <= time) i++
+    const k = (time - t[i]) / Math.max(1e-9, t[i + 1] - t[i])
+    return mix(Array.from(v.subarray(i * n, i * n + n)), Array.from(v.subarray((i + 1) * n, (i + 1) * n + n)), k)
+  }
+  const mixV = (a: number[], b: number[], k: number): number[] => a.map((x, i) => x + (b[i] - x) * k)
+  const mixQ = (a: number[], b: number[], k: number): number[] => nlerp(a as Quat, b as Quat, k)
+
+  // the hierarchy
+  const order: Node[] = []
+  const lines: string[] = [ "HIERARCHY" ]
+  const wrapper = opts.wrapperRoot ?? "Root"
+  const emit = (n: Node, depth: number, isRoot: boolean): void => {
+    order.push(n)
+    const pad = "  ".repeat(depth)
+    const o = n.getTranslation()
+    lines.push(`${pad}${isRoot && !wrapper ? "ROOT" : "JOINT"} ${n.getName()}`)
+    lines.push(`${pad}{`)
+    lines.push(`${pad}  OFFSET ${f(o[0] / U)} ${f(o[1] / U)} ${f(o[2] / U)}`)
+    lines.push(`${pad}  CHANNELS ${isRoot ? "6 Xposition Yposition Zposition " : "3 "}Zrotation Yrotation Xrotation`)
+    for (const c of n.listChildren()) if (jointSet.has(c)) emit(c, depth + 1, false)
+    lines.push(`${pad}}`)
+  }
+  if (wrapper) {
+    lines.push(`ROOT ${wrapper}`, "{", "  OFFSET 0.0 0.0 0.0", "  CHANNELS 6 Xposition Yposition Zposition Zrotation Yrotation Xrotation")
+    emit(skelRoot, 1, true)
+    lines.push("}")
+  } else emit(skelRoot, 0, true)
+
+  lines.push("MOTION", `Frames: ${frames}`, `Frame Time: ${1 / fps}`)
+  for (let fi = 0; fi < frames; fi++) {
+    const time = fi / fps
+    const row: string[] = []
+    if (wrapper) row.push("0.0 0.0 0.0 0.0 0.0 0.0")
+    order.forEach((n, i) => {
+      const tr = tracks.get(n)
+      if (i === 0) {
+        const p = tr?.pos ? sample(tr.pos.t, tr.pos.v, 3, time, mixV) : Array.from(n.getTranslation())
+        row.push(f(p[0] / U), f(p[1] / U), f(p[2] / U))
+      }
+      const q = (tr?.rot ? sample(tr.rot.t, tr.rot.v, 4, time, mixQ) : Array.from(n.getRotation())) as Quat
+      const [ z, y, x ] = eulerZYX(q)
+      row.push(f(z), f(y), f(x))
+    })
+    lines.push(row.join(" "))
+  }
+  return { text: lines.join("\n") + "\n", report: { clip: anim.getName(), joints: order.length, frames, fps } }
+}

package/src/bvh/toDocument.ts

@@ -0,0 +1,202 @@
+// BVH → glTF document: a skeleton-only rig (nodes + a skin with inverse binds, no mesh) carrying the
+// file's motion as one animation clip — what `retarget --from <clip>.bvh` and `convert <clip>.bvh`
+// read. Written for Kimodo's SOMA export (`kimodo_gen --bvh --bvh_standard_tpose` / `kimodo_convert
+// … .bvh --bvh_standard_tpose`: centimetres, Y-up, a zero `Root` above `Hips`, ZYX Euler channels,
+// the rest pose = the standard T-pose), but the parser is plain BVH.
+//
+// Conventions taken: OFFSET = the joint's rest translation; a joint's own position channels REPLACE
+// its offset (bvhio / Kimodo: the T-pose file's Hips channels equal its offset); rotation channels
+// compose in the listed order (Zrotation Yrotation Xrotation → R = Rz·Ry·Rx); End Sites become
+// `<parent>_End` leaves outside the skin. A zero-offset root with a single child (Kimodo's `Root`
+// above `Hips`) is folded into that child unless `keepRoot`.
+
+import { Document } from "@gltf-transform/core"
+
+type Quat = [number, number, number, number]
+type Vec3 = [number, number, number]
+type Joint = { name: string, parent: number, offset: Vec3, channels: string[], end: boolean }
+
+export type BvhOptions = {
+  /** the clip's name (default: the file's stem) */
+  name?: string
+  /** keep a zero-offset single-child root joint instead of folding it into its child */
+  keepRoot?: boolean
+  /** the file's length unit in metres (default 0.01: centimetres, the mocap convention) */
+  unit?: number
+}
+
+export type BvhReport = {
+  joints: number
+  skinJoints: number
+  folded?: string
+  frames: number
+  fps: number
+  duration: number
+  rotationTracks: number
+  translationTracks: number
+  /** the hips' height range and horizontal travel, metres */
+  hipsY: [number, number]
+  travel: number
+}
+
+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],
+]
+const qaxis = (axis: string, deg: number): Quat => {
+  const h = deg * Math.PI / 360, s = Math.sin(h), c = Math.cos(h)
+  return axis === "X" ? [ s, 0, 0, c ] : axis === "Y" ? [ 0, s, 0, c ] : [ 0, 0, s, c ]
+}
+const qrot = (q: Quat, v: Vec3): Vec3 => {
+  const [ x, y, z, w ] = q
+  const ix = w * v[0] + y * v[2] - z * v[1], iy = w * v[1] + z * v[0] - x * v[2], iz = w * v[2] + x * v[1] - y * v[0], iw = -x * v[0] - y * v[1] - z * v[2]
+  return [ ix * w + iw * -x + iy * -z - iz * -y, iy * w + iw * -y + iz * -x - ix * -z, iz * w + iw * -z + ix * -y - iy * -x ]
+}
+
+export const parseBvh = (text: string): { joints: Joint[], frames: number, frameTime: number, rows: number[][] } => {
+  const motionAt = text.indexOf("MOTION")
+  if (motionAt < 0) throw new Error("BVH: no MOTION section")
+  const hier = text.slice(0, motionAt).replace(/\r/g, "").split(/\s+/).filter(Boolean)
+  const joints: Joint[] = []
+  const stack: number[] = []
+  let i = 0
+  const next = (): string => hier[i++]
+  while (i < hier.length) {
+    const tok = next()
+    if (tok === "HIERARCHY") continue
+    if (tok === "ROOT" || tok === "JOINT") {
+      joints.push({ name: next(), parent: stack.length ? stack[stack.length - 1] : -1, offset: [ 0, 0, 0 ], channels: [], end: false })
+    } else if (tok === "End") {
+      next() // Site
+      joints.push({ name: `${joints[stack[stack.length - 1]].name}_End`, parent: stack[stack.length - 1], offset: [ 0, 0, 0 ], channels: [], end: true })
+    } else if (tok === "{") {
+      stack.push(joints.length - 1)
+    } else if (tok === "}") {
+      stack.pop()
+    } else if (tok === "OFFSET") {
+      joints[joints.length - 1].offset = [ +next(), +next(), +next() ]
+    } else if (tok === "CHANNELS") {
+      const n = +next()
+      for (let k = 0; k < n; k++) joints[joints.length - 1].channels.push(next())
+    }
+  }
+  const motion = text.slice(motionAt).replace(/\r/g, "").split("\n")
+  const frames = +(motion.find((l) => l.startsWith("Frames:"))?.split(":")[1] ?? 0)
+  const frameTime = +(motion.find((l) => l.startsWith("Frame Time:"))?.split(":")[1] ?? 1 / 30)
+  const dataStart = motion.findIndex((l) => l.startsWith("Frame Time:")) + 1
+  const rows = motion.slice(dataStart).map((l) => l.trim()).filter(Boolean).slice(0, frames).map((l) => l.split(/\s+/).map(Number))
+  const channelCount = joints.reduce((n, j) => n + j.channels.length, 0)
+  if (rows.length !== frames || rows.some((r) => r.length !== channelCount)) throw new Error(`BVH: motion data mismatch — ${rows.length}/${frames} frames, ${channelCount} channels per frame expected`)
+  return { joints, frames, frameTime, rows }
+}
+
+export const bvhToDocument = (text: string, opts: BvhOptions = {}): { doc: Document, report: BvhReport } => {
+  const { joints, frames, frameTime, rows } = parseBvh(text)
+  const U = opts.unit ?? 0.01
+  const clipName = opts.name ?? "bvh"
+
+  // per frame, per joint: local translation (m) and rotation
+  const local = rows.map((row) => {
+    let c = 0
+    return joints.map((j) => {
+      const t: Vec3 = [ j.offset[0] * U, j.offset[1] * U, j.offset[2] * U ]
+      let q: Quat = [ 0, 0, 0, 1 ]
+      let hasPos = false
+      for (const ch of j.channels) {
+        const v = row[c++]
+        if (ch === "Xposition") { t[0] = v * U; hasPos = true } else if (ch === "Yposition") { t[1] = v * U; hasPos = true } else if (ch === "Zposition") { t[2] = v * U; hasPos = true }
+        else if (ch.endsWith("rotation")) q = qmul(q, qaxis(ch[0], v))
+      }
+      return { t, q, hasPos }
+    })
+  })
+
+  // fold a zero-offset, single-child root into its child (Kimodo's `Root` above `Hips`)
+  let dropped = -1
+  let folded: string | undefined
+  if (!opts.keepRoot && joints[0].parent === -1 && joints.filter((j) => j.parent === 0).length === 1 && joints[0].offset.every((v) => v === 0)) {
+    const child = joints.findIndex((j) => j.parent === 0)
+    for (const f of local) {
+      const r = f[0], h = f[child]
+      const t = qrot(r.q, h.t)
+      f[child] = { t: [ r.t[0] + t[0], r.t[1] + t[1], r.t[2] + t[2] ], q: qmul(r.q, h.q), hasPos: true }
+    }
+    joints[child].parent = -1
+    dropped = 0
+    folded = `${joints[0].name} → ${joints[child].name}`
+  }
+
+  const doc = new Document()
+  const buffer = doc.createBuffer()
+  const scene = doc.createScene("Scene")
+  const nodes = joints.map((j, i) => i === dropped ? null : doc.createNode(j.name).setTranslation([ j.offset[0] * U, j.offset[1] * U, j.offset[2] * U ]))
+  const worldRest: Vec3[] = joints.map(() => [ 0, 0, 0 ])
+  joints.forEach((j, i) => {
+    if (i === dropped) return
+    const p = j.parent
+    const pw = p >= 0 && p !== dropped ? worldRest[p] : [ 0, 0, 0 ]
+    worldRest[i] = [ pw[0] + j.offset[0] * U, pw[1] + j.offset[1] * U, pw[2] + j.offset[2] * U ]
+    if (p >= 0 && p !== dropped) nodes[p]!.addChild(nodes[i]!); else scene.addChild(nodes[i]!)
+  })
+
+  // the skin: every non-end joint, inverse binds from the rest pose (offsets only — pure translations)
+  const armature = doc.createNode("Armature")
+  scene.addChild(armature)
+  const skin = doc.createSkin("bvh")
+  const skinJoints = joints.map((_, i) => i).filter((i) => i !== dropped && !joints[i].end)
+  const ibm = new Float32Array(skinJoints.length * 16)
+  skinJoints.forEach((ji, k) => {
+    const o = k * 16
+    ibm[o] = 1; ibm[o + 5] = 1; ibm[o + 10] = 1; ibm[o + 15] = 1
+    ibm[o + 12] = -worldRest[ji][0]; ibm[o + 13] = -worldRest[ji][1]; ibm[o + 14] = -worldRest[ji][2]
+    skin.addJoint(nodes[ji]!)
+  })
+  skin.setInverseBindMatrices(doc.createAccessor("ibm").setType("MAT4").setArray(ibm).setBuffer(buffer))
+  skin.setSkeleton(nodes[joints.findIndex((j, i) => i !== dropped && (j.parent === -1 || j.parent === dropped))]!)
+  armature.setSkin(skin)
+
+  // the clip
+  const anim = doc.createAnimation(clipName)
+  const times = new Float32Array(frames)
+  for (let f = 0; f < frames; f++) times[f] = f * frameTime
+  const timeAcc = doc.createAccessor("time").setType("SCALAR").setArray(times).setBuffer(buffer)
+  let rotationTracks = 0, translationTracks = 0
+  joints.forEach((j, i) => {
+    if (i === dropped || j.end) return
+    if (j.channels.some((c) => c.endsWith("rotation"))) {
+      const out = new Float32Array(frames * 4)
+      let prev: Quat = [ 0, 0, 0, 1 ]
+      for (let f = 0; f < frames; f++) {
+        let q = local[f][i].q
+        if (q[0] * prev[0] + q[1] * prev[1] + q[2] * prev[2] + q[3] * prev[3] < 0) q = [ -q[0], -q[1], -q[2], -q[3] ]
+        out.set(q, f * 4); prev = q
+      }
+      const s = doc.createAnimationSampler().setInput(timeAcc).setOutput(doc.createAccessor().setType("VEC4").setArray(out).setBuffer(buffer)).setInterpolation("LINEAR")
+      anim.addSampler(s).addChannel(doc.createAnimationChannel().setTargetNode(nodes[i]!).setTargetPath("rotation").setSampler(s))
+      rotationTracks++
+    }
+    if (local.some((f) => f[i].hasPos)) {
+      const out = new Float32Array(frames * 3)
+      for (let f = 0; f < frames; f++) out.set(local[f][i].t, f * 3)
+      const s = doc.createAnimationSampler().setInput(timeAcc).setOutput(doc.createAccessor().setType("VEC3").setArray(out).setBuffer(buffer)).setInterpolation("LINEAR")
+      anim.addSampler(s).addChannel(doc.createAnimationChannel().setTargetNode(nodes[i]!).setTargetPath("translation").setSampler(s))
+      translationTracks++
+    }
+  })
+
+  const hipsI = Math.max(0, joints.findIndex((j, i) => i !== dropped && (j.parent === -1 || j.parent === dropped)))
+  const hipY = local.map((f) => f[hipsI].t[1])
+  const a = local[0][hipsI].t, b = local[frames - 1][hipsI].t
+  return {
+    doc,
+    report: {
+      joints: joints.length - (dropped >= 0 ? 1 : 0), skinJoints: skinJoints.length, folded, frames, fps: 1 / frameTime, duration: frames * frameTime,
+      rotationTracks, translationTracks, hipsY: [ Math.min(...hipY), Math.max(...hipY) ], travel: Math.hypot(b[0] - a[0], b[2] - a[2]),
+    },
+  }
+}
+
+export const describeBvh = (r: BvhReport): string =>
+  `${r.joints} joints (${r.skinJoints} in the skin${r.folded ? `, ${r.folded} folded` : ""}), ${r.frames} frames @ ${r.fps.toFixed(1)} fps = ${r.duration.toFixed(2)} s · ${r.rotationTracks} rotation + ${r.translationTracks} translation tracks · hips y ${r.hipsY[0].toFixed(3)}…${r.hipsY[1].toFixed(3)} m · travel ${r.travel.toFixed(2)} m`