topotopo 0.1.0 → 0.3.0

package/dist/io/export.js

@@ -168,6 +168,9 @@ export function exportPLY(g, o = {}) {
 const usdName = (s) => (s.replace(/[^A-Za-z0-9_]/g, '_').replace(/^(\d)/, '_$1') || 'mesh');
 const fmt = (n) => (Number.isInteger(n) ? String(n) : n.toFixed(6).replace(/0+$/, '').replace(/\.$/, ''));
 const tup = (a, k, n) => '(' + Array.from({ length: n }, (_, c) => fmt(a[k * n + c])).join(', ') + ')';
+/** A colour tuple for USD: TopoTopo colours are display values, USD colour inputs and primvars are linear. */
+const linear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const tupColor = (a, k, n) => '(' + Array.from({ length: n }, (_, c) => fmt(linear(a[k * n + c]))).join(', ') + ')';
 /**
  * USDA stage: meshes, curves and points under /root, split by prim name. Packed instances (instancing 'packed', the
  * default) become one PointInstancer /root/instances whose prototypes (one per packed source, under its
@@ -226,10 +229,10 @@ function usdaMaterials(table, o, out) {
         const I = '            ';
         out.push(`        def Material "${id}"`, '        {', `            token outputs:surface.connect = <${mp}/surface.outputs:surface>`, '');
         out.push(`${I}def Shader "surface"`, `${I}{`, `${I}    uniform token info:id = "UsdPreviewSurface"`);
-        out.push(`${I}    color3f inputs:diffuseColor = ${tup(m.baseColor, 0, 3)}`);
+        out.push(`${I}    color3f inputs:diffuseColor = ${tupColor(m.baseColor, 0, 3)}`);
         if (tex.baseColor)
             out.push(`${I}    color3f inputs:diffuseColor.connect = <${mp}/base_color_map.outputs:rgb>`);
-        out.push(`${I}    color3f inputs:emissiveColor = ${tup(m.emissive, 0, 3)}`);
+        out.push(`${I}    color3f inputs:emissiveColor = ${tupColor(m.emissive, 0, 3)}`);
         out.push(`${I}    float inputs:metallic = ${fmt(m.metallic)}`);
         if (tex.orm)
             out.push(`${I}    float inputs:metallic.connect = <${mp}/orm_map.outputs:b>`);
@@ -343,7 +346,7 @@ function usdaInstancer(g, o, uniq, out, mats = null) {
         if ((a.name === 'Cd' || a.name === 'Alpha') && t === 'float' && num.every((v) => v.every((x) => x === 1)))
             continue;
         if (a.name === 'Cd' && t === 'float' && sz >= 3) {
-            out.push(`        color3f[] primvars:displayColor = [${num.map((v) => tup(v, 0, 3)).join(', ')}] (`, ...vertex);
+            out.push(`        color3f[] primvars:displayColor = [${num.map((v) => tupColor(v, 0, 3)).join(', ')}] (`, ...vertex);
             continue;
         }
         if (a.name === 'Alpha' && t === 'float' && sz === 1) {
@@ -419,7 +422,7 @@ function usdaPrims(g, o, uniq, out, mats = null) {
                     const c = cd.attr.get(i);
                     return Array.isArray(c) ? c.slice(0, 3) : [c, c, c];
                 });
-                out.push(`        color3f[] primvars:displayColor = [${Array.from({ length: cols.length / 3 }, (_, k) => tup(cols, k, 3)).join(', ')}] (`, '            interpolation = "faceVarying"', '        )');
+                out.push(`        color3f[] primvars:displayColor = [${Array.from({ length: cols.length / 3 }, (_, k) => tupColor(cols, k, 3)).join(', ')}] (`, '            interpolation = "faceVarying"', '        )');
             }
             if (o.custom)
                 for (const [n, a] of geo.points.map) {

package/dist/io/gltf.d.ts

@@ -32,7 +32,7 @@ export interface GLTFImportOptions {
     /** EXT_mesh_gpu_instancing: 'packed' (default) = packed prims sharing one source per mesh; 'expand' = real geometry */
     instancing?: 'packed' | 'expand';
 }
-/** Geometry from a gltf-transform Document (all scenes' nodes flattened into world space). */
+/** Geometry from the default (or first) scene, traversed in scene order with world transforms. */
 export declare function documentToGeometry(doc: Document, warn?: (m: string) => void, instancing?: 'packed' | 'expand', base?: string): Geometry;
 /** Import GLB or .gltf bytes (external buffers through opts.readFile). */
 export declare function importGLTFAsync(bytes: Uint8Array, opts?: GLTFImportOptions): Promise<Geometry>;

package/dist/io/gltf.js

@@ -17,8 +17,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //   or the smallest integer type that holds an int attribute). The original names and types are kept in mesh
 //   extras (topotopo.attributes), so imports restore them exactly. POINTS always carry pscale as `_PSCALE`.
 //   Materials: the prim "material" attribute names a material of the detail table "materials" (core/materials.ts).
+//   Colour space: TopoTopo colours (Cd, material base/emissive colours) are display values; glTF defines
+//   baseColorFactor, emissiveFactor and COLOR_0 as linear, so they are converted on export and back on import.
 //   Vertex colours win: a primitive with Cd gets baseColorFactor white × COLOR_0, the material supplies the PBR
 //   scalars; the original material is kept in material extras (topotopo.material) for lossless re-import.
+//   A primitive whose Cd is one constant colour writes it as the baseColorFactor instead of COLOR_0 (the same
+//   colour under glTF's factor × COLOR_0, and visible in engines whose default materials ignore vertex colours,
+//   such as Unreal's Interchange); primitive extras (topotopo.Cd) restore it as point Cd on import.
 //   Options: quantize (KHR_mesh_quantization), compress 'meshopt' (EXT_meshopt_compression, implies quantize),
 //   compress 'draco' (KHR_draco_mesh_compression, only when the optional draco3dgltf package is installed).
 //   Packed instances (instancing 'packed', the default): one mesh + node per packed source with EXT_mesh_gpu_instancing
@@ -54,7 +59,7 @@ import { resolveVertexNormals, triangulate } from '../core/topology.js';
 import { DEFAULT_MATERIAL, mergeMaterialTables, normalizeMaterial, primMaterials, texturePaths, writeMaterials } from '../core/materials.js';
 import { m4apply, m4applyDir, m4fromQuat, m4mul, m4normalMatrix, m4scale, m4translate } from '../core/math.js';
 import { INSTANCE_ATTRIB_SKIP, anchorAttribs, anchorValue, baseOf, decomposeXform, isolatedMask, packedSourceNames, pieces, xf, xfDir, xfLinear } from './common.js';
-import { DEFAULT_TRANSFER, expandPacked, flattenSource, packedFromMatrices, stripPacked } from '../core/packed.js';
+import { DEFAULT_TRANSFER, expandPacked, flattenSource, packedFromMatrices, stripPacked, xform3 } from '../core/packed.js';
 import { hasSplinesDeep, splinesToPolylinesDeep } from '../core/splines.js';
 import { imageFromPNG, imageTextureData } from './textures.js';
 import { decodePNG } from './png-decode.js';
@@ -270,8 +275,8 @@ function textureFor(st, path) {
     st.textures.set(path, t);
     return t;
 }
-function getMaterial(st, name, vertexColors, blend) {
-    const key = `${name}\u0000${vertexColors ? 1 : 0}${blend ? 1 : 0}`;
+function getMaterial(st, name, vertexColors, blend, tint) {
+    const key = `${name}\u0000${vertexColors ? 1 : 0}${blend ? 1 : 0}${tint ? `\u0000${tint.join(',')}` : ''}`;
     let m = st.cache.get(key);
     if (m)
         return m;
@@ -286,9 +291,10 @@ function getMaterial(st, name, vertexColors, blend) {
         st.warn?.(`glTF: material "${name}" has an orm and a roughness map; the orm map's green channel is used`);
     // a map replaces its factor: white base colour under a base colour map, roughness 1 under a roughness map,
     // metallic 1 under an ORM map
-    const rgb = vertexColors || baseTex ? [1, 1, 1] : mat.baseColor;
+    // a folded constant vertex colour multiplies a base colour map exactly as COLOR_0 would have
+    const rgb = tint ?? (vertexColors || baseTex ? [1, 1, 1] : mat.baseColor);
     m = st.doc.createMaterial(isDefault ? 'default' : name)
-        .setBaseColorFactor([rgb[0], rgb[1], rgb[2], mat.alpha])
+        .setBaseColorFactor([toLinear(rgb[0]), toLinear(rgb[1]), toLinear(rgb[2]), mat.alpha]) // glTF factors are linear
         .setMetallicFactor(ormTex ? 1 : mat.metallic)
         .setRoughnessFactor(roughTex ? 1 : mat.roughness)
         .setDoubleSided(mat.doubleSided);
@@ -302,12 +308,12 @@ function getMaterial(st, name, vertexColors, blend) {
         m.setOcclusionTexture(ormTex);
     const emax = Math.max(...mat.emissive);
     if (emax > 1) {
-        m.setEmissiveFactor([mat.emissive[0] / emax, mat.emissive[1] / emax, mat.emissive[2] / emax]);
+        m.setEmissiveFactor([toLinear(mat.emissive[0] / emax), toLinear(mat.emissive[1] / emax), toLinear(mat.emissive[2] / emax)]);
         const ext = st.doc.createExtension(KHRMaterialsEmissiveStrength);
         m.setExtension('KHR_materials_emissive_strength', ext.createEmissiveStrength().setEmissiveStrength(emax));
     }
     else
-        m.setEmissiveFactor([mat.emissive[0], mat.emissive[1], mat.emissive[2]]);
+        m.setEmissiveFactor([toLinear(mat.emissive[0]), toLinear(mat.emissive[1]), toLinear(mat.emissive[2])]);
     if (mat.alpha < 1 || blend)
         m.setAlphaMode('BLEND');
     if (mat.unlit)
@@ -316,6 +322,17 @@ function getMaterial(st, name, vertexColors, blend) {
     st.cache.set(key, m);
     return m;
 }
+/** Display (sRGB-encoded) value to linear and back: glTF's factors and COLOR_0 are linear, TopoTopo colours are display
+ *  values (docs/DESIGN.md, colour). */
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const toDisplay = (c) => (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+/** True when every element of a colour stream has the same rgb. */
+const constantRGB = (d, size) => {
+    for (let i = size; i < d.length; i += size)
+        if (d[i] !== d[0] || d[i + 1] !== d[1] || d[i + 2] !== d[2])
+            return false;
+    return true;
+};
 /** True when every rgb component of a colour stream is 1 (Houdini's default Cd). */
 const rgbAllOnes = (d, size) => {
     for (let i = 0; i < d.length; i++)
@@ -382,18 +399,27 @@ export function gltfDocument(g, o = {}) {
             const finishColor = (out, mat) => {
                 // vertex colours win where they are set; all-white Cd lets the material colour through
                 const ci = color ? out.channels.indexOf(color) : -1;
-                let vc = false, blend = false;
+                let vc = false, blend = false, tint;
                 if (ci >= 0) {
                     const ch = out.channels[ci], d = out.data[ci];
                     const rgbSet = !!geo.findAttrib('Cd') && !rgbAllOnes(d, ch.size);
                     blend = ch.size === 4 && d.some((x, i) => i % 4 === 3 && x < 1);
                     vc = rgbSet;
-                    if (!rgbSet && !blend) {
+                    // one colour over the whole primitive: the factor carries it (identical under glTF's factor × COLOR_0), so
+                    // engines that ignore vertex colours in their default materials (Unreal Interchange) still show it
+                    if (rgbSet && !blend && d.length >= ch.size && constantRGB(d, ch.size)) {
+                        tint = [d[0], d[1], d[2]].map((x) => Math.max(0, Math.min(1, x)));
+                        out.foldedColor = tint;
+                        vc = false;
+                    }
+                    else if (rgbSet && o.materialColorWins && mat && st.table[mat])
+                        vc = false; // keeps COLOR_0, factor = material colour
+                    if ((!rgbSet || tint) && !blend) {
                         out.channels.splice(ci, 1);
                         out.data.splice(ci, 1);
                     }
                 }
-                out.material = getMaterial(st, mat, vc, blend);
+                out.material = getMaterial(st, mat, vc, blend, tint);
                 if (out.material.getBaseColorTexture() || out.material.getNormalTexture() || out.material.getMetallicRoughnessTexture()) {
                     if (!out.channels.some((c) => c.semantic === 'TEXCOORD_0'))
                         noUV++;
@@ -699,6 +725,8 @@ function writeMesh(doc, buffer, scene, name, outs, info, quantize) {
     const acc = (arr, size, normalized = false) => doc.createAccessor().setArray(arr).setType(TYPES[size - 1]).setBuffer(buffer).setNormalized(normalized);
     for (const out of outs) {
         const prim = doc.createPrimitive().setMode(out.mode);
+        if (out.foldedColor)
+            prim.setExtras({ topotopo: { Cd: out.foldedColor } });
         out.channels.forEach((ch, ci) => {
             const d = out.data[ci];
             let a;
@@ -715,10 +743,11 @@ function writeMesh(doc, buffer, scene, name, outs, info, quantize) {
                 a = acc(Uint16Array.from(d, (x) => Math.round(x * 65535)), 2, true);
             }
             else if (ch.semantic === 'COLOR_0' && quantize && d.every((x) => x >= 0 && x <= 1)) {
-                a = acc(Uint16Array.from(d, (x) => Math.round(x * 65535)), ch.size, true);
+                // COLOR_0 is linear: rgb from display values, alpha as it is
+                a = acc(Uint16Array.from(d, (x, i) => Math.round((i % ch.size < 3 ? toLinear(x) : x) * 65535)), ch.size, true);
             }
             else if (ch.semantic === 'COLOR_0') {
-                a = acc(Float32Array.from(d, (x) => Math.max(0, Math.min(1, x))), ch.size);
+                a = acc(Float32Array.from(d, (x, i) => { const c = Math.max(0, Math.min(1, x)); return i % ch.size < 3 ? toLinear(c) : c; }), ch.size);
             }
             else if (ch.int) {
                 let mn = Infinity, mx = -Infinity;
@@ -882,9 +911,10 @@ function materialEntry(m, base = '', index = () => 0) {
         return normalizeMaterial(ex);
     const bc = m.getBaseColorFactor(), em = m.getEmissiveFactor();
     const strength = m.getExtension('KHR_materials_emissive_strength')?.getEmissiveStrength() ?? 1;
+    // glTF factors are linear; the material table holds display values
     return normalizeMaterial({
-        baseColor: [bc[0], bc[1], bc[2]], metallic: m.getMetallicFactor(), roughness: m.getRoughnessFactor(),
-        emissive: [em[0] * strength, em[1] * strength, em[2] * strength], alpha: bc[3],
+        baseColor: [toDisplay(bc[0]), toDisplay(bc[1]), toDisplay(bc[2])], metallic: m.getMetallicFactor(), roughness: m.getRoughnessFactor(),
+        emissive: [toDisplay(em[0]) * strength, toDisplay(em[1]) * strength, toDisplay(em[2]) * strength], alpha: bc[3],
         doubleSided: m.getDoubleSided(), unlit: !!m.getExtension('KHR_materials_unlit'),
         textures: {
             baseColor: texturePathOf(m.getBaseColorTexture(), base, index),
@@ -970,7 +1000,8 @@ function primitiveGeometry(prim, attrInfo, warn) {
         else if (sem === 'TEXCOORD_0' || sem === 'TEXCOORD_1')
             setPt(sem === 'TEXCOORD_0' ? 'uv' : 'uv2', a, 3, 'float', (s, i, out) => { out[i * 3] = s[i * es]; out[i * 3 + 1] = 1 - s[i * es + 1]; out[i * 3 + 2] = 0; });
         else if (sem === 'COLOR_0') {
-            setPt('Cd', a, 3, 'float', (s, i, out) => { out[i * 3] = s[i * es]; out[i * 3 + 1] = s[i * es + 1]; out[i * 3 + 2] = s[i * es + 2]; });
+            // COLOR_0 is linear; Cd holds display values
+            setPt('Cd', a, 3, 'float', (s, i, out) => { out[i * 3] = toDisplay(s[i * es]); out[i * 3 + 1] = toDisplay(s[i * es + 1]); out[i * 3 + 2] = toDisplay(s[i * es + 2]); });
             if (es === 4)
                 setPt('Alpha', a, 1, 'float', (s, i, out) => { out[i] = s[i * 4 + 3]; });
         }
@@ -981,6 +1012,18 @@ function primitiveGeometry(prim, attrInfo, warn) {
         }
         // TANGENT, JOINTS_n, WEIGHTS_n, TEXCOORD_2+, COLOR_1+ are not imported
     }
+    // a constant Cd that the exporter folded into the material factor comes back as the point colour it was
+    const folded = prim.getExtras()?.topotopo?.Cd;
+    if (!prim.getAttribute('COLOR_0') && Array.isArray(folded) && folded.length === 3 && folded.every((x) => typeof x === 'number')) {
+        const cd = new Attribute('float', 3, new Float64Array(n * 3), defaultValueFor('Cd', 3, 'float'));
+        const d = cd.data;
+        for (let i = 0; i < n; i++) {
+            d[i * 3] = folded[0];
+            d[i * 3 + 1] = folded[1];
+            d[i * 3 + 2] = folded[2];
+        }
+        g.points.set('Cd', cd);
+    }
     return g;
 }
 function transformGeo(local, m) {
@@ -1015,7 +1058,35 @@ function instanceMatrices(inst) {
     }
     return out;
 }
-/** Geometry from a gltf-transform Document (all scenes' nodes flattened into world space). */
+const RESERVED_EXTRAS = new Set('P N uv uv2 Cd Alpha material name path orient scale pscale'.split(' '));
+function constantAttribute(table, name, type, size, value) {
+    const a = table.add(name, type, size);
+    for (let i = 0; i < table.count; i++)
+        a.set(i, value);
+}
+/** Object extras only; topotopo's private round-trip metadata keeps its existing readers. */
+function objectExtras(table, extras, collisions) {
+    // Explicit key order keeps schemas stable even when producers serialize extras in a different order.
+    for (const key of Object.keys(extras).sort()) {
+        if (key === 'topotopo')
+            continue;
+        if (RESERVED_EXTRAS.has(key)) {
+            collisions.add(key);
+            continue;
+        }
+        const value = extras[key];
+        if (typeof value === 'string')
+            constantAttribute(table, key, 'string', 1, value);
+        else if (typeof value === 'boolean')
+            constantAttribute(table, key, 'int', 1, value ? 1 : 0);
+        else if (typeof value === 'number' && Number.isFinite(value))
+            constantAttribute(table, key, Number.isInteger(value) ? 'int' : 'float', 1, value);
+        else if (Array.isArray(value) && value.length >= 2 && value.length <= 4 && value.every((v) => typeof v === 'number' && Number.isFinite(v))) {
+            constantAttribute(table, key, 'float', value.length, value);
+        }
+    }
+}
+/** Geometry from the default (or first) scene, traversed in scene order with world transforms. */
 export function documentToGeometry(doc, warn = () => { }, instancing = 'packed', base = '') {
     const root = doc.getRoot();
     const texIndex = (t) => root.listTextures().indexOf(t);
@@ -1040,24 +1111,62 @@ export function documentToGeometry(doc, warn = () => { }, instancing = 'packed',
     const parts = [];
     const localCache = new Map();
     const sourceCache = new Map();
+    const sharedSources = new Map();
+    const nodes = [];
+    const scene = root.getDefaultScene() ?? root.listScenes()[0] ?? null;
+    if (scene)
+        scene.traverse((n) => { nodes.push(n); });
+    else
+        for (const n of root.listNodes())
+            if (!n.getParentNode())
+                n.traverse((n) => { nodes.push(n); });
+    const meshRefs = new Map();
+    for (const node of nodes) {
+        const mesh = node.getMesh();
+        if (mesh && !node.getExtension('EXT_mesh_gpu_instancing') && !node.getCamera() && !node.getExtension('KHR_lights_punctual'))
+            meshRefs.set(mesh, (meshRefs.get(mesh) ?? 0) + 1);
+    }
+    const collisions = new Set();
+    let skipped = 0;
     let instanced = false;
     const visitNode = (node) => {
-        const mesh = node.getMesh();
-        if (!mesh)
+        if (node.getCamera() || node.getExtension('KHR_lights_punctual')) {
+            skipped++;
             return;
+        }
+        const mesh = node.getMesh();
         const world = Float64Array.from(node.getWorldMatrix());
+        const ancestors = [];
+        for (let p = node.getParentNode(); p; p = p.getParentNode())
+            ancestors.push(p.getName());
+        const path = ancestors.reverse().join('/');
+        const extras = { ...mesh?.getExtras(), ...node.getExtras() };
+        if (!mesh) {
+            const g = new Geometry({ positions: [world[12], world[13], world[14]] });
+            const { q, s } = decomposeXform(xform3(world));
+            constantAttribute(g.points, 'name', 'string', 1, node.getName());
+            constantAttribute(g.points, 'path', 'string', 1, path);
+            constantAttribute(g.points, 'orient', 'float', 4, q);
+            constantAttribute(g.points, 'scale', 'float', 3, s);
+            constantAttribute(g.points, 'pscale', 'float', 1, 1);
+            objectExtras(g.points, extras, collisions);
+            parts.push(g);
+            return;
+        }
         const inst = node.getExtension('EXT_mesh_gpu_instancing');
         const mats = inst ? instanceMatrices(inst).map((m) => m4mul(world, m)) : [world];
         const info = (mesh.getExtras()?.topotopo?.attributes ?? {});
         const label = node.getName() || mesh.getName();
-        if (inst && instancing === 'packed') {
-            // one packed source per mesh (and node name): the mesh in its local space, the instances as packed prims
+        const shared = !inst && (meshRefs.get(mesh) ?? 0) > 1;
+        if ((inst || shared) && instancing === 'packed') {
+            // Shared-node sources omit name: the packed prim owns it, so unpack's normal transfer keeps each label.
+            // Existing EXT sources retain their labels for round trips and source naming in instance-stream exports.
             let byLabel = sourceCache.get(mesh);
             if (!byLabel) {
                 byLabel = new Map();
                 sourceCache.set(mesh, byLabel);
             }
-            let src = byLabel.get(label);
+            let src = shared ? sharedSources.get(mesh) : byLabel.get(label);
             if (!src) {
                 const ps = [];
                 for (const prim of mesh.listPrimitives()) {
@@ -1070,7 +1179,7 @@ export function documentToGeometry(doc, warn = () => { }, instancing = 'packed',
                         continue;
                     const g = local.clone();
                     const mname = matName(prim.getMaterial());
-                    if (label) {
+                    if (!shared && label) {
                         const a = g.prims.add('name', 'string', 1);
                         for (let k = 0; k < g.numPrims; k++)
                             a.set(k, label);
@@ -1083,10 +1192,23 @@ export function documentToGeometry(doc, warn = () => { }, instancing = 'packed',
                     ps.push(g);
                 }
                 src = Geometry.merge(ps);
-                byLabel.set(label, src);
+                if (shared)
+                    sharedSources.set(mesh, src);
+                else
+                    byLabel.set(label, src);
             }
             const part = packedFromMatrices(src, mats);
-            applyInstanceAttribs(part, inst, (node.getExtras()?.topotopo?.instanceAttributes ?? {}), warn);
+            constantAttribute(part.prims, 'name', 'string', 1, label);
+            constantAttribute(part.prims, 'path', 'string', 1, path);
+            objectExtras(part.prims, extras, collisions);
+            if (inst)
+                applyInstanceAttribs(part, inst, (node.getExtras()?.topotopo?.instanceAttributes ?? {}), warn);
+            // Native instance metadata can carry these in point class; expose the effective label on the prim too.
+            for (const key of ['name', 'path']) {
+                const a = part.points.get(key);
+                if (a?.type === 'string')
+                    part.prims.set(key, a.clone());
+            }
             parts.push(part);
             return;
         }
@@ -1113,19 +1235,30 @@ export function documentToGeometry(doc, warn = () => { }, instancing = 'packed',
                     for (let k = 0; k < g.numPrims; k++)
                         a.set(k, mname);
                 }
+                constantAttribute(g.prims, 'path', 'string', 1, path);
+                objectExtras(g.prims, extras, collisions);
                 parts.push(g);
             }
         }
     };
-    const scene = root.getDefaultScene() ?? root.listScenes()[0] ?? null;
-    if (scene)
-        scene.traverse(visitNode);
-    else
-        for (const n of root.listNodes())
-            if (!n.getParentNode())
-                n.traverse(visitNode);
+    for (const node of nodes)
+        visitNode(node);
+    if (skipped)
+        warn(`skipped ${skipped} cameras/lights`);
+    if (collisions.size)
+        warn(`glTF extras skipped reserved attributes: ${[...collisions].sort().join(', ')}`);
     if (instanced)
         warn('EXT_mesh_gpu_instancing instances were expanded into geometry');
+    // Existing unpack/export rules prefer point attributes over prim attributes. Empty-point schemas must not
+    // hide an instance's values with merge defaults. Mirror only colliding keys onto its anchor, before the normal
+    // Geometry.merge handles type promotion/defaults. Explicit native instance point metadata still wins.
+    const pointKeys = new Set(parts.flatMap((g) => g.points.names()));
+    for (const part of parts)
+        if (part.hasPacked()) {
+            for (const [key, a] of part.prims.map)
+                if (pointKeys.has(key) && !part.points.has(key))
+                    part.points.set(key, a.clone());
+        }
     const out = Geometry.merge(parts);
     if (Object.keys(table).length)
         writeMaterials(out, table);
@@ -1143,7 +1276,9 @@ export function documentToGeometry(doc, warn = () => { }, instancing = 'packed',
             if (name === null || images.has(name) || !bytes?.length || imageMime(bytes) !== 'image/png')
                 continue;
             try {
-                images.set(name, imageFromPNG(decodePNG(bytes), name));
+                // one layer per texture: a grey + alpha map stays RGBA, so a re-export writes its alpha
+                const png = decodePNG(bytes);
+                images.set(name, imageFromPNG(png, name, { layers: png.channels === 1 ? 'grey' : 'rgba' }));
             }
             catch (e) {
                 warn(`texture "${path}": ${e?.message ?? e}`);

package/dist/io/heightmap.d.ts

@@ -3,7 +3,7 @@ import type { Heightfield } from '../core/heightfield.ts';
 export type HeightmapFormat = 'png16' | 'r16' | 'mask_png';
 export declare const HEIGHTMAP_FORMATS: HeightmapFormat[];
 export interface HeightmapOptions {
-    /** png16/r16: the layer to write (default "height"); mask_png: the layer when `layers` is not given (default "mask") */
+    /** png16/r16: the layer to write (default "height"); mask_png: the layer when `layers` is not given (default "mask"); unreal_landscape: the height layer */
     layer?: string;
     /** mask_png: layers to write, one 8-bit PNG each */
     layers?: string[];

package/dist/io/import.d.ts

@@ -10,10 +10,10 @@ export interface ImportOptions {
     path?: string;
     /** receives non-fatal problems (skipped primitives or attributes) */
     warn?: (msg: string) => void;
-    /** glTF EXT_mesh_gpu_instancing: 'packed' (default) = packed prims sharing one source per mesh; 'expand' = real geometry */
+    /** glTF shared meshes / EXT_mesh_gpu_instancing: 'packed' (default) = packed prims; 'expand' = real geometry */
     instancing?: 'packed' | 'expand';
 }
-/** Format from a file name: the extension, with ".points.json" → pointsjson. */
+/** Format from a file name: the extension, with ".points.json" → pointsjson (".png" → png: an image). */
 export declare function importFormatFromPath(path: string): string;
 /** Synchronous import for every format except glb/gltf (see importGeometryAsync). */
 export declare function importGeometry(bytes: Uint8Array, fmt: string, opts?: ImportOptions): Geometry;

package/dist/io/import.js

@@ -1,5 +1,5 @@
 // Importers: OBJ, STL, PLY, glTF/GLB (gltf-transform, src/io/gltf.ts), native JSON, Houdini .geo (src/io/hgeo.ts),
-// CSV and points JSON (src/io/points.ts).
+// CSV and points JSON (src/io/points.ts), and PNG as a geometry holding one image volume (src/io/textures.ts).
 //
 // importGeometry() is synchronous and covers every format except glTF, whose reader (gltf-transform) is
 // asynchronous: use importGeometryAsync() for glb/gltf (it handles every format, and reads external .bin files).
@@ -8,12 +8,13 @@ import { geoFromJSON } from './json.js';
 import { importGLTFAsync } from './gltf.js';
 import { importHoudiniBgeo, importHoudiniGeo, isBinaryJSON } from './hgeo.js';
 import { importCSV, importPointsJSON, isPointsJSON } from './points.js';
+import { imageFromPNGFile } from './textures.js';
 export { importGLTFAsync } from './gltf.js';
 export { importHoudiniBgeo, importHoudiniGeo } from './hgeo.js';
 export { importCSV, importPointsJSON } from './points.js';
 const td = new TextDecoder();
-export const IMPORT_FORMATS = ['obj', 'stl', 'ply', 'glb', 'gltf', 'json', 'geo', 'bgeo', 'csv', 'pointsjson'];
-/** Format from a file name: the extension, with ".points.json" → pointsjson. */
+export const IMPORT_FORMATS = ['obj', 'stl', 'ply', 'glb', 'gltf', 'blend', 'json', 'geo', 'bgeo', 'csv', 'pointsjson', 'png'];
+/** Format from a file name: the extension, with ".points.json" → pointsjson (".png" → png: an image). */
 export function importFormatFromPath(path) {
     const p = String(path).split('?')[0].toLowerCase();
     if (p.endsWith('.points.json'))
@@ -42,6 +43,12 @@ export function importGeometry(bytes, fmt, opts = {}) {
         case 'bgeo': return isBinaryJSON(bytes) ? importHoudiniBgeo(bytes, opts.warn) : importHoudiniGeo(td.decode(bytes), opts.warn);
         case 'csv': return importCSV(td.decode(bytes));
         case 'pointsjson': return importPointsJSON(JSON.parse(td.decode(bytes)));
+        case 'png': {
+            // an image volume named after the file, as the image_file node reads it with its defaults
+            const g = new Geometry();
+            g.volumes = [imageFromPNGFile(bytes, opts.path ?? 'image.png')];
+            return g;
+        }
         case 'glb':
         case 'gltf': throw new Error(`${fmt} import is asynchronous (gltf-transform): use importGeometryAsync`);
         case 'bgeo.sc': throw new Error('compressed Houdini geometry (.bgeo.sc / .gz) is not supported: save as .geo or uncompressed .bgeo');

package/dist/io/png-decode.d.ts

@@ -14,8 +14,11 @@ export interface PngImage {
     /** samples, row-major, channels interleaved; row 0 is the top of the image */
     data: Uint16Array;
 }
-/** Decode a PNG file. Throws a readable Error for unsupported or corrupt files. */
-export declare function decodePNG(bytes: Uint8Array): PngImage;
+/**
+ * Decode a PNG file. Throws a readable Error for unsupported or corrupt files, and for images of more than maxPixels
+ * pixels before any pixel memory is allocated.
+ */
+export declare function decodePNG(bytes: Uint8Array, maxPixels?: number): PngImage;
 export type PngChannel = 'luminance' | 'average' | 'r' | 'g' | 'b' | 'a';
 /** One channel of a decoded image as floats 0..1 (luminance = Rec. 709 weights; grey images ignore r/g/b). */
 export declare function pngChannel(img: PngImage, channel?: PngChannel): Float32Array;

package/dist/io/png-decode.js

@@ -1,6 +1,6 @@
 // Minimal PNG decoder (pure TypeScript, no host APIs): non-interlaced grey, grey+alpha, RGB, RGBA and palette
 // images at 1/2/4/8/16 bits per channel, with a small inflate (RFC 1950/1951) so it runs anywhere the core runs.
-// Used by heightfield_from_image; exported for other readers (attribute from map, textures).
+// Used by heightfield_from_image, attribute_from_map and image_file (io/textures.ts), and the glTF importer.
 // ---------------------------------------------------------------- inflate
 class Bits {
     data;
@@ -180,8 +180,11 @@ export function inflateZlib(data, sizeHint = 0) {
     return inflateRaw(data, sizeHint, 2);
 }
 const SIG = [137, 80, 78, 71, 13, 10, 26, 10];
-/** Decode a PNG file. Throws a readable Error for unsupported or corrupt files. */
-export function decodePNG(bytes) {
+/**
+ * Decode a PNG file. Throws a readable Error for unsupported or corrupt files, and for images of more than maxPixels
+ * pixels before any pixel memory is allocated.
+ */
+export function decodePNG(bytes, maxPixels = Infinity) {
     for (let i = 0; i < 8; i++)
         if (bytes[i] !== SIG[i])
             throw new Error('not a PNG file (bad signature)');
@@ -226,6 +229,10 @@ export function decodePNG(bytes) {
         throw new Error(`unsupported PNG bit depth ${depth} for colour type ${ctype}`);
     if (ctype === 3 && !palette)
         throw new Error('palette PNG without a PLTE chunk');
+    if (width * height > maxPixels) {
+        const side = Math.floor(Math.sqrt(maxPixels));
+        throw new Error(`the image is ${width} × ${height} pixels, more than the ${maxPixels.toLocaleString('en-US')} pixels allowed here (e.g. ${side} × ${side}): scale it down`);
+    }
     let total = 0;
     for (const c of idat)
         total += c.length;

package/dist/io/targets.d.ts

@@ -0,0 +1,31 @@
+import type { ExportFormat } from './export.ts';
+import type { ExportTarget, GraphSpec } from '../graph/types.ts';
+/** Every export format with the label the viewer shows, in the order it offers them (a Record, so none is missing). */
+export declare const FORMAT_LABELS: Record<ExportFormat, string>;
+export declare const TARGET_FORMATS: ExportFormat[];
+/** The extension a target's file gets: '' for unreal_landscape and textures, which write a folder. */
+export declare const targetExtension: (format: ExportFormat) => string;
+/** A format name in canonical form ("USD" → usda), or null. */
+export declare function targetFormat(f: unknown): ExportFormat | null;
+/** Why a target is invalid, or null when it is valid. */
+export declare function targetError(t: unknown): string | null;
+export interface ResolvedTarget {
+    format: ExportFormat;
+    /** posix path inside exports/: a file, or a folder for unreal_landscape and textures */
+    path: string;
+    /** the export tool's options (up_axis, scale, …) */
+    options: Record<string, unknown>;
+}
+/** A file name stem from an output id or graph name. */
+export declare const fileStem: (s: string) => string;
+/** A valid target with its path filled in: <stem><extension> unless it names one. */
+export declare function resolveTarget(t: ExportTarget, stem: string): ResolvedTarget;
+export interface PublishedOutput {
+    /** null for the graph's default output (graph.export), else the id in graph.outputs */
+    output: string | null;
+    node: string;
+    label: string;
+    target: ResolvedTarget | null;
+}
+/** A graph's default output (its files named after the graph) and its named outputs, each with its target if valid. */
+export declare function publishedOutputs(graph: string, spec: GraphSpec, defaultNode: string): PublishedOutput[];

package/dist/io/targets.js

@@ -0,0 +1,75 @@
+/** Every export format with the label the viewer shows, in the order it offers them (a Record, so none is missing). */
+export const FORMAT_LABELS = {
+    glb: 'GLB (one file, textures inside)', gltf: 'glTF + texture files', usda: 'USD (.usda)', obj: 'OBJ', geo: 'Houdini .geo',
+    unreal_landscape: 'Unreal Landscape bundle (folder)', csv: 'CSV points (Unreal PCG)', pointsjson: 'Points JSON',
+    textures: 'PNG textures (folder)', png16: 'Heightmap, 16-bit PNG', r16: 'Heightmap, RAW .r16', mask_png: 'Masks, PNG',
+    ply: 'PLY', stl: 'STL', json: 'TopoTopo JSON',
+};
+export const TARGET_FORMATS = Object.keys(FORMAT_LABELS);
+const EXTENSIONS = { unreal_landscape: '', textures: '', png16: '.png', mask_png: '.png', pointsjson: '.points.json' };
+/** The extension a target's file gets: '' for unreal_landscape and textures, which write a folder. */
+export const targetExtension = (format) => EXTENSIONS[format] ?? '.' + format;
+/** A format name in canonical form ("USD" → usda), or null. */
+export function targetFormat(f) {
+    const s = typeof f === 'string' ? f.trim().toLowerCase() : '';
+    const c = s === 'usd' ? 'usda' : s;
+    return Object.hasOwn(FORMAT_LABELS, c) ? c : null;
+}
+// the export tool's options (src/mcp/tools.ts), by value type
+const BOOLEAN = ['split_by_name', 'materials', 'custom_attribs', 'quantize', 'pcg', 'pcg_struct', 'meshes'];
+const CHOICES = { up_axis: ['y', 'z'], compress: ['none', 'meshopt', 'draco'], instancing: ['packed', 'expand'], instances: ['rows', 'expand'], precision: [32, 64] };
+const NUMBER = ['scale', 'height_min', 'height_max', 'tile_size', 'heightfield'];
+const NAMES = ['attributes', 'layers'];
+const OPTIONS = [...BOOLEAN, ...Object.keys(CHOICES), ...NUMBER, ...NAMES, 'layer'];
+/** A path segment Windows and POSIX both accept, and that cannot climb out of exports/. */
+const segmentOk = (s) => !!s && s !== '.' && s !== '..' && !/[<>:"|?*\x00-\x1f]/.test(s) && !/[. ]$/.test(s) && !/^(con|prn|aux|nul|com\d|lpt\d)(\.|$)/i.test(s);
+const pathOk = (p) => typeof p === 'string' && p.length <= 240 && !/^[A-Za-z]:|^[\\/]/.test(p) && p.replace(/\\/g, '/').split('/').every(segmentOk);
+/** Why a target is invalid, or null when it is valid. */
+export function targetError(t) {
+    const o = typeof t === 'string' ? { format: t } : t;
+    if (!o || typeof o !== 'object' || Array.isArray(o))
+        return 'export must be a format name ("glb") or {format, path?, ...options}';
+    if (!targetFormat(o.format))
+        return `export format "${o.format}" is not one of ${TARGET_FORMATS.join(', ')} (or usd)`;
+    if (o.path !== undefined && !pathOk(o.path))
+        return `export path "${o.path}" must stay inside exports/: relative, without "..", a drive or a leading slash`;
+    for (const [k, v] of Object.entries(o)) {
+        if (k === 'format' || k === 'path')
+            continue;
+        if (!OPTIONS.includes(k))
+            return `unknown export option "${k}" (options: ${OPTIONS.join(', ')})`;
+        if (BOOLEAN.includes(k) && typeof v !== 'boolean')
+            return `export option ${k} must be true or false`;
+        if (k in CHOICES && !CHOICES[k].includes(v))
+            return `export option ${k} must be one of ${CHOICES[k].join(', ')}`;
+        if (NUMBER.includes(k) && !(typeof v === 'number' && Number.isFinite(v)))
+            return `export option ${k} must be a number`;
+        if (k === 'scale' && !(v > 0))
+            return 'export option scale must be positive';
+        if (NAMES.includes(k) && !(Array.isArray(v) && v.every((s) => typeof s === 'string')))
+            return `export option ${k} must be a list of names`;
+        if (k === 'layer' && typeof v !== 'string')
+            return 'export option layer must be a name';
+    }
+    return null;
+}
+/** A file name stem from an output id or graph name. */
+export const fileStem = (s) => s.replace(/[^A-Za-z0-9_.-]+/g, '_').replace(/^\.+|[. ]+$/g, '') || 'output';
+/** A valid target with its path filled in: <stem><extension> unless it names one. */
+export function resolveTarget(t, stem) {
+    const { format, path, ...options } = typeof t === 'string' ? { format: t } : t;
+    const f = targetFormat(format);
+    return { format: f, path: (typeof path === 'string' ? path : fileStem(stem) + targetExtension(f)).replace(/\\/g, '/'), options };
+}
+/** A graph's default output (its files named after the graph) and its named outputs, each with its target if valid. */
+export function publishedOutputs(graph, spec, defaultNode) {
+    const valid = (t) => (t !== undefined && t !== null && !targetError(t) ? t : null);
+    const main = valid(spec.export);
+    return [
+        { output: null, node: defaultNode, label: 'Main output', target: main ? resolveTarget(main, graph) : null },
+        ...Object.entries(spec.outputs ?? {}).map(([id, o]) => {
+            const t = valid(o?.export);
+            return { output: id, node: o.node, label: o.label ?? id, target: t ? resolveTarget(t, id) : null };
+        }),
+    ];
+}