lecodes-assets 0.2.1 → 2.4.10

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. */

package/src/doctor/merge/accessors.ts

@@ -0,0 +1,30 @@
+// Accessor reads as flat typed arrays.
+
+import type { Accessor, Primitive } from '@gltf-transform/core'
+
+export const readAttr = (acc: Accessor): { size: number; data: Float32Array } => {
+  const size = acc.getElementSize(), n = acc.getCount()
+  const data = new Float32Array(n * size)
+  const el = new Array<number>(size)
+  for (let i = 0; i < n; i++) { acc.getElement(i, el); for (let k = 0; k < size; k++) data[i * size + k] = el[k] }
+  return { size, data }
+}
+export const readIndices = (p: Primitive): Uint32Array => {
+  const idx = p.getIndices()
+  if (idx) return Uint32Array.from(idx.getArray() as ArrayLike<number>)
+  const n = p.getAttribute('POSITION')!.getCount()
+  return Uint32Array.from({ length: n }, (_, i) => i)
+}
+/** Area-weighted vertex normals for a primitive that has none. */
+export function flatNormals(pos: Float32Array, idx: Uint32Array): Float32Array {
+  const n = new Float32Array(pos.length)
+  for (let t = 0; t + 2 < 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 i of [ a, b, c ]) { n[i] += nx; n[i + 1] += ny; n[i + 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
+}

package/src/doctor/merge/atlasLayout.ts

@@ -0,0 +1,94 @@
+// Atlas layout: one tile per distinct material look, shelf-packed into a power-of-two square, scaled
+// down BY SURFACE AREA (equal texel density) when the cap is hit.
+
+import type { Material, Texture } from '@gltf-transform/core'
+import type { MatInfo } from './classify'
+import type { AtlasLayout, MapKind, Tile } from './types'
+
+function shelfPack(items: { w: number; h: number }[], S: number): { x: number; y: number }[] | null {
+  const order = items.map((_, i) => i).sort((a, b) => items[b].h - items[a].h || items[b].w - items[a].w)
+  const pos: { x: number; y: number }[] = new Array(items.length)
+  let x = 0, y = 0, rowH = 0
+  for (const i of order) {
+    const { w, h } = items[i]
+    if (w > S || h > S) return null
+    if (x + w > S) { y += rowH; x = 0; rowH = 0 }
+    if (y + h > S) return null
+    pos[i] = { x, y }; x += w; rowH = Math.max(rowH, h)
+  }
+  return pos
+}
+
+/** Tile scales for a texel-density budget `D` (texels² per m² of surface): the tile's used texels
+ *  (edge² × UV coverage) per square metre of the material's surface reach D, capped at the native map. */
+const scalesForDensity = (tiles: Tile[], D: number): number[] => tiles.map((t) => {
+  const uv = Math.max(0.02, t.uvArea), area = Math.max(1e-6, t.area)
+  return Math.min(1, Math.sqrt(D * area / uv / (t.srcW * t.srcH)))
+})
+
+function layoutTiles(tiles: Tile[], atlasSize: number, pad: number, uniform: boolean): { size: number; scale: number; scaleMax: number } | null {
+  const place = (S: number, scales: number[]): boolean => {
+    const items = tiles.map((t, i) => ({ w: Math.max(4, Math.round(t.srcW * scales[i])) + 2 * pad, h: Math.max(4, Math.round(t.srcH * scales[i])) + 2 * pad }))
+    const pos = shelfPack(items, S)
+    if (!pos) return false
+    tiles.forEach((t, i) => { t.w = items[i].w - 2 * pad; t.h = items[i].h - 2 * pad; t.x = pos[i].x + pad; t.y = pos[i].y + pad; t.scale = t.w / t.srcW })
+    return true
+  }
+  const ones = tiles.map(() => 1)
+  const done = (S: number) => ({ size: S, scale: Math.min(...tiles.map((t) => t.scale)), scaleMax: Math.max(...tiles.map((t) => t.scale)) })
+  // the smallest power-of-two square that holds everything at full resolution …
+  for (let S = 64; S <= atlasSize; S *= 2) if (place(S, ones)) return done(S)
+  if (place(atlasSize, ones)) return done(atlasSize)
+  // … else the cap, with the tiles scaled down as little as possible: one factor for all, or a texel-density
+  // budget that gives every part the same texels per metre (the density at which the densest part is native
+  // is the upper bound — above it nothing changes)
+  const scalesAt = uniform ? (x: number) => tiles.map(() => x) : (x: number) => scalesForDensity(tiles, x)
+  let lo = 0, hi = uniform ? 1 : Math.max(...tiles.map((t) => t.srcW * t.srcH * Math.max(0.02, t.uvArea) / Math.max(1e-6, t.area)))
+  for (let i = 0; i < 40; i++) { const mid = (lo + hi) / 2; if (place(atlasSize, scalesAt(mid))) lo = mid; else hi = mid }
+  if (lo === 0 || !place(atlasSize, scalesAt(lo))) return null
+  return done(atlasSize)
+}
+
+function tileKey(info: MatInfo, texId: (t: Texture) => string): string {
+  const m = info.material
+  const id = (t?: Texture) => (t ? texId(t) : '-')
+  return [
+    id(info.maps.base), m.getBaseColorFactor().map((v) => v.toFixed(4)).join(','),
+    id(info.maps.normal), m.getNormalScale().toFixed(3),
+    id(info.maps.mr), id(info.maps.occ), m.getRoughnessFactor().toFixed(3), m.getMetallicFactor().toFixed(3), m.getOcclusionStrength().toFixed(3),
+    id(info.maps.emissive), m.getEmissiveFactor().map((v) => v.toFixed(4)).join(','),
+    info.uv ? `${info.uv.u0},${info.uv.v0},${info.uv.ru},${info.uv.rv}` : '-',
+  ].join('|')
+}
+
+export function planAtlas(infos: MatInfo[], atlasSize: number, pad: number, uniform: boolean, texId: (t: Texture) => string): { layout: AtlasLayout | null; reason?: string } {
+  const anyTex = (k: keyof MatInfo['maps']) => infos.some((i) => i.maps[k])
+  const differ = (f: (m: Material) => number[]) => { const first = f(infos[0].material); return infos.some((i) => f(i.material).some((v, k) => Math.abs(v - first[k]) > 1e-4)) }
+  const maps: MapKind[] = []
+  if (anyTex('base') || differ((m) => m.getBaseColorFactor())) maps.push('base')
+  if (anyTex('normal')) maps.push('normal')
+  if (anyTex('mr') || anyTex('occ') || differ((m) => [ m.getRoughnessFactor(), m.getMetallicFactor() ])) maps.push('orm')
+  if (anyTex('emissive') || infos.some((i) => i.material.getEmissiveFactor().some((v) => v > 0))) maps.push('emissive')
+  const byKey = new Map<string, Tile>()
+  for (const info of infos) {
+    const key = tileKey(info, texId)
+    let t = byKey.get(key)
+    if (!t) {
+      const dims = Object.values(info.sizes)
+      const uv = info.uv ?? { u0: 0, v0: 0, ru: 1, rv: 1 }
+      const maxW = dims.length ? Math.max(...dims.map((d) => d[0])) : 8
+      const maxH = dims.length ? Math.max(...dims.map((d) => d[1])) : 8
+      const cap = atlasSize - 2 * pad
+      t = { key, materials: [], srcW: Math.min(cap, maxW * uv.ru), srcH: Math.min(cap, maxH * uv.rv), ...uv, area: 0, uvArea: 0, w: 0, h: 0, x: 0, y: 0, scale: 1 }
+      byKey.set(key, t)
+    }
+    t.materials.push(info.material)
+    t.area += info.area
+    t.uvArea = Math.min(1, t.uvArea + info.uvArea)
+  }
+  const tiles = [ ...byKey.values() ]
+  const fit = layoutTiles(tiles, atlasSize, pad, uniform)
+  if (!fit) return { layout: null, reason: `${tiles.length} tiles do not fit a ${atlasSize}² atlas (raise --atlas-size or lower --atlas-pad)` }
+  const hasAlpha = infos[0].material.getAlphaMode() !== 'OPAQUE'
+  return { layout: { size: fit.size, scale: fit.scale, scaleMax: fit.scaleMax, byArea: !uniform, pad, maps, tiles, hasAlpha } }
+}

package/src/doctor/merge/atlasPixels.ts

@@ -0,0 +1,114 @@
+// Atlas pixels: every tile rendered with its material's FACTORS baked in, blitted with edge
+// replication, one PNG per map kind, and the merged material that reads them.
+
+import type { Document, Material, Texture } from '@gltf-transform/core'
+import { KHRMaterialsUnlit } from '@gltf-transform/extensions'
+import sharp from 'sharp'
+import { texels } from './textures'
+import type { MapKind, MergeGroupPlan, Tile } from './types'
+
+const SRGB_TO_LINEAR = new Float32Array(256).map((_, i) => { const c = i / 255; return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4) })
+const linearToSrgb = (v: number): number => { const c = v <= 0.0031308 ? v * 12.92 : 1.055 * Math.pow(v, 1 / 2.4) - 0.055; return Math.max(0, Math.min(255, Math.round(c * 255))) }
+const clamp8 = (v: number): number => Math.max(0, Math.min(255, Math.round(v)))
+
+/** The tile's pixels for one map kind, factors baked in. */
+async function tilePixels(kind: MapKind, m: Material, t: Tile, ktxTool: string | null, cache: Map<Texture, Buffer | null>): Promise<Uint8Array> {
+  const n = t.w * t.h
+  const out = new Uint8Array(n * 4)
+  const fetch = (tex: Texture | null) => (tex ? texels(tex, t.w, t.h, t.ru, t.rv, ktxTool, cache) : Promise.resolve(null))
+  if (kind === 'base') {
+    const f = m.getBaseColorFactor()
+    const src = await fetch(m.getBaseColorTexture())
+    for (let i = 0; i < n; i++) {
+      const o = i * 4
+      if (src) {
+        for (let c = 0; c < 3; c++) out[o + c] = f[c] === 1 ? src[o + c] : linearToSrgb(SRGB_TO_LINEAR[src[o + c]] * f[c])
+        out[o + 3] = clamp8(src[o + 3] * f[3])
+      } else { out[o] = linearToSrgb(f[0]); out[o + 1] = linearToSrgb(f[1]); out[o + 2] = linearToSrgb(f[2]); out[o + 3] = clamp8(f[3] * 255) }
+    }
+  } else if (kind === 'normal') {
+    const src = await fetch(m.getNormalTexture())
+    const s = m.getNormalScale()
+    for (let i = 0; i < n; i++) {
+      const o = i * 4
+      if (src) {
+        if (s === 1) { out[o] = src[o]; out[o + 1] = src[o + 1]; out[o + 2] = src[o + 2] }
+        else {
+          const x = (src[o] / 255 * 2 - 1) * s, y = (src[o + 1] / 255 * 2 - 1) * s, z = src[o + 2] / 255 * 2 - 1
+          const l = Math.hypot(x, y, z) || 1
+          out[o] = clamp8((x / l * 0.5 + 0.5) * 255); out[o + 1] = clamp8((y / l * 0.5 + 0.5) * 255); out[o + 2] = clamp8((z / l * 0.5 + 0.5) * 255)
+        }
+      } else { out[o] = 128; out[o + 1] = 128; out[o + 2] = 255 }
+      out[o + 3] = 255
+    }
+  } else if (kind === 'orm') {
+    const mr = await fetch(m.getMetallicRoughnessTexture())
+    const occTex = m.getOcclusionTexture()
+    const occ = occTex === m.getMetallicRoughnessTexture() ? mr : await fetch(occTex)
+    const rough = m.getRoughnessFactor(), metal = m.getMetallicFactor(), strength = m.getOcclusionStrength()
+    for (let i = 0; i < n; i++) {
+      const o = i * 4
+      out[o] = occ ? clamp8(255 * (1 + strength * (occ[o] / 255 - 1))) : 255
+      out[o + 1] = mr ? clamp8(mr[o + 1] * rough) : clamp8(rough * 255)
+      out[o + 2] = mr ? clamp8(mr[o + 2] * metal) : clamp8(metal * 255)
+      out[o + 3] = 255
+    }
+  } else {
+    const f = m.getEmissiveFactor()
+    const src = await fetch(m.getEmissiveTexture())
+    for (let i = 0; i < n; i++) {
+      const o = i * 4
+      if (src) for (let c = 0; c < 3; c++) out[o + c] = f[c] === 1 ? src[o + c] : linearToSrgb(SRGB_TO_LINEAR[src[o + c]] * f[c])
+      else { out[o] = linearToSrgb(f[0]); out[o + 1] = linearToSrgb(f[1]); out[o + 2] = linearToSrgb(f[2]) }
+      out[o + 3] = 255
+    }
+  }
+  return out
+}
+
+/** Blit a tile into the atlas with `pad` texels of edge replication around it. */
+function blit(atlas: Uint8Array, S: number, t: Tile, pad: number, px: Uint8Array): void {
+  for (let y = t.y - pad; y < t.y + t.h + pad; y++) {
+    if (y < 0 || y >= S) continue
+    const sy = Math.max(0, Math.min(t.h - 1, y - t.y))
+    for (let x = t.x - pad; x < t.x + t.w + pad; x++) {
+      if (x < 0 || x >= S) continue
+      const sx = Math.max(0, Math.min(t.w - 1, x - t.x))
+      const si = (sy * t.w + sx) * 4, di = (y * S + x) * 4
+      atlas[di] = px[si]; atlas[di + 1] = px[si + 1]; atlas[di + 2] = px[si + 2]; atlas[di + 3] = px[si + 3]
+    }
+  }
+}
+
+export async function buildAtlas(doc: Document, g: MergeGroupPlan, ktxTool: string | null): Promise<{ material: Material; textures: Texture[]; tileOf: Map<Material, Tile> }> {
+  const a = g.atlas!
+  const S = a.size
+  const cache = new Map<Texture, Buffer | null>()
+  const tileOf = new Map<Material, Tile>()
+  for (const t of a.tiles) for (const m of t.materials) tileOf.set(m, t)
+  const textures: Texture[] = []
+  const material = doc.createMaterial(g.label).setAlphaMode(g.alphaMode).setAlphaCutoff(g.alphaCutoff).setDoubleSided(g.doubleSided)
+  if (g.unlit) material.setExtension('KHR_materials_unlit', doc.createExtension(KHRMaterialsUnlit).createUnlit())
+  for (const kind of a.maps) {
+    const atlas = new Uint8Array(S * S * 4)
+    // unused space: a neutral value per kind (mips of the border sample it)
+    const fill = kind === 'normal' ? [ 128, 128, 255, 255 ] : kind === 'orm' ? [ 255, 255, 0, 255 ] : kind === 'emissive' ? [ 0, 0, 0, 255 ] : [ 0, 0, 0, a.hasAlpha ? 0 : 255 ]
+    for (let i = 0; i < S * S; i++) atlas.set(fill, i * 4)
+    for (const t of a.tiles) blit(atlas, S, t, a.pad, await tilePixels(kind, t.materials[0], t, ktxTool, cache))
+    let pipe = sharp(Buffer.from(atlas.buffer, atlas.byteOffset, atlas.byteLength), { raw: { width: S, height: S, channels: 4 } })
+    if (kind !== 'base' || !a.hasAlpha) pipe = pipe.removeAlpha()
+    const png = new Uint8Array(await pipe.png({ compressionLevel: 6 }).toBuffer())
+    const tex = doc.createTexture(`${g.label}_${kind}`).setImage(png).setMimeType('image/png')
+    textures.push(tex)
+    if (kind === 'base') material.setBaseColorTexture(tex).setBaseColorFactor([ 1, 1, 1, 1 ])
+    else if (kind === 'normal') material.setNormalTexture(tex).setNormalScale(1)
+    else if (kind === 'orm') material.setMetallicRoughnessTexture(tex).setOcclusionTexture(tex).setRoughnessFactor(1).setMetallicFactor(1).setOcclusionStrength(1)
+    else material.setEmissiveTexture(tex).setEmissiveFactor([ 1, 1, 1 ])
+  }
+  // maps every material agreed on stay factors
+  const m0 = g.materials[0]
+  if (!a.maps.includes('base')) material.setBaseColorFactor(m0.getBaseColorFactor())
+  if (!a.maps.includes('orm')) material.setRoughnessFactor(m0.getRoughnessFactor()).setMetallicFactor(m0.getMetallicFactor())
+  if (!a.maps.includes('emissive')) material.setEmissiveFactor([ 0, 0, 0 ])
+  return { material, textures, tileOf }
+}

package/src/doctor/merge/bindSpace.ts

@@ -0,0 +1,59 @@
+// ONE bind space for several skins. Modular parts are often skinned separately, each with its own
+// inverse bind matrices; two skins can be unified when, on every joint they share, their matrices
+// differ by the SAME rigid transform D (IBM_part = IBM_canon · D) — the part was simply bound in
+// another space, and its vertices move into the canonical one by D. Different transforms per joint
+// mean the parts were bound in different POSES, and no single transform reconciles them.
+
+import type { Node, Skin } from '@gltf-transform/core'
+import { invert, isIdentity, mul, same } from './matrix'
+import type { Mat4 } from './types'
+
+const ibmAt = (skin: Skin, i: number): Mat4 => { const m = new Array<number>(16); skin.getInverseBindMatrices()!.getElement(i, m); return m }
+
+/** Skins by joint count, largest first: the one with most joints defines the canonical space. */
+export const bySize = (skins: Iterable<Skin | null>): Skin[] =>
+  [ ...new Set([ ...skins ].filter((s): s is Skin => !!s)) ].sort((a, b) => b.listJoints().length - a.listJoints().length)
+
+/**
+ * The canonical inverse bind matrix per joint over `skins` (already ordered, see `bySize`), and the
+ * skins that cannot join: no inverse bind matrices, or joints that disagree by different transforms.
+ * `verify: false` is for skins the plan already vetted: D is taken from the first shared joint.
+ */
+export function canonicalBinds(skins: Skin[], verify = true): { ibm: Map<Node, Mat4>; bad: Set<Skin> } {
+  const ibm = new Map<Node, Mat4>()
+  const bad = new Set<Skin>()
+  for (const skin of skins) {
+    if (!skin.getInverseBindMatrices()) { bad.add(skin); continue }
+    const js = skin.listJoints()
+    let D: Mat4 | null = null, ok = true
+    const own: [Node, Mat4][] = []
+    for (let i = 0; i < js.length && ok; i++) {
+      const m = ibmAt(skin, i)
+      const c = ibm.get(js[i])
+      if (!c) { own.push([ js[i], m ]); continue }
+      if (D && !verify) continue
+      const inv = invert(c)
+      if (!inv) { ok = false; break }
+      const d = mul(inv, m)
+      if (!D) D = d
+      else if (verify && !same(D, d, 1e-3)) ok = false
+    }
+    if (!ok) { bad.add(skin); continue }
+    // this skin's new joints enter the canon in the canonical space: IBM_canon = IBM_skin · D⁻¹
+    const Dinv = D ? invert(D) : null
+    for (const [ j, m ] of own) ibm.set(j, Dinv && !isIdentity(Dinv) ? mul(m, Dinv) : m)
+  }
+  return { ibm, bad }
+}
+
+/** The transform that moves a part skinned on `skin` into the canonical space (identity when it already is). */
+export function intoCanon(skin: Skin, canon: Map<Node, Mat4>): Mat4 | null {
+  const js = skin.listJoints()
+  for (let i = 0; i < js.length; i++) {
+    const c = canon.get(js[i])
+    if (!c) continue
+    const D = mul(invert(c)!, ibmAt(skin, i))
+    return isIdentity(D, 1e-6) ? null : D
+  }
+  return null
+}