lecodes-assets 0.2.0 → 2.4.10

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
+}

package/src/doctor/merge/classify.ts

@@ -0,0 +1,136 @@
+// Which primitives can merge (and as what), and what each material brings to an atlas.
+
+import type { Document, Material, Node, Primitive, Texture, TextureInfo } from '@gltf-transform/core'
+import { readAttr, readIndices } from './accessors'
+import { I4, point, worldMatrix } from './matrix'
+import { imageSize } from './textures'
+import type { Kind, Mat4, MergeSkipped, Source } from './types'
+
+export interface MatInfo {
+  material: Material
+  classKey: string
+  /** why the material cannot share an atlas (own group) */
+  own: string | null
+  maps: Partial<Record<'base' | 'normal' | 'mr' | 'occ' | 'emissive', Texture>>
+  sizes: Partial<Record<'base' | 'normal' | 'mr' | 'occ' | 'emissive', [number, number]>>
+  /** UV range over every candidate primitive using it */
+  uv: { u0: number; v0: number; ru: number; rv: number } | null
+  /** surface on the model and UV coverage (fraction of the [u0,u0+ru)×[v0,v0+rv) rectangle) */
+  area: number; uvArea: number
+}
+
+const UV_EPS = 2e-3
+const MAX_REPEAT = 4
+
+export const classSuffix = (m: Material): string => {
+  const parts: string[] = []
+  if (m.getAlphaMode() === 'BLEND') parts.push('blend')
+  if (m.getAlphaMode() === 'MASK') parts.push('mask')
+  if (m.getDoubleSided()) parts.push('2side')
+  if (m.getExtension('KHR_materials_unlit')) parts.push('unlit')
+  return parts.join('.')
+}
+
+function texInfos(m: Material): TextureInfo[] {
+  return [ m.getBaseColorTextureInfo(), m.getNormalTextureInfo(), m.getMetallicRoughnessTextureInfo(), m.getOcclusionTextureInfo(), m.getEmissiveTextureInfo() ].filter((t): t is TextureInfo => !!t)
+}
+
+export async function materialInfo(m: Material, ownId: number, uvOf: (m: Material) => number[][], measure: (m: Material) => { area: number; uvArea: number }): Promise<MatInfo> {
+  const maps: MatInfo['maps'] = {}
+  if (m.getBaseColorTexture()) maps.base = m.getBaseColorTexture()!
+  if (m.getNormalTexture()) maps.normal = m.getNormalTexture()!
+  if (m.getMetallicRoughnessTexture()) maps.mr = m.getMetallicRoughnessTexture()!
+  if (m.getOcclusionTexture()) maps.occ = m.getOcclusionTexture()!
+  if (m.getEmissiveTexture()) maps.emissive = m.getEmissiveTexture()!
+  const sizes: MatInfo['sizes'] = {}
+  for (const k of Object.keys(maps) as (keyof MatInfo['maps'])[]) { const s = await imageSize(maps[k]!); if (s) sizes[k] = s }
+  let own: string | null = null
+  const exts = m.listExtensions().map((e) => e.extensionName).filter((n) => n !== 'KHR_materials_unlit')
+  if (exts.length) own = `material extension ${exts.join(', ')}`
+  else if (texInfos(m).some((i) => i.getExtension('KHR_texture_transform'))) own = 'KHR_texture_transform'
+  else if ((Object.keys(maps) as (keyof MatInfo['maps'])[]).some((k) => !sizes[k])) own = 'a texture could not be read'
+  // UV range: every primitive of the material, over all its texture-using channels (one UV set: TEXCOORD_0)
+  let uv: MatInfo['uv'] = null
+  if (Object.keys(maps).length) {
+    let umin = Infinity, umax = -Infinity, vmin = Infinity, vmax = -Infinity
+    for (const arr of uvOf(m)) for (let i = 0; i < arr.length; i += 2) { umin = Math.min(umin, arr[i]); umax = Math.max(umax, arr[i]); vmin = Math.min(vmin, arr[i + 1]); vmax = Math.max(vmax, arr[i + 1]) }
+    if (umin === Infinity) uv = { u0: 0, v0: 0, ru: 1, rv: 1 }
+    else {
+      const inUnit = umin >= -UV_EPS && umax <= 1 + UV_EPS && vmin >= -UV_EPS && vmax <= 1 + UV_EPS
+      if (inUnit) uv = { u0: 0, v0: 0, ru: 1, rv: 1 }
+      else {
+        const u0 = Math.floor(umin + UV_EPS), v0 = Math.floor(vmin + UV_EPS)
+        const ru = Math.ceil(umax - UV_EPS) - u0, rv = Math.ceil(vmax - UV_EPS) - v0
+        if (ru <= MAX_REPEAT && rv <= MAX_REPEAT && ru >= 1 && rv >= 1) uv = { u0, v0, ru, rv }
+        else if (!own) own = `UVs tile the texture ${Math.max(ru, rv)}×`
+      }
+    }
+  }
+  const classKey = own ? `own:${ownId}` : `${m.getAlphaMode()}|${m.getAlphaMode() === 'MASK' ? m.getAlphaCutoff().toFixed(3) : ''}|${m.getDoubleSided() ? 1 : 0}|${m.getExtension('KHR_materials_unlit') ? 1 : 0}`
+  const { area, uvArea } = measure(m)
+  const span = uv ? uv.ru * uv.rv : 1
+  return { material: m, classKey, own, maps, sizes, uv, area, uvArea: uvArea / span }
+}
+
+const primTris = (p: Primitive): number => Math.floor((p.getIndices()?.getCount() ?? p.getAttribute('POSITION')?.getCount() ?? 0) / 3)
+
+/** Every mergeable primitive with its kind, and the reasons for the rest. */
+export function classify(doc: Document, exclude: RegExp | null): { sources: Source[]; skipped: MergeSkipped[]; joints: Set<Node>; animated: Set<Node> } {
+  const root = doc.getRoot()
+  const joints = new Set<Node>(root.listSkins().flatMap((s) => s.listJoints()))
+  const animated = new Set<Node>()
+  for (const a of root.listAnimations()) for (const c of a.listChannels()) { const n = c.getTargetNode(); if (n) animated.add(n) }
+  const sources: Source[] = []
+  const skipped: MergeSkipped[] = []
+  const seen = new Set<Node>()
+  for (const scene of root.listScenes()) scene.traverse((node) => {
+    if (seen.has(node)) return
+    seen.add(node)
+    const mesh = node.getMesh()
+    if (!mesh) return
+    const name = node.getName() || mesh.getName() || 'mesh'
+    if (exclude && (exclude.test(node.getName()) || exclude.test(mesh.getName()))) { skipped.push({ name, reason: 'excluded' }); return }
+    // the chain up to the nearest joint (a rigid part) or the root (a static part)
+    let kind: Kind = node.getSkin() ? 'skinned' : 'static'
+    let joint: Node | null = null
+    if (kind !== 'skinned') {
+      for (let n: Node | null = node; n; n = n.getParentNode()) {
+        if (joints.has(n)) { joint = n; break }
+        if (animated.has(n)) { skipped.push({ name, reason: `animated node${n === node ? '' : ` (${n.getName()})`}` }); return }
+      }
+      if (joint) kind = 'rigid'
+    }
+    for (const prim of mesh.listPrimitives()) {
+      const pname = mesh.listPrimitives().length > 1 ? `${name}[${mesh.listPrimitives().indexOf(prim)}]` : name
+      if (prim.getMode() !== 4) { skipped.push({ name: pname, reason: 'not triangles' }); continue }
+      if (!prim.getAttribute('POSITION')) { skipped.push({ name: pname, reason: 'no positions' }); continue }
+      if (prim.listTargets().length) { skipped.push({ name: pname, reason: 'morph targets' }); continue }
+      if (kind === 'skinned' && (!prim.getAttribute('JOINTS_0') || !prim.getAttribute('WEIGHTS_0'))) { skipped.push({ name: pname, reason: 'skinned node without joints/weights' }); continue }
+      sources.push({ node, mesh, prim, kind, skin: node.getSkin(), joint, name: pname, material: prim.getMaterial(), triangles: primTris(prim) })
+    }
+  })
+  return { sources, skipped, joints, animated }
+}
+
+/** Surface area on the model (bind space for skinned parts, the rest pose for rigid / static ones) and
+ *  how much of the UV square the triangles cover — the texel-density budget of the atlas packer. */
+export function measureSurface(sources: Source[], worldCache: Map<Node, Mat4>): { area: number; uvArea: number } {
+  let area = 0, uvArea = 0
+  for (const s of sources) {
+    const M = s.kind === 'skinned' ? I4 : worldMatrix(s.node, worldCache)
+    const pos = readAttr(s.prim.getAttribute('POSITION')!).data
+    const uvAcc = s.prim.getAttribute('TEXCOORD_0')
+    const uv = uvAcc ? readAttr(uvAcc).data : null
+    const idx = readIndices(s.prim)
+    for (let t = 0; t + 2 < idx.length; t += 3) {
+      const [ a, b, c ] = [ idx[t], idx[t + 1], idx[t + 2] ].map((i) => point(M, [ pos[i * 3], pos[i * 3 + 1], pos[i * 3 + 2] ]))
+      const ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2], vx = c[0] - a[0], vy = c[1] - a[1], vz = c[2] - a[2]
+      area += 0.5 * Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx)
+      if (uv) {
+        const i0 = idx[t] * 2, i1 = idx[t + 1] * 2, i2 = idx[t + 2] * 2
+        uvArea += 0.5 * Math.abs((uv[i1] - uv[i0]) * (uv[i2 + 1] - uv[i0 + 1]) - (uv[i2] - uv[i0]) * (uv[i1 + 1] - uv[i0 + 1]))
+      }
+    }
+  }
+  return { area, uvArea }
+}

package/src/doctor/merge/geometry.ts

@@ -0,0 +1,167 @@
+// The merged primitive: every source's vertices moved into one space (world for static parts, the
+// canonical bind space for skinned / rigid ones), UVs remapped into the atlas, one union skin.
+
+import type { Accessor, Document, Material, Node, Primitive, Skin } from '@gltf-transform/core'
+import { flatNormals, readAttr, readIndices } from './accessors'
+import { bySize, canonicalBinds, intoCanon } from './bindSpace'
+import { I4, det3, dir, invert, localMatrix, mul, normalMatrix, point, worldMatrix } from './matrix'
+import type { AtlasLayout, Mat4, MergeGroupPlan, Source, Tile } from './types'
+
+interface UnionSkin { skin: Skin; index: Map<Node, number>; ibm: Map<Node, Mat4>; bindSpace: Mat4 }
+
+/** One skin over every joint the group touches, inverse bind matrices in one canonical space. */
+function unionSkin(doc: Document, g: MergeGroupPlan): UnionSkin {
+  const root = doc.getRoot()
+  const skins = bySize(g.sources.map((s) => s.skin))
+  const { ibm } = canonicalBinds(skins, false)         // the plan kept only skins that can be unified
+  const cache = new Map<Node, Mat4>()
+  const lead = skins[0]?.listJoints()[0]
+  const bindSpace: Mat4 = lead ? mul(worldMatrix(lead, cache), ibm.get(lead)!) : I4
+  // a rigid part's joint that no skin of the group lists: any skin of the file that has it, else the rest pose
+  for (const s of g.sources) {
+    if (!s.joint || ibm.has(s.joint)) continue
+    let found: Mat4 | null = null
+    for (const skin of root.listSkins()) {
+      const i = skin.listJoints().indexOf(s.joint)
+      const acc = skin.getInverseBindMatrices()
+      if (i >= 0 && acc) { const m = new Array<number>(16); acc.getElement(i, m); found = m; break }
+    }
+    ibm.set(s.joint, found ?? mul(invert(worldMatrix(s.joint, cache)) ?? I4, bindSpace))
+  }
+  // joints in tree order
+  const ordered: Node[] = []
+  const seen = new Set<Node>()
+  for (const scene of root.listScenes()) scene.traverse((n) => { if (ibm.has(n) && !seen.has(n)) { seen.add(n); ordered.push(n) } })
+  for (const j of ibm.keys()) if (!seen.has(j)) { seen.add(j); ordered.push(j) }
+  const index = new Map<Node, number>(ordered.map((j, i) => [ j, i ]))
+  const mats = new Float32Array(ordered.length * 16)
+  ordered.forEach((j, i) => mats.set(ibm.get(j)!, i * 16))
+  const buffer = root.listBuffers()[0] ?? doc.createBuffer()
+  const skin = doc.createSkin(g.label).setInverseBindMatrices(doc.createAccessor(`${g.label}_ibm`).setType('MAT4').setArray(mats).setBuffer(buffer))
+  for (const j of ordered) skin.addJoint(j)
+  const skel = skins[0]?.getSkeleton()
+  if (skel) skin.setSkeleton(skel)
+  return { skin, index, ibm, bindSpace }
+}
+
+/** Where a source's vertices go: the transform into the merged primitive's space. */
+function sourceTransform(s: Source, u: UnionSkin | null, cache: Map<Node, Mat4>): Mat4 {
+  if (s.kind === 'static') return worldMatrix(s.node, cache)
+  if (s.kind === 'rigid') {
+    // world = J(t) · IBM_j · p'  must equal  J(t) · L · p  (L = the chain from the joint down to the node)
+    let L: Mat4 = I4
+    const chain: Node[] = []
+    for (let n: Node | null = s.node; n && n !== s.joint; n = n.getParentNode()) chain.unshift(n)
+    for (const n of chain) L = mul(L, localMatrix(n))
+    return mul(invert(u!.ibm.get(s.joint!)!) ?? I4, L)
+  }
+  // skinned: the part's bind space → the canonical one (D = IBM_canon⁻¹ · IBM_part, same for every shared joint)
+  return intoCanon(s.skin!, u!.ibm) ?? I4
+}
+
+export function mergeGroup(doc: Document, g: MergeGroupPlan, tileOf: Map<Material, Tile> | null, atlas: AtlasLayout | null, material: Material | null): { node: Node; vertices: number; triangles: number } {
+  const root = doc.getRoot()
+  const buffer = root.listBuffers()[0] ?? doc.createBuffer()
+  const cache = new Map<Node, Mat4>()
+  const u = g.family === 'skinned' ? unionSkin(doc, g) : null
+  const has = (sem: string) => g.sources.map((s) => !!s.prim.getAttribute(sem))
+  const wantTangent = has('TANGENT').every(Boolean)
+  const wantUv1 = has('TEXCOORD_1').every(Boolean)
+  const wantColor = has('COLOR_0').some(Boolean)
+  const wantJ1 = u ? has('JOINTS_1').some(Boolean) : false
+  const total = g.sources.reduce((n, s) => n + s.prim.getAttribute('POSITION')!.getCount(), 0)
+  const P = new Float32Array(total * 3), N = new Float32Array(total * 3), UV = new Float32Array(total * 2)
+  const T = wantTangent ? new Float32Array(total * 4) : null
+  const UV1 = wantUv1 ? new Float32Array(total * 2) : null
+  const C = wantColor ? new Float32Array(total * 4).fill(1) : null
+  const J = u ? new Uint16Array(total * 4) : null, W = u ? new Float32Array(total * 4) : null
+  const J1 = wantJ1 ? new Uint16Array(total * 4) : null, W1 = wantJ1 ? new Float32Array(total * 4) : null
+  const indices: number[] = []
+  let base = 0
+  for (const s of g.sources) {
+    const prim = s.prim
+    const count = prim.getAttribute('POSITION')!.getCount()
+    const M = sourceTransform(s, u, cache)
+    const n3 = normalMatrix(M)
+    const flip = det3(M) < 0
+    const pos = readAttr(prim.getAttribute('POSITION')!).data
+    const idx = readIndices(prim)
+    const nrmAcc = prim.getAttribute('NORMAL')
+    const nrm = nrmAcc ? readAttr(nrmAcc).data : flatNormals(pos, idx)
+    const uvAcc = prim.getAttribute('TEXCOORD_0')
+    const uv = uvAcc ? readAttr(uvAcc).data : null
+    const tile = s.material && tileOf ? tileOf.get(s.material) ?? null : null
+    const S = atlas?.size ?? 1
+    for (let i = 0; i < count; i++) {
+      const p = point(M, [ pos[i * 3], pos[i * 3 + 1], pos[i * 3 + 2] ])
+      P[(base + i) * 3] = p[0]; P[(base + i) * 3 + 1] = p[1]; P[(base + i) * 3 + 2] = p[2]
+      const nn = dir(n3, [ nrm[i * 3], nrm[i * 3 + 1], nrm[i * 3 + 2] ])
+      N[(base + i) * 3] = nn[0]; N[(base + i) * 3 + 1] = nn[1]; N[(base + i) * 3 + 2] = nn[2]
+      let uu = uv ? uv[i * 2] : 0.5, vv = uv ? uv[i * 2 + 1] : 0.5
+      if (tile) {
+        // into the tile: [u0, u0 + ru) → [x, x + w) of an S-wide atlas (clamped to the tile's own texels)
+        const fu = Math.max(0, Math.min(1, (uu - tile.u0) / tile.ru)), fv = Math.max(0, Math.min(1, (vv - tile.v0) / tile.rv))
+        uu = (tile.x + fu * tile.w) / S; vv = (tile.y + fv * tile.h) / S
+      }
+      UV[(base + i) * 2] = uu; UV[(base + i) * 2 + 1] = vv
+    }
+    if (T) {
+      const t = readAttr(prim.getAttribute('TANGENT')!)
+      for (let i = 0; i < count; i++) {
+        const el = t.size === 4 ? [ t.data[i * 4], t.data[i * 4 + 1], t.data[i * 4 + 2], t.data[i * 4 + 3] ] : [ t.data[i * 3], t.data[i * 3 + 1], t.data[i * 3 + 2], 1 ]
+        const d = dir(n3, el)
+        T[(base + i) * 4] = d[0]; T[(base + i) * 4 + 1] = d[1]; T[(base + i) * 4 + 2] = d[2]; T[(base + i) * 4 + 3] = flip ? -el[3] : el[3]
+      }
+    }
+    if (UV1) UV1.set(readAttr(prim.getAttribute('TEXCOORD_1')!).data, base * 2)
+    if (C) {
+      const cAcc = prim.getAttribute('COLOR_0')
+      if (cAcc) { const c = readAttr(cAcc); for (let i = 0; i < count; i++) for (let k = 0; k < 4; k++) C[(base + i) * 4 + k] = k < c.size ? c.data[i * c.size + k] : 1 }
+    }
+    if (J && W) {
+      if (s.kind === 'skinned') {
+        const remap = s.skin!.listJoints().map((j) => u!.index.get(j) ?? 0)
+        const readSet = (n: number, Jo: Uint16Array, Wo: Float32Array) => {
+          const ja = readAttr(prim.getAttribute(`JOINTS_${n}`)!).data, wa = readAttr(prim.getAttribute(`WEIGHTS_${n}`)!).data
+          for (let i = 0; i < count * 4; i++) { Jo[base * 4 + i] = remap[ja[i]] ?? 0; Wo[base * 4 + i] = wa[i] }
+        }
+        readSet(0, J, W)
+        if (J1 && W1 && prim.getAttribute('JOINTS_1')) readSet(1, J1, W1)
+      } else {
+        const ji = u!.index.get(s.joint!) ?? 0
+        for (let i = 0; i < count; i++) { J[(base + i) * 4] = ji; W[(base + i) * 4] = 1 }
+      }
+    }
+    for (let t = 0; t + 2 < idx.length; t += 3) {
+      if (flip) indices.push(base + idx[t], base + idx[t + 2], base + idx[t + 1])
+      else indices.push(base + idx[t], base + idx[t + 1], base + idx[t + 2])
+    }
+    base += count
+  }
+  const acc = (name: string, type: 'SCALAR' | 'VEC2' | 'VEC3' | 'VEC4', arr: Float32Array | Uint16Array | Uint8Array | Uint32Array) => doc.createAccessor(`${g.label}_${name}`).setType(type).setArray(arr as never).setBuffer(buffer)
+  const prim = doc.createPrimitive().setMode(4)
+    .setAttribute('POSITION', acc('pos', 'VEC3', P))
+    .setAttribute('NORMAL', acc('nrm', 'VEC3', N))
+    .setAttribute('TEXCOORD_0', acc('uv', 'VEC2', UV))
+  if (T) prim.setAttribute('TANGENT', acc('tan', 'VEC4', T))
+  if (UV1) prim.setAttribute('TEXCOORD_1', acc('uv1', 'VEC2', UV1))
+  if (C) prim.setAttribute('COLOR_0', acc('col', 'VEC4', C))
+  if (J && W) {
+    prim.setAttribute('JOINTS_0', acc('j0', 'VEC4', u!.index.size <= 256 ? Uint8Array.from(J) : J)).setAttribute('WEIGHTS_0', acc('w0', 'VEC4', W))
+    if (J1 && W1) prim.setAttribute('JOINTS_1', acc('j1', 'VEC4', u!.index.size <= 256 ? Uint8Array.from(J1) : J1)).setAttribute('WEIGHTS_1', acc('w1', 'VEC4', W1))
+  }
+  prim.setIndices(acc('idx', 'SCALAR', total > 65535 ? Uint32Array.from(indices) : Uint16Array.from(indices)))
+  prim.setMaterial(material ?? g.materials[0] ?? null)
+  const mesh = doc.createMesh(g.label).addPrimitive(prim)
+  const node = doc.createNode(g.label).setMesh(mesh)
+  if (u) {
+    node.setSkin(u.skin)
+    // where the canonical part sat (the spec ignores a skinned node's transform; a host that reads it sees the same)
+    const first = g.sources.find((s) => s.kind === 'skinned')?.node
+    const parent = first?.getParentNode()
+    if (first) node.setTranslation(first.getTranslation()).setRotation(first.getRotation()).setScale(first.getScale())
+    if (parent) parent.addChild(node)
+    else (root.getDefaultScene() ?? root.listScenes()[0]).addChild(node)
+  } else (root.getDefaultScene() ?? root.listScenes()[0]).addChild(node)
+  return { node, vertices: total, triangles: indices.length / 3 }
+}

package/src/doctor/merge/index.ts

@@ -0,0 +1,98 @@
+// Mesh merging + texture atlasing (`lecodes assets doctor --merge`): fewer draw calls per model.
+//
+// A modular character arrives as a dozen parts — head, hands, shirt, pants, boots, vest, helmet,
+// pouches — each its own mesh node, its own skin (a subset of the joints) and its own material with
+// its own base / normal / ORM maps. The renderer draws one primitive per material, so the character
+// costs 16 draw calls and 45 texture binds; a squad of twelve is 200 draw calls of characters alone.
+// This pass folds all of it into ONE primitive over ONE material per compatibility class:
+//
+//   • every primitive is classified — SKINNED (on a skin), RIGID (a static mesh sitting under a joint:
+//     a hat, a strap, a holstered weapon — it is skinned to that joint with weight 1), STATIC (a plain
+//     node: its world transform is baked into the vertices); anything animated by a node channel, with
+//     morph targets, or excluded by name is left alone (reported);
+//   • primitives are grouped by what the material pipeline cannot mix in one draw: alpha mode (+ cutoff),
+//     double-sidedness, unlit; a material carrying an extension this pass does not understand, or a
+//     KHR_texture_transform, or UVs that tile the texture too far, forms a group of its own (its geometry
+//     still merges with its siblings, its textures are kept as they are);
+//   • one union SKIN per skinned group: joints in tree order, the inverse bind matrices from the skin that
+//     has most of them; a part bound in another bind space (each of its inverse bind matrices differs from
+//     the canonical one by the same rigid transform) is moved into the canonical space; a part whose joints
+//     disagree by different transforms is skipped;
+//   • one ATLAS per map kind (base colour, normal, packed occlusion-roughness-metallic, emissive) per group:
+//     every material gets a tile sized like its largest map (materials with the same maps and factors share
+//     a tile), the tiles are shelf-packed into the smallest power-of-two square that holds them at full
+//     resolution, or scaled down to fit `--atlas-size` (default 2048) BY SURFACE AREA: each material's area
+//     on the model (its triangles in bind / world space) and its UV coverage give the texel density its tile
+//     would have, and the tiles are sized so every part lands at the same texels-per-metre — a torso keeps
+//     its map, a strap or a buckle gets the small tile it needs, never past a map's native size
+//     (`--atlas-uniform` = the plain rule instead: every tile at the same fraction); each tile is padded by
+//     `--atlas-pad` texels of edge replication (bilinear + the first mips stay clean); the material's
+//     FACTORS are baked into its tile (base colour factor in linear light, roughness / metallic into the
+//     ORM channels, normal scale, emissive factor, occlusion strength), so the merged material is factor-
+//     free and reads the same as the parts did; UVs are remapped into the tile; a material without a map
+//     gets a flat tile of its factor;
+//   • the merged primitive carries the union of the parts' attributes (positions, normals — computed for a
+//     part without any —, UVs, colours, joints / weights; tangents only when every part has them, a
+//     lightmap UV set only when every part has one), the old meshes, skins, materials, textures and empty
+//     part nodes are gone, and the new node is named `merged` (`merged.blend`, `merged.mask`, `merged.2side`,
+//     `merged.<material>` for the further classes).
+//
+// The pass runs BEFORE the texture passes: the atlases are written as PNG and picked up by `--ktx2` /
+// the size cap like any other texture — except that an atlas is capped by `--atlas-size`, not
+// `--max-size` (the per-part cap): a kit whose 15 maps were capped at 1024 each is one 4096² map now.
+// KTX2 source textures are decoded through KTX-Software's `ktx extract` (next to toktx); without the
+// tool a group holding KTX2 maps is reported and skipped.
+import type { Document, Material, Mesh, Node } from '@gltf-transform/core'
+import { buildAtlas } from './atlasPixels'
+import { mergeGroup } from './geometry'
+import type { AtlasLayout, MergePlan, MergeResult, Tile } from './types'
+
+export { planMerge } from './plan'
+export { findKtxTool } from './textures'
+export { DEFAULT_ATLAS_PAD, DEFAULT_ATLAS_SIZE } from './types'
+export type { AtlasLayout, MergeGroupPlan, MergeOptions, MergePlan, MergeResult, MergeSkipped } from './types'
+
+/** Drop what the merge replaced: the parts' primitives, meshes, skins, nodes (when empty), unused materials / textures / accessors. */
+function cleanup(doc: Document, plan: MergePlan, mergedNodes: Set<Node>): void {
+  const root = doc.getRoot()
+  const animated = new Set<Node>()
+  for (const a of root.listAnimations()) for (const c of a.listChannels()) { const n = c.getTargetNode(); if (n) animated.add(n) }
+  const joints = new Set<Node>(root.listSkins().flatMap((s) => s.listJoints()))
+  const meshes = new Set<Mesh>()
+  const nodes = new Set<Node>()
+  for (const g of plan.groups) for (const s of g.sources) { s.prim.dispose(); meshes.add(s.mesh); nodes.add(s.node) }
+  for (const m of meshes) if (!m.listPrimitives().length) m.dispose()
+  for (const n of nodes) {
+    if (mergedNodes.has(n) || n.getMesh() || joints.has(n) || animated.has(n)) continue
+    if (n.listChildren().length) continue
+    n.setSkin(null)
+    n.dispose()
+  }
+  for (const s of root.listSkins()) if (!s.listParents().some((p) => p.propertyType === 'Node')) s.dispose()
+  for (const m of root.listMaterials()) if (!m.listParents().some((p) => p.propertyType === 'Primitive')) m.dispose()
+  for (const t of root.listTextures()) if (!t.listParents().some((p) => p.propertyType !== 'Root')) t.dispose()
+  for (const a of root.listAccessors()) if (a.listParents().every((p) => p === root)) a.dispose()
+}
+
+/** "tiles at 40%" / "tiles 12–100% by area" — nothing when every tile is native. */
+export const describeScale = (a: AtlasLayout): string =>
+  a.scaleMax >= 0.999 && a.scale >= 0.999 ? '' : a.byArea && a.scaleMax - a.scale > 0.005 ? ` (tiles ${(a.scale * 100).toFixed(0)}–${(a.scaleMax * 100).toFixed(0)}% by area)` : ` (tiles at ${(a.scale * 100).toFixed(0)}%)`
+
+/** Apply the plan (mutates). The atlas textures come back as PNG for the caller's texture passes. */
+export async function applyMerge(doc: Document, plan: MergePlan): Promise<MergeResult> {
+  const res: MergeResult = { groups: [], skipped: plan.skipped, textures: [], primitivesBefore: plan.primitivesBefore, primitivesAfter: plan.primitivesAfter }
+  const mergedNodes = new Set<Node>()
+  for (const g of plan.groups) {
+    let material: Material | null = null, tileOf: Map<Material, Tile> | null = null
+    if (g.atlas) {
+      const built = await buildAtlas(doc, g, plan.ktxTool)
+      material = built.material; tileOf = built.tileOf
+      res.textures.push(...built.textures)
+    }
+    const r = mergeGroup(doc, g, tileOf, g.atlas, material)
+    mergedNodes.add(r.node)
+    res.groups.push({ label: g.label, primitives: g.sources.length, materials: g.materials.length, vertices: r.vertices, triangles: r.triangles, joints: g.joints, atlas: g.atlas ? `${g.atlas.size}² ${g.atlas.maps.join('+')}${describeScale(g.atlas)}` : null })
+  }
+  cleanup(doc, plan, mergedNodes)
+  return res
+}

package/src/doctor/merge/matrix.ts

@@ -0,0 +1,60 @@
+// A small matrix kit (column-major, like glTF).
+
+import type { Node } from '@gltf-transform/core'
+import type { Mat4 } from './types'
+
+export const I4: Mat4 = [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ]
+export const mul = (a: Mat4, b: Mat4): Mat4 => {
+  const o = new Array<number>(16).fill(0)
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3]
+  return o
+}
+export const invert = (m: Mat4): Mat4 | null => {
+  const [ a00, a01, a02, a03, a10, a11, a12, a13, a20, a21, a22, a23, a30, a31, a32, a33 ] = m
+  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-30) return null
+  det = 1 / det
+  return [
+    (a11 * b11 - a12 * b10 + a13 * b09) * det, (a02 * b10 - a01 * b11 - a03 * b09) * det, (a31 * b05 - a32 * b04 + a33 * b03) * det, (a22 * b04 - a21 * b05 - a23 * b03) * det,
+    (a12 * b08 - a10 * b11 - a13 * b07) * det, (a00 * b11 - a02 * b08 + a03 * b07) * det, (a32 * b02 - a30 * b05 - a33 * b01) * det, (a20 * b05 - a22 * b02 + a23 * b01) * det,
+    (a10 * b10 - a11 * b08 + a13 * b06) * det, (a01 * b08 - a00 * b10 - a03 * b06) * det, (a30 * b04 - a31 * b02 + a33 * b00) * det, (a21 * b02 - a20 * b04 - a23 * b00) * det,
+    (a11 * b07 - a10 * b09 - a12 * b06) * det, (a00 * b09 - a01 * b07 + a02 * b06) * det, (a31 * b01 - a30 * b03 - a32 * b00) * det, (a20 * b03 - a21 * b01 + a22 * b00) * det,
+  ]
+}
+export const isIdentity = (m: Mat4, tol = 1e-5): boolean => m.every((v, i) => Math.abs(v - I4[i]) < tol)
+export const same = (a: Mat4, b: Mat4, tol: number): boolean => a.every((v, i) => Math.abs(v - b[i]) <= tol * Math.max(1, Math.abs(v), Math.abs(b[i])))
+export const det3 = (m: Mat4): number => m[0] * (m[5] * m[10] - m[6] * m[9]) - m[4] * (m[1] * m[10] - m[2] * m[9]) + m[8] * (m[1] * m[6] - m[2] * m[5])
+/** Inverse-transpose of the upper 3×3, as a column-major 3×3 (`dir` applies it). */
+export const normalMatrix = (m: Mat4): number[] => {
+  const a = m[0], b = m[4], c = m[8], d = m[1], e = m[5], f = m[9], g = m[2], h = m[6], i = m[10]
+  const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g)
+  if (Math.abs(det) < 1e-20) return [ 1, 0, 0, 0, 1, 0, 0, 0, 1 ]
+  // inverse (row-major rows), then transposed = columns of the inverse become rows
+  const inv = [
+    (e * i - f * h) / det, (c * h - b * i) / det, (b * f - c * e) / det,
+    (f * g - d * i) / det, (a * i - c * g) / det, (c * d - a * f) / det,
+    (d * h - e * g) / det, (b * g - a * h) / det, (a * e - b * d) / det,
+  ]
+  // n' = inv^T · n → n'[r] = Σ_c inv[c*3 + r] · n[c]; stored column-major: col c = inv row c
+  return [ inv[0], inv[1], inv[2], inv[3], inv[4], inv[5], inv[6], inv[7], inv[8] ]
+}
+export const point = (m: Mat4, p: number[]): number[] => [
+  m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12], m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13], m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],
+]
+export const dir = (n3: number[], v: number[]): number[] => {
+  const x = n3[0] * v[0] + n3[3] * v[1] + n3[6] * v[2], y = n3[1] * v[0] + n3[4] * v[1] + n3[7] * v[2], z = n3[2] * v[0] + n3[5] * v[1] + n3[8] * v[2]
+  const l = Math.hypot(x, y, z) || 1
+  return [ x / l, y / l, z / l ]
+}
+export const localMatrix = (n: Node): Mat4 => Array.from(n.getMatrix() as unknown as ArrayLike<number>)
+export const worldMatrix = (n: Node, cache = new Map<Node, Mat4>()): Mat4 => {
+  const hit = cache.get(n)
+  if (hit) return hit
+  const parent = n.getParentNode()
+  const w = parent ? mul(worldMatrix(parent, cache), localMatrix(n)) : localMatrix(n)
+  cache.set(n, w)
+  return w
+}