Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Build terrain from rasters in typed-array passes (part of #406)

Nguyen Xuan An4f7385bb0754
diff --git a/changes/406.md b/changes/406.md
new file mode 100644
index 00000000..e80abb04
--- /dev/null
+++ b/changes/406.md
@@ -0,0 +1 @@
+- Add `67js/addons/heightfield` (`sampleRasterGrid`, `createHeightfieldGeometry`): a terrain mesh from height, mask and photo rasters in typed-array passes instead of per-vertex closures and allocations (issue #406). On the AIS port film the terrain code falls from about 3.4 s to 0.6 s and the page loads in 3.6 to 3.7 s instead of 5.5 to 6.7 s (three.js: 1.0 to 1.4 s); the rendered frame is pixel-identical.
diff --git a/changes/406.size.md b/changes/406.size.md
new file mode 100644
index 00000000..fbfbf72a
--- /dev/null
+++ b/changes/406.size.md
@@ -0,0 +1 @@
+- entry:heightfield: new addon `67js/addons/heightfield` (`sampleRasterGrid`, `createHeightfieldGeometry`) that replaces the per-vertex JavaScript a terrain built from a mask needed; no other bundle changes
diff --git a/docs/terrain.md b/docs/terrain.md
index 3b2c3880..aef1bb4c 100644
--- a/docs/terrain.md
+++ b/docs/terrain.md
@@ -90,6 +90,17 @@ Memory: three `TEXTURE_2D_ARRAY`s on units 11 to 13 (sRGB colour, normal, roughn
In a recipe, the same ground is the `terrain` geometry (`size`, `resolution`, `seed`, `amplitude`, `holes`): see [agent-scene](agent-scene.md).
+## Heightfield from rasters
+
+`67js/addons/heightfield` builds a mesh from georeferenced rasters (heights, a mask, a photo) when `createTerrain` does not fit, such as a shoreline cut from a sea mask. A raster is `{ values, width, height, box: { x_min, x_max, y_min, y_max } }`, pixel centres on the box, row 0 at the north edge.
+
+- `sampleRasterGrid(raster, { columns, rows, eastAt, northAt, cellSize, samplesPerSide, scale })` returns a `Float64Array` with the mean of the raster over a square cell around each vertex (`cellSize` 0 with one sample reads the raster at the vertex). The mean of bilinear samples is a weighted sum of pixels, so it runs as two passes over the pixels, not 16 bilinear reads and an allocation per vertex.
+- `createHeightfieldGeometry({ columns, rows, eastAt, northAt, heights, uvBox, keepCell })` returns `{ positions, normals, uvs, indices }` in one pass over typed arrays, with `keepCell(column, row)` dropping cells a finer tier covers.
+
+Combine the sampled arrays into `heights` in your own loop (for a sea mask: lower the vertex by the mask share), then build the geometry. A test pins the output against the per-vertex build it replaces: positions, normals, uvs and indices are bit-equal.
+
+Measured on the AIS port film (4.9 M vertices over three tiers, 10 m core mesh, sea mask averaged over each cell), page open to `stageReady`, RTX 3060, headless Chrome on ANGLE D3D11, four runs while other sessions loaded the machine: 5.5 to 13.1 s before (5.5 to 6.7 s in the quiet runs), 3.6 to 9.6 s after (3.6 to 3.7 s in three of four runs), against 1.0 to 1.4 s for the three.js build of the same scene. The terrain code fell from about 3.4 s of CPU to about 0.6 s; the frame at film second 1 is pixel-identical (max difference 0 of 255). What stays: image decode and mask readback (about 0.6 s), texture upload (about 0.7 s) and shader compile (about 0.6 s). The three.js build does the shoreline per pixel in a shader, so it needs no mask pass.
+
## Navigation
`addons/navmesh` finds walking routes over any triangle ground, so a character can go around holes, steep slopes and obstacles. It is pure JavaScript and gives the same path for the same input.
diff --git a/package.json b/package.json
index 219748a1..1a3c170b 100644
--- a/package.json
+++ b/package.json
@@ -72,6 +72,7 @@
"./addons/vehicle": "./build/vehicle.js",
"./addons/vegetation": "./build/vegetation.js",
"./addons/terrain": "./build/terrain.js",
+ "./addons/heightfield": "./build/heightfield.js",
"./addons/navmesh": "./build/navmesh.js",
"./addons/grass": "./build/grass.js",
"./addons/clutter": "./build/clutter.js",
diff --git a/src/heightfield.js b/src/heightfield.js
new file mode 100644
index 00000000..cc335f61
--- /dev/null
+++ b/src/heightfield.js
@@ -0,0 +1,170 @@
+// A mesh grid over georeferenced rasters (heights, a mask, a photo) without a closure call per sample. Rasters are
+// { values, width, height, box: { x_min, x_max, y_min, y_max } } with pixel centres on the box and row 0 at the north edge.
+// World axes: x east, y up, z = -north.
+
+function clamp(value, low, high) {
+ return Math.min(high, Math.max(low, value));
+}
+
+// For one axis, the raster pixels each grid index reads and their weights. The mean of bilinear samples is a
+// weighted sum of pixels, and a bilinear sample is separable across the axes, so the east weights and the north
+// weights can be built apart and applied in two passes.
+function axisTaps({ count, coordinateAt, boxLow, boxHigh, pixels, reversed, cellSize, samplesPerSide }) {
+ const firstPixel = new Int32Array(count);
+ const tapCount = new Int32Array(count);
+ const tapOffset = new Int32Array(count);
+ const lowPixels = new Int32Array(samplesPerSide);
+ const fractions = new Float64Array(samplesPerSide);
+ const share = 1 / samplesPerSide;
+ let weights = new Float64Array(count * (samplesPerSide + 1));
+ let used = 0;
+ for (let index = 0; index < count; index += 1) {
+ const centre = coordinateAt(index);
+ let lowest = pixels;
+ let highest = 0;
+ for (let sample = 0; sample < samplesPerSide; sample += 1) {
+ const world = centre + ((sample + 0.5) / samplesPerSide - 0.5) * cellSize;
+ const unit = reversed ? (boxHigh - world) / (boxHigh - boxLow) : (world - boxLow) / (boxHigh - boxLow);
+ const position = unit * pixels - 0.5;
+ const low = clamp(Math.floor(position), 0, pixels - 2);
+ lowPixels[sample] = low;
+ fractions[sample] = clamp(position - low, 0, 1);
+ lowest = Math.min(lowest, low);
+ highest = Math.max(highest, low + 1);
+ }
+ const taps = highest - lowest + 1;
+ if (used + taps > weights.length) {
+ const grown = new Float64Array(Math.max(weights.length * 2, used + taps));
+ grown.set(weights);
+ weights = grown;
+ }
+ firstPixel[index] = lowest;
+ tapCount[index] = taps;
+ tapOffset[index] = used;
+ for (let sample = 0; sample < samplesPerSide; sample += 1) {
+ const slot = used + lowPixels[sample] - lowest;
+ weights[slot] += (1 - fractions[sample]) * share;
+ weights[slot + 1] += fractions[sample] * share;
+ }
+ used += taps;
+ }
+ return { firstPixel, tapCount, tapOffset, weights };
+}
+
+/**
+ * The mean of a raster over a square cell centred on every vertex of a regular grid, from a samplesPerSide by
+ * samplesPerSide pattern of bilinear samples; `cellSize` 0 with one sample reads the raster at the vertex.
+ * Returns a Float64Array of columns * rows values (row-major), each multiplied by `scale`. The same values as
+ * averaging bilinear samples vertex by vertex, in a pass over the pixels per axis and no allocation per vertex.
+ */
+export function sampleRasterGrid(raster, { columns, rows, eastAt, northAt, cellSize = 0, samplesPerSide = 1, scale = 1 }) {
+ const { values, width, height, box } = raster;
+ if (width < 2 || height < 2) throw new RangeError('A raster needs at least 2 by 2 pixels.');
+ const east = axisTaps({ count: columns, coordinateAt: eastAt, boxLow: box.x_min, boxHigh: box.x_max, pixels: width, reversed: false, cellSize, samplesPerSide });
+ const north = axisTaps({ count: rows, coordinateAt: northAt, boxLow: box.y_min, boxHigh: box.y_max, pixels: height, reversed: true, cellSize, samplesPerSide });
+ let firstRow = height;
+ let lastRow = 0;
+ for (let row = 0; row < rows; row += 1) {
+ firstRow = Math.min(firstRow, north.firstPixel[row]);
+ lastRow = Math.max(lastRow, north.firstPixel[row] + north.tapCount[row] - 1);
+ }
+ const across = new Float64Array((lastRow - firstRow + 1) * columns);
+ for (let pixelRow = firstRow; pixelRow <= lastRow; pixelRow += 1) {
+ const rowStart = pixelRow * width;
+ const outputStart = (pixelRow - firstRow) * columns;
+ for (let column = 0; column < columns; column += 1) {
+ const offset = east.tapOffset[column];
+ const start = rowStart + east.firstPixel[column];
+ let total = 0;
+ for (let tap = 0, taps = east.tapCount[column]; tap < taps; tap += 1) total += east.weights[offset + tap] * values[start + tap];
+ across[outputStart + column] = total;
+ }
+ }
+ const output = new Float64Array(columns * rows);
+ for (let row = 0; row < rows; row += 1) {
+ const offset = north.tapOffset[row];
+ const outputStart = row * columns;
+ for (let tap = 0, taps = north.tapCount[row]; tap < taps; tap += 1) {
+ const weight = north.weights[offset + tap] * scale;
+ const sourceStart = (north.firstPixel[row] + tap - firstRow) * columns;
+ for (let column = 0; column < columns; column += 1) output[outputStart + column] += weight * across[sourceStart + column];
+ }
+ }
+ return output;
+}
+
+function gridNormals(positions, columns, rows) {
+ const normals = new Float32Array(positions.length);
+ for (let row = 0; row < rows; row += 1) {
+ const upRow = Math.max(0, row - 1) * columns;
+ const downRow = Math.min(rows - 1, row + 1) * columns;
+ for (let column = 0; column < columns; column += 1) {
+ const vertex = row * columns + column;
+ const left = row * columns + Math.max(0, column - 1);
+ const right = row * columns + Math.min(columns - 1, column + 1);
+ const up = upRow + column;
+ const down = downRow + column;
+ const normalX = -(positions[right * 3 + 1] - positions[left * 3 + 1]) / (positions[right * 3] - positions[left * 3]);
+ const normalZ = -(positions[down * 3 + 1] - positions[up * 3 + 1]) / (positions[down * 3 + 2] - positions[up * 3 + 2]);
+ const length = Math.hypot(normalX, 1, normalZ);
+ normals[vertex * 3] = normalX / length;
+ normals[vertex * 3 + 1] = 1 / length;
+ normals[vertex * 3 + 2] = normalZ / length;
+ }
+ }
+ return normals;
+}
+
+/**
+ * Mesh geometry ({ positions, normals, uvs, indices }) for a regular grid of `heights` (columns * rows, row-major,
+ * row 0 first). `eastAt(column)` and `northAt(row)` give the world position of each line; uvs span `uvBox`;
+ * `keepCell(column, row)` drops the cells a finer tier covers.
+ */
+export function createHeightfieldGeometry({ columns, rows, eastAt, northAt, heights, uvBox, keepCell }) {
+ if (heights.length !== columns * rows) throw new RangeError('heights must hold columns * rows values.');
+ const positions = new Float32Array(columns * rows * 3);
+ const uvs = new Float32Array(columns * rows * 2);
+ const uvWidth = uvBox.x_max - uvBox.x_min;
+ const uvHeight = uvBox.y_max - uvBox.y_min;
+ const eastLines = new Float64Array(columns);
+ for (let column = 0; column < columns; column += 1) eastLines[column] = eastAt(column);
+ for (let row = 0; row < rows; row += 1) {
+ const north = northAt(row);
+ const uvNorth = (uvBox.y_max - north) / uvHeight;
+ for (let column = 0; column < columns; column += 1) {
+ const east = eastLines[column];
+ const vertex = row * columns + column;
+ positions[vertex * 3] = east;
+ positions[vertex * 3 + 1] = heights[vertex];
+ positions[vertex * 3 + 2] = -north;
+ uvs[vertex * 2] = (east - uvBox.x_min) / uvWidth;
+ uvs[vertex * 2 + 1] = uvNorth;
+ }
+ }
+ const kept = new Uint8Array((columns - 1) * (rows - 1));
+ let keptCount = 0;
+ for (let row = 0; row < rows - 1; row += 1) {
+ for (let column = 0; column < columns - 1; column += 1) {
+ if (keepCell && !keepCell(column, row)) continue;
+ kept[row * (columns - 1) + column] = 1;
+ keptCount += 1;
+ }
+ }
+ const indices = new Uint32Array(keptCount * 6);
+ let cursor = 0;
+ for (let row = 0; row < rows - 1; row += 1) {
+ for (let column = 0; column < columns - 1; column += 1) {
+ if (!kept[row * (columns - 1) + column]) continue;
+ const a = row * columns + column;
+ const c = a + columns;
+ indices[cursor] = a;
+ indices[cursor + 1] = c;
+ indices[cursor + 2] = a + 1;
+ indices[cursor + 3] = a + 1;
+ indices[cursor + 4] = c;
+ indices[cursor + 5] = c + 1;
+ cursor += 6;
+ }
+ }
+ return { positions, normals: gridNormals(positions, columns, rows), uvs, indices };
+}
diff --git a/tests/heightfield.test.js b/tests/heightfield.test.js
new file mode 100644
index 00000000..5d11c749
--- /dev/null
+++ b/tests/heightfield.test.js
@@ -0,0 +1,129 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { createHeightfieldGeometry, sampleRasterGrid } from '../src/heightfield.js';
+
+// The per-vertex code the AIS port film used before: a closure call per sample, a cell mean of 4 by 4 bilinear
+// samples, an index array grown with push. The new path must give the same mesh from it.
+function referenceBilinear(raster, east, north) {
+ const { box } = raster;
+ const column = ((east - box.x_min) / (box.x_max - box.x_min)) * raster.width - 0.5;
+ const row = ((box.y_max - north) / (box.y_max - box.y_min)) * raster.height - 0.5;
+ const left = Math.min(raster.width - 2, Math.max(0, Math.floor(column)));
+ const top = Math.min(raster.height - 2, Math.max(0, Math.floor(row)));
+ const across = Math.min(1, Math.max(0, column - left));
+ const down = Math.min(1, Math.max(0, row - top));
+ const at = (x, y) => raster.values[y * raster.width + x];
+ const upper = at(left, top) * (1 - across) + at(left + 1, top) * across;
+ const lower = at(left, top + 1) * (1 - across) + at(left + 1, top + 1) * across;
+ return upper * (1 - down) + lower * down;
+}
+
+function referenceCellAverage(raster, east, north, cellSize, samplesPerSide) {
+ let total = 0;
+ for (let across = 0; across < samplesPerSide; across += 1) {
+ for (let down = 0; down < samplesPerSide; down += 1) {
+ const offsetEast = ((across + 0.5) / samplesPerSide - 0.5) * cellSize;
+ const offsetNorth = ((down + 0.5) / samplesPerSide - 0.5) * cellSize;
+ total += referenceBilinear(raster, east + offsetEast, north + offsetNorth);
+ }
+ }
+ return total / (samplesPerSide * samplesPerSide);
+}
+
+function referenceGeometry({ columns, rows, eastAt, northAt, heightAt, uvBox, keepCell }) {
+ const positions = new Float32Array(columns * rows * 3);
+ const uvs = new Float32Array(columns * rows * 2);
+ for (let row = 0; row < rows; row += 1) {
+ const north = northAt(row);
+ for (let column = 0; column < columns; column += 1) {
+ const east = eastAt(column);
+ const vertex = row * columns + column;
+ positions[vertex * 3] = east;
+ positions[vertex * 3 + 1] = heightAt(east, north);
+ positions[vertex * 3 + 2] = -north;
+ uvs[vertex * 2] = (east - uvBox.x_min) / (uvBox.x_max - uvBox.x_min);
+ uvs[vertex * 2 + 1] = (uvBox.y_max - north) / (uvBox.y_max - uvBox.y_min);
+ }
+ }
+ const normals = new Float32Array(positions.length);
+ for (let row = 0; row < rows; row += 1) {
+ for (let column = 0; column < columns; column += 1) {
+ const left = row * columns + Math.max(0, column - 1);
+ const right = row * columns + Math.min(columns - 1, column + 1);
+ const up = Math.max(0, row - 1) * columns + column;
+ const down = Math.min(rows - 1, row + 1) * columns + column;
+ const normalX = -(positions[right * 3 + 1] - positions[left * 3 + 1]) / (positions[right * 3] - positions[left * 3]);
+ const normalZ = -(positions[down * 3 + 1] - positions[up * 3 + 1]) / (positions[down * 3 + 2] - positions[up * 3 + 2]);
+ const length = Math.hypot(normalX, 1, normalZ);
+ const vertex = row * columns + column;
+ normals[vertex * 3] = normalX / length;
+ normals[vertex * 3 + 1] = 1 / length;
+ normals[vertex * 3 + 2] = normalZ / length;
+ }
+ }
+ const indices = [];
+ for (let row = 0; row < rows - 1; row += 1) {
+ for (let column = 0; column < columns - 1; column += 1) {
+ if (keepCell && !keepCell(column, row)) continue;
+ const a = row * columns + column;
+ indices.push(a, a + columns, a + 1, a + 1, a + columns, a + columns + 1);
+ }
+ }
+ return { positions, normals, uvs, indices: Uint32Array.from(indices) };
+}
+
+function seededRaster(width, height, box, seed) {
+ const values = new Uint8Array(width * height);
+ let state = seed;
+ for (let index = 0; index < values.length; index += 1) {
+ state = (state * 1664525 + 1013904223) >>> 0;
+ values[index] = state >>> 24;
+ }
+ return { values, width, height, box };
+}
+
+function checksum(array) {
+ return createHash('sha256').update(Buffer.from(array.buffer, array.byteOffset, array.byteLength)).digest('hex').slice(0, 16);
+}
+
+const mapBox = { x_min: 100, x_max: 740, y_min: -200, y_max: 440 };
+const mask = seededRaster(53, 47, mapBox, 7);
+const grid = { columns: 41, rows: 37, eastAt: (column) => 90 + column * 17, northAt: (row) => 450 - row * 18.5 };
+
+test('sampleRasterGrid equals the cell mean of bilinear samples taken vertex by vertex', () => {
+ for (const [cellSize, samplesPerSide] of [[17, 4], [0, 1], [40, 3]]) {
+ const fast = sampleRasterGrid(mask, { ...grid, cellSize, samplesPerSide, scale: 1 / 255 });
+ let largestDifference = 0;
+ for (let row = 0; row < grid.rows; row += 1) {
+ for (let column = 0; column < grid.columns; column += 1) {
+ const expected = referenceCellAverage(mask, grid.eastAt(column), grid.northAt(row), cellSize, samplesPerSide) / 255;
+ largestDifference = Math.max(largestDifference, Math.abs(fast[row * grid.columns + column] - expected));
+ }
+ }
+ assert.ok(largestDifference < 1e-12, `cell ${cellSize}, ${samplesPerSide} samples: largest difference ${largestDifference}`);
+ }
+});
+
+test('createHeightfieldGeometry matches the old per-vertex build, with dropped cells', () => {
+ const heightOf = (east, north) => referenceCellAverage(mask, east, north, 17, 4) / 255 * 30 + Math.sin(east / 60) * 5 - north * 0.01;
+ const keepCell = (column, row) => !(column > 10 && column < 25 && row > 8 && row < 20);
+ const uvBox = mapBox;
+ const expected = referenceGeometry({ ...grid, heightAt: heightOf, uvBox, keepCell });
+ const heights = new Float32Array(grid.columns * grid.rows);
+ for (let row = 0; row < grid.rows; row += 1) {
+ for (let column = 0; column < grid.columns; column += 1) heights[row * grid.columns + column] = heightOf(grid.eastAt(column), grid.northAt(row));
+ }
+ const actual = createHeightfieldGeometry({ ...grid, heights, uvBox, keepCell });
+ assert.deepEqual(actual.indices, expected.indices);
+ assert.deepEqual(actual.uvs, expected.uvs);
+ assert.deepEqual(actual.positions, expected.positions);
+ assert.deepEqual(actual.normals, expected.normals);
+ assert.equal(checksum(actual.positions), '4e667c0630cadd69');
+ assert.equal(checksum(actual.normals), 'a0164146e3b24eb8');
+ assert.equal(checksum(actual.indices), 'cad638e3a2ef4d96');
+});
+
+test('createHeightfieldGeometry rejects a height array of the wrong length', () => {
+ assert.throws(() => createHeightfieldGeometry({ ...grid, heights: new Float32Array(3), uvBox: mapBox }), RangeError);
+});
diff --git a/vite.lib.config.js b/vite.lib.config.js
index bd1c54a9..c264e966 100644
--- a/vite.lib.config.js
+++ b/vite.lib.config.js
@@ -38,6 +38,7 @@ export default defineConfig({
vehicle: 'src/vehicle.js',
vegetation: 'src/vegetation.js',
terrain: 'src/terrain.js',
+ heightfield: 'src/heightfield.js',
navmesh: 'src/navmesh.js',
grass: 'src/grass.js',
clutter: 'src/clutter.js',