lecodes-assets 0.2.1 → 2.5.0

package/src/doctor/doctor.ts

@@ -6,26 +6,27 @@
 //             unbound joints / re-encoding webp→png) vs LOSSY fixes (bound-joint removal,
 //             webp→jpg, downscaling, heavy-png→jpg).
 //   Fix     : applies everything; the caller writes <name>.fixed.glb and re-validates.
-//   KTX2    : textures → KTX2 (ETC1S; --ktx2-hq keeps normals UASTC) via KTX-Software's toktx.
+//   KTX2    : textures → KTX2 (ETC1S; --ktx2-hq keeps normals UASTC) via KTX-Software (toktx, or `ktx create` where toktx is gone).
 import { gatherSkinPrims, planSkin, applySkinPlan, DEFAULT_TARGET, type SkinPlan } from './reduceGlbBones'
 import { planTexture, applyTexturePlan, getTextureRoles, DEFAULT_MAX_SIZE, type TexturePlan } from './transcodeTextures'
-import { planKtx2, applyKtx2, findToktx, checkToktx, type Ktx2Plan } from './transcodeKtx2'
+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 { analyzeLightmapUv, applyLightmapUv, type LightmapUvPlan, type LightmapUvOptions, type LightmapUvResult } from './lightmapUv'
+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'
 import { duplicateNodeNames } from '../mergeSkins'
 import { KHRTextureBasisu } from '@gltf-transform/extensions'
 import type { Document, Material } from '@gltf-transform/core'
 import { mkdirSync, existsSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-export { DEFAULT_TARGET, DEFAULT_MAX_SIZE, findToktx, checkToktx }
+export { DEFAULT_TARGET, DEFAULT_MAX_SIZE, findKtxEncoder, KTX_ENCODER_MISSING }
 export { sceneBounds, measureScale, applyScale } from './normalizeScale'
 
 interface MetallicWarn { mat: Material; name: string; metal: number }
-export interface DoctorPlan { skinPlans: SkinPlan[]; texPlans: TexturePlan[]; ktx2Plans: Ktx2Plan[]; metallicWarn: MetallicWarn[]; shadingPlan: ShadingPlan; lightmapPlan: LightmapUvPlan; scaleInfo: ScaleInfo | null; scalePlan: ScalePlan | null; lodPlan: LodPlan | null; conflicts: number; target: number; dupNames: { name: string; count: number; shadowsJoint: boolean }[] }
-export interface DoctorOptions extends ScaleOptions, ShadingOptions, LightmapUvOptions, LodOptions { target?: number; maxSize?: number; ktx2?: boolean; ktx2Hq?: boolean; ktx2Uastc?: boolean }
+export interface DoctorPlan { skinPlans: SkinPlan[]; texPlans: TexturePlan[]; ktx2Plans: Ktx2Plan[]; metallicWarn: MetallicWarn[]; bareCount: number; shadingPlan: ShadingPlan; scaleInfo: ScaleInfo | null; scalePlan: ScalePlan | null; lodPlan: LodPlan | null; cardTrimPlan: CardTrimPlan; mergePlan: MergePlan; conflicts: number; target: number; dupNames: { name: string; count: number; shadowsJoint: boolean }[] }
+export interface DoctorOptions extends ScaleOptions, ShadingOptions, LodOptions, CardTrimOptions, MergeOptions { target?: number; maxSize?: number; ktx2?: boolean; ktx2Hq?: boolean; ktx2Uastc?: boolean }
 
 export async function analyzeDoc(doc: Document, opts: DoctorOptions = {}): Promise<DoctorPlan> {
   const target = opts.target ?? DEFAULT_TARGET
@@ -50,9 +51,12 @@ export async function analyzeDoc(doc: Document, opts: DoctorOptions = {}): Promi
   const metallicWarn: MetallicWarn[] = root.listMaterials()
     .filter((m) => m.getMetallicFactor() > 0.01 && !m.getMetallicRoughnessTexture())
     .map((m) => ({ mat: m, name: m.getName() || '?', metal: m.getMetallicFactor() }))
+  // Primitives with NO material at all: glTF's default material is metallic 1 / roughness 1 — a white ROUGH METAL,
+  // which under an environment (or a lightmap's reflection probe) is a dark featureless blob (the school's
+  // cabinets and sinks, 2026-09-17). --fix-metallic gives them a plain white dielectric.
+  let bareCount = 0
+  for (const mesh of root.listMeshes()) for (const prim of mesh.listPrimitives()) if (!prim.getMaterial()) bareCount++
   const shadingPlan = analyzeShading(doc, opts)
-  // Lightmap UVs are only ever ADDED on request (--lightmap-uv); the analysis just says what would be unwrapped.
-  const lightmapPlan = analyzeLightmapUv(doc, opts)
   // Scale is always MEASURED (probe/report it even with no flag); it is only APPLIED when asked.
   const scaleInfo = measureScale(doc)
   const scalePlan = planScale(scaleInfo, opts)
@@ -61,7 +65,11 @@ export async function analyzeDoc(doc: Document, opts: DoctorOptions = {}): Promi
   const dupNames = duplicateNodeNames(doc)
   // LOD levels are only ever ADDED on request (--lod); see doctor/lod.ts.
   const lodPlan = planLod(doc, opts)
-  return { skinPlans, texPlans, ktx2Plans, metallicWarn, shadingPlan, lightmapPlan, scaleInfo, scalePlan, lodPlan, conflicts, target, dupNames }
+  // Card trimming only on request (--trim-cards); the analysis lists the alpha-MASK primitives it would cut.
+  const cardTrimPlan = planCardTrim(doc, opts)
+  // Mesh merge + atlas only on request (--merge); the analysis says how many draw calls it would fold.
+  const mergePlan = await planMerge(doc, opts)
+  return { skinPlans, texPlans, ktx2Plans, metallicWarn, bareCount, shadingPlan, scaleInfo, scalePlan, lodPlan, cardTrimPlan, mergePlan, conflicts, target, dupNames }
 }
 
 export const kb = (n?: number) => (n === undefined ? '?' : `${Math.round(n / 1024)}KB`)
@@ -137,15 +145,16 @@ export function reportPlan(plan: DoctorPlan): { text: string; lossless: number;
   if (lossless.length) { lines.push('  ── LOSSLESS (no quality loss) ──'); lossless.forEach((l) => lines.push('   • ' + l)) }
   if (lossy.length) { lines.push('  ── LOSSY (some degradation) ──'); lossy.forEach((l) => lines.push('   • ' + l)) }
   if (blocking.length) { lines.push('  ── BLOCKING / manual ──'); blocking.forEach((l) => lines.push('   ✗ ' + l)) }
+  if (plan.metallicWarn.length || plan.bareCount) lines.push(`  ── MATERIALS ──`)
   if (plan.metallicWarn.length) {
-    lines.push(`  ── MATERIALS ──`)
     lines.push(`   ℹ ${plan.metallicWarn.length} material(s) have metallic without an MR texture → may render BLACK without IBL (--fix-metallic zeroes them):`)
     lines.push(`     ${plan.metallicWarn.map((w) => `${w.name}(${w.metal.toFixed(2)})`).join(', ')}`)
   }
+  if (plan.bareCount) lines.push(`   ℹ ${plan.bareCount} primitive(s) have NO material → glTF's default is a white ROUGH METAL (a dark blob under any environment; --fix-metallic gives them a white dielectric)`)
   const selfLit = plan.shadingPlan.issues.filter((i) => i.selfLit)
   const boosted = plan.shadingPlan.issues.filter((i) => i.specularBoost > 0)
   if (selfLit.length || boosted.length) {
-    if (!plan.metallicWarn.length) lines.push(`  ── MATERIALS ──`)
+    if (!plan.metallicWarn.length && !plan.bareCount) lines.push(`  ── MATERIALS ──`)
     if (selfLit.length) {
       lines.push(`   ⚠ ${selfLit.length} material(s) emit their own base colour (emissive = albedo) → render ~2× too bright, washed out (--fix-emissive drops it, --unlit goes flat):`)
       lines.push(`     ${selfLit.map((i) => i.name).join(', ')}`)
@@ -163,14 +172,24 @@ export function reportPlan(plan: DoctorPlan): { text: string; lossless: number;
     else if (sc && sc.suggested !== 1) lines.push(`     --fix-scale applies ×${fmtFactor(sc.suggested)} → ${dims3(sc.dims.map((d) => d * sc.suggested))}; --scale-to <m> / --scale <n> to decide yourself`)
     else lines.push(`     --scale-to <m> sets the largest dimension explicitly`)
   }
-  const lm = plan.lightmapPlan
-  if (lm.enabled || lm.prims.some((p) => p.hasUv1)) {
-    lines.push(`  ── LIGHTMAP ──`)
-    const tris = lm.prims.reduce((n, p) => n + p.triangles, 0)
-    const existing = lm.prims.filter((p) => p.hasUv1).length
-    if (lm.enabled) lines.push(`   • lightmap UV (TEXCOORD_1) for ${lm.prims.length} primitive(s), ${tris} triangles — xatlas, padding ${lm.padding}${existing ? `; ${existing} existing set(s) replaced` : ''}`)
-    else lines.push(`   ℹ ${existing} primitive(s) already carry TEXCOORD_1 (lightmap UV); --lightmap-uv re-unwraps all ${lm.prims.length}`)
-    if (lm.skipped.length) lines.push(`     skipped: ${lm.skipped.slice(0, 6).map((s) => `${s.name} (${s.reason})`).join(', ')}${lm.skipped.length > 6 ? '…' : ''}`)
+  const ct = plan.cardTrimPlan
+  if (ct.prims.length) {
+    lines.push(`  ── CARDS ──`)
+    const tris = ct.prims.reduce((n, p) => n + p.triangles, 0)
+    const ready = ct.prims.filter((p) => p.texture === 'ok').length
+    if (ct.enabled) lines.push(`   • trim ${ready} alpha-MASK primitive(s) (${tris} triangles) to their opaque texels, margin ${ct.margin} texel(s)${ready < ct.prims.length ? `; ${ct.prims.length - ready} skipped (${ct.prims.filter((p) => p.texture !== 'ok').map((p) => `${p.name}: ${p.texture}`).slice(0, 4).join(', ')})` : ''}`)
+    else lines.push(`   ℹ ${ct.prims.length} alpha-MASK primitive(s), ${tris} triangles — foliage cards? --trim-cards cuts each quad to its opaque texels (less discarded fill)${ready < ct.prims.length ? `; ${ct.prims.length - ready} carry KTX2 / transformed / no textures and would be skipped` : ''}`)
+  }
+  const mg = plan.mergePlan
+  if (mg.groups.length || mg.skipped.length) {
+    lines.push(`  ── MERGE ──`)
+    const fold = `${mg.primitivesBefore} primitive(s) over ${mg.materialsBefore} material(s) → ${mg.primitivesAfter} draw call(s)`
+    if (mg.enabled) {
+      lines.push(`   • merge ${fold}`)
+      for (const g of mg.groups) lines.push(`     ${g.label}: ${g.sources.length} primitives, ${g.materials.length} material(s)${g.atlas ? ` → 1 (atlas ${g.atlas.size}² ${g.atlas.maps.join('+')}, ${g.atlas.tiles.length} tiles${describeScale(g.atlas)}, pad ${g.atlas.pad})` : g.materials.length === 1 ? ` (kept: ${g.materials[0].getName() || 'material'}${g.note ? ` — ${g.note}` : ''})` : ''}${g.family === 'skinned' ? `, ${g.joints} joints in one skin` : ', transforms baked'}`)
+      if (mg.joints > plan.target) blocking.push(`bones  merged skin has ${mg.joints} joints > ${plan.target} — exclude parts (--merge-exclude) or raise --target`)
+    } else if (mg.groups.length) lines.push(`   ℹ ${fold} with --merge (one atlas material per alpha mode / sidedness)`)
+    if (mg.skipped.length) lines.push(`     ${mg.enabled ? 'skipped' : 'would skip'}: ${mg.skipped.slice(0, 6).map((s) => `${s.name} (${s.reason})`).join(', ')}${mg.skipped.length > 6 ? '…' : ''}`)
   }
   const plainDups = plan.dupNames.filter((d) => !d.shadowsJoint)
   if (plainDups.length) {
@@ -181,10 +200,10 @@ export function reportPlan(plan: DoctorPlan): { text: string; lossless: number;
   return { text: lines.join('\n'), lossless: lossless.length, lossy: lossy.length, blocking: blocking.length }
 }
 
-export interface ApplyOptions extends DoctorOptions { fixMetallic?: boolean; toktx?: string; progress?: (done: number, total: number) => void }
-export interface ApplyResult { metallicZeroed: number; ktx2Encoded: number; scaled: number; unlit: number; emissiveCleared: number; lightmapUv: LightmapUvResult | null; lod: LodResult | null }
+export interface ApplyOptions extends DoctorOptions { fixMetallic?: boolean; ktxEncoder?: KtxEncoder; progress?: (done: number, total: number) => void }
+export interface ApplyResult { metallicZeroed: number; bareFixed: number; ktx2Encoded: number; scaled: number; unlit: number; emissiveCleared: number; lod: LodResult | null; cards: CardTrimResult | null; merge: MergeResult | null; emptied: number }
 
-/** Apply a plan to the document (mutates). Resolves toktx itself when `ktx2` and no path is given. */
+/** Apply a plan to the document (mutates). Resolves the KTX encoder itself when `ktx2` and none is given. */
 export async function applyPlan(doc: Document, plan: DoctorPlan, opts: ApplyOptions = {}): Promise<ApplyResult> {
   const maxSize = opts.maxSize ?? DEFAULT_MAX_SIZE
   for (const s of plan.skinPlans) applySkinPlan(doc, s)
@@ -196,19 +215,48 @@ export async function applyPlan(doc: Document, plan: DoctorPlan, opts: ApplyOpti
     for (const w of plan.metallicWarn) w.mat.setMetallicFactor(0)
     metallicZeroed = plan.metallicWarn.length
   }
+  let bareFixed = 0
+  if (opts.fixMetallic && plan.bareCount) {
+    const plain = doc.createMaterial('Default').setBaseColorFactor([1, 1, 1, 1]).setMetallicFactor(0).setRoughnessFactor(1)
+    for (const mesh of doc.getRoot().listMeshes()) for (const prim of mesh.listPrimitives()) if (!prim.getMaterial()) { prim.setMaterial(plain); bareFixed++ }
+  }
   const shading = applyShading(doc, plan.shadingPlan)
-  // After scale (the unwrap reads world-ish sizes for chart proportions) and before textures (geometry only).
-  const lightmapUv = plan.lightmapPlan.enabled ? await applyLightmapUv(doc, plan.lightmapPlan) : null
+  // Merge + atlas before every other geometry pass (they see the merged primitive) and before the texture
+  // passes: the atlases are new PNG textures, planned below like any other — capped by --atlas-size, not
+  // --max-size — while the plans of the textures the atlases replaced are dropped with them.
+  const merge = plan.mergePlan.enabled ? await applyMerge(doc, plan.mergePlan) : null
+  if (merge) {
+    const root = doc.getRoot()
+    const alive = new Set(root.listTextures())
+    plan.ktx2Plans = plan.ktx2Plans.filter((t) => alive.has(t.tex))
+    plan.texPlans = plan.texPlans.filter((t) => alive.has(t.tex))
+    const codecPolicy = opts.ktx2Uastc ? 'uastc' : opts.ktx2Hq ? 'hq' : 'default'
+    for (const tex of merge.textures) {
+      if (opts.ktx2) { const p = await planKtx2(tex, root, plan.mergePlan.atlasSize, codecPolicy); if (p) plan.ktx2Plans.push(p) }
+      else { const p = await planTexture(tex, root, plan.mergePlan.atlasSize); if (p) plan.texPlans.push(p) }
+    }
+    // …and the geometry passes are planned AGAIN: their plans were made in `analyzeDoc`, against primitives
+    // the merge has just disposed (a plan that kept one died on it: `pos.getCount` of null).
+    plan.lodPlan = planLod(doc, opts)
+    plan.cardTrimPlan = planCardTrim(doc, opts)
+  }
   // LOD levels after every geometry pass (they copy the final base mesh) and before textures.
   const lod = plan.lodPlan ? await applyLod(doc, plan.lodPlan) : null
+  // Card trimming before the texture passes: it decodes the base colour (PNG / JPEG), which a KTX2
+  // encode below would take away.
+  const cards = plan.cardTrimPlan.enabled ? await applyCardTrim(doc, plan.cardTrimPlan) : null
   let ktx2Encoded = 0
   if (opts.ktx2) {
-    const toktx = opts.toktx ?? findToktx()
-    if (!checkToktx(toktx)) throw new Error('toktx not found (looked at $KTX_TOKTX, %LOCALAPPDATA%\\Programs\\KTX-Software, PATH). Install KTX-Software or set KTX_TOKTX=<path to toktx>.')
-    for (const t of plan.ktx2Plans) {
-      await applyKtx2(t, toktx, maxSize)
+    const enc = opts.ktxEncoder ?? findKtxEncoder()
+    if (!enc) throw new Error(KTX_ENCODER_MISSING)
+    // Launched together, not one after another: `applyKtx2` bounds the real concurrency with its own
+    // pool of encoder processes (LECODES_KTX_JOBS, default one per core less one). Encoding used to be
+    // strictly sequential — a `spawnSync` per texture blocked the event loop — so a project's whole
+    // 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)
-    }
+    }))
     // 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.
     if (plan.ktx2Plans.length && !doc.getRoot().listExtensionsUsed().some((e) => e.extensionName === 'KHR_texture_basisu')) {
@@ -224,7 +272,23 @@ export async function applyPlan(doc: Document, plan: DoctorPlan, opts: ApplyOpti
       if (ext.extensionName === 'EXT_texture_webp') ext.dispose()
     }
   }
-  return { metallicZeroed, ktx2Encoded, scaled: plan.scalePlan?.factor ?? 1, unlit: shading.unlit, emissiveCleared: shading.emissiveCleared, lightmapUv, lod }
+  // LAST, after every pass that can eat geometry: a primitive with no vertices left is not a
+  // primitive. Card trimming produces them — it cuts an alpha-MASK quad down to its opaque texels,
+  // and the Modular Shooting Range's floor stripes have LOD levels whose texels are all clear, so
+  // the level came out carrying five empty meshes. That is not a cosmetic problem: filament's
+  // gltfio walks the primitive in `ResourceLoader::loadResources` and takes the host down with an
+  // access violation before the first frame.
+  let emptied = 0
+  for (const mesh of doc.getRoot().listMeshes()) {
+    for (const prim of mesh.listPrimitives()) {
+      if ((prim.getAttribute("POSITION")?.getCount() ?? 0) > 0) continue
+      mesh.removePrimitive(prim)
+      prim.dispose()
+      emptied++
+    }
+    if (!mesh.listPrimitives().length) mesh.dispose()
+  }
+  return { metallicZeroed, bareFixed, ktx2Encoded, scaled: plan.scalePlan?.factor ?? 1, unlit: shading.unlit, emissiveCleared: shading.emissiveCleared, lod, cards, merge, emptied }
 }
 
 /** Output path for a doctored file: single file + -o → exact path; -o as dir (or batch) → derived name inside it. */