Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Keep water ripples a pixel can still show, fade at the sampling limit (#853)

Nguyen Xuan An07b698ff3263
diff --git a/changes/853-water-detail-footprint.md b/changes/853-water-detail-footprint.md
new file mode 100644
index 00000000..86089590
--- /dev/null
+++ b/changes/853-water-detail-footprint.md
@@ -0,0 +1 @@
+- `water` ripples keep every wave a pixel can still show, so far open sea matches a supersampled render more closely and shimmers less when the camera moves (#853)
diff --git a/scripts/capture-water-aliasing.mjs b/scripts/capture-water-aliasing.mjs
new file mode 100644
index 00000000..a1e2ddf3
--- /dev/null
+++ b/scripts/capture-water-aliasing.mjs
@@ -0,0 +1,79 @@
+// Renders the open-sea views of #827 (beauty and low camera) at 336x189 and as a 3x supersampled reference, at three small camera
+// pan steps, for scripts/score-water-aliasing.mjs. Needs a GPU. Run it through gpu-lock.
+// node scripts/capture-water-aliasing.mjs <output directory>
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+import { mkdtemp, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const repositoryRoot = resolve(import.meta.dirname, '..');
+const outputDirectory = resolve(process.argv[2] ?? 'artifacts/water-aliasing');
+const VIEW_EYES = { beauty: [-4, 8, 80], low: [-4, 2, 80] };
+const PAN_STEPS = [0, 0.25, 0.5];
+
+function seaRecipe() {
+ return {
+ format: '67js.scene', schemaVersion: 1,
+ geometries: [{
+ id: 'sea', type: 'mesh', base: { type: 'box', bevel: 0.002 },
+ edits: [
+ { op: 'delete', select: { not: { normal: [0, 1, 0], maxAngle: 10 } } },
+ { op: 'subdivide_edges', edges: { all: true }, cuts: 16 },
+ { op: 'subdivide', levels: 4 },
+ { op: 'set_position', position: { mul: [{ attr: 'position' }, [400, 1, 400]] } },
+ { op: 'ocean', axis: 'y', windSpeed: 16, direction: 100, choppiness: 1.5, size: 50, seed: 7, time: 2, resolution: 10 },
+ ],
+ }],
+ materials: [{ id: 'water', tag: 'water', color: [0.0033, 0.042, 0.069], metallic: 0, roughness: 0.14 }],
+ nodes: [{ id: 'sea', geometry: 'sea', material: 'water' }],
+ camera: { eye: [-4, 8, 80], target: [0, 0, 0], fov: 50 },
+ effects: { exposure: 0.6 },
+ environment: { sky: { type: 'physical', sunElevation: 9, sunRotation: 0, turbidity: 2, aerialPerspective: 0.3 }, world: true, ground: false, fogDensity: 0.0008 },
+ };
+}
+
+// Frame time proxy: the median of 15 full-size looks of the same scene. Compare two checkouts on a quiet machine.
+async function printMedianLookTime(client, sessionId, view) {
+ const timings = [];
+ for (let repeat = 0; repeat < 15; repeat += 1) {
+ const started = performance.now();
+ await client.callTool({ name: 'scene_look', arguments: { sessionId, width: 1024, height: 576 } }, { timeout: 300000 });
+ timings.push(performance.now() - started);
+ }
+ timings.sort((first, second) => first - second);
+ console.log('median look', view, timings[7].toFixed(1), 'ms (min', timings[0].toFixed(1), 'max', timings[14].toFixed(1), ')');
+}
+
+await mkdir(outputDirectory, { recursive: true });
+const workDirectory = await mkdtemp(join(tmpdir(), '67js-water-aliasing-'));
+const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [join(repositoryRoot, 'bin/67js-mcp.mjs'), '--backend', 'gpu', '--memory', '384', '--jobs', join(workDirectory, 'jobs')],
+ cwd: workDirectory, stderr: 'pipe',
+});
+const client = new Client({ name: 'water-aliasing', version: '1' });
+await client.connect(transport);
+try {
+ for (const [view, eye] of Object.entries(VIEW_EYES)) {
+ for (const [index, pan] of PAN_STEPS.entries()) {
+ const recipe = seaRecipe();
+ recipe.camera = { eye: [eye[0] + pan, eye[1], eye[2]], target: [pan, 0, 0], fov: 50 };
+ const created = await client.callTool({ name: 'scene_create', arguments: { recipe } }, { timeout: 300000 });
+ if (created.isError) throw new Error(JSON.stringify(created.content).slice(0, 800));
+ const sessionId = created.structuredContent.sessionId;
+ for (const [name, width, height] of [['n', 336, 189], ['ref', 1008, 567]]) {
+ const started = performance.now();
+ const look = await client.callTool({ name: 'scene_look', arguments: { sessionId, width, height } }, { timeout: 300000 });
+ const image = look.content.find(item => item.type === 'image')?.data;
+ if (!image) throw new Error(JSON.stringify(look.content).slice(0, 600));
+ await writeFile(join(outputDirectory, `${view}-${index}-${name}.png`), Buffer.from(image, 'base64'));
+ console.log('look', view, index, name, Math.round(performance.now() - started), 'ms');
+ }
+ if (index === 0) await printMedianLookTime(client, sessionId, view);
+ await client.callTool({ name: 'scene_dispose', arguments: { sessionId } });
+ }
+ }
+} finally {
+ await client.close();
+}
diff --git a/scripts/score-water-aliasing.mjs b/scripts/score-water-aliasing.mjs
new file mode 100644
index 00000000..8a49f143
--- /dev/null
+++ b/scripts/score-water-aliasing.mjs
@@ -0,0 +1,113 @@
+// Scores the stills of scripts/capture-water-aliasing.mjs. For the far third of the water rows it prints:
+// errorEnergy mean square of the high-pass of (frame - supersampled reference): the aliasing the frame adds
+// frameEnergy mean square of the high-pass of the frame; referenceEnergy the same for the reference
+// flicker mean square change of (frame - reference) between pan steps: shimmer that is not real motion
+// node scripts/score-water-aliasing.mjs <directory with the stills> [more directories to compare]
+import sharp from 'sharp';
+import { join, resolve } from 'node:path';
+
+const VIEWS = ['beauty', 'low'];
+const PAN_COUNT = 3;
+const SUPERSAMPLE = 3;
+
+async function luminanceOf(path, downsample) {
+ const { data, info } = await sharp(path).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+ const width = info.width / downsample;
+ const height = info.height / downsample;
+ const luminance = new Float64Array(width * height);
+ for (let y = 0; y < height; y += 1) {
+ for (let x = 0; x < width; x += 1) {
+ let sum = 0;
+ for (let dy = 0; dy < downsample; dy += 1) {
+ for (let dx = 0; dx < downsample; dx += 1) {
+ const offset = ((y * downsample + dy) * info.width + x * downsample + dx) * 3;
+ sum += 0.2126 * data[offset] + 0.7152 * data[offset + 1] + 0.0722 * data[offset + 2];
+ }
+ }
+ luminance[y * width + x] = sum / (downsample * downsample);
+ }
+ }
+ return { luminance, width, height };
+}
+
+function highPass(luminance, width, height) {
+ const result = new Float64Array(width * height);
+ for (let y = 1; y < height - 1; y += 1) {
+ for (let x = 1; x < width - 1; x += 1) {
+ let sum = 0;
+ for (let dy = -1; dy <= 1; dy += 1) {
+ for (let dx = -1; dx <= 1; dx += 1) sum += luminance[(y + dy) * width + x + dx];
+ }
+ result[y * width + x] = luminance[y * width + x] - sum / 9;
+ }
+ }
+ return result;
+}
+
+// The horizon is the first row from the top whose centre is clearly darker than the row above it (the sea against the sky).
+function horizonRow(reference, width, height) {
+ const column = width >> 1;
+ for (let y = 20; y < height - 8; y += 1) {
+ if (reference[(y - 8) * width + column] - reference[(y + 8) * width + column] > 12) return y;
+ }
+ return height >> 1;
+}
+
+function meanSquare(values, width, firstRow, lastRow) {
+ let sum = 0;
+ let count = 0;
+ for (let y = firstRow; y < lastRow; y += 1) {
+ for (let x = 2; x < width - 2; x += 1) {
+ sum += values[y * width + x] ** 2;
+ count += 1;
+ }
+ }
+ return sum / count;
+}
+
+function difference(first, second) {
+ return first.map((value, index) => value - second[index]);
+}
+
+async function scoreDirectory(directory) {
+ const report = {};
+ for (const view of VIEWS) {
+ const errors = [];
+ const frames = [];
+ let frameEnergy = 0;
+ let referenceEnergy = 0;
+ let errorEnergy = 0;
+ let region;
+ let frameWidth;
+ for (let pan = 0; pan < PAN_COUNT; pan += 1) {
+ const frame = await luminanceOf(join(directory, `${view}-${pan}-n.png`), 1);
+ const reference = await luminanceOf(join(directory, `${view}-${pan}-ref.png`), SUPERSAMPLE);
+ const { width, height } = frame;
+ frameWidth = width;
+ const horizon = horizonRow(reference.luminance, width, height);
+ region ??= [horizon + 4, horizon + 4 + Math.floor((height - horizon - 4) / 3)];
+ const error = difference(frame.luminance, reference.luminance);
+ errors.push(error);
+ frames.push(frame.luminance);
+ frameEnergy += meanSquare(highPass(frame.luminance, width, height), width, ...region);
+ referenceEnergy += meanSquare(highPass(reference.luminance, width, height), width, ...region);
+ errorEnergy += meanSquare(highPass(error, width, height), width, ...region);
+ }
+ let flicker = 0;
+ for (let pan = 1; pan < PAN_COUNT; pan += 1) {
+ flicker += meanSquare(difference(errors[pan], errors[pan - 1]), frameWidth, ...region) / (PAN_COUNT - 1);
+ }
+ report[view] = {
+ farRows: region,
+ frameEnergy: Number((frameEnergy / PAN_COUNT).toFixed(3)),
+ referenceEnergy: Number((referenceEnergy / PAN_COUNT).toFixed(3)),
+ errorEnergy: Number((errorEnergy / PAN_COUNT).toFixed(3)),
+ flicker: Number(flicker.toFixed(3)),
+ };
+ }
+ return report;
+}
+
+for (const directory of process.argv.slice(2)) {
+ console.log(directory, JSON.stringify(await scoreDirectory(resolve(directory)), null, 1));
+}
diff --git a/src/world-material-shader.js b/src/world-material-shader.js
index f7dddbf8..a635da6f 100644
--- a/src/world-material-shader.js
+++ b/src/world-material-shader.js
@@ -322,7 +322,8 @@ vec3 terrainNoise(vec2 position) {
// Wind ripples the mesh is too coarse to carry: eight travelling waves from 3 m down to 0.15 m, about 0.15 rms slope in all, which
// is what breaks a sun glint into facets. The wavelengths step by an irrational ratio and the directions by the golden angle, and
// each wave's phase and strength drift with slow noise, so no pair of waves repeats the same blob pattern over the water. A wave
-// fades out once a pixel is wider than a quarter of its length, so far water does not shimmer; the slope variance the faded waves
+// stays whole while a pixel is under a fifth of its length and is gone at half (two pixels per wave, the limit of one sample per
+// pixel), so far water does not shimmer but keeps every wave a pixel can still show; the slope variance the faded waves
// took with them comes back as lostVariance, to widen the glint instead.
vec2 waterDetailSlope(vec2 position, float footprint, out float lostVariance) {
vec2 slope = vec2(0.0);
@@ -330,7 +331,7 @@ vec2 waterDetailSlope(vec2 position, float footprint, out float lostVariance) {
float wavenumber = 2.1;
float angle = 0.4;
for (int index = 0; index < 8; index++) {
- float visible = 1.0 - smoothstep(0.06, 0.2, footprint * wavenumber / 6.2831853);
+ float visible = 1.0 - smoothstep(0.2, 0.5, footprint * wavenumber / 6.2831853);
vec2 direction = vec2(cos(angle), sin(angle));
float drift = terrainNoise(position * wavenumber * 0.09 + float(index) * 9.17).x - 0.5;
float strength = 0.15 + 1.7 * terrainNoise(position * wavenumber * 0.06 + float(index) * 23.9 + 4.0).x;
diff --git a/tests/water-ocean-look.test.js b/tests/water-ocean-look.test.js
index b80e77ac..d4cff6e4 100644
--- a/tests/water-ocean-look.test.js
+++ b/tests/water-ocean-look.test.js
@@ -73,3 +73,14 @@ test('wind ripples break the glint into facets and the foam into streaks', () =>
assert.match(shader, /1\.0 \/ \(1\.0 \/ 500\.0 \+ 0\.35 \* waterLostVariance\)/);
assert.match(shader, /terrainNoise\(crestPosition \* vec2\(3\.1, 14\.0\)/);
});
+
+test('a ripple stays whole down to five pixels per wave and is gone at the two-pixel limit of the sampling', () => {
+ const shader = createFragmentShader(['water', 'vertexColors']);
+ const fade = shader.match(/float visible = 1\.0 - smoothstep\(([\d.]+), ([\d.]+), footprint \* wavenumber/);
+ assert.ok(fade, 'the detail slope fades each wave by its pixel footprint');
+ const fadeStart = Number(fade[1]);
+ const fadeEnd = Number(fade[2]);
+ // footprint * wavenumber / 2pi is the pixel size in wavelengths: 0.2 is five pixels per wave, 0.5 is the Nyquist limit.
+ assert.ok(fadeStart >= 0.2, `the fade starts at ${fadeStart} pixels per wavelength, so waves that five pixels carry are thinned`);
+ assert.ok(fadeEnd <= 0.5, `the fade ends at ${fadeEnd} pixels per wavelength, so waves are still sampled below two pixels`);
+});