lecodes-assets 0.2.1 → 2.4.10

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

package/src/doctor/merge/plan.ts

@@ -0,0 +1,88 @@
+// The plan: classify, group by what one draw cannot mix, check the skins can be unified, lay the atlases out.
+
+import type { Document, Material, Node, Texture } from '@gltf-transform/core'
+import { planAtlas } from './atlasLayout'
+import { bySize, canonicalBinds } from './bindSpace'
+import { classify, classSuffix, materialInfo, measureSurface, type MatInfo } from './classify'
+import { readAttr } from './accessors'
+import { findKtxTool, isKtx2 } from './textures'
+import { DEFAULT_ATLAS_PAD, DEFAULT_ATLAS_SIZE, type AtlasLayout, type Kind, type Mat4, type MergeGroupPlan, type MergeOptions, type MergePlan, type Source } from './types'
+
+export async function planMerge(doc: Document, opts: MergeOptions): Promise<MergePlan> {
+  const atlasSize = Math.max(64, Math.round(opts.atlasSize ?? DEFAULT_ATLAS_SIZE))
+  const pad = Math.max(0, Math.round(opts.atlasPad ?? DEFAULT_ATLAS_PAD))
+  const exclude = opts.mergeExclude ? new RegExp(opts.mergeExclude) : null
+  const root = doc.getRoot()
+  const primitivesBefore = root.listMeshes().reduce((n, m) => n + m.listPrimitives().length, 0)
+  const materialsBefore = root.listMaterials().length
+  const empty: MergePlan = { enabled: false, atlasSize, pad, groups: [], skipped: [], primitivesBefore, materialsBefore, primitivesAfter: primitivesBefore, joints: 0, ktxTool: null }
+  if (primitivesBefore < 2) return empty
+  const { sources, skipped } = classify(doc, exclude)
+  if (!sources.length) return { ...empty, skipped }
+
+  // material infos (UV ranges over the candidate primitives)
+  const uvOf = (m: Material): number[][] => sources.filter((s) => s.material === m).map((s) => { const a = s.prim.getAttribute('TEXCOORD_0'); return a ? Array.from(readAttr(a).data) : [] })
+  const texId = (t: Texture): string => String(root.listTextures().indexOf(t))
+  const wm = new Map<Node, Mat4>()
+  const measure = (m: Material) => measureSurface(sources.filter((x) => x.material === m), wm)
+  const infos = new Map<Material, MatInfo>()
+  for (const s of sources) if (s.material && !infos.has(s.material)) infos.set(s.material, await materialInfo(s.material, root.listMaterials().indexOf(s.material), uvOf, measure))
+
+  // KTX2 sources need the ktx tool — checked once, only when some candidate map is KTX2
+  const needsKtx = [ ...infos.values() ].some((i) => Object.values(i.maps).some((t) => isKtx2(t)))
+  const ktxTool = needsKtx ? findKtxTool() : null
+
+  // group by family × material class
+  const groupsMap = new Map<string, Source[]>()
+  for (const s of sources) {
+    const family = s.kind === 'static' ? 'static' : 'skinned'
+    const cls = s.material ? infos.get(s.material)!.classKey : 'OPAQUE||0|0'
+    const key = `${family}|${cls}`
+    const list = groupsMap.get(key) ?? []
+    list.push(s)
+    groupsMap.set(key, list)
+  }
+  // skinned family: can every skin join one bind space? (against the skin with most joints)
+  const badSkins = canonicalBinds(bySize(sources.filter((x) => x.kind !== 'static').map((x) => x.skin))).bad
+  const groups: MergeGroupPlan[] = []
+  let kept = 0
+  const usedLabels = new Set<string>()
+  for (const [ key, list ] of groupsMap) {
+    const family = key.startsWith('static') ? 'static' : 'skinned'
+    const usable = list.filter((s) => { if (s.skin && badSkins.has(s.skin)) { skipped.push({ name: s.name, reason: 'bind spaces differ per joint (skin cannot be unified)' }); return false } return true })
+    if (usable.length < 2) { kept += usable.length; continue }
+    // skinned parts first (the merged node is placed where the first one sat), then rigid, then static
+    const rank: Record<Kind, number> = { skinned: 0, rigid: 1, static: 2 }
+    usable.sort((x, y) => rank[x.kind] - rank[y.kind])
+    const mats = [ ...new Set(usable.map((s) => s.material).filter((m): m is Material => !!m)) ]
+    const first = mats[0]
+    let label = family === 'static' && groupsMap.size > 1 && [ ...groupsMap.keys() ].some((k) => k.startsWith('skinned')) ? 'merged.static' : 'merged'
+    if (first) {
+      const info = infos.get(first)!
+      const suffix = info.own ? (first.getName() || 'material').replace(/[^\w.-]+/g, '_') : classSuffix(first)
+      if (suffix) label = `${label}.${suffix}`
+    }
+    while (usedLabels.has(label)) label += '_'
+    usedLabels.add(label)
+    let atlas: AtlasLayout | null = null
+    let note: string | undefined
+    if (mats.length > 1) {
+      const minfos = mats.map((m) => infos.get(m)!)
+      const ktxNeeded = minfos.some((i) => Object.values(i.maps).some((t) => isKtx2(t)))
+      if (ktxNeeded && !ktxTool) { skipped.push({ name: label, reason: `${mats.length} materials carry KTX2 textures and the ktx tool was not found (KTX-Software, next to toktx)` }); kept += usable.length; continue }
+      const a = planAtlas(minfos, atlasSize, pad, !!opts.atlasUniform, texId)
+      if (!a.layout) { skipped.push({ name: label, reason: a.reason! }); kept += usable.length; continue }
+      atlas = a.layout
+    } else if (first && infos.get(first)!.own) note = infos.get(first)!.own!
+    const jointSet = new Set<Node>()
+    for (const s of usable) { if (s.skin) for (const j of s.skin.listJoints()) jointSet.add(j); if (s.joint) jointSet.add(s.joint) }
+    groups.push({
+      label, family, sources: usable, materials: mats, atlas,
+      alphaMode: first?.getAlphaMode() ?? 'OPAQUE', alphaCutoff: first?.getAlphaCutoff() ?? 0.5, doubleSided: first?.getDoubleSided() ?? false, unlit: !!first?.getExtension('KHR_materials_unlit'),
+      joints: jointSet.size, note,
+    })
+  }
+  const inGroups = groups.reduce((n, g) => n + g.sources.length, 0)
+  const primitivesAfter = primitivesBefore - inGroups + groups.length
+  return { enabled: !!opts.merge && groups.length > 0, atlasSize, pad, groups, skipped, primitivesBefore, materialsBefore, primitivesAfter, joints: Math.max(0, ...groups.map((g) => g.joints)), ktxTool }
+}

package/src/doctor/merge/textures.ts

@@ -0,0 +1,60 @@
+// Reading the parts' textures: sizes without decoding, pixels at a tile's size — a Basis KTX2 goes
+// back to PNG through KTX-Software's `ktx extract`.
+
+import type { Texture } from '@gltf-transform/core'
+import sharp from 'sharp'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { checkToktx, findKtxCli } from '../transcodeKtx2'
+
+export function findKtxTool(): string | null {
+  const ktx = findKtxCli()
+  return checkToktx(ktx) ? ktx : null
+}
+
+export const isKtx2 = (t: Texture): boolean => (t.getMimeType() || '').includes('ktx2')
+
+/** Pixel size of a texture without decoding it: the KTX2 header, or sharp's metadata. */
+export async function imageSize(t: Texture): Promise<[number, number] | null> {
+  const img = t.getImage()
+  if (!img) return null
+  if (isKtx2(t)) {
+    if (img.length < 28) return null
+    const dv = new DataView(img.buffer, img.byteOffset, img.byteLength)
+    return [ dv.getUint32(20, true), dv.getUint32(24, true) ]
+  }
+  try { const m = await sharp(Buffer.from(img)).metadata(); return m.width && m.height ? [ m.width, m.height ] : null } catch { return null }
+}
+
+/** Encoded bytes sharp can read for a texture (a KTX2 goes through `ktx extract`). */
+export async function decodable(tex: Texture, ktxTool: string | null, cache: Map<Texture, Buffer | null>): Promise<Buffer | null> {
+  if (cache.has(tex)) return cache.get(tex)!
+  const img = tex.getImage()
+  let out: Buffer | null = null
+  if (img && !isKtx2(tex)) out = Buffer.from(img)
+  else if (img && ktxTool) {
+    const dir = mkdtempSync(join(tmpdir(), 'glbatlas-'))
+    try {
+      const inK = join(dir, 'in.ktx2'), outP = join(dir, 'out.png')
+      writeFileSync(inK, img)
+      const p = spawnSync(ktxTool, [ 'extract', '--transcode', 'rgba8', inK, outP ], { encoding: 'utf8' })
+      if (p.status === 0 && existsSync(outP)) out = readFileSync(outP)
+    } finally { rmSync(dir, { recursive: true, force: true }) }
+  }
+  cache.set(tex, out)
+  return out
+}
+
+/** A texture as RGBA at exactly w×h (tiled `ru`×`rv` times), or null when it cannot be read. */
+export async function texels(tex: Texture, w: number, h: number, ru: number, rv: number, ktxTool: string | null, cache: Map<Texture, Buffer | null>): Promise<Uint8Array | null> {
+  const bytes = await decodable(tex, ktxTool, cache)
+  if (!bytes) return null
+  const cw = Math.max(1, Math.round(w / ru)), ch = Math.max(1, Math.round(h / rv))
+  const cell = new Uint8Array(await sharp(bytes).resize({ width: cw, height: ch, fit: 'fill', kernel: 'lanczos3' }).ensureAlpha().raw().toBuffer())
+  if (ru === 1 && rv === 1 && cw === w && ch === h) return cell
+  const out = new Uint8Array(w * h * 4)
+  for (let y = 0; y < h; y++) { const sy = y % ch; for (let x = 0; x < w; x++) { const sx = x % cw; const si = (sy * cw + sx) * 4, di = (y * w + x) * 4; out[di] = cell[si]; out[di + 1] = cell[si + 1]; out[di + 2] = cell[si + 2]; out[di + 3] = cell[si + 3] } }
+  return out
+}