Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
fix(kit): drop the orphaned occlusion image after ORM packing (#17)
Matthew Kissingere14bb20788c1
diff --git a/src/__tests__/kit.test.ts b/src/__tests__/kit.test.tsindex 98e6dff8..c7d6e6cd 100644--- a/src/__tests__/kit.test.ts+++ b/src/__tests__/kit.test.ts@@ -84,6 +84,34 @@ async function build() {}`;+/** A packed metallic-roughness image beside a same-size occlusion image — the pair+ * channel packing exists to merge. */+const ORM = `+const meta = { name: 'Panel', category: 'prop' };++async function build() {+ const root = createRoot('Panel');+ const mr = proceduralTexture({+ size: 64,+ usage: 'metallicRoughness',+ layers: [+ { op: 'solid', color: 0x008000 },+ { op: 'noise', colorA: 0x004000, colorB: 0x00c000, octaves: 3, scale: 8, blend: 'overlay' },+ ],+ });+ const ao = proceduralTexture({+ size: 64,+ usage: 'occlusion',+ layers: [+ { op: 'solid', color: 0xffffff },+ { op: 'stripes', colorA: 0x808080, colorB: 0xffffff, scale: 6, blend: 'multiply' },+ ],+ });+ root.add(createPart('Body', boxGeo(1, 1, 1), pbrMaterial({ albedo: 0x8a5a2b, metallicRoughness: mr, aoMap: ao }), {}));+ return root;+}+`;+const PALETTES: KitVariantSpec[] = [{ name: 'Rust', slots: [{ color: '#8a3b21' }, { color: '#c76a3a' }] },{ name: 'Frost', slots: [{ color: '#9fc9d8' }, { color: '#e8f2f6' }] },@@ -93,6 +121,45 @@ async function glbOf(code: string): Promise<Uint8Array> {return (await renderGLB(code, {})).glb;}+describe('ORM channel packing', () => {+ test('the occlusion image is folded in AND removed from the file', async () => {+ const original = await glbOf(ORM);+ const packed = await packKitGlb(original, { ktx2: false });++ expect(packed).toBeDefined();+ expect(packed!.summary.ormPacked).toBe(1);+ expect(packed!.gltfValidation.issues.numErrors).toBe(0);++ const before = await io().readBinary(original);+ const after = await io().readBinary(packed!.bytes);+ // The load-bearing half. gltf-transform's writer does not prune, so re-pointing the+ // material without disposing the old image leaves both in the binary chunk — the+ // material reads one texture, the file still ships two, and packing saved nothing.+ expect(before.getRoot().listTextures().length).toBe(2);+ expect(after.getRoot().listTextures().length).toBe(1);++ // Deliberately NOT a byte assertion, and this is the interesting part. The payoff+ // here is one fewer image to fetch, decode, and hold on the GPU — for a 512px pair+ // that is a megabyte of VRAM — not a smaller file. Merging a low-entropy occlusion+ // map into a noisy metallic-roughness map can cost bytes: PNG compresses flat+ // stripes to almost nothing on their own and to real bytes once interleaved with+ // noise. Measured on this 64px pair, 7032 unpacked against 7232 packed. Anyone who+ // adds a "keep the smaller" guard here the way the KTX2 step has one will decline+ // the glTF ORM convention to save 200 bytes and lose the VRAM win that motivates it.++ // Both slots now name the same image, which is what glTF's ORM convention means.+ const material = after.getRoot().listMaterials()[0];+ expect(material?.getOcclusionTexture()).toBe(material?.getMetallicRoughnessTexture() ?? null);+ });++ test('nothing to pack means no rewrite', async () => {+ // TEXTURED has one albedo image and no occlusion/metallic-roughness pair.+ const packed = await packKitGlb(await glbOf(TEXTURED), { ktx2: false });++ expect(packed).toBeUndefined();+ });+});+describe('palette colourways as KHR_materials_variants', () => {test('one file carries every palette, and the default look is unchanged', async () => {const original = await glbOf(UNTEXTURED);diff --git a/src/kit.ts b/src/kit.tsindex 87bd7318..b5e6f664 100644--- a/src/kit.ts+++ b/src/kit.ts@@ -7,7 +7,10 @@** 1. **ORM channel packing.** A separate occlusion image is folded into the R* channel of the metallic-roughness image, which is where glTF expects it.- * One fewer image to fetch and decode.+ * One fewer image to fetch, decode, and hold on the GPU — for a 512px pair+ * that is a megabyte of VRAM. Note that it is NOT reliably a byte saving: a+ * flat occlusion map that PNG compresses to nothing on its own costs real+ * bytes once interleaved with a noisy metallic-roughness map.* 2. **Palette colourways** as `KHR_materials_variants`, so one file carries* every look instead of one file per look.* 3. **KTX2 supercompression** via `KHR_texture_basisu`. Measured at -80% to@@ -123,6 +126,22 @@ export function resetKtxEncoderProbe(): void {const isPng = (texture: Texture): boolean => texture.getMimeType() === 'image/png';+/**+ * Drop a texture nothing points at any more.+ *+ * gltf-transform's writer does NOT prune unreferenced properties — an image left+ * behind by a re-point is still serialized into the binary chunk. Without this the+ * whole point of channel packing is lost: the material would read one image while+ * the FILE still carried two, so the saving would be a claim rather than a fact.+ *+ * `listParents()` always includes the document Root, which is bookkeeping and not a+ * reference; anything else means something still uses the texture.+ */+function disposeIfOrphaned(texture: Texture): void {+ const stillUsed = texture.listParents().some((parent) => parent.propertyType !== 'Root');+ if (!stillUsed) texture.dispose();+}+/*** Fold occlusion into metallic-roughness R.*@@ -159,13 +178,23 @@ async function packOcclusionIntoMetallicRoughness(doc: Document): Promise<numbercontinue;}- // R <- occlusion R, G/B (roughness/metalness) untouched.- const merged = Buffer.from(mrImage.data);- for (let i = 0; i < merged.length; i += 4) merged[i] = occImage.data[i] ?? 255;- const png = await sharp(merged, {- raw: { width: mrImage.info.width, height: mrImage.info.height, channels: 4 },- })- .png()+ // R <- occlusion R, G/B (roughness/metalness) untouched, and NO alpha channel.+ //+ // Three channels, not four, is the difference between this pass saving bytes and+ // costing them. glTF's ORM convention uses R/G/B only, so the alpha `ensureAlpha`+ // added for a uniform stride is pure padding once merged — and a fourth constant+ // channel plus default PNG compression made the merged image larger than the two+ // separate images it replaced. Measured on a 64px pair: 7512 bytes at RGBA/level 6+ // against 7032 for the unpacked original.+ const { width, height } = mrImage.info;+ const merged = Buffer.allocUnsafe(width * height * 3);+ for (let i = 0, o = 0; o < merged.length; i += 4, o += 3) {+ merged[o] = occImage.data[i] ?? 255;+ merged[o + 1] = mrImage.data[i + 1] ?? 255;+ merged[o + 2] = mrImage.data[i + 2] ?? 255;+ }+ const png = await sharp(merged, { raw: { width, height, channels: 3 } })+ .png({ compressionLevel: 9 }).toBuffer();metallicRoughness.setImage(new Uint8Array(png));@@ -173,13 +202,13 @@ async function packOcclusionIntoMetallicRoughness(doc: Document): Promise<numberconst info = material.getOcclusionTextureInfo();const mrInfo = material.getMetallicRoughnessTextureInfo();if (info && mrInfo) info.setTexCoord(mrInfo.getTexCoord());+ disposeIfOrphaned(occlusion);packed += 1;} catch {// A texture we cannot decode stays as it is. The file is still valid.}}- // Any occlusion image left with no reference is dropped by the writer.return packed;}