lecodes-assets 0.2.1 → 2.5.0

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

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