lecodes-assets 0.2.1 → 2.4.10

package/src/doctor/vertexAo.ts

@@ -0,0 +1,321 @@
+// VERTEX AMBIENT OCCLUSION FOR VEGETATION — the sky's visibility from every vertex of a plant, baked into
+// COLOR_0.r at import (what SpeedTree bakes for its trees, and the one thing that makes a crown read as
+// a volume instead of a heap of green cards: the leaves deep inside take less sky than the ones on the
+// outside, and the trunk under the crown stands in its shade).
+//
+// The convention the vegetation tier reads (creator-gl materials/src/foliage.mat):
+//   COLOR_0 = (ao, cavity, 1, wind)   ao      = sky visibility 0..1 (cosine-weighted upper hemisphere, WORLD up)
+//                                     cavity  = the bark's short-range occlusion 0..1 (the hemisphere of its own normal,
+//                                               hits within `cavity` metres: limb joints, the trunk under a limb); cards 1
+//                                     wind    = the per-vertex wind weight — the pack's own (COLOR_0.a as it came)
+//                                               or, for a mesh without one, the height over the plant squared
+// An exact white (1, 1, 1, 1) is what gltfio hands a mesh WITHOUT a colour set, and the shader takes that
+// as "no data" (ao 1, height weight) — a vertex whose ao AND wind both round to 1 lands there too, and it
+// is exactly the vertex nothing changes for.
+//
+// Occluders = every triangle of the asset's level-0 meshes (`_LOD<n>` n ≥ 1 are copies of the same
+// plant), cards counted opaque — a coarse hit for an alpha-cutout leaf, which over-darkens a little and
+// is what the shader's strength knob is for. A BVH over the triangles, `rays` cosine-weighted rays per
+// vertex from a fixed sequence rotated per vertex, rays start `bias` metres off the surface.
+
+import type { Document, Primitive } from "@gltf-transform/core"
+
+type Tri = { ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number }
+type BvhNode = { min: [number, number, number], max: [number, number, number], left: number, right: number, first: number, count: number }
+
+const buildBvh = (tris: Tri[]): { nodes: BvhNode[], order: number[] } => {
+  const order = tris.map((_, i) => i)
+  const nodes: BvhNode[] = []
+  const cx = (t: Tri): number => (t.ax + t.bx + t.cx) / 3, cy = (t: Tri): number => (t.ay + t.by + t.cy) / 3, cz = (t: Tri): number => (t.az + t.bz + t.cz) / 3
+  const build = (first: number, count: number): number => {
+    const min: [number, number, number] = [ Infinity, Infinity, Infinity ], max: [number, number, number] = [ -Infinity, -Infinity, -Infinity ]
+    for (let i = first; i < first + count; i++) {
+      const t = tris[order[i]]
+      min[0] = Math.min(min[0], t.ax, t.bx, t.cx); min[1] = Math.min(min[1], t.ay, t.by, t.cy); min[2] = Math.min(min[2], t.az, t.bz, t.cz)
+      max[0] = Math.max(max[0], t.ax, t.bx, t.cx); max[1] = Math.max(max[1], t.ay, t.by, t.cy); max[2] = Math.max(max[2], t.az, t.bz, t.cz)
+    }
+    const id = nodes.length
+    nodes.push({ min, max, left: -1, right: -1, first, count })
+    if (count <= 8) return id
+    const ext = [ max[0] - min[0], max[1] - min[1], max[2] - min[2] ]
+    const axis = ext[0] >= ext[1] && ext[0] >= ext[2] ? 0 : ext[1] >= ext[2] ? 1 : 2
+    const key = axis === 0 ? cx : axis === 1 ? cy : cz
+    const slice = order.slice(first, first + count).sort((a, b) => key(tris[a]) - key(tris[b]))
+    for (let i = 0; i < count; i++) order[first + i] = slice[i]
+    const half = count >> 1
+    const n = nodes[id]
+    n.count = 0
+    n.left = build(first, half)
+    n.right = build(first + half, count - half)
+    return id
+  }
+  if (tris.length) build(0, tris.length)
+  return { nodes, order }
+}
+
+/** Möller–Trumbore, both sides: the hit distance in (tmin, tmax), or -1. */
+const triDist = (t: Tri, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): number => {
+  const e1x = t.bx - t.ax, e1y = t.by - t.ay, e1z = t.bz - t.az
+  const e2x = t.cx - t.ax, e2y = t.cy - t.ay, e2z = t.cz - t.az
+  const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x
+  const det = e1x * px + e1y * py + e1z * pz
+  if (Math.abs(det) < 1e-9) return -1
+  const inv = 1 / det
+  const tx = ox - t.ax, ty = oy - t.ay, tz = oz - t.az
+  const u = (tx * px + ty * py + tz * pz) * inv
+  if (u < 0 || u > 1) return -1
+  const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x
+  const v = (dx * qx + dy * qy + dz * qz) * inv
+  if (v < 0 || u + v > 1) return -1
+  const d = (e2x * qx + e2y * qy + e2z * qz) * inv
+  return d > tmin && d < tmax ? d : -1
+}
+const hitTri = (t: Tri, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): boolean =>
+  triDist(t, ox, oy, oz, dx, dy, dz, tmin, tmax) >= 0
+
+const hitBox = (n: BvhNode, ox: number, oy: number, oz: number, ix: number, iy: number, iz: number, tmax: number): boolean => {
+  let t0 = 0, t1 = tmax
+  const a = (n.min[0] - ox) * ix, b = (n.max[0] - ox) * ix; t0 = Math.max(t0, Math.min(a, b)); t1 = Math.min(t1, Math.max(a, b))
+  const c = (n.min[1] - oy) * iy, d = (n.max[1] - oy) * iy; t0 = Math.max(t0, Math.min(c, d)); t1 = Math.min(t1, Math.max(c, d))
+  const e = (n.min[2] - oz) * iz, f = (n.max[2] - oz) * iz; t0 = Math.max(t0, Math.min(e, f)); t1 = Math.min(t1, Math.max(e, f))
+  return t1 >= t0
+}
+
+const occluded = (bvh: { nodes: BvhNode[], order: number[] }, tris: Tri[], ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): boolean => {
+  if (!bvh.nodes.length) return false
+  const ix = 1 / (dx || 1e-12), iy = 1 / (dy || 1e-12), iz = 1 / (dz || 1e-12)
+  const stack = [ 0 ]
+  while (stack.length) {
+    const n = bvh.nodes[stack.pop()!]
+    if (!hitBox(n, ox, oy, oz, ix, iy, iz, tmax)) continue
+    if (n.left < 0) {
+      for (let i = n.first; i < n.first + n.count; i++) if (hitTri(tris[bvh.order[i]], ox, oy, oz, dx, dy, dz, tmin, tmax)) return true
+    } else { stack.push(n.left, n.right) }
+  }
+  return false
+}
+
+/** The nearest hit along the ray in (tmin, tmax), or Infinity. */
+const nearestHit = (bvh: { nodes: BvhNode[], order: number[] }, tris: Tri[], ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tmin: number, tmax: number): number => {
+  let best = Infinity
+  if (!bvh.nodes.length) return best
+  const ix = 1 / (dx || 1e-12), iy = 1 / (dy || 1e-12), iz = 1 / (dz || 1e-12)
+  const stack = [ 0 ]
+  while (stack.length) {
+    const n = bvh.nodes[stack.pop()!]
+    if (!hitBox(n, ox, oy, oz, ix, iy, iz, Math.min(tmax, best))) continue
+    if (n.left < 0) {
+      for (let i = n.first; i < n.first + n.count; i++) {
+        const d = triDist(tris[bvh.order[i]], ox, oy, oz, dx, dy, dz, tmin, Math.min(tmax, best))
+        if (d >= 0 && d < best) best = d
+      }
+    } else { stack.push(n.left, n.right) }
+  }
+  return best
+}
+
+export type VertexAoOptions = {
+  /** Rays per vertex (default 48). */
+  rays?: number
+  /** Metres a ray starts off its vertex (default 0.02). */
+  bias?: number
+  /** Metres a ray travels (default: the asset's extent). */
+  maxDistance?: number
+  /** CAVITY (junction) occlusion for the OPAQUE primitives — the bark: `cavityRays` cosine-weighted rays in the
+   *  hemisphere of the vertex' own normal, a hit within `cavity` metres counts by (1 - distance / cavity) → COLOR_0.g,
+   *  1 = open. The base of a limb and the trunk around it darken, the joint reads as grown, not laid on. Leaf cards
+   *  keep 1 (their own neighbours would darken every crown). Default 0.8 m, 0 = off. */
+  cavity?: number
+  /** Rays per vertex for the cavity term (default 24). */
+  cavityRays?: number
+  /** CANOPY NORMALS: how far the normals of the alpha-MASK primitives (the leaf cards) are bent toward the
+   *  direction from the crown's centre — 0 keeps the cards' own (each card lit as a flat plane: a heap of
+   *  cut-outs), 1 makes the crown shade like one sphere. Default 0.6 — what a tree tool bakes. */
+  canopy?: number
+}
+
+const LOD_RE = /_LOD([1-9]\d*)$/i
+
+/** World-space triangles of every level-0 mesh node. */
+const collectOccluders = (doc: Document): { tris: Tri[], min: [number, number, number], max: [number, number, number] } => {
+  const tris: Tri[] = []
+  const min: [number, number, number] = [ Infinity, Infinity, Infinity ], max: [number, number, number] = [ -Infinity, -Infinity, -Infinity ]
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh || LOD_RE.test(node.getName())) continue
+    const m = node.getWorldMatrix()
+    for (const p of mesh.listPrimitives()) {
+      const pos = p.getAttribute("POSITION"), idx = p.getIndices()
+      if (!pos || p.getMode() !== 4) continue
+      const n = idx ? idx.getCount() : pos.getCount()
+      const v: number[] = []
+      const at = (k: number): [number, number, number] => {
+        pos.getElement(idx ? idx.getScalar(k) : k, v)
+        const x = m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12], y = m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13], z = m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]
+        min[0] = Math.min(min[0], x); min[1] = Math.min(min[1], y); min[2] = Math.min(min[2], z)
+        max[0] = Math.max(max[0], x); max[1] = Math.max(max[1], y); max[2] = Math.max(max[2], z)
+        return [ x, y, z ]
+      }
+      for (let k = 0; k + 2 < n; k += 3) {
+        const a = at(k), b = at(k + 1), c = at(k + 2)
+        tris.push({ ax: a[0], ay: a[1], az: a[2], bx: b[0], by: b[1], bz: b[2], cx: c[0], cy: c[1], cz: c[2] })
+      }
+    }
+  }
+  return { tris, min, max }
+}
+
+/** Cosine-weighted directions on the upper hemisphere (world +Y), a fixed Fibonacci set. */
+const skyRays = (count: number): [number, number, number][] => {
+  const out: [number, number, number][] = []
+  const golden = Math.PI * (3 - Math.sqrt(5))
+  for (let i = 0; i < count; i++) {
+    const u = (i + 0.5) / count                 // cosine-weighted: y = sqrt(1 - u) puts more rays near the zenith
+    const y = Math.sqrt(1 - u), r = Math.sqrt(u), phi = i * golden
+    out.push([ r * Math.cos(phi), y, r * Math.sin(phi) ])
+  }
+  return out
+}
+
+/**
+ * Bake the sky visibility of every vertex of the document's meshes into COLOR_0 as (ao, 1, 1, wind) — see the
+ * header. Returns the number of vertices written and the mean ao (a plant reads ~0.5–0.7).
+ */
+export const bakeVertexAo = (doc: Document, opts: VertexAoOptions = {}): { vertices: number, meanAo: number } => {
+  const { tris, min, max } = collectOccluders(doc)
+  if (!tris.length) return { vertices: 0, meanAo: 1 }
+  const bvh = buildBvh(tris)
+  const rays = skyRays(opts.rays ?? 48)
+  const bias = opts.bias ?? 0.02
+  const reach = opts.maxDistance ?? Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2])
+  const cavReach = Math.max(opts.cavity ?? 0.8, 0)
+  const cavRays = skyRays(opts.cavityRays ?? 24)
+  const height = Math.max(max[1] - min[1], 0.05)
+  let vertices = 0, sum = 0
+  const done = new Set<Primitive>()
+  // the crown: the centre of every leaf card's vertices (world), what the canopy normals point away from
+  const canopy = Math.min(Math.max(opts.canopy ?? 0.6, 0), 1)
+  const crown = [ 0, 0, 0 ]
+  let crownN = 0
+  if (canopy > 0) {
+    for (const node of doc.getRoot().listNodes()) {
+      const mesh = node.getMesh()
+      if (!mesh || LOD_RE.test(node.getName())) continue
+      const m = node.getWorldMatrix()
+      for (const p of mesh.listPrimitives()) {
+        if (p.getMaterial()?.getAlphaMode() !== "MASK") continue
+        const pos = p.getAttribute("POSITION"); if (!pos) continue
+        const v: number[] = []
+        for (let i = 0; i < pos.getCount(); i++) { pos.getElement(i, v); crown[0] += m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12]; crown[1] += m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13]; crown[2] += m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]; crownN++ }
+      }
+    }
+    if (crownN) { crown[0] /= crownN; crown[1] /= crownN; crown[2] /= crownN }
+  }
+  for (const node of doc.getRoot().listNodes()) {
+    const mesh = node.getMesh()
+    if (!mesh) continue
+    const m = node.getWorldMatrix()
+    for (const p of mesh.listPrimitives()) {
+      if (done.has(p)) continue
+      done.add(p)
+      const pos = p.getAttribute("POSITION")
+      if (!pos) continue
+      const n = pos.getCount()
+      // canopy normals on the leaf cards: the card's normal blended toward "away from the crown's centre" (in the
+      // node's frame: the crown centre pulled back through the inverse world matrix, rotation-only for the normal)
+      const nrm = p.getAttribute("NORMAL")
+      if (canopy > 0 && crownN && nrm && p.getMaterial()?.getAlphaMode() === "MASK") {
+        const inv = invert4(m)
+        const cl = inv ? [ inv[0] * crown[0] + inv[4] * crown[1] + inv[8] * crown[2] + inv[12], inv[1] * crown[0] + inv[5] * crown[1] + inv[9] * crown[2] + inv[13], inv[2] * crown[0] + inv[6] * crown[1] + inv[10] * crown[2] + inv[14] ] : null
+        if (cl) {
+          const out = new Float32Array(new ArrayBuffer(n * 12)), v: number[] = [], q: number[] = []
+          for (let i = 0; i < n; i++) {
+            pos.getElement(i, v); nrm.getElement(i, q)
+            let dx = v[0] - cl[0], dy = v[1] - cl[1], dz = v[2] - cl[2]
+            const l = Math.hypot(dx, dy, dz) || 1
+            dx /= l; dy /= l; dz /= l
+            // a card facing the wrong way is flipped into the hemisphere of its radial first (double-sided cards
+            // have no side of their own), then blended
+            const flip = q[0] * dx + q[1] * dy + q[2] * dz < 0 ? -1 : 1
+            let nx = q[0] * flip * (1 - canopy) + dx * canopy, ny = q[1] * flip * (1 - canopy) + dy * canopy, nz = q[2] * flip * (1 - canopy) + dz * canopy
+            const nl = Math.hypot(nx, ny, nz) || 1
+            out[i * 3] = nx / nl; out[i * 3 + 1] = ny / nl; out[i * 3 + 2] = nz / nl
+          }
+          p.setAttribute("NORMAL", doc.createAccessor().setType("VEC3").setArray(out).setBuffer(doc.getRoot().listBuffers()[0] ?? doc.createBuffer()))
+          if (nrm.listParents().length <= 1) nrm.dispose()
+        }
+      }
+      const old = p.getAttribute("COLOR_0")
+      const oldEl = old ? old.getElementSize() : 0
+      const out = new Float32Array(new ArrayBuffer(n * 16))
+      const v: number[] = [], c: number[] = [], q: number[] = []
+      // the cavity term: the bark (opaque) with a normal, rays in the hemisphere of the vertex' world normal
+      const cavNrm = cavReach > 0 && p.getMaterial()?.getAlphaMode() !== "MASK" ? p.getAttribute("NORMAL") : null
+      for (let i = 0; i < n; i++) {
+        pos.getElement(i, v)
+        const x = m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12], y = m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13], z = m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]
+        // a per-vertex rotation of the fixed set about +Y, so neighbours never share a banding pattern
+        const rot = ((x * 12.9898 + z * 78.233 + y * 37.719) % 1 + 1) % 1 * Math.PI * 2, cr = Math.cos(rot), sr = Math.sin(rot)
+        let open = 0
+        for (const d of rays) {
+          const dx = d[0] * cr - d[2] * sr, dz = d[0] * sr + d[2] * cr
+          if (!occluded(bvh, tris, x + dx * bias, y + d[1] * bias, z + dz * bias, dx, d[1], dz, 0, reach)) open++
+        }
+        const ao = open / rays.length
+        let cav = 1
+        if (cavNrm) {
+          nrmOf(cavNrm, i, m, q)
+          // a tangent frame about the normal: the +Y ray set turned into it, and the per-vertex rotation kept
+          const ax = Math.abs(q[1]) < 0.9 ? 0 : 1, ay = ax ? 0 : 1
+          let tx = ay * q[2] - 0, ty = 0 - ax * q[2], tz = ax * q[1] - ay * q[0]      // cross(n, a) for a = (ax, ay, 0)
+          const tl = Math.hypot(tx, ty, tz) || 1; tx /= tl; ty /= tl; tz /= tl
+          const bx = q[1] * tz - q[2] * ty, by = q[2] * tx - q[0] * tz, bz = q[0] * ty - q[1] * tx   // cross(n, t)
+          let occ = 0
+          for (const d of cavRays) {
+            const rx = d[0] * cr - d[2] * sr, rz = d[0] * sr + d[2] * cr
+            const dx = tx * rx + q[0] * d[1] + bx * rz, dy = ty * rx + q[1] * d[1] + by * rz, dz = tz * rx + q[2] * d[1] + bz * rz
+            // the origin is lifted off the vertex' OWN surface along its normal only, and a hit at distance 0 counts: a limb's
+            // base vertex lies ON the trunk, and the rays into the trunk meet its surface right there - that IS the joint
+            const h = nearestHit(bvh, tris, x + q[0] * bias, y + q[1] * bias, z + q[2] * bias, dx, dy, dz, -1e-6, cavReach)
+            if (h < cavReach) occ += 1 - h / cavReach
+          }
+          cav = 1 - occ / cavRays.length
+        }
+        // the wind weight: the pack's own (its alpha, as it came) or the height over the plant, squared
+        let wind: number
+        if (old && oldEl === 4) { old.getElement(i, c); wind = c[3] } else { const h = Math.min(Math.max((y - min[1]) / height, 0), 1); wind = h * h }
+        out[i * 4] = ao; out[i * 4 + 1] = cav; out[i * 4 + 2] = 1; out[i * 4 + 3] = wind
+        sum += ao; vertices++
+      }
+      const acc = doc.createAccessor().setType("VEC4").setArray(out).setBuffer(doc.getRoot().listBuffers()[0] ?? doc.createBuffer())
+      p.setAttribute("COLOR_0", acc)
+      if (old && old.listParents().length <= 1) old.dispose()
+    }
+  }
+  return { vertices, meanAo: vertices ? sum / vertices : 1 }
+}
+
+/** The vertex' normal in world space (the node's rotation part, then normalised), into `q`. */
+const nrmOf = (nrm: { getElement(i: number, out: number[]): number[] }, i: number, m: ArrayLike<number>, q: number[]): void => {
+  nrm.getElement(i, q)
+  const x = m[0] * q[0] + m[4] * q[1] + m[8] * q[2], y = m[1] * q[0] + m[5] * q[1] + m[9] * q[2], z = m[2] * q[0] + m[6] * q[1] + m[10] * q[2]
+  const l = Math.hypot(x, y, z) || 1
+  q[0] = x / l; q[1] = y / l; q[2] = z / l
+}
+
+/** 4×4 column-major inverse (null when singular). */
+const invert4 = (m: ArrayLike<number>): number[] | null => {
+  const a = Array.from(m), r = new Array<number>(16)
+  const [ a00, a01, a02, a03, a10, a11, a12, a13, a20, a21, a22, a23, a30, a31, a32, a33 ] = a
+  const b00 = a00 * a11 - a01 * a10, b01 = a00 * a12 - a02 * a10, b02 = a00 * a13 - a03 * a10, b03 = a01 * a12 - a02 * a11
+  const b04 = a01 * a13 - a03 * a11, b05 = a02 * a13 - a03 * a12, b06 = a20 * a31 - a21 * a30, b07 = a20 * a32 - a22 * a30
+  const b08 = a20 * a33 - a23 * a30, b09 = a21 * a32 - a22 * a31, b10 = a21 * a33 - a23 * a31, b11 = a22 * a33 - a23 * a32
+  let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06
+  if (Math.abs(det) < 1e-12) return null
+  det = 1 / det
+  r[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det; r[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det; r[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det; r[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det
+  r[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det; r[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det; r[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det; r[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det
+  r[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det; r[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det; r[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det; r[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det
+  r[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det; r[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det; r[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det; r[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det
+  return r
+}

package/src/fbx/read.ts

@@ -22,6 +22,8 @@ export type FbxPrimitive = {
   vertexCount: number
   indexCount: number
   pos: number; nrm: number; uv: number; col: number; joints: number; weights: number; indices: number
+  /** UV sets 1..3 (Unity uv2 / uv3 / uv4) — a pack's detail layer lives there; -1 when the mesh has none. */
+  uv1: number; uv2: number; uv3: number
   min: [number, number, number]
   max: [number, number, number]
 }