Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

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.ts
index 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.ts
index 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<number
continue;
}
- // 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<number
const 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;
}