lecodes-assets 2.5.1 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-assets",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "LeCodes asset pipeline: FBX → GLB (ufbx), clip merging by bone name, texture embedding, GLB doctor (bone cap, texture normalize, KTX2).",
   "type": "module",
   "bin": {

package/src/commands/doctor.ts

@@ -17,6 +17,7 @@ export default defineCommand({
     "lod-bones": bool("fold fingers / toes / twists onto their parents in the last level's skin"),
     impostor: str("bake the level-0 geometry into an impostor atlas (albedo + hull normal / AO) and add it as a LOD level, one camera-facing quad (<name>_LOD<k>, k = --impostor-level, never past the first missing level; the levels from k up are replaced). PNG / JPEG base colours only — run it with --ktx2, not after it; the atlases skip --max-size. <A>x<E>[@<px>] = A azimuths × E elevation rows (0°, 90°/E, …; 8x2@256), oct<N>[@<px>] = the N×N hemi-octahedron (steep views too); bare = 12x3; px = a frame's pixels (default 256 for a plant ≥ 8 m, 128 under)", { value: "<A>x<E>[@px]|oct<N>[@px]", bare: "12x3" }),
     "impostor-level": int("the LOD slot the quad takes (default 2: shown under 0.12 of the viewport height; 1 = under 0.30)"),
+    "impostor-samples": int("the impostor bake's supersamples a texel's side, S: S×S samples (default 8: 5.3 s for a 16 m pine against 2.1 s at 4) - the coverage is covered / S², a porous crown's holes kept as a fraction the engine's mask cuts (alphaToCoverage takes it under MSAA)"),
   },
   examples: [
     "lecodes assets doctor hero.glb",
@@ -31,7 +32,7 @@ export default defineCommand({
     const { validateGlb, formatReport } = await import("../doctor/validateGlb")
     const useKtx2 = wantsKtx2(flags)
     const lod = (flags.lod ?? "").split(",").map(Number).filter((n) => n > 0 && n < 1)
-    const impostor = impostorFlag(flags.impostor, flags["impostor-level"])
+    const impostor = impostorFlag(flags.impostor, flags["impostor-level"], flags["impostor-samples"])
     const doFix = wantsDoctorFix(flags) || flags["fix-metallic"] || lod.length > 0 || !!impostor
     const opts = { ...doctorOptions(flags), lod, lodBones: flags["lod-bones"] }
     const ktxEncoder = useKtx2 ? findKtxEncoder() : null

package/src/commands/scene.ts

@@ -50,6 +50,7 @@ export default defineCommand({
     "max-tris": int("triangles a kind may have before the import simplifies it (default 50000, 0 = no cap): a photogrammetry scan otherwise arrives as a million-triangle prop AND mesh collider"),
     impostor: str("foliage kinds ≥ 4 m tall get their far LOD level as ONE camera-facing quad over an atlas of views (albedo + hull normal / AO), replacing the pack's billboard; the atlases skip --max-size. <A>x<E>[@<px>] = A azimuths × E elevation rows (0°, 90°/E, …; 8x2@256), oct<N>[@<px>] = the N×N hemi-octahedron (steep views too); bare = 12x3; px = a frame's pixels (default 256 for a plant ≥ 8 m, 128 under)", { value: "<A>x<E>[@px]|oct<N>[@px]", bare: "12x3" }),
     "impostor-level": int("the LOD slot the quad takes (default 2: shown under 0.12 of the viewport height; 1 = under 0.30, the pack's LOD1 goes; never past the first missing level)"),
+    "impostor-samples": int("the impostor bake's supersamples a texel's side, S: S×S samples (default 8: 5.3 s for a 16 m pine against 2.1 s at 4) - the coverage is covered / S², a porous crown's holes kept as a fraction the engine's mask cuts (alphaToCoverage takes it under MSAA)"),
     "no-trim-cards": bool("skip the alpha-card trim the import otherwise runs (it can empty a kind whose decal atlas is mostly clear)"),
     filter: str("keep only instances whose kind name / scene group / node name matches", { value: "<re>", group: "Subset" }),
     "drop-at": str(`leave OUT the placements standing at these points ("x,y,z;x,y,z", the lecodes frame the scene file prints, within 10 cm): the one instance of a kind the game moves while its twins stay put — the range's five lane targets, which Unity names like the sixth on a shelf`, { value: "<x,y,z;…>" }),
@@ -89,7 +90,7 @@ export default defineCommand({
         project: flags.project, name: flags.name, force: flags.force, maxSize: flags["max-size"] ?? 1024, ktx2: !flags.png, log,
         foliage: regexFlag(flags.foliage), noFoliage: flags["no-foliage"], noSun: flags["no-sun"],
         noLightmap: regexFlag(flags["no-lightmap"]), noTrimCards: flags["no-trim-cards"], colliderFit: flags["collider-fit"], noColliders: flags["no-colliders"], noShadows: regexFlag(flags["no-shadows"]), maxTris: flags["max-tris"],
-        impostor: impostorFlag(flags.impostor, flags["impostor-level"]),
+        impostor: impostorFlag(flags.impostor, flags["impostor-level"], flags["impostor-samples"]),
         terrainRes: flags["terrain-res"] ?? 1025,
         // the invocation, for the scene file's header (quote what a shell would need quoted)
         command: "lecodes assets scene " + argv.map((a) => (/[\s"'|<>^&();]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" "),

package/src/commands/shared.ts

@@ -120,9 +120,10 @@ export const resolveInputs = (args: string[], ext = /\.glb$/i, skipGenerated = t
 /** `--impostor <A>x<E>[@<px>]` (the grid of A azimuths × E elevation rows: "12x3", "8x2@256") or `oct<N>[@<px>]` (the
  *  hemi-octahedron: "oct8", "oct8@128"), bare = 12x3, + `--impostor-level` → the bake's options (rows 0 = the
  *  octahedron, cols = N), or undefined when absent. */
-export const impostorFlag = (v: string | undefined, level?: number): { cols: number, rows: number, px?: number, level?: number } | undefined => {
+export const impostorFlag = (v: string | undefined, level?: number, samples?: number): { cols: number, rows: number, px?: number, level?: number, samples?: number } | undefined => {
   if (v === undefined) return undefined
   if (level !== undefined && (!Number.isInteger(level) || level < 1 || level > 3)) throw usageError(`--impostor-level wants 1, 2 or 3 — got "${level}"`)
+  if (samples !== undefined && (!Number.isInteger(samples) || samples < 1 || samples > 16)) throw usageError(`--impostor-samples wants 1..16 — got "${samples}"`)
   const s = v.trim() || "12x3"
   const bad = (why: string): Error => usageError(`--impostor wants <A>x<E>[@<px>] (azimuths ≥ 3, rows 1..8) or oct<N>[@<px>] (N 2..64), px 32..1024 a multiple of 4 — e.g. 12x3, 8x2@256, oct8@128 — got "${v}" (${why})`)
   const grid = /^(\d+)x(\d+)(?:@(\d+))?$/i.exec(s), oct = /^oct(\d+)(?:@(\d+))?$/i.exec(s)
@@ -133,7 +134,7 @@ export const impostorFlag = (v: string | undefined, level?: number): { cols: num
   if (grid && (rows < 1 || rows > 8)) throw bad("rows 1..8")
   if (oct && (cols < 2 || cols > 64)) throw bad("N 2..64")
   if (px !== undefined && (px < 32 || px > 1024 || px % 4 !== 0)) throw bad("px 32..1024, a multiple of 4")
-  return { cols, rows, px, level }
+  return { cols, rows, px, level, samples }
 }
 
 /** `--x <regex>` as a case-insensitive RegExp, or undefined. */

package/src/doctor/cardTrim.ts

@@ -17,6 +17,7 @@
 import type { Accessor, Document, Primitive } from '@gltf-transform/core'
 import { weldPrimitive } from '@gltf-transform/functions'
 import { decodeImage } from '../unity/image'
+import { ByteLru } from '../textures/byteLru'
 
 export interface CardTrimOptions {
   /** Trim alpha-MASK quads to their opaque texels (see the header). */
@@ -82,6 +83,7 @@ class OpaqueTable {
     }
     this.sat = sat
   }
+  get bytes(): number { return this.sat.byteLength }
   /** Opaque texels in [x0, x1) × [y0, y1) (clamped). */
   count(x0: number, y0: number, x1: number, y1: number): number {
     x0 = Math.max(0, Math.min(this.w, x0)); x1 = Math.max(0, Math.min(this.w, x1))
@@ -166,10 +168,21 @@ function findQuads(indices: Uint32Array, uv: Float32Array): Quad[] {
   return quads
 }
 
+/**
+ * THE OPAQUE TABLES OUTLIVE THE CALL, keyed by the image OBJECT and the cutoff: a level import runs this pass per
+ * kind, and its foliage kinds share a handful of atlases by the same bytes (unity/materialWriter.ts
+ * `SharedTextures`) — each kind decoded every MASK base colour again (a 2048² PNG: ~50 ms of inflate + 16 MB).
+ * Bounded by the tables' own size (a 2048² table is 16 MB; 512 MB ≈ 30 atlases). The id is per object and never
+ * reused, so a table whose image is gone just ages out.
+ */
+const tableCache = new ByteLru<OpaqueTable | null>(512 * 1024 * 1024, (t) => t?.bytes ?? 0)
+const imageIds = new WeakMap<Uint8Array, number>()
+let nextImageId = 0
+const imageId = (b: Uint8Array): number => { let id = imageIds.get(b); if (id === undefined) imageIds.set(b, id = ++nextImageId); return id }
+
 /** Apply the pass to every planned primitive. */
 export async function applyCardTrim(doc: Document, plan: CardTrimPlan): Promise<CardTrimResult> {
   const res: CardTrimResult = { primitives: 0, quads: 0, trimmed: 0, dropped: 0, areaBefore: 0, areaAfter: 0, skipped: [] }
-  const tables = new Map<string, Promise<OpaqueTable | null>>()
   for (const p of plan.prims) {
     const mat = p.prim.getMaterial()!
     if (p.texture !== 'ok') {
@@ -178,18 +191,11 @@ export async function applyCardTrim(doc: Document, plan: CardTrimPlan): Promise<
     }
     const tex = mat.getBaseColorTexture()!
     const cutoff = Math.max(0, Math.min(1, mat.getAlphaCutoff())) * 255 / Math.max(1e-3, mat.getBaseColorFactor()[3])
-    const key = `${tex.getName()}#${tex.getImage()?.byteLength ?? 0}#${cutoff.toFixed(2)}`
-    let table = tables.get(key)
-    if (!table) {
-      table = (async () => {
-        const bytes = tex.getImage()
-        if (!bytes) return null
-        const img = await decodeImage(bytes, tex.getURI() || tex.getMimeType() || 'texture.png')
-        return img ? new OpaqueTable(img.data, img.width, img.height, cutoff) : null
-      })()
-      tables.set(key, table)
-    }
-    const opaque = await table
+    const bytes = tex.getImage()
+    const opaque = bytes ? await tableCache.get(`${imageId(bytes)}#${cutoff}`, async () => {
+      const img = await decodeImage(bytes, tex.getURI() || tex.getMimeType() || 'texture.png')
+      return img ? new OpaqueTable(img.data, img.width, img.height, cutoff) : null
+    }) : null
     if (!opaque) { res.skipped.push({ name: `${p.name}/${p.material}`, reason: 'base colour texture could not be decoded' }); continue }
     const r = trimPrimitive(p.prim, opaque, plan.margin)
     if (!r) continue

package/src/doctor/coverageMips.ts

@@ -0,0 +1,132 @@
+// COVERAGE-PRESERVING MIPS for an alpha-MASK texture (Castaño, "Computing alpha mipmaps"; Unity's "Mip Maps Preserve
+// Coverage"). A leaf card's alpha is hard-edged: 13 % of a birch atlas' texels stand over the material's cutoff, and a
+// plain box mip averages that edge into a grey that falls UNDER the cutoff — four levels down (a 1 m card at 20 m) the
+// alpha test passes almost nothing and the crown goes bare. Here every level is box-filtered and then its alpha is
+// scaled by ONE scalar, chosen so that the fraction of texels at or over the cutoff equals the fraction the full-size
+// source has. A `--max-size` downscale is a level like any other: the target is measured once, on the source.
+//
+//   colour   area-weighted box, averaged in LINEAR light (the sRGB transfer undone and redone), weighted by alpha so a
+//            transparent texel's colour (often black) does not bleed into the leaf's; a footprint with no alpha at all
+//            keeps the plain average
+//   alpha    the area-weighted box average, then × s (clamped to 1), s from a 4096-bin histogram: the alpha τ at which
+//            the level's own coverage reaches the target, s = cutoff / τ
+//
+// Pure functions over raw RGBA8 buffers: the doctor writes the levels as PNGs and hands them to the encoder as an
+// explicit mip chain (transcodeKtx2.ts), the tests call them directly.
+
+export type Level = { data: Uint8Array, width: number, height: number }
+
+const SRGB_TO_LINEAR = Float32Array.from({ length: 256 }, (_, i) => {
+  const c = i / 255
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
+})
+const linearToSrgb8 = (x: number): number => {
+  const c = x <= 0 ? 0 : x >= 1 ? 1 : x <= 0.0031308 ? x * 12.92 : 1.055 * Math.pow(x, 1 / 2.4) - 0.055
+  return Math.round(c * 255)
+}
+
+/** The fraction of texels whose alpha (8-bit, as the GPU reads it) is at or over `cutoff`. */
+export const alphaCoverage = (rgba: Uint8Array, cutoff: number): number => {
+  const n = rgba.length >> 2
+  if (!n) return 0
+  const min8 = Math.ceil(cutoff * 255 - 1e-6)
+  let k = 0
+  for (let i = 3; i < rgba.length; i += 4) if (rgba[i] >= min8) k++
+  return k / n
+}
+
+/** Area-weighted box resample of RGBA8 to dw × dh: colour in linear light (sRGB in and out when `srgb`) weighted by
+ *  alpha, alpha the plain area average. Returns floats: rgb linear 0..1, alpha 0..1. */
+const boxResample = (src: Uint8Array, sw: number, sh: number, dw: number, dh: number, srgb: boolean): Float32Array => {
+  const out = new Float32Array(dw * dh * 4)
+  const lin = srgb ? SRGB_TO_LINEAR : Float32Array.from({ length: 256 }, (_, i) => i / 255)
+  const fx = sw / dw, fy = sh / dh
+  for (let y = 0; y < dh; y++) {
+    const y0 = y * fy, y1 = y0 + fy
+    for (let x = 0; x < dw; x++) {
+      const x0 = x * fx, x1 = x0 + fx
+      let wa = 0, ra = 0, ga = 0, ba = 0, w = 0, r = 0, g = 0, b = 0
+      for (let sy = Math.floor(y0); sy < Math.min(Math.ceil(y1), sh); sy++) {
+        const wy = Math.min(sy + 1, y1) - Math.max(sy, y0)
+        if (wy <= 0) continue
+        for (let sx = Math.floor(x0); sx < Math.min(Math.ceil(x1), sw); sx++) {
+          const wx = Math.min(sx + 1, x1) - Math.max(sx, x0)
+          if (wx <= 0) continue
+          const k = wx * wy, o = (sy * sw + sx) * 4
+          const a = src[o + 3] / 255
+          const lr = lin[src[o]], lg = lin[src[o + 1]], lb = lin[src[o + 2]]
+          w += k; r += lr * k; g += lg * k; b += lb * k
+          wa += a * k; ra += lr * a * k; ga += lg * a * k; ba += lb * a * k
+        }
+      }
+      const o = (y * dw + x) * 4
+      if (wa > 1e-6) { out[o] = ra / wa; out[o + 1] = ga / wa; out[o + 2] = ba / wa }
+      else if (w > 0) { out[o] = r / w; out[o + 1] = g / w; out[o + 2] = b / w }
+      out[o + 3] = w > 0 ? wa / w : 0
+    }
+  }
+  return out
+}
+
+/** The scale s that brings `alpha`'s coverage at `cutoff` to `target` (the fraction of texels at or over it). */
+const coverageScale = (lvl: Float32Array, cutoff: number, target: number): number => {
+  const n = lvl.length >> 2
+  const want = Math.round(target * n)
+  if (want <= 0 || cutoff <= 0) return 1
+  const BINS = 4096
+  const hist = new Uint32Array(BINS + 1)
+  for (let i = 3; i < lvl.length; i += 4) hist[Math.min(BINS, Math.floor(lvl[i] * BINS))]++
+  // walk down from the top: τ = the alpha at which `want` texels are at or over it
+  let k = 0, bin = BINS
+  for (; bin > 0; bin--) { k += hist[bin]; if (k >= want) break }
+  const tau = bin / BINS
+  if (tau <= 1e-4) return 1          // the level has (almost) no alpha left to scale
+  return cutoff / tau
+}
+
+/** Floats (linear rgb, alpha) → RGBA8 with the alpha scaled by `s` (and clamped). */
+const toBytes = (lvl: Float32Array, s: number, srgb: boolean): Uint8Array => {
+  const out = new Uint8Array(lvl.length)
+  for (let o = 0; o < lvl.length; o += 4) {
+    for (let c = 0; c < 3; c++) out[o + c] = srgb ? linearToSrgb8(lvl[o + c]) : Math.round(Math.min(Math.max(lvl[o + c], 0), 1) * 255)
+    out[o + 3] = Math.round(Math.min(lvl[o + 3] * s, 1) * 255)
+  }
+  return out
+}
+
+export type MipChainOptions = {
+  /** The alpha test's cutoff (the lowest of the MASK materials sharing the texture). */
+  cutoff: number
+  /** Level 0's size (the `--max-size` cap, ×4 snapped by the caller); the source's when equal. */
+  width: number
+  height: number
+  /** The colour is sRGB-encoded (base colour): averaged in linear light. */
+  srgb: boolean
+  /** false = the plain box chain (no alpha scaling) — the tests' contrast. Default true. */
+  preserve?: boolean
+}
+
+/**
+ * The full mip chain, level 0 (`width` × `height`) down to 1 × 1, each level max(1, ⌊w / 2^i⌋) × max(1, ⌊h / 2^i⌋) (the
+ * encoder's own level sizes). Every level is box-filtered from the one above (level 0 from the source) and, with
+ * `preserve`, its alpha scaled to the SOURCE's coverage at the cutoff. A level 0 at the source's size is the source.
+ */
+export const coverageMipChain = (src: Uint8Array, sw: number, sh: number, o: MipChainOptions): { levels: Level[], target: number } => {
+  const preserve = o.preserve !== false
+  const target = alphaCoverage(src, o.cutoff)
+  const levels: Level[] = []
+  let w = o.width, h = o.height
+  let cur: Level = { data: src, width: sw, height: sh }
+  for (let i = 0; ; i++) {
+    if (i === 0 && w === sw && h === sh) levels.push(cur)
+    else {
+      const f = boxResample(cur.data, cur.width, cur.height, w, h, o.srgb)
+      const s = preserve ? coverageScale(f, o.cutoff, target) : 1
+      cur = { data: toBytes(f, s, o.srgb), width: w, height: h }
+      levels.push(cur)
+    }
+    if (w === 1 && h === 1) break
+    w = Math.max(1, w >> 1); h = Math.max(1, h >> 1)
+  }
+  return { levels, target }
+}

package/src/doctor/doctor.ts

@@ -12,6 +12,7 @@ import { planTexture, applyTexturePlan, getTextureRoles, DEFAULT_MAX_SIZE, type
 import { planKtx2, applyKtx2, findKtxEncoder, KTX_ENCODER_MISSING, type Ktx2Plan, type KtxEncoder } from './transcodeKtx2'
 import { measureScale, planScale, applyScale, type ScaleInfo, type ScalePlan, type ScaleOptions } from './normalizeScale'
 import { analyzeShading, applyShading, type ShadingPlan, type ShadingOptions } from './shading'
+import { imageInfo } from './imageFacts'
 import { planCardTrim, applyCardTrim, type CardTrimPlan, type CardTrimOptions, type CardTrimResult } from './cardTrim'
 import { planLod, applyLod, type LodPlan, type LodOptions, type LodResult } from './lod'
 import { planMerge, applyMerge, describeScale, type MergePlan, type MergeOptions, type MergeResult } from './merge'
@@ -39,6 +40,9 @@ export async function analyzeDoc(doc: Document, opts: DoctorOptions = {}): Promi
   // KTX2 mode: everything → ETC1S (max compression). --ktx2-hq upgrades NORMAL maps to UASTC
   // (much higher quality, same VRAM, larger file); colour/metalRough stay ETC1S either way.
   const codecPolicy = opts.ktx2Uastc ? 'uastc' : opts.ktx2Hq ? 'hq' : 'default'
+  // sharp's look at every image, all at once (its own threads; cached per image object, imageFacts.ts) — one after
+  // another was 0.1–0.25 s a map: 3 s of the 30 maps of Chernobyl's Department_Store
+  await Promise.all(root.listTextures().map((t) => { const img = t.getImage(); return img && !(t.getMimeType() || '').includes('ktx') ? imageInfo(img) : null }))
   for (const tex of root.listTextures()) {
     if (opts.ktx2) {
       const p = await planKtx2(tex, root, maxSize, codecPolicy); if (p) ktx2Plans.push(p)
@@ -255,7 +259,10 @@ export async function applyPlan(doc: Document, plan: DoctorPlan, opts: ApplyOpti
     // texture set went through one core however many were idle.
     await Promise.all(plan.ktx2Plans.map(async (t) => {
       await applyKtx2(t, enc, maxSize)
-      opts.progress?.(++ktx2Encoded, plan.ktx2Plans.length)
+      // counted OUTSIDE the optional call: `progress?.(++n)` skips its arguments without a callback, so the
+      // result said 0 encoded for every caller that passed none
+      ktx2Encoded++
+      opts.progress?.(ktx2Encoded, plan.ktx2Plans.length)
     }))
     // KTX2 textures must be written via KHR_texture_basisu (core texture.source allows only PNG/JPEG);
     // gltf-transform only emits that form when the extension is attached to the document.

package/src/doctor/imageFacts.ts

@@ -0,0 +1,44 @@
+// What sharp says about an image, once per image OBJECT: its size, whether its alpha is used, and its sha1 (the
+// key of transcodeKtx2.ts's encode cache).
+//
+// A level import hands every kind the same `Uint8Array` of a shared map (unity/materialWriter.ts
+// `SharedTextures`), and `metadata()` + `stats()` of each was the whole of the `analyze` stage — 12 s of a
+// 14-kind Chernobyl sample, 0.1–0.25 s a 2048–4096² map, paid again in every kind that used it (2026-11-04).
+// Weak: an entry dies with its bytes.
+import { createHash } from 'node:crypto'
+import sharp from 'sharp'
+import type { Rgba } from '../textures/resolveImage'
+
+type ImageFacts = { width: number; height: number; hasAlpha: boolean; sha1?: string }
+const facts = new WeakMap<Uint8Array, Promise<ImageFacts | null>>()
+export function imageInfo(img: Uint8Array): Promise<ImageFacts | null> {
+  let f = facts.get(img)
+  if (!f) {
+    f = (async () => {
+      try {
+        const b = Buffer.from(img.buffer, img.byteOffset, img.byteLength)
+        const m = await sharp(b).metadata()
+        return { width: m.width || 0, height: m.height || 0, hasAlpha: !(await sharp(b).stats()).isOpaque }
+      } catch { return null }
+    })()
+    facts.set(img, f)
+  }
+  return f
+}
+/** The image's sha1, hashed once per image object. */
+export const imageSha1 = async (img: Uint8Array): Promise<string> => {
+  const f = await imageInfo(img)
+  if (f) return (f.sha1 ??= createHash('sha1').update(img).digest('hex'))
+  return createHash('sha1').update(img).digest('hex')
+}
+
+/** The facts of a PNG the caller has just encoded from `rgba` itself — sharp is not asked. Sharp's `isOpaque` is
+ *  "the minimum alpha is the maximum", which is exactly "no texel below 255" here. Not past sharp's own input
+ *  limit (16383² pixels): sharp refuses such an image, and the passes must go on seeing that refusal. */
+export function knownImageInfo(png: Uint8Array, rgba: Rgba): void {
+  if (facts.has(png) || rgba.width * rgba.height > 0x3fff * 0x3fff) return
+  const d = rgba.data
+  let hasAlpha = false
+  for (let i = 3; i < d.length; i += 4) if (d[i] !== 255) { hasAlpha = true; break }
+  facts.set(png, Promise.resolve({ width: rgba.width, height: rgba.height, hasAlpha }))
+}