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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 changesdiff --git a/docs/terrain.md b/docs/terrain.mdindex 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, roughnIn 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.jsonindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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',