topotopo 0.1.0 → 0.3.0

package/dist/nodes/flow.js

@@ -5,7 +5,8 @@ import { NodeError } from '../graph/types.js';
 import { connectivity } from '../core/topology.js';
 import { stableStringify } from '../graph/engine.js';
 import { hashString } from '../core/random.js';
-import { importFormatFromPath, importGeometryAsync } from '../io/import.js';
+import { IMPORT_FORMATS, importFormatFromPath, importGeometryAsync } from '../io/import.js';
+import { readImageFile } from '../io/textures.js';
 import { mergeMaterialTables, writeMaterials } from '../core/materials.js';
 import { fusePoints } from './transform.js';
 import { DEFAULT_TRANSFER, composePackedXforms, expandPacked } from '../core/packed.js';
@@ -402,59 +403,159 @@ defineNode({
         return r.geo;
     },
 });
+const folderError = 'folder import needs a host with isDirectory/listDir support (use the Node host)';
+const childPath = (dir, name) => `${dir.replace(/[\\/]+$/, '')}/${name}`;
+/** null = a file; a directory listing includes unsupported files too, for signature invalidation. */
+function directoryFiles(path, host) {
+    if (/^https?:\/\//i.test(path))
+        return null;
+    if (!host.isDirectory) {
+        if (/[\\/]$/.test(path))
+            throw new NodeError(folderError);
+        return null;
+    }
+    if (!host.isDirectory(path))
+        return null;
+    if (!host.listDir)
+        throw new NodeError(folderError);
+    return host.listDir(path).sort((a, b) => a.localeCompare(b, 'en'));
+}
+/** One folder member is a variant, unless it already contains multiple named objects. */
+function folderNames(input, file) {
+    const g = input.clone();
+    const stem = file.replace(/(?:\.points\.json|\.[^.]+)$/i, '');
+    const used = new Uint8Array(g.numPoints);
+    for (const pt of g.vertexPoint)
+        used[pt] = 1;
+    const primName = g.prims.get('name'), pointName = g.points.get('name');
+    const names = new Set();
+    if (primName)
+        for (let i = 0; i < g.numPrims; i++)
+            names.add(String(primName.get(i)));
+    if (pointName)
+        for (let i = 0; i < g.numPoints; i++)
+            if (!used[i])
+                names.add(String(pointName.get(i)));
+    const label = (name) => names.size > 1 ? `${stem}/${name}` : stem;
+    const prims = g.prims.add('name', 'string', 1);
+    for (let i = 0; i < g.numPrims; i++)
+        prims.set(i, label(String(primName?.get(i) ?? '')));
+    if (used.some((v) => !v)) {
+        const points = g.points.add('name', 'string', 1);
+        for (let i = 0; i < g.numPoints; i++)
+            if (!used[i])
+                points.set(i, label(String(pointName?.get(i) ?? '')));
+    }
+    // Mixed scenes also carry names on anchors (point attributes take precedence during unpack/export).
+    const anchors = g.hasPacked() ? g.points.add('name', 'string', 1) : g.points.get('name');
+    if (anchors)
+        for (let p = 0; p < g.numPrims; p++)
+            if (g.primKind?.[p] === 1)
+                anchors.set(g.vertexPoint[g.primStart[p]], prims.get(p));
+    return g;
+}
 defineNode({
     type: 'file',
     category: 'io',
     packed: 'keep',
-    summary: 'Load geometry from disk/URL: OBJ, STL, PLY, glTF/GLB, Houdini .geo/.bgeo, CSV, points JSON or topotopo JSON. Z-up files can be converted.',
+    summary: 'Load a scene or folder from disk, or geometry from a URL: OBJ, STL, PLY, glTF/GLB, .blend, Houdini .geo/.bgeo, CSV, points JSON or topotopo JSON; a PNG becomes an image volume named after the file, as image_file reads it with its defaults (image_file has the layer and colour options). .blend needs the Node host and Blender (TOPOTOPO_BLENDER selects its executable); Blender’s own exporter converts it to a cached GLB. Folder mode loads supported files in name order, non-recursively: name becomes the file stem, or `<stem>/<name>` when the file has multiple distinct object names (on prims, packed prims and isolated points); its PNGs become images. copy_to_points {variants: \'name\'} consumes a dropped folder of models directly. glTF empties become points; path holds ancestor names, and object extras become attributes. For a manual Blender GLB: +Y up (default), Apply Modifiers, Loose Edges and Custom Properties; convert curves to mesh first because the exporter drops curves without bevel geometry. Z-up files can be converted.',
     aliases: ['import', 'load', 'read'],
     inputs: [],
     params: {
-        path: { type: 'path', default: '', desc: 'file path (relative to the workspace) or URL', aliases: ['file', 'filename'] },
-        format: { type: 'enum', options: ['auto', 'obj', 'stl', 'ply', 'glb', 'gltf', 'json', 'geo', 'bgeo', 'csv', 'pointsjson'], default: 'auto', desc: 'file format (auto = by extension; ".points.json" = pointsjson; json also reads points streams and Houdini .geo; bgeo = uncompressed binary Houdini geometry, not .bgeo.sc)' },
+        path: { type: 'path', default: '', desc: 'file or folder path (relative to the workspace) or file URL; folder mode needs directory support in the host', aliases: ['file', 'filename'] },
+        format: { type: 'enum', options: ['auto', ...IMPORT_FORMATS], default: 'auto', desc: 'file format (auto = by extension; folders always use each file’s extension; ".points.json" = pointsjson; json also reads points streams and Houdini .geo; bgeo = uncompressed binary Houdini geometry, not .bgeo.sc; png = an image volume)' },
         up_axis: { type: 'enum', options: ['y', 'z'], default: 'y', desc: 'source up axis; z converts Z-up files (Blender/Unreal exports) to Y-up' },
         scale: { type: 'float', default: 1, desc: 'uniform scale (e.g. 0.01 for centimetres → metres)' },
         weld: { type: 'bool', default: false, desc: 'fuse coincident points (glTF/STL meshes are split at seams; weld before booleans; expands packed instances)' },
-        instancing: { type: 'enum', options: ['packed', 'expand'], default: 'packed', desc: 'glTF EXT_mesh_gpu_instancing: keep instances as packed prims, or expand them into geometry' },
+        instancing: { type: 'enum', options: ['packed', 'expand'], default: 'packed', desc: 'glTF shared meshes and EXT_mesh_gpu_instancing: keep instances as packed prims, or expand them into geometry' },
+    },
+    signatureExtra: (p, engine) => {
+        const host = engine.host, files = directoryFiles(p.path, host);
+        return files === null ? host.fileStamp(p.path) : JSON.stringify([host.fileStamp(p.path), files.map((f) => [f, host.fileStamp(childPath(p.path, f))])]);
     },
-    signatureExtra: (p, engine) => engine.host.fileStamp(p.path),
     example: { type: 'file', params: { path: 'props/chair.obj', up_axis: 'z', weld: true } },
     async cook({ p, engine, warn }) {
         if (!p.path)
             throw new NodeError('path is empty');
-        const bytes = await engine.host.readFile(p.path).catch((e) => { throw new NodeError(`cannot read "${p.path}": ${e.message}`); });
-        const fmt = p.format === 'auto' ? importFormatFromPath(p.path) : p.format;
-        let g = await importGeometryAsync(bytes, fmt, { path: p.path, readFile: (f) => engine.host.readFile(f), warn, instancing: p.instancing });
-        if (p.up_axis === 'z' || p.scale !== 1) {
-            // packed instances: anchors convert like points, the conversion composes into their transforms (sources stay)
-            if (g.primKind)
-                composePackedXforms(g, p.up_axis === 'z' ? Float64Array.from([p.scale, 0, 0, 0, 0, 0, -p.scale, 0, 0, p.scale, 0, 0, 0, 0, 0, 1]) : Float64Array.from([p.scale, 0, 0, 0, 0, p.scale, 0, 0, 0, 0, p.scale, 0, 0, 0, 0, 1]));
-            const P = g.P;
-            for (let i = 0; i < P.length; i += 3) {
-                let x = P[i], y = P[i + 1], z = P[i + 2];
-                if (p.up_axis === 'z')
-                    [x, y, z] = [x, z, -y];
-                P[i] = x * p.scale;
-                P[i + 1] = y * p.scale;
-                P[i + 2] = z * p.scale;
+        const host = engine.host, files = directoryFiles(p.path, host);
+        const read = async (file, format) => {
+            if (format === 'png') {
+                // an image, not a mesh: the image_file loader (its defaults), and no axis, scale or weld
+                const g = new Geometry();
+                try {
+                    g.volumes = [await readImageFile((f) => host.readFile(f), file)];
+                }
+                catch (e) {
+                    throw new NodeError(String(e?.message ?? e));
+                }
+                return g;
             }
-            const N = g.points.get('N') ?? g.vertices.get('N');
-            if (N && p.up_axis === 'z') {
-                const d = N.data;
-                for (let i = 0; i < d.length; i += 3) {
-                    const y = d[i + 1];
-                    d[i + 1] = d[i + 2];
-                    d[i + 2] = -y;
+            let fmt = format;
+            let bytes;
+            if (fmt === 'blend') {
+                if (!host.convertFile)
+                    throw new NodeError('.blend needs the Node host with Blender installed (set TOPOTOPO_BLENDER); export a .glb instead');
+                bytes = await host.convertFile(host.resolvePath(file), 'glb');
+                fmt = 'glb';
+            }
+            else
+                bytes = await host.readFile(file).catch((e) => { throw new NodeError(`cannot read "${file}": ${e.message}${!host.isDirectory || !host.listDir ? `; ${folderError}` : ''}`); });
+            let g = await importGeometryAsync(bytes, fmt, { path: file, readFile: (f) => host.readFile(f), warn, instancing: p.instancing });
+            if (p.up_axis === 'z' || p.scale !== 1) {
+                // packed instances: anchors convert like points, the conversion composes into their transforms (sources stay)
+                if (g.primKind)
+                    composePackedXforms(g, p.up_axis === 'z' ? Float64Array.from([p.scale, 0, 0, 0, 0, 0, -p.scale, 0, 0, p.scale, 0, 0, 0, 0, 0, 1]) : Float64Array.from([p.scale, 0, 0, 0, 0, p.scale, 0, 0, 0, 0, p.scale, 0, 0, 0, 0, 1]));
+                const P = g.P;
+                for (let i = 0; i < P.length; i += 3) {
+                    let x = P[i], y = P[i + 1], z = P[i + 2];
+                    if (p.up_axis === 'z')
+                        [x, y, z] = [x, z, -y];
+                    P[i] = x * p.scale;
+                    P[i + 1] = y * p.scale;
+                    P[i + 2] = z * p.scale;
+                }
+                const N = g.points.get('N') ?? g.vertices.get('N');
+                if (N && p.up_axis === 'z') {
+                    const d = N.data;
+                    for (let i = 0; i < d.length; i += 3) {
+                        const y = d[i + 1];
+                        d[i + 1] = d[i + 2];
+                        d[i + 2] = -y;
+                    }
                 }
             }
+            if (p.weld) {
+                if (g.hasPacked())
+                    g = expandPacked(g, { transfer: DEFAULT_TRANSFER }).geo;
+                const b = g.bbox();
+                const diag = Math.hypot(b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2]) || 1;
+                return fusePoints(g, diag * 1e-7);
+            }
+            return g;
+        };
+        if (files === null)
+            return read(p.path, p.format === 'auto' ? importFormatFromPath(p.path) : p.format);
+        const parts = [];
+        for (const file of files) {
+            const fmt = importFormatFromPath(file);
+            if (!IMPORT_FORMATS.includes(fmt) || (fmt === 'blend' && !host.convertFile))
+                continue;
+            if (fmt === 'png') {
+                // images ride along with the models; one that cannot be read (a thumbnail too large, interlaced) is skipped
+                try {
+                    parts.push(await read(childPath(p.path, file), fmt));
+                }
+                catch (e) {
+                    warn(`skipped ${file}: ${e?.message ?? e}`);
+                }
+                continue;
+            }
+            parts.push(folderNames(await read(childPath(p.path, file), fmt), file));
         }
-        if (p.weld) {
-            if (g.hasPacked())
-                g = expandPacked(g, { transfer: DEFAULT_TRANSFER }).geo;
-            const b = g.bbox();
-            const diag = Math.hypot(b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2]) || 1;
-            return fusePoints(g, diag * 1e-7);
-        }
+        const g = Geometry.merge(parts);
+        const materials = mergeMaterialTables(parts);
+        if (Object.keys(materials).length)
+            writeMaterials(g, materials);
         return g;
     },
 });

package/dist/nodes/heightfield.js

@@ -12,6 +12,8 @@ import { defineNode } from '../graph/registry.js';
 import { NodeError } from '../graph/types.js';
 import { evalRamp } from '../graph/params.js';
 import { sampleEliminate } from './copy.js';
+import { connectivity } from '../core/topology.js';
+import { minDistanceSelect } from '../core/pcg.js';
 import { P, simBudget } from './util.js';
 import { wasmCallUnderBudget } from './wasmcall.js';
 import { getLoadedKernels, loadHostKernels } from '../wasm/kernels.js';
@@ -777,8 +779,12 @@ defineNode({
                     throw new NodeError(`${ctx.type}: expression exceeded ${engine.scriptTimeoutMs} ms (infinite loop?)`);
                 throw new NodeError(`${ctx.type}: ${e?.message ?? e}`);
             }
-            if (failed !== undefined)
+            if (failed !== undefined) {
+                const missing = /^(\w+) is not defined$/.exec(failed);
+                if (missing)
+                    throw new NodeError(`${ctx.type}: "${missing[1]}" is not a layer of this heightfield (layers: ${[...hf.layers.keys()].join(', ')}) and not an expression variable`, 'Compute the layer upstream, or connect the heightfield that has it as input 1 and read it as b_' + missing[1] + '.');
                 throw new NodeError(`${ctx.type}: ${failed}`);
+            }
             if (bad)
                 ctx.warn(`${bad} sample(s) gave NaN or infinity; written as 0`);
             writeLayer(hf, p.layer, mask, (k) => res[k]);
@@ -1254,7 +1260,7 @@ defineNode({
     type: 'heightfield_project',
     category: 'heightfield',
     summary: 'Stamp meshes or curves onto a heightfield: replace, raise (max), lower (min), add or subtract, blended over a radius.',
-    description: 'Houdini: HeightField Project. Polygons stamp the Y of their surface straight above/below each sample; open curves stamp their own height within width/2 of the curve. Outside the stamp the effect fades over radius metres towards the terrain (the nearest stamped height is used). mask_layer stores the blend weight (e.g. to freeze it during erosion or to texture it).',
+    description: 'Houdini: HeightField Project. Polygons stamp the Y of their surface straight above/below each sample; open curves stamp their own height within width/2 of the curve. Outside the stamp the effect fades over radius metres towards the terrain (the nearest stamped height is used). level mean sets each connected polygon piece to the average terrain height under it instead of its own Y: building pads, plazas and car parks sit where cut and fill balance, so slopes get the smallest embankments. mask_layer stores the blend weight (e.g. to freeze it during erosion or to texture it).',
     aliases: ['hf_project', 'heightfield_stamp'],
     inputs: [{ name: 'heightfield', desc: 'geometry with a heightfield' }, { name: 'stamp', desc: 'polygons (plateaus, platforms, rocks) and/or curves (ridges, dykes)' }],
     params: {
@@ -1264,6 +1270,7 @@ defineNode({
         offset: { type: 'float', default: 0, desc: 'added to the stamped height (metres)' },
         width: { type: 'float', default: 1, min: 0, desc: 'curves: stamp width (metres)' },
         direction: { type: 'enum', options: ['down', 'up'], default: 'down', desc: 'polygons: stamp the highest (down) or lowest (up) surface' },
+        level: { type: 'enum', options: ['stamp', 'mean'], default: 'stamp', desc: 'polygons: stamp height = the polygon surface (stamp), or the mean terrain height under each connected piece (mean: building pads that balance cut and fill; offset still applies)', aliases: ['pad', 'flatten_to'] },
         mask_layer: { type: 'string', default: '', desc: 'store the stamp weight in this layer ("" = no)' },
     },
     outputs: 'the layer (and mask_layer)',
@@ -1280,9 +1287,33 @@ defineNode({
         return eachField(ctx, (hf) => {
             const n = hf.count, up = p.direction === 'up';
             const SH = new Float64Array(n).fill(NaN), sites = new Uint8Array(n);
+            const levelMean = p.level === 'mean' && closed > 0;
+            const primPiece = levelMean ? connectivity(st).primClass : null, pieceOf = levelMean ? new Int32Array(n).fill(-1) : null;
             if (closed)
-                rasterizeMesh(hf, st, (k, y) => { if (!sites[k] || (up ? y < SH[k] : y > SH[k]))
-                    SH[k] = y; sites[k] = 1; });
+                rasterizeMesh(hf, st, (k, y, prim) => {
+                    if (!sites[k] || (up ? y < SH[k] : y > SH[k])) {
+                        SH[k] = y;
+                        if (pieceOf)
+                            pieceOf[k] = primPiece[prim];
+                    }
+                    sites[k] = 1;
+                });
+            if (pieceOf) {
+                // each piece at the mean of the terrain it covers (the layer before this stamp)
+                const cur = hf.read(p.layer), sum = new Map(), cnt = new Map();
+                for (let k = 0; k < n; k++) {
+                    const c = pieceOf[k];
+                    if (c >= 0) {
+                        sum.set(c, (sum.get(c) ?? 0) + cur[k]);
+                        cnt.set(c, (cnt.get(c) ?? 0) + 1);
+                    }
+                }
+                for (let k = 0; k < n; k++) {
+                    const c = pieceOf[k];
+                    if (c >= 0)
+                        SH[k] = sum.get(c) / cnt.get(c);
+                }
+            }
             const best = new Float64Array(n).fill(Infinity);
             for (const c of curvesOf(st)) {
                 if (c.closed)
@@ -1476,8 +1507,8 @@ defineNode({
 defineNode({
     type: 'heightfield_scatter',
     category: 'heightfield',
-    summary: 'Scatter points on a heightfield by a mask layer\'s density: P on the surface, N from the slope, height/slope/mask attributes. Feed copy_to_points.',
-    description: 'Houdini: HeightField Scatter. Count = density × area weighted by the mask (or count). Candidates are drawn by the mask (seeded), then thinned to even blue-noise spacing with relax (weighted sample elimination, as scatter, in chunks on the worker pool). Points sit exactly on the field\'s surface: bilinear between the samples (default), or with sample unreal_triangles the surface of an Unreal Landscape imported from this field\'s heightmap (export png16/r16): each cell split along its (0,0)–(1,1) diagonal in heightmap index space, column = X, row = Z (row 0 = min Z), which is how the Landscape triangulates its quads (vertex (x, y) = (column, row), Unreal Y = our Z), so instance bases land on the Landscape exactly. The modes agree at the samples and along cell edges and differ inside a cell by up to a quarter of its twist |h00 + h11 − h10 − h01|. N and slope come from central differences over one cell of the same surface; mask stays bilinear (Unreal samples weightmaps as textures). Attributes: height (Y), slope (degrees), mask (the density layer value at the point).',
+    summary: 'Scatter points on a heightfield by a mask layer\'s density: P on the surface, N from the slope (or straight up), height/slope/mask attributes, optional minimum distance. Feed copy_to_points.',
+    description: 'Houdini: HeightField Scatter. Count = density × area weighted by the mask (or count). Candidates are drawn by the mask (seeded), then thinned to even blue-noise spacing with relax (weighted sample elimination, as scatter, in chunks on the worker pool). Points sit exactly on the field\'s surface: bilinear between the samples (default), or with sample unreal_triangles the surface of an Unreal Landscape imported from this field\'s heightmap (export png16/r16): each cell split along its (0,0)–(1,1) diagonal in heightmap index space, column = X, row = Z (row 0 = min Z), which is how the Landscape triangulates its quads (vertex (x, y) = (column, row), Unreal Y = our Z), so instance bases land on the Landscape exactly. The modes agree at the samples and along cell edges and differ inside a cell by up to a quarter of its twist |h00 + h11 − h10 − h01|. N and slope come from central differences over one cell of the same surface; mask stays bilinear (Unreal samples weightmaps as textures). Attributes: height (Y), slope (degrees), mask (the density layer value at the point). N is the surface normal, and copy_to_points aims a copy\'s +Z along N (Houdini convention), which lays a Y-up tree down: align upright writes orient = identity so trees, houses and posts stand as modelled, align slope writes an orient that turns +Y onto the normal so rocks and shrubs lean with the terrain (orient wins over N in copy_to_points; random yaw goes on top with copy_to_points rotate_attrib). min_distance keeps every pair of points at least that far apart in XZ (exact dart throwing over the drawn candidates, replacing relax): building lots that never overlap; the count can come out lower when the masked area is full.',
     aliases: ['hf_scatter', 'heightfield_scatter_points'],
     inputs: [{ name: 'heightfield', desc: 'geometry with a heightfield' }],
     params: {
@@ -1487,12 +1518,14 @@ defineNode({
         relax: { type: 'bool', default: true, desc: 'even (blue-noise) spacing' },
         seed: P.seed(),
         keep_heightfield: { type: 'bool', default: false, desc: 'also keep the heightfield (default: points only)' },
+        align: { type: 'enum', options: ['none', 'upright', 'slope'], default: 'none', desc: 'instance orientation for copy_to_points: none = only N (the surface normal; copy_to_points then aims a copy\'s +Z along it, the Houdini convention, which lays Y-up models down); upright = orient identity, models stand as authored (trees, buildings, posts); slope = orient turns a model\'s +Y onto the surface normal (rocks, shrubs leaning with the terrain). N stays the surface normal', aliases: ['orientation', 'upright'] },
+        min_distance: { type: 'float', default: 0, min: 0, desc: 'exact minimum distance between points in XZ (metres; 0 = off), e.g. lot spacing so buildings never overlap; replaces relax, and the count can come out lower', aliases: ['mindist', 'min_dist', 'spacing'] },
         sample: {
             type: 'enum', options: ['bilinear', 'unreal_triangles'], default: 'bilinear', aliases: ['sampling', 'sample_mode'],
             desc: 'surface between samples: bilinear, or unreal_triangles = Unreal Landscape\'s triangles (each cell cut along its (0,0)–(1,1) diagonal in heightmap index space, column = X, row = Z), so points land exactly on a Landscape imported from this field\'s png16/r16 export',
         },
     },
-    outputs: 'points: N, height, slope, mask',
+    outputs: 'points: N, height, slope, mask; orient with align upright or slope',
     example: { nodes: { hf: { type: 'heightfield' }, n: { type: 'heightfield_noise', in: ['hf'], params: { amplitude: 3 } }, m: { type: 'heightfield_mask_by_feature', in: ['n'], params: { feature: 'slope', min_angle: 20 } }, s: { type: 'heightfield_scatter', in: ['m'], params: { density: 0.3 } } }, output: 's' },
     cook: async (ctx) => {
         const { p, input } = ctx;
@@ -1522,7 +1555,8 @@ defineNode({
             }
             if (count > 2e6)
                 throw new NodeError(`${ctx.type}: ${count.toLocaleString('en-US')} points is too many (max 2,000,000); lower density`);
-            const ncand = p.relax ? Math.min(count * 4, 8e6) : count;
+            const md = Math.max(0, p.min_distance || 0);
+            const ncand = md > 0 ? Math.min(Math.max(count * 8, 64), 8e6) : p.relax ? Math.min(count * 4, 8e6) : count;
             const pos = new Float64Array(ncand * 3);
             const x0 = hf.origin[0], z0 = hf.origin[1], x1 = x0 + hf.sizeX, z1 = z0 + hf.sizeZ;
             for (let q = 0; q < ncand; q++) {
@@ -1539,9 +1573,14 @@ defineNode({
                 pos[q * 3] = Math.min(x1, Math.max(x0, hf.x(i) + (r() - 0.5) * c));
                 pos[q * 3 + 2] = Math.min(z1, Math.max(z0, hf.z(j) + (r() - 0.5) * c));
             }
-            const keep = p.relax && ncand > count
-                ? await sampleEliminate(pos, count, Math.sqrt(total / (2 * Math.sqrt(3) * count)), undefined, ctx.parallelMap)
-                : Int32Array.from({ length: Math.min(ncand, count) }, (_, i) => i);
+            // candidates are drawn in mask-weighted random order, so greedy dart throwing over them keeps the density
+            const keep = md > 0
+                ? minDistanceSelect(pos, Int32Array.from({ length: ncand }, (_, i) => i), md, count)
+                : p.relax && ncand > count
+                    ? await sampleEliminate(pos, count, Math.sqrt(total / (2 * Math.sqrt(3) * count)), undefined, ctx.parallelMap)
+                    : Int32Array.from({ length: Math.min(ncand, count) }, (_, i) => i);
+            if (md > 0 && keep.length < count)
+                ctx.warn(`min_distance ${md} m fits ${keep.length} of ${count} points on "${hf.name}"`);
             const np = keep.length;
             const out = new Geometry({ positions: new Float64Array(np * 3) });
             const Pd = out.P;
@@ -1549,6 +1588,7 @@ defineNode({
             const ha = out.points.add('height', 'float', 1).data;
             const sa = out.points.add('slope', 'float', 1).data;
             const ma = out.points.add('mask', 'float', 1).data;
+            const OR = p.align === 'upright' || p.align === 'slope' ? out.points.add('orient', 'float', 4).data : null;
             // height, N and slope from the chosen surface (bilinear or Unreal's triangles); the mask always bilinear
             const H = hf.read('height'), e = c * 0.5, s = p.sample === 'unreal_triangles' ? 'unreal_triangles' : 'bilinear';
             keep.forEach((q, o) => {
@@ -1562,6 +1602,22 @@ defineNode({
                 N[o * 3] = -gx / l;
                 N[o * 3 + 1] = 1 / l;
                 N[o * 3 + 2] = -gz / l;
+                if (OR) {
+                    // upright: identity; slope: the shortest rotation taking +Y onto N, q = normalise((Y × N), 1 + Y·N)
+                    if (p.align === 'upright') {
+                        OR[o * 4] = 0;
+                        OR[o * 4 + 1] = 0;
+                        OR[o * 4 + 2] = 0;
+                        OR[o * 4 + 3] = 1;
+                    }
+                    else {
+                        const nx = N[o * 3], ny = N[o * 3 + 1], nz = N[o * 3 + 2], ql = Math.hypot(nz, nx, 1 + ny);
+                        OR[o * 4] = nz / ql;
+                        OR[o * 4 + 1] = 0;
+                        OR[o * 4 + 2] = -nx / ql;
+                        OR[o * 4 + 3] = (1 + ny) / ql;
+                    }
+                }
                 ha[o] = y;
                 sa[o] = (Math.atan(Math.hypot(gx, gz)) * 180) / Math.PI;
                 ma[o] = mask ? hf.sampleArray(mask, x, z) : 1;

package/dist/nodes/texture.d.ts

@@ -1,7 +1,7 @@
 import { Geometry } from '../core/geometry.ts';
 import { Image } from '../core/image.ts';
 import type { CookContext, ParamDef } from '../graph/types.ts';
-export declare const NO_IMAGE = "make one with a generator (tex_noise, tex_pattern, tex_shape, tex_cells \u2026), a bake (bake_ao, bake_curvature \u2026) or heightfield_to_tex";
+export declare const NO_IMAGE = "make one with a generator (tex_noise, tex_pattern, tex_shape, tex_cells \u2026), a bake (bake_ao, bake_curvature \u2026) or heightfield_to_tex, or load a PNG with image_file";
 export declare const resolutionParam: (def?: number) => ParamDef;
 export declare const nameParam: (def: string, desc?: string) => ParamDef;
 export declare function checkSize(w: number, h: number, node: string): void;

package/dist/nodes/texture.js

@@ -1,21 +1,22 @@
 // Texture nodes (category "texture"): a Substance Designer / Houdini COP style image family. Images are volumes of
-// kind 'image' carried in the geometry (core/image.ts): generators make a geometry holding one image, filters
-// process one layer of one image of their first input and pass everything else through, texture_to_material attaches
-// images to a material ("image:<name>" texture slots), and exporters embed them (glTF) or write them next to the file
-// (USD, the "textures" format). Bakes from meshes live in nodes/bake.ts.
+// kind 'image' carried in the geometry (core/image.ts): generators make a geometry holding one image, image_file loads
+// a PNG, filters process one layer of one image of their first input and pass everything else through,
+// texture_to_material attaches images to a material ("image:<name>" texture slots), and exporters embed them (glTF) or
+// write them next to the file (USD, the "textures" format). Bakes from meshes live in nodes/bake.ts.
 import { Geometry } from '../core/geometry.js';
 import { Image, MAIN_LAYER, MAX_PIXELS, channelsOf, findImage, imagesOf, isImage, resizeLayer, toGrey } from '../core/image.js';
 import { BLEND_MODES, GRADIENTS, PATTERNS, SHAPES, WARP_MODES, blendLayers, blurLayer, colorize, curvesLayer, edgeDetect, genGradient, genPattern, genScratches, genShape, genSplatter, heightToAO, histogramScanFn, levelsFn, mapValues, normalFromHeight, rampLUT, tileSampler, transformLayer, warpLayer, } from '../core/texture.js';
 import { Heightfield, heightfieldsOf } from '../core/heightfield.js';
 import { MATERIAL_ATTRIB, normalizeMaterial, readMaterials, writeMaterials } from '../core/materials.js';
 import { readUV } from '../core/uv.js';
+import { PNG_LAYERS, readImageFile } from '../io/textures.js';
 import { defineNode } from '../graph/registry.js';
 import { NodeError } from '../graph/types.js';
 import { evalRamp } from '../graph/params.js';
 import { andThen } from '../graph/parallel.js';
 import { P, mask } from './util.js';
 // ---------------------------------------------------------------- shared params and helpers
-export const NO_IMAGE = 'make one with a generator (tex_noise, tex_pattern, tex_shape, tex_cells …), a bake (bake_ao, bake_curvature …) or heightfield_to_tex';
+export const NO_IMAGE = 'make one with a generator (tex_noise, tex_pattern, tex_shape, tex_cells …), a bake (bake_ao, bake_curvature …) or heightfield_to_tex, or load a PNG with image_file';
 export const resolutionParam = (def = 512) => ({
     type: 'ivec2', default: [def, def], min: 1, max: 8192,
     desc: `image size in pixels [width, height] (one number = square; at most ${MAX_PIXELS.toLocaleString('en-US')} pixels); powers of two suit GPUs`,
@@ -372,6 +373,61 @@ defineNode({
         return imageGeo(img.set(MAIN_LAYER, fillContours(contours, w, h)));
     },
 });
+// ---------------------------------------------------------------- files
+defineNode({
+    type: 'image_file',
+    category: 'texture',
+    packed: 'keep',
+    summary: 'Load a PNG (8 or 16 bit, grey or colour) as an image: your own textures and masks into the texture nodes and materials.',
+    description: 'Houdini COP: File; Substance: Bitmap. The image is named after the file ("inputs/brick.png" → "brick") unless name ' +
+        'is set; layer C holds it, grey or RGBA (layers), and a grey image keeps the file\'s alpha, when it has one, in layer ' +
+        '"A". Values are samples / 255 (16-bit files / 65535: their precision is kept). Colour layers hold display values, as ' +
+        'every colour in the engine does ("#a5462e" is 0.65, 0.27, 0.18), so srgb (on by default) keeps the numbers the file ' +
+        'stores: a PNG this engine wrote reads back unchanged, and masks, heights, normal and roughness maps load as they are. ' +
+        'Turn srgb off only for a file holding linear-light colour (a linear render): grey and RGB are then encoded to display ' +
+        'values, alpha never (unlike Unreal\'s sRGB checkbox, off does not mean "data"). With input 0 connected the image is ' +
+        'added to that geometry, replacing an image of the same name, so image_file nodes chain. The file node reads .png ' +
+        'files the same way (with these defaults).',
+    aliases: ['image_read', 'png_read', 'texture_file'],
+    inputs: [{ name: 'geo', desc: 'optional: add the image to this geometry (chain image_file nodes, or carry a mesh); else the output holds only the image', optional: true }],
+    params: {
+        path: { type: 'path', default: '', desc: 'PNG file (relative to the workspace, e.g. "inputs/brick.png") or URL', aliases: ['file', 'filename'] },
+        name: nameParam('', 'image name ("" = the file name without .png); materials reference it as "image:<name>"'),
+        layers: { type: 'enum', options: [...PNG_LAYERS], default: 'auto', desc: 'auto = grey for grey PNGs (1–2 channels), RGBA for colour ones; grey = the luminance of a colour file; rgba = always four channels', aliases: ['channels'] },
+        srgb: { type: 'bool', default: true, desc: 'the file holds display (sRGB) values: kept as stored, like every colour in the engine (masks and data maps load unchanged too); off = it holds linear-light colour, encoded to display values on load (alpha never)' },
+    },
+    signatureExtra: (p, engine) => engine.host.fileStamp(p.path),
+    outputs: 'image <name>: C grey or RGBA 0..1; A grey (the file\'s alpha, for a grey image of a file with alpha)',
+    example: {
+        nodes: {
+            color: { type: 'image_file', params: { path: 'inputs/brick_color.png' } },
+            maps: { type: 'image_file', in: ['color'], params: { path: 'inputs/brick_rough.png', layers: 'grey' } },
+            box: { type: 'box' },
+            uv: { type: 'uv_project', in: ['box'], params: { method: 'box' } },
+            out: { type: 'texture_to_material', in: ['uv', 'maps'], params: { material: 'brick', base_color: 'brick_color', roughness: 'brick_rough' } },
+        },
+        output: 'out',
+    },
+    async cook(ctx) {
+        const { p, type, engine } = ctx;
+        if (!String(p.path ?? '').trim())
+            throw new NodeError(`${type}: path is empty`, 'a PNG relative to the workspace (people drop theirs into inputs/) or a URL');
+        let img;
+        try {
+            img = await readImageFile((f) => engine.host.readFile(f), p.path, { name: String(p.name ?? '').trim(), layers: p.layers, srgb: !!p.srgb });
+        }
+        catch (e) {
+            throw new NodeError(`${type}: ${e?.message ?? e}`);
+        }
+        const g = ctx.hasInput(0) ? ctx.input(0).clone() : new Geometry();
+        const before = g.volumes.length;
+        g.volumes = g.volumes.filter((v) => !(isImage(v) && v.name === img.name));
+        if (g.volumes.length < before)
+            ctx.warn(`${type}: replaced the input's image "${img.name}" (set name to keep both)`);
+        g.volumes.push(img);
+        return g;
+    },
+});
 // ---------------------------------------------------------------- filters
 const FILTER_INPUT = [{ name: 'image', desc: 'geometry holding the image to process (everything else passes through)' }];
 defineNode({

package/dist/render/options.js

@@ -28,7 +28,8 @@ export function renderArgs(a) {
     if (has('views'))
         o.views = parseViews(a.views);
     for (const [s, c] of [['size', 'size'], ['azimuth', 'azimuth'], ['elevation', 'elevation'], ['zoom', 'zoom'], ['hard_angle', 'hardAngle'], ['max_labels', 'maxLabels'],
-        ['glyph_scale', 'glyphScale'], ['max_glyphs', 'maxGlyphs'], ['ao_radius', 'aoRadius'], ['ortho_scale', 'orthoScale'], ['scale', 'scale'], ['ssaa', 'ssaa']]) {
+        ['glyph_scale', 'glyphScale'], ['max_glyphs', 'maxGlyphs'], ['ao_radius', 'aoRadius'], ['ortho_scale', 'orthoScale'], ['scale', 'scale'], ['ssaa', 'ssaa'],
+        ['max_triangles', 'maxTriangles']]) {
         const v = pick(s, c);
         if (v !== undefined)
             o[c] = num(v, s);

package/dist/render/raster.d.ts

@@ -38,6 +38,8 @@ export interface RenderOptions {
     /** look-at point (default bbox centre) */
     target?: Vec3 | null;
     ssaa?: number;
+    /** packed instances: triangles to draw at most (default RENDER_TRIANGLE_BUDGET, 600k; up to 50M); above it an evenly spread subset */
+    maxTriangles?: number;
     title?: string;
     /** shade 3D views with an 8×8 procedural checker from uv (stretch and flips become visible) */
     checker?: boolean;

package/dist/render/raster.js

@@ -105,7 +105,8 @@ function makeCam(name, bmin, bmax, W, H, o, kind = name, azDeg, secAxis = 1) {
 export function renderGeometry(g, o = {}) {
     // packed instances are drawn expanded (within a triangle budget), spline curves as polylines, see core/packed.ts
     if (g.hasPacked() || g.hasSplines()) {
-        const x = expandForRender(g, o);
+        const budget = o.maxTriangles !== undefined && o.maxTriangles > 0 ? Math.min(o.maxTriangles, 50_000_000) : undefined;
+        const x = expandForRender(g, o, budget);
         const r = renderGeometry(x.geo, x.opts);
         r.notes.unshift(...x.notes);
         return r;
@@ -1394,10 +1395,9 @@ export function renderGeometry(g, o = {}) {
     drawText(out, outW, outH, 6 * ui, fy, (o.title ? o.title.toUpperCase() + '  ' : '') + stats, [0.85, 0.85, 0.85], 2 * ui, false);
     if (legend) {
         const lx = outW - textWidth(legend, 2 * ui) - 8 * ui;
+        // drawn when it fits; the note below reports it either way (once)
         if (lx > textWidth(stats, 2 * ui) + 30 * ui)
             drawText(out, outW, outH, lx, fy, legend, [1, 0.85, 0.4], 2 * ui, false);
-        else
-            notes.push(legend.toLowerCase());
     }
     if (labelsSkipped)
         notes.push(`labels: ${labelsSkipped} not drawn to avoid overlaps (raise size, zoom in, or lower max_labels)`);

package/dist/render/texview.d.ts

@@ -1,9 +1,17 @@
-import type { Geometry } from '../core/geometry.ts';
+import { Geometry } from '../core/geometry.ts';
 /**
  * Draw the texture view into col (W × H RGB floats at SSAA scale ss). Returns the tile label. `spec` is the render
  * option `texture` (see entriesFor).
  */
 export declare function drawTextureView(g: Geometry, col: Float32Array, W: number, H: number, ss: number, spec: string, notes: string[]): string;
+/**
+ * For 3D viewers (the live viewer's GLB): a geometry holding only images (a dropped PNG, a texture graph) draws nothing,
+ * so each image (at most 16, as in the texture view) becomes a flat quad 1 m wide and height / width tall, standing on
+ * y = 0 in the XY plane and facing +Z, in reading order on a grid. Each quad has an unlit, double-sided material named
+ * "image:<name>" whose base colour map is the image (the GLB embeds it as a PNG), so it shows the stored values as the
+ * texture view does. Anything else (points, prims, other volumes) is returned as it is.
+ */
+export declare function withImagePreview(g: Geometry, max?: number): Geometry;
 /** Base colour maps per prim for persp/ortho views: sample(prim, u, v, lod, out) fills out with RGB and returns true. */
 export interface TextureSampler {
     /** true when prim p shows a base colour map */

package/dist/render/texview.js

@@ -1,5 +1,11 @@
-import { Image, channelsOf, imageRef, referenceableImages, resizeLayer } from '../core/image.js';
-import { primMaterials, readMaterials } from '../core/materials.js';
+// Textures in the renderer: the "texture" view (images drawn flat, labelled, several as a grid: every image, one image's
+// layers, or a material's maps as a strip) and the sampler persp/ortho views use with `textures: true` to show base
+// colour maps on meshes with uv. Pixels are drawn with the numbers they hold (as the PNG export writes them); RGBA
+// layers sit over a checkerboard where alpha < 1. For 3D viewers (the live viewer's GLB), withImagePreview turns a
+// geometry holding only images into flat textured quads laid out like the texture view.
+import { Geometry } from '../core/geometry.js';
+import { Image, channelsOf, imageRef, isImage, referenceableImages, resizeLayer } from '../core/image.js';
+import { MATERIAL_ATTRIB, normalizeMaterial, primMaterials, readMaterials, writeMaterials } from '../core/materials.js';
 import { drawText, textWidth } from './font.js';
 const SLOT_LABEL = { baseColor: 'BASE COLOR', normal: 'NORMAL', roughness: 'ROUGHNESS', orm: 'ORM' };
 /**
@@ -139,6 +145,41 @@ export function drawTextureView(g, col, W, H, ss, spec, notes) {
         notes.push(`texture view: values outside 0..1 are shown clamped (${ranges.slice(0, 4).join(', ')})`);
     return n === 1 ? `TEXTURE  ${entries[0].label.toUpperCase()}` : `TEXTURES  ${n} MAPS`;
 }
+/**
+ * For 3D viewers (the live viewer's GLB): a geometry holding only images (a dropped PNG, a texture graph) draws nothing,
+ * so each image (at most 16, as in the texture view) becomes a flat quad 1 m wide and height / width tall, standing on
+ * y = 0 in the XY plane and facing +Z, in reading order on a grid. Each quad has an unlit, double-sided material named
+ * "image:<name>" whose base colour map is the image (the GLB embeds it as a PNG), so it shows the stored values as the
+ * texture view does. Anything else (points, prims, other volumes) is returned as it is.
+ */
+export function withImagePreview(g, max = 16) {
+    if (g.numPoints || !g.volumes.length || !g.volumes.every(isImage))
+        return g;
+    const imgs = [...referenceableImages(g).values()].slice(0, max);
+    const n = imgs.length, cols = Math.ceil(Math.sqrt(n)), rows = Math.ceil(n / cols), gap = 0.1;
+    const cellH = Math.max(...imgs.map((im) => im.height / im.width));
+    const P = [], prims = [], uv = [];
+    imgs.forEach((im, k) => {
+        const h = im.height / im.width, c = k % cols, r = Math.floor(k / cols);
+        const x = c * (1 + gap) - (cols * (1 + gap) - gap) / 2, y = (rows - 1 - r) * (cellH + gap) + (cellH - h) / 2;
+        const b = P.length / 3;
+        P.push(x, y, 0, x + 1, y, 0, x + 1, y + h, 0, x, y + h, 0);
+        uv.push(0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0);
+        prims.push([b, b + 1, b + 2, b + 3]);
+    });
+    const out = new Geometry({ positions: P, prims });
+    out.points.add('uv', 'float', 3).data.set(uv);
+    const mat = out.prims.add(MATERIAL_ATTRIB, 'string', 1);
+    const table = {};
+    imgs.forEach((im, k) => {
+        const name = `image:${im.name}`;
+        mat.set(k, name);
+        table[name] = normalizeMaterial({ baseColor: [1, 1, 1], roughness: 1, metallic: 0, unlit: true, doubleSided: true, textures: { baseColor: name } });
+    });
+    writeMaterials(out, table);
+    out.volumes = imgs;
+    return out;
+}
 /** A mip chain of a layer (area-averaged halves, wrapping) down to 1 × 1. */
 function mipChain(img, layer) {
     const a = img.layer(layer), ch = channelsOf(a, img.count) || 1;