topotopo 0.1.0 → 0.2.0

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/textures.d.ts

@@ -7,8 +7,37 @@ import type { PngImage } from './png-decode.ts';
  * per channel). deflate compresses (Node: zlib.deflateSync); without it the PNG uses stored (uncompressed) blocks.
  */
 export declare function imagePNG(img: Image, layer?: string, deflate?: (d: Uint8Array) => Uint8Array): Uint8Array;
-/** An image volume from a decoded PNG: grey → 1 channel, grey+alpha / RGB / RGBA → RGBA; samples / maxValue. */
-export declare function imageFromPNG(png: PngImage, name: string): Image;
+/** How a PNG's channels become layers: see ImageFromPNGOptions. */
+export declare const PNG_LAYERS: readonly ['auto', 'grey', 'rgba'];
+export type PngLayers = (typeof PNG_LAYERS)[number];
+export interface ImageFromPNGOptions {
+    /**
+     * 'auto' (default): grey files (1 or 2 channels) give a grey layer C, colour files an RGBA one; 'grey': a grey C
+     * (Rec. 709 luminance of a colour file); 'rgba': an RGBA C (grey g as g, g, g). A grey C puts the file's alpha, when
+     * it has one, in the grey layer "A" (Houdini's alpha plane).
+     */
+    layers?: PngLayers;
+    /**
+     * true (default): the samples are display (sRGB-encoded) values, which colour layers hold too, so they are kept as
+     * they are; false: they are linear light, and grey and RGB are encoded to display values (alpha never is).
+     */
+    srgb?: boolean;
+}
+/** An image volume from a decoded PNG: values = samples / maxValue (16-bit files keep their precision). */
+export declare function imageFromPNG(png: PngImage, name: string, o?: ImageFromPNGOptions): Image;
+/** The image name a file gives: its name without folders and extension ("inputs/brick.png" → "brick"). */
+export declare function imageNameOf(path: string): string;
+/**
+ * An image volume from the bytes of the PNG file `path` (the image_file node and the file node's .png path), named
+ * `name` or after the file (imageNameOf). Errors name the file; images over MAX_PIXELS are refused before decoding.
+ */
+export declare function imageFromPNGFile(bytes: Uint8Array, path: string, o?: ImageFromPNGOptions & {
+    name?: string;
+}): Image;
+/** imageFromPNGFile on a file read through `readFile` (usually Host.readFile). */
+export declare function readImageFile(readFile: (path: string) => Promise<Uint8Array>, path: string, o?: ImageFromPNGOptions & {
+    name?: string;
+}): Promise<Image>;
 /** A file-name-safe version of an image name ("" → "image"). */
 export declare function safeFileName(name: string): string;
 /** The images a material table references ("image:<name>"), with the slots using each. */

package/dist/io/textures.js

@@ -1,7 +1,8 @@
-import { Image, channelsOf, imageRef, imageToBytes, opaque, referenceableImages } from '../core/image.js';
+import { Image, LUMA, MAX_PIXELS, channelsOf, imageRef, imageToBytes, opaque, referenceableImages } from '../core/image.js';
 import { TEXTURE_SLOTS, mergeMaterialTables } from '../core/materials.js';
 import { encodePNG } from '../render/png.js';
 import { encodeGreyPNG, zlibStored } from './heightmap.js';
+import { decodePNG } from './png-decode.js';
 import { baseOf, dirOf, joinPath } from './common.js';
 /**
  * PNG bytes of an image layer ("" = the main layer): 8-bit grey for 1-channel layers, RGBA for 4-channel ones (8 bits
@@ -13,32 +14,79 @@ export function imagePNG(img, layer = '', deflate) {
         return encodeGreyPNG(bytes, img.width, img.height, 8, deflate);
     return encodePNG(bytes, img.width, img.height, deflate ?? zlibStored);
 }
-/** An image volume from a decoded PNG: grey → 1 channel, grey+alpha / RGB / RGBA → RGBA; samples / maxValue. */
-export function imageFromPNG(png, name) {
-    const n = png.width * png.height, ch = png.channels, d = png.data, k = 1 / (png.maxValue || 255);
+/** How a PNG's channels become layers: see ImageFromPNGOptions. */
+export const PNG_LAYERS = ['auto', 'grey', 'rgba'];
+/** Display (sRGB-encoded) value of a linear one (io/gltf.ts converts back and forth for glTF's linear factors). */
+const toDisplay = (c) => (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+/** An image volume from a decoded PNG: values = samples / maxValue (16-bit files keep their precision). */
+export function imageFromPNG(png, name, o = {}) {
+    const n = png.width * png.height, ch = png.channels, d = png.data, max = png.maxValue || 255, k = 1 / max;
+    // samples are integers 0..max: tables give every value once (alpha is never converted)
+    const lin = new Float32Array(max + 1);
+    for (let s = 0; s <= max; s++)
+        lin[s] = s * k;
+    const col = o.srgb === false ? Float32Array.from(lin, (_, s) => toDisplay(s * k)) : lin;
     const img = new Image(png.width, png.height, name);
-    if (ch === 1) {
-        const a = new Float32Array(n);
-        for (let i = 0; i < n; i++)
-            a[i] = d[i] * k;
-        return img.set('C', a);
+    const mode = o.layers ?? 'auto';
+    if (mode === 'grey' || (mode === 'auto' && ch <= 2)) {
+        const C = new Float32Array(n);
+        if (ch <= 2)
+            for (let i = 0; i < n; i++)
+                C[i] = col[d[i * ch]];
+        else
+            for (let i = 0; i < n; i++) {
+                const p = i * ch;
+                C[i] = col[d[p]] * LUMA[0] + col[d[p + 1]] * LUMA[1] + col[d[p + 2]] * LUMA[2];
+            }
+        img.set('C', C);
+        if (ch === 2 || ch === 4) {
+            const A = new Float32Array(n);
+            for (let i = 0; i < n; i++)
+                A[i] = lin[d[i * ch + ch - 1]];
+            img.set('A', A);
+        }
+        return img;
     }
     const a = new Float32Array(n * 4);
     for (let i = 0; i < n; i++) {
-        const o = i * ch;
-        if (ch === 2) {
-            a[i * 4] = a[i * 4 + 1] = a[i * 4 + 2] = d[o] * k;
-            a[i * 4 + 3] = d[o + 1] * k;
-        }
+        const p = i * ch, q = i * 4;
+        if (ch <= 2)
+            a[q] = a[q + 1] = a[q + 2] = col[d[p]];
         else {
-            a[i * 4] = d[o] * k;
-            a[i * 4 + 1] = d[o + 1] * k;
-            a[i * 4 + 2] = d[o + 2] * k;
-            a[i * 4 + 3] = ch === 4 ? d[o + 3] * k : 1;
+            a[q] = col[d[p]];
+            a[q + 1] = col[d[p + 1]];
+            a[q + 2] = col[d[p + 2]];
         }
+        a[q + 3] = ch === 2 || ch === 4 ? lin[d[p + ch - 1]] : 1;
     }
     return img.set('C', a);
 }
+/** The image name a file gives: its name without folders and extension ("inputs/brick.png" → "brick"). */
+export function imageNameOf(path) {
+    let p = String(path);
+    if (/^\w+:\/\//.test(p))
+        p = p.split(/[?#]/)[0];
+    return baseOf(p.replace(/[\\/]+$/, '')).replace(/\.[^.]*$/, '') || 'image';
+}
+/**
+ * An image volume from the bytes of the PNG file `path` (the image_file node and the file node's .png path), named
+ * `name` or after the file (imageNameOf). Errors name the file; images over MAX_PIXELS are refused before decoding.
+ */
+export function imageFromPNGFile(bytes, path, o = {}) {
+    let png;
+    try {
+        png = decodePNG(bytes, MAX_PIXELS);
+    }
+    catch (e) {
+        throw new Error(`"${path}" cannot be read as a PNG image: ${e?.message ?? e}`);
+    }
+    return imageFromPNG(png, o.name || imageNameOf(path), o);
+}
+/** imageFromPNGFile on a file read through `readFile` (usually Host.readFile). */
+export async function readImageFile(readFile, path, o = {}) {
+    const bytes = await readFile(path).catch((e) => { throw new Error(`cannot read "${path}": ${e?.message ?? e}`); });
+    return imageFromPNGFile(bytes, path, o);
+}
 /** A file-name-safe version of an image name ("" → "image"). */
 export function safeFileName(name) {
     return String(name).replace(/[^A-Za-z0-9_.-]+/g, '_').replace(/^\.+/, '') || 'image';