lecodes-assets 0.2.0 → 0.2.1

package/src/doctor/doctor.ts

@@ -0,0 +1,241 @@
+// glTF doctor — analyze a Document against creator-gl/filament constraints and (optionally) fix it.
+// The former tools/glb-reduce/glbDoctor.ts, as functions so `convert` can run the same passes on a
+// freshly converted model (`convert … --ktx2`) and the CLI can run them on any GLB (`doctor`).
+//
+//   Analyze : reports issues grouped by impact — LOSSLESS fixes (no degradation, e.g. dropping
+//             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.
+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 { 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 { planLod, applyLod, type LodPlan, type LodOptions, type LodResult } from './lod'
+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 { 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 async function analyzeDoc(doc: Document, opts: DoctorOptions = {}): Promise<DoctorPlan> {
+  const target = opts.target ?? DEFAULT_TARGET
+  const maxSize = opts.maxSize ?? DEFAULT_MAX_SIZE
+  const root = doc.getRoot()
+  const { bySkin, conflicts } = gatherSkinPrims(doc)
+  const skinPlans = root.listSkins().map((s, i) => planSkin(s, i, bySkin.get(s) ?? [], target))
+  const texPlans: TexturePlan[] = []
+  const ktx2Plans: Ktx2Plan[] = []
+  // 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'
+  for (const tex of root.listTextures()) {
+    if (opts.ktx2) {
+      const p = await planKtx2(tex, root, maxSize, codecPolicy); if (p) ktx2Plans.push(p)
+    } else {
+      const p = await planTexture(tex, root, maxSize); if (p) texPlans.push(p)
+    }
+  }
+  // Materials with a flat metallic factor but NO metallicRoughness texture render BLACK without an
+  // IBL/environment (metal reflects nothing, has no diffuse). Common export quirk on non-metal assets.
+  const metallicWarn: MetallicWarn[] = root.listMaterials()
+    .filter((m) => m.getMetallicFactor() > 0.01 && !m.getMetallicRoughnessTexture())
+    .map((m) => ({ mat: m, name: m.getName() || '?', metal: m.getMetallicFactor() }))
+  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)
+  // Duplicate node names: the Animator binds clips BY NAME and takes the first match. A leftover
+  // donor skeleton (two skinned files merged by hand) shadows the real joints → the mesh freezes.
+  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 }
+}
+
+export const kb = (n?: number) => (n === undefined ? '?' : `${Math.round(n / 1024)}KB`)
+
+/** A length in metres, in whatever unit reads best — 0.0055 is "5.5mm", not "0.01m". */
+export const metres = (m: number): string =>
+  m >= 1 ? `${m.toFixed(m >= 10 ? 0 : 2)}m` : m >= 0.01 ? `${(m * 100).toFixed(1)}cm` : `${(m * 1000).toFixed(m >= 0.001 ? 1 : 3)}mm`
+const dims3 = (d: readonly number[]): string => d.map((x) => metres(x)).join(' × ')
+const fmtFactor = (f: number): string => (f >= 0.001 && f < 1e6 ? +f.toPrecision(6) : f.toExponential(2)).toString()
+
+const EXT_BY_MIME: Record<string, string> = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/ktx2': 'ktx2' }
+const safeName = (n: string) => (n || 'tex').replace(/[\\/:*?"<>|\s]+/g, '_').slice(0, 60)
+
+/** Write every texture's raw bytes to `dir` (+ a _manifest.txt) for manual inspection. */
+export async function dumpTextures(doc: Document, dir: string, log: (s: string) => void = console.log) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const root = doc.getRoot()
+  const rows: string[] = []
+  let sharp: any = null
+  try { sharp = (await import('sharp')).default } catch { /* dims/alpha columns stay '-' */ }
+  let i = 0
+  for (const tex of root.listTextures()) {
+    const img = tex.getImage()
+    const mime = tex.getMimeType() || ''
+    const ext = EXT_BY_MIME[mime] ?? 'bin'
+    const file = `${String(i).padStart(2, '0')}_${safeName(tex.getName())}.${ext}`
+    if (img) writeFileSync(`${dir}/${file}`, img)
+    const { roles } = getTextureRoles(tex, root)
+    let dims = '-', alpha = '-'
+    if (img && ext !== 'ktx2' && sharp) {
+      try {
+        const m = await sharp(Buffer.from(img)).metadata()
+        dims = `${m.width}x${m.height}`
+        alpha = (await sharp(Buffer.from(img)).stats()).isOpaque ? 'opaque' : 'ALPHA'
+      } catch { /* undecodable by sharp */ }
+    }
+    rows.push(`${file.padEnd(48)} ${ext.padEnd(5)} ${dims.padEnd(11)} ${alpha.padEnd(7)} ${roles.padEnd(12)} ${kb(img?.length)}`)
+    i++
+  }
+  const header = `# ${i} textures from this GLB\n# file  format  dimensions  alpha  role  size\n`
+  writeFileSync(`${dir}/_manifest.txt`, header + rows.join('\n') + '\n')
+  log(`\n🖼  dumped ${i} textures → ${dir}`)
+  log(rows.join('\n'))
+}
+
+export function reportPlan(plan: DoctorPlan): { text: string; lossless: number; lossy: number; blocking: number } {
+  const lossless: string[] = [], lossy: string[] = [], blocking: string[] = []
+
+  for (const s of plan.skinPlans) {
+    if (s.before <= plan.target) continue
+    if (s.removedDeep === 0) {
+      lossless.push(`bones  ${s.name}: drop ${s.removedUnbound} unbound joints  (${s.before} → ${s.after})`)
+    } else {
+      if (s.removedUnbound > 0) lossless.push(`bones  ${s.name}: drop ${s.removedUnbound} unbound joints`)
+      lossy.push(`bones  ${s.name}: drop ${s.removedDeep} deepest BOUND joints, merge weights → parent  (${s.before} → ${s.after})`)
+    }
+    if (s.after > plan.target) blocking.push(`bones  ${s.name}: still ${s.after} > ${plan.target} after reduction (too many root joints)`)
+  }
+
+  for (const t of plan.texPlans) {
+    if (!t.toFmt) continue
+    const line = `tex    "${t.name}" [${t.roles}] ${t.fromFmt}→${t.toFmt}  (${t.reason}, ${kb(t.beforeBytes)})`
+    ;(t.category === 'lossless' ? lossless : lossy).push(line)
+  }
+  for (const t of plan.ktx2Plans) {
+    lossy.push(`tex    "${t.name}" [${t.roles}] ${t.reason}  (${kb(t.beforeBytes)})`)
+  }
+  if (plan.conflicts > 0) blocking.push(`${plan.conflicts} primitive(s) shared across skins — skipped`)
+  const shadowing = plan.dupNames.filter((d) => d.shadowsJoint)
+  if (shadowing.length) blocking.push(`names  ${shadowing.length} skinned joint(s) shadowed by a plain node of the same name (${shadowing.slice(0, 5).map((d) => d.name).join(', ')}${shadowing.length > 5 ? '…' : ''}) — a name-bound Animator drives the copy and the mesh freezes; rebuild with convert --merge-skins, or delete the stray skeleton`)
+
+  const lines: string[] = []
+  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) {
+    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(', ')}`)
+  }
+  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 (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(', ')}`)
+    }
+    if (boosted.length) {
+      lines.push(`   ℹ ${boosted.length} material(s) boost specular above 1 (${boosted.map((i) => `${i.name}(×${i.specularBoost.toFixed(1)})`).join(', ')}) — gltfio also refuses specular + unlit, so --unlit drops it`)
+    }
+  }
+  const sc = plan.scaleInfo
+  if (sc?.suspicious || plan.scalePlan) {
+    lines.push(`  ── SCALE ──`)
+    if (sc) lines.push(`   ${sc.suspicious ? '⚠' : 'ℹ'} model measures ${dims3(sc.dims)}${sc.suspicious ? ` — implausible for a real-world asset (${sc.label})` : ''}`)
+    else lines.push(`   ℹ no geometry to measure (clip-only file)`)
+    if (plan.scalePlan) lines.push(`     → ×${fmtFactor(plan.scalePlan.factor)}${plan.scalePlan.source === 'explicit' ? '' : ` (${plan.scalePlan.label})`}${sc ? ` → ${dims3(plan.scalePlan.after)}` : ''}`)
+    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 plainDups = plan.dupNames.filter((d) => !d.shadowsJoint)
+  if (plainDups.length) {
+    lines.push(`  ── NAMES ──`)
+    lines.push(`   ℹ ${plainDups.length} node name(s) used more than once (${plainDups.slice(0, 6).map((d) => `${d.name} ×${d.count}`).join(', ')}${plainDups.length > 6 ? '…' : ''}) — clips and node paths address the FIRST one`)
+  }
+  if (!lines.length) lines.push('  ✅ no issues — model is within all limits')
+  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 }
+
+/** Apply a plan to the document (mutates). Resolves toktx itself when `ktx2` and no path 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)
+  // After the skin plan: bone reduction rewrites joints/IBMs, and scaling the reduced set is both
+  // cheaper and keeps the IBM offsets it just wrote consistent with the geometry.
+  if (plan.scalePlan) applyScale(doc, plan.scalePlan.factor)
+  let metallicZeroed = 0
+  if (opts.fixMetallic && plan.metallicWarn.length) {
+    for (const w of plan.metallicWarn) w.mat.setMetallicFactor(0)
+    metallicZeroed = plan.metallicWarn.length
+  }
+  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
+  // 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
+  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)
+      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')) {
+      doc.createExtension(KHRTextureBasisu).setRequired(true)
+    }
+  } else {
+    for (const t of plan.texPlans) if (t.toFmt) await applyTexturePlan(t, maxSize)
+  }
+  // Once no texture is webp anymore, drop EXT_texture_webp — else it lingers in extensionsRequired
+  // and a strict loader (gltfio) can reject the file for a now-unused requirement.
+  if (!doc.getRoot().listTextures().some((t) => (t.getMimeType() || '').includes('webp'))) {
+    for (const ext of doc.getRoot().listExtensionsUsed()) {
+      if (ext.extensionName === 'EXT_texture_webp') ext.dispose()
+    }
+  }
+  return { metallicZeroed, ktx2Encoded, scaled: plan.scalePlan?.factor ?? 1, unlit: shading.unlit, emissiveCleared: shading.emissiveCleared, lightmapUv, lod }
+}
+
+/** Output path for a doctored file: single file + -o → exact path; -o as dir (or batch) → derived name inside it. */
+export function outputFor(input: string, oVal: string | null, batch: boolean, ktx2: boolean): string {
+  const derived = input.replace(/\.glb$/i, ktx2 ? '.ktx2.glb' : '.fixed.glb')
+  if (!oVal) return derived
+  const oNorm = oVal.replace(/\\/g, '/')
+  const asDir = batch || /\/$/.test(oNorm) || (existsSync(oNorm) && statSync(oNorm).isDirectory())
+  if (asDir) {
+    if (!existsSync(oNorm)) mkdirSync(oNorm, { recursive: true })
+    return join(oNorm, derived.split(/[\\/]/).pop()!)
+  }
+  return oVal
+}