lecodes-assets 0.2.1 → 2.5.0

package/src/geometry.ts

@@ -0,0 +1,222 @@
+// geometry — a GLB's triangles as ONE plain vertex buffer the SDK's `Geometry` can hold
+// (`lecodes assets geometry casing.glb` → casing.geometry.json → `Geometry.load(asset(...))`).
+// Made for small debris the particle system draws per particle (shell casings, rubble, coins):
+// every mesh node's world transform is baked in, primitives are merged, and the result is what
+// `Geometry` carries — positions, normals, one UV set, uint16 indices. Materials, skins and
+// animations are dropped on purpose: the particle material is the SDK's.
+
+import type { Document, Node, Primitive } from "@gltf-transform/core"
+
+export type GeometryFile = {
+  format: "lecodes-geometry"
+  version: 1
+  /** xyz per vertex, metres, Y-up. */
+  vertices: number[]
+  /** xyz per vertex, unit length. */
+  normals: number[]
+  /** uv per vertex (zeros when the source has no TEXCOORD_0). */
+  uv: number[]
+  /** Triangle list, 3 per face, counter-clockwise front faces. */
+  indices: number[]
+  bounds: { min: [number, number, number], max: [number, number, number] }
+  /** What went in — for the reader's eyes only. */
+  source?: { file?: string, nodes: string[] }
+}
+
+export type ExtractOptions = {
+  /** Take only this node's subtree (name, exact match). Default: every mesh in the scene. */
+  node?: string
+  /** Re-origin the result: `center` = bounds centre at 0, `bottom` = footprint centre at X/Z = 0
+   *  and the lowest point at Y = 0. Default: keep the file's placement. */
+  origin?: "keep" | "center" | "bottom"
+  /** Uniform scale applied after the origin move (a casing modelled in cm → 0.01). */
+  scale?: number
+  /** Significant digits written to the file (default 6). */
+  precision?: number
+}
+
+export type ExtractReport = {
+  nodes: string[]
+  vertices: number
+  triangles: number
+  size: [number, number, number]
+  warnings: string[]
+}
+
+/** The SDK caps a Geometry's index buffer at uint16, and the particle vertex stream at ~1 M
+ *  vertices per system — a debris mesh past this is the wrong asset for the job anyway. */
+export const MAX_VERTICES = 65535
+
+type Mat4 = number[]
+
+const mul3 = (m: Mat4, x: number, y: number, z: number, w: number): [number, number, number] => [
+  m[0] * x + m[4] * y + m[8] * z + m[12] * w,
+  m[1] * x + m[5] * y + m[9] * z + m[13] * w,
+  m[2] * x + m[6] * y + m[10] * z + m[14] * w,
+]
+
+/** Inverse-transpose of the upper 3×3 (row-major 3×3 for `mulN`), null when singular. */
+const normalMatrix = (m: Mat4): number[] | null => {
+  const a = m[0], b = m[4], c = m[8], d = m[1], e = m[5], f = m[9], g = m[2], h = m[6], i = m[10]
+  const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g)
+  if (Math.abs(det) < 1e-20) return null
+  const inv = [
+    (e * i - f * h) / det, (c * h - b * i) / det, (b * f - c * e) / det,
+    (f * g - d * i) / det, (a * i - c * g) / det, (c * d - a * f) / det,
+    (d * h - e * g) / det, (b * g - a * h) / det, (a * e - b * d) / det,
+  ]
+  // transpose(inverse): n' = inv^T · n → n'[r] = Σ inv[c*3 + r] · n[c]
+  return [ inv[0], inv[3], inv[6], inv[1], inv[4], inv[7], inv[2], inv[5], inv[8] ]
+}
+
+const det3 = (m: Mat4): number =>
+  m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9]) + m[8] * (m[1] * m[6] - m[2] * m[5])
+
+const meshNodes = (doc: Document, only?: string): { nodes: Node[], missing: boolean } => {
+  const all = doc.getRoot().listNodes()
+  if (!only) return { nodes: all.filter((n) => n.getMesh()), missing: false }
+  const root = all.find((n) => n.getName() === only)
+  if (!root) return { nodes: [], missing: true }
+  const out: Node[] = []
+  root.traverse((n) => { if (n.getMesh()) out.push(n) })
+  return { nodes: out, missing: false }
+}
+
+const round = (v: number, precision: number): number => {
+  const r = Number(v.toPrecision(precision))
+  return r === 0 ? 0 : r    // no "-0" in the file
+}
+
+/** Smooth, area-weighted vertex normals for a primitive that ships none. */
+const computeNormals = (pos: Float32Array, idx: Uint32Array): Float32Array => {
+  const n = new Float32Array(pos.length)
+  for (let t = 0; t < idx.length; t += 3) {
+    const a = idx[t] * 3, b = idx[t + 1] * 3, c = idx[t + 2] * 3
+    const ux = pos[b] - pos[a], uy = pos[b + 1] - pos[a + 1], uz = pos[b + 2] - pos[a + 2]
+    const vx = pos[c] - pos[a], vy = pos[c + 1] - pos[a + 1], vz = pos[c + 2] - pos[a + 2]
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx
+    for (const k of [ a, b, c ]) { n[k] += nx; n[k + 1] += ny; n[k + 2] += nz }
+  }
+  for (let i = 0; i < n.length; i += 3) {
+    const l = Math.hypot(n[i], n[i + 1], n[i + 2]) || 1
+    n[i] /= l; n[i + 1] /= l; n[i + 2] /= l
+  }
+  return n
+}
+
+const primitiveIndices = (prim: Primitive, count: number): Uint32Array => {
+  const acc = prim.getIndices()
+  if (acc) return Uint32Array.from(acc.getArray() as ArrayLike<number>)
+  const seq = new Uint32Array(count)
+  for (let i = 0; i < count; i++) seq[i] = i
+  return seq
+}
+
+/** The merged, world-space triangle buffer of `doc` (or of one node's subtree). */
+export const extractGeometry = (doc: Document, opts: ExtractOptions = {}): { data: GeometryFile, report: ExtractReport } => {
+  const precision = opts.precision ?? 6
+  const warnings: string[] = []
+  const { nodes, missing } = meshNodes(doc, opts.node)
+  if (missing) throw new Error(`no node "${opts.node}" in the file (--list-nodes prints them)`)
+  if (nodes.length === 0) throw new Error(opts.node ? `node "${opts.node}" has no mesh` : "the file has no mesh")
+
+  const V: number[] = [], N: number[] = [], UV: number[] = [], I: number[] = []
+  const used: string[] = []
+  for (const node of nodes) {
+    const mesh = node.getMesh()!
+    const world = Array.from(node.getWorldMatrix()) as Mat4
+    const nm = normalMatrix(world)
+    if (!nm) { warnings.push(`${node.getName() || "(unnamed)"}: zero-scale transform, skipped`); continue }
+    const flip = det3(world) < 0
+    if (node.getSkin()) warnings.push(`${node.getName() || "(unnamed)"}: skinned — baked in its bind pose`)
+    let took = false
+    for (const prim of mesh.listPrimitives()) {
+      const mode = prim.getMode()
+      if (mode !== 4) { warnings.push(`${node.getName() || "(unnamed)"}: primitive mode ${mode} (not TRIANGLES) skipped`); continue }
+      const posAcc = prim.getAttribute("POSITION")
+      if (!posAcc) continue
+      const pos = Float32Array.from(posAcc.getArray() as ArrayLike<number>)
+      const count = pos.length / 3
+      const idx = primitiveIndices(prim, count)
+      const nrmAcc = prim.getAttribute("NORMAL")
+      const nrm = nrmAcc ? Float32Array.from(nrmAcc.getArray() as ArrayLike<number>) : computeNormals(pos, idx)
+      const uvAcc = prim.getAttribute("TEXCOORD_0")
+      const uv = uvAcc ? Float32Array.from(uvAcc.getArray() as ArrayLike<number>) : new Float32Array(count * 2)
+      if (uvAcc && uvAcc.getNormalized()) warnings.push(`${node.getName() || "(unnamed)"}: TEXCOORD_0 is a normalized integer set, read as floats`)
+      const base = V.length / 3
+      for (let i = 0; i < count; i++) {
+        const p = mul3(world, pos[i * 3], pos[i * 3 + 1], pos[i * 3 + 2], 1)
+        V.push(p[0], p[1], p[2])
+        const nx = nrm[i * 3], ny = nrm[i * 3 + 1], nz = nrm[i * 3 + 2]
+        let tx = nm[0] * nx + nm[1] * ny + nm[2] * nz
+        let ty = nm[3] * nx + nm[4] * ny + nm[5] * nz
+        let tz = nm[6] * nx + nm[7] * ny + nm[8] * nz
+        const l = Math.hypot(tx, ty, tz) || 1
+        tx /= l; ty /= l; tz /= l
+        N.push(tx, ty, tz)
+        UV.push(uv[i * 2], uv[i * 2 + 1])
+      }
+      for (let t = 0; t < idx.length; t += 3) {
+        // a mirrored transform turns the winding inside out — swap two corners to keep front faces
+        if (flip) I.push(base + idx[t], base + idx[t + 2], base + idx[t + 1])
+        else I.push(base + idx[t], base + idx[t + 1], base + idx[t + 2])
+      }
+      took = true
+    }
+    if (took) used.push(node.getName() || "(unnamed)")
+  }
+  const vertexCount = V.length / 3
+  if (vertexCount === 0) throw new Error("no triangles to take")
+  if (vertexCount > MAX_VERTICES) throw new Error(`${vertexCount} vertices — a Geometry holds at most ${MAX_VERTICES} (uint16 indices). Pick one node (--node) or decimate the asset first`)
+
+  // origin + scale, then bounds
+  const min: [number, number, number] = [ Infinity, Infinity, Infinity ], max: [number, number, number] = [ -Infinity, -Infinity, -Infinity ]
+  const bounds = (): void => {
+    min.fill(Infinity); max.fill(-Infinity)
+    for (let i = 0; i < V.length; i += 3) for (let k = 0; k < 3; k++) { min[k] = Math.min(min[k], V[i + k]); max[k] = Math.max(max[k], V[i + k]) }
+  }
+  bounds()
+  const origin = opts.origin ?? "keep"
+  if (origin !== "keep") {
+    const dx = (min[0] + max[0]) / 2, dz = (min[2] + max[2]) / 2
+    const dy = origin === "center" ? (min[1] + max[1]) / 2 : min[1]
+    for (let i = 0; i < V.length; i += 3) { V[i] -= dx; V[i + 1] -= dy; V[i + 2] -= dz }
+  }
+  const scale = opts.scale ?? 1
+  if (scale !== 1) for (let i = 0; i < V.length; i++) V[i] *= scale
+  bounds()
+
+  const data: GeometryFile = {
+    format: "lecodes-geometry",
+    version: 1,
+    vertices: V.map((v) => round(v, precision)),
+    normals: N.map((v) => round(v, 4)),
+    uv: UV.map((v) => round(v, precision)),
+    indices: I,
+    bounds: { min: min.map((v) => round(v, precision)) as typeof min, max: max.map((v) => round(v, precision)) as typeof max },
+    source: { nodes: used },
+  }
+  const report: ExtractReport = {
+    nodes: used, vertices: vertexCount, triangles: I.length / 3,
+    size: [ max[0] - min[0], max[1] - min[1], max[2] - min[2] ], warnings,
+  }
+  return { data, report }
+}
+
+/** Compact JSON: one number list per line, so the file diffs and reads like an asset, not a dump. */
+export const formatGeometryFile = (g: GeometryFile): string => {
+  const list = (a: number[]): string => `[${a.join(",")}]`
+  return [
+    "{",
+    `  "format": ${JSON.stringify(g.format)},`,
+    `  "version": ${g.version},`,
+    `  "bounds": ${JSON.stringify(g.bounds)},`,
+    ...(g.source ? [ `  "source": ${JSON.stringify(g.source)},` ] : []),
+    `  "vertices": ${list(g.vertices)},`,
+    `  "normals": ${list(g.normals)},`,
+    `  "uv": ${list(g.uv)},`,
+    `  "indices": ${list(g.indices)}`,
+    "}",
+    "",
+  ].join("\n")
+}

package/src/index.ts

@@ -6,6 +6,8 @@ export { convertFbx, mergeClipScene, writeGlb, makeIO, type ConvertOptions, type
 export { probeFile, probeFbx, probeDocument } from "./probe"
 export { analyzeDoc, applyPlan, reportPlan, dumpTextures, type DoctorPlan, type DoctorOptions } from "./doctor/doctor"
 export { validateGlb, formatReport } from "./doctor/validateGlb"
+export { unwrapGlbFile, unwrapGlbFiles, unwrapDocument, planUnwrap, applyUnwrap, type UnwrapOptions, type UnwrapFileOptions, type UnwrapFileReport, type UnwrapResult } from "./unwrap"
+export { planMerge, applyMerge, findKtxTool, type MergeOptions, type MergePlan, type MergeResult } from "./doctor/merge"
 export { measureScale, applyScale, sceneBounds, type ScaleInfo } from "./doctor/normalizeScale"
 export { loadRig, rigFromFbx, rigFromDocument, checkUniformScale, type Rig, type DocRig } from "./retarget/rig"
 export { retarget, analyzeFacing, facingMismatch, bindAccessors, type BoneMap, type RetargetOptions, type RetargetReport, type AlignPolicy, type DonorRef, type LegReport, type ClipContacts, type ContactSpan, type RetargetEvent } from "./retarget/retarget"