Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Keep far tree levels as bright as level 0 from every side (closes #432)

Nguyen Xuan An9cdbb2e0e4c6
diff --git a/changes/432-tree-level-luminance.md b/changes/432-tree-level-luminance.md
new file mode 100644
index 00000000..9188764d
--- /dev/null
+++ b/changes/432-tree-level-luminance.md
@@ -0,0 +1,7 @@
+- Far tree levels no longer pop darker than level 0 when a tree switches level (issue #432). Four changes:
+ - The standing card of each clump on levels 2 and 3 is rolled by the golden angle from the last clump. All of them used to face one world direction, so a far tree drew about three times darker from some sides than from others (0.80 of level 0 from one side and 0.27 from the others, for a conifer under even sky light).
+ - The clump cards of levels 2 and 3 take their own normals again instead of blending 70% toward the crown's (`clumpCanopyBlend`, 0 by default, 0.3 for the bush). With the crown normal, a sun behind a tree left its far levels near black while level 0 still glowed through its leaves.
+ - The level match in `src/tree-sky.js` takes the mean sky visibility over the leaf each vertex stands for (`vertexCoverage`, a third of the area of its triangles) instead of over the vertices, because a clump has few vertices for a lot of leaf.
+ - Each species carries a colour gain and a sky gain for levels 2 and 3 in `src/tree-level-gains.js`. `node scripts/measure-tree-level-luminance.mjs --fit` solves them: it draws each level against level 0 from three sides under sky light, a sun behind and a sun in front, and brings the ratios close to 1. The file holds the geometric mean of the fits on seeds 1 to 6, recentred a little below 1. Trees of one species still differ, so each tree's colour gain also follows how much clump area its far level carries against level 0 (`area`, `areaExponent`). Over seeds 1 to 8, each species' mean ratio of levels 2 and 3 to level 0 lies within 0.90 to 1.07 under every light (0.15 to 0.66 on main for the four trees), and 226 of the 240 seed ratios (5 species, 2 levels, 3 lights, 8 seeds) land within 0.85 to 1.15.
+ - The probe (`scripts/measure-tree-level-luminance.mjs`) also prints the ratio from each side (`sides`), which is how the one-way cards showed up: pooled over three sides, they averaged out.
+- `tests/tree-sky-levels.test.js` pins the coverage-weighted mean and the range of the gains. This changes how far trees look.
diff --git a/changes/432-tree-level-luminance.size.md b/changes/432-tree-level-luminance.size.md
new file mode 100644
index 00000000..a41b1919
--- /dev/null
+++ b/changes/432-tree-level-luminance.size.md
@@ -0,0 +1 @@
+- scene:agent-scene+lazy: 364625 to 365189 bytes gzip (+564) for the per-level tree gains (`src/tree-level-gains.js`, 10 rows of three numbers and one exponent per species), the leaf-area correction of the colour gain, the leaf-area weighted sky match (`vertexCoverage`, `coverageMean`, `scaleVisibility`) and the rolled standing clump cards, which keep the far levels of a tree as bright as level 0 from every side so a tree no longer pops darker when it switches level (issue #432); no budget in `bench/size/budgets.json` changes
diff --git a/scripts/measure-tree-level-luminance.mjs b/scripts/measure-tree-level-luminance.mjs
new file mode 100644
index 00000000..4d854224
--- /dev/null
+++ b/scripts/measure-tree-level-luminance.mjs
@@ -0,0 +1,222 @@
+// Draws only the foliage of one tree at each level of detail, from three sides and under three lights (sky only, sun behind the
+// tree, sun in front of it), in headless Chrome (SwiftShader unless `--gpu`). It prints, as JSON, the mean linear luminance of
+// the pure leaf pixels (every pixel that differs from an empty frame) and each level's ratio to level 0 (issue #432).
+// --species a,b limit the species (default all five) --seed N tree seed (default 3)
+// --pictures <dir> also write every frame as <species>-<light>-L<level>.png
+// --fit solve, per species and level, the colour gain and sky gain that bring all three ratios closest to 1 for
+// this seed, and print them with the ratios (the gains in src/tree-level-gains.js are ignored while fitting);
+// scripts/merge-tree-level-gains.mjs merges the fits of several seeds into that file
+import { chromium } from 'playwright';
+import { spawn } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+
+const port = 5189;
+const useGpu = process.argv.includes('--gpu');
+const fit = process.argv.includes('--fit');
+const optionValue = (name, fallback) => {
+ const index = process.argv.indexOf(name);
+ return index >= 0 ? process.argv[index + 1] : fallback;
+};
+const speciesList = optionValue('--species', 'palm,broadleaf,conifer,birch,bush').split(',');
+const seed = Number(optionValue('--seed', 3));
+const plainMeanMode = process.argv.includes('--plain-mean');
+const pictureDirectory = optionValue('--pictures', null);
+if (pictureDirectory) await mkdir(pictureDirectory, { recursive: true });
+
+const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+let browser;
+try {
+ await new Promise((resolve, reject) => {
+ const timeout = setTimeout(() => reject(new Error('The server did not start.')), 30000);
+ server.stdout.on('data', (data) => {
+ if (/ready in/.test(data.toString())) {
+ clearTimeout(timeout);
+ resolve();
+ }
+ });
+ server.on('exit', (code) => reject(new Error(`The server exited ${code}.`)));
+ });
+ const args = useGpu ? ['--use-angle=d3d11', '--enable-gpu', '--ignore-gpu-blocklist'] : ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--enable-webgl', '--ignore-gpu-blocklist'];
+ browser = await chromium.launch({ headless: true, args });
+ const page = await browser.newPage({ viewport: { width: 512, height: 512 } });
+ page.on('pageerror', error => console.error(error.message));
+ await page.goto(`http://127.0.0.1:${port}/`);
+ const result = await page.evaluate(async ({ speciesList, seed, pictureDirectory, fit, plainMeanMode }) => {
+ const { createTree, vegetationParts } = await import('/src/vegetation.js');
+ const { Renderer67 } = await import('/src/renderer.js');
+ const { matchMeanVisibility, scaleVisibility } = await import('/src/tree-sky.js');
+ const { TREE_LEVEL_GAINS } = await import('/src/tree-level-gains.js');
+ const { constantLighting, environment, SUN_COLOR } = await import('/bench/reference/scenes.js');
+ if (fit) for (const species of Object.keys(TREE_LEVEL_GAINS)) delete TREE_LEVEL_GAINS[species];
+
+ const SIZE = 512;
+ const AZIMUTHS = [0, 120, 240];
+ const LIGHTS = ['sky', 'sunBehind', 'sunFront'];
+ const canvas = document.createElement('canvas');
+ canvas.width = SIZE;
+ canvas.height = SIZE;
+ document.body.append(canvas);
+ const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+ const sky = constantLighting(1);
+ const toLinear = value => {
+ const unit = value / 255;
+ return unit <= 0.04045 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
+ };
+ const turn = ([x, y, z], degrees) => {
+ const angle = degrees * Math.PI / 180;
+ return [x * Math.cos(angle) + z * Math.sin(angle), y, -x * Math.sin(angle) + z * Math.cos(angle)];
+ };
+ const sunFor = (lightName, azimuth) => {
+ if (lightName === 'sky') return environment(sky);
+ const toward = lightName === 'sunBehind' ? [-3, 4, -6] : [3, 4, 6];
+ return environment(sky, { lightDirection: turn(toward, azimuth), keyColor: SUN_COLOR });
+ };
+
+ function drawPixels(parts, frame) {
+ const renderer = new Renderer67(canvas, parts, { ground: false, world: true, samples: 1, pixelRatio: 1 });
+ renderer.render(frame);
+ renderer.render(frame);
+ const context = renderer.context;
+ const pixels = new Uint8Array(SIZE * SIZE * 4);
+ context.readPixels(0, 0, SIZE, SIZE, context.RGBA, context.UNSIGNED_BYTE, pixels);
+ return pixels;
+ }
+
+ const pictures = {};
+ const pictureOf = (pixels) => {
+ const flat = document.createElement('canvas');
+ flat.width = SIZE;
+ flat.height = SIZE;
+ const image = new ImageData(SIZE, SIZE);
+ for (let row = 0; row < SIZE; row++) image.data.set(pixels.subarray(row * SIZE * 4, (row + 1) * SIZE * 4), (SIZE - 1 - row) * SIZE * 4);
+ flat.getContext('2d').putImageData(image, 0, 0);
+ return flat.toDataURL('image/png');
+ };
+
+ // Mean linear luminance of the pure leaf pixels of `parts`, pooled over the three sides, for each light. `sides` keeps the
+ // mean of each side too, because a crown whose cards face one way averages out over the sides while it pops on screen.
+ function measureLights(parts, view, label) {
+ const means = { sides: {} };
+ for (const lightName of LIGHTS) {
+ let sum = 0;
+ let count = 0;
+ means.sides[lightName] = [];
+ AZIMUTHS.forEach((azimuth, side) => {
+ let sideSum = 0;
+ let sideCount = 0;
+ const frame = { eye: turn([0, 1.7 - view.middle, view.distance], azimuth).map((value, axis) => value + (axis === 1 ? view.middle : 0)), target: [0, view.middle, 0], up: [0, 1, 0], fov: 25, near: 0.1, far: 500, time: 0, wind: 0, exposure: 1, environment: sunFor(lightName, azimuth) };
+ const empty = drawPixels([], frame);
+ const pixels = drawPixels(parts, frame);
+ for (let offset = 0; offset < pixels.length; offset += 4) {
+ if (pixels[offset] === empty[offset] && pixels[offset + 1] === empty[offset + 1] && pixels[offset + 2] === empty[offset + 2]) continue;
+ const luminance = 0.2126 * toLinear(pixels[offset]) + 0.7152 * toLinear(pixels[offset + 1]) + 0.0722 * toLinear(pixels[offset + 2]);
+ sum += luminance;
+ count++;
+ sideSum += luminance;
+ sideCount++;
+ }
+ means.sides[lightName].push(sideSum / Math.max(1, sideCount));
+ if (pictureDirectory && side === 0) pictures[`${label}-${lightName}`] = pictureOf(pixels);
+ });
+ means[lightName] = sum / Math.max(1, count);
+ }
+ return means;
+ }
+
+ const foliageParts = (tree, level, override) => {
+ const parts = vegetationParts(tree, identity, level).filter(part => part.name.endsWith('foliage'));
+ // The shadow layers point at the original geometry, and the frames have no shadows.
+ return override ? parts.map(part => ({ ...part, geometry: override(part.geometry), shadowLods: undefined })) : parts;
+ };
+ const ratiosOf = (means, reference) => LIGHTS.map(light => means[light] / reference[light]);
+
+ // Solves for the two columns' weights that best reach `target` over the three lights (least squares).
+ function solveTwo([first, second], target) {
+ const dot = (left, right) => left.reduce((sum, value, index) => sum + value * right[index], 0);
+ const firstSquared = dot(first, first);
+ const cross = dot(first, second);
+ const secondSquared = dot(second, second);
+ const determinant = firstSquared * secondSquared - cross * cross;
+ if (Math.abs(determinant) < 1e-9) return [0, 0];
+ const firstTarget = dot(first, target);
+ const secondTarget = dot(second, target);
+ return [(firstTarget * secondSquared - cross * secondTarget) / determinant, (firstSquared * secondTarget - cross * firstTarget) / determinant];
+ }
+
+ const output = {};
+ const gains = {};
+ for (const species of speciesList) {
+ const tree = createTree(species, seed);
+ const crown = tree.levels[0].parts.find(part => part.role === 'foliage').geometry.positions;
+ let top = -Infinity;
+ let reach = 0;
+ for (let offset = 0; offset < crown.length; offset += 3) {
+ top = Math.max(top, crown[offset + 1]);
+ reach = Math.max(reach, Math.hypot(crown[offset], crown[offset + 2]));
+ }
+ // A far tree is seen from the ground: eye at 1.7 m, so the flat clumps of the far levels show from below.
+ const view = { middle: top / 2, distance: Math.max(top, reach * 2) * 3 };
+ const reference = measureLights(foliageParts(tree, 0), view, `${species}-L0`);
+ output[species] = { level0: reference, levels: [] };
+ gains[species] = {};
+ for (let level = 1; level < tree.levels.length; level++) {
+ // `--plain-mean` re-matches the level to level 0 by the plain mean over vertices, as main did before #432.
+ const plainMean = geometry => {
+ const levelZero = tree.levels[0].parts.find(part => part.role === 'foliage').geometry.skyVisibility;
+ const mean = values => values.reduce((sum, value) => sum + value, 0) / values.length;
+ return { ...geometry, skyVisibility: matchMeanVisibility(geometry.skyVisibility, mean(levelZero), new Float32Array(geometry.skyVisibility.length).fill(1)) };
+ };
+ const drawn = measureLights(foliageParts(tree, level, plainMeanMode ? plainMean : null), view, `${species}-L${level}`);
+ const before = ratiosOf(drawn, reference);
+ // The ratio of each light and side to level 0 from the same side.
+ const sides = LIGHTS.map(light => drawn.sides[light].map((value, side) => Number((value / reference.sides[light][side]).toFixed(3))));
+ let after = before;
+ if (fit) {
+ // The colour gain moves every light and the sky gain the sky share. Gauss-Newton steps on the log ratios of the three
+ // lights, with a measured Jacobian.
+ const drawWith = ([logColor, logSky]) => ratiosOf(measureLights(foliageParts(tree, level, geometry => ({
+ ...geometry,
+ colors: geometry.colors.map(channel => channel * Math.exp(logColor)),
+ skyVisibility: scaleVisibility(geometry.skyVisibility, Math.exp(logSky)),
+ })), view, `${species}-L${level}-fit`), reference).map(Math.log);
+ const limits = [[-1, 1.6], [Math.log(0.25), Math.log(16)]];
+ const steps = [0.15, 0.2];
+ let parameters = [0, 0];
+ let residual = before.map(Math.log);
+ const worst = values => Math.max(...values.map(Math.abs));
+ // A level that already passes keeps its look.
+ for (let iteration = 0; iteration < 6 && worst(residual) > Math.log(1.08); iteration++) {
+ const jacobian = steps.map((step, column) => {
+ const moved = parameters.map((value, index) => index === column ? value + step : value);
+ return drawWith(moved).map((value, light) => (value - residual[light]) / step);
+ });
+ const change = solveTwo(jacobian, residual.map(value => -value));
+ // Damped: halve the step until the worst light improves, so a noisy Jacobian cannot throw the fit off.
+ let improved = false;
+ for (let scale = 1; scale >= 0.125 && !improved; scale /= 2) {
+ const trial = parameters.map((value, index) => Math.min(limits[index][1], Math.max(limits[index][0], value + change[index] * scale)));
+ const trialResidual = drawWith(trial);
+ if (worst(trialResidual) < worst(residual)) {
+ parameters = trial;
+ residual = trialResidual;
+ improved = true;
+ }
+ }
+ if (!improved) break;
+ }
+ after = residual.map(Math.exp);
+ gains[species][level] = { color: Number(Math.exp(parameters[0]).toFixed(3)), sky: Number(Math.exp(parameters[1]).toFixed(3)) };
+ }
+ output[species].levels.push({ level, before, after, sides });
+ }
+ }
+ return { output, gains, pictures };
+ }, { speciesList, seed, pictureDirectory, fit, plainMeanMode });
+ for (const [name, dataUrl] of Object.entries(result.pictures)) {
+ await writeFile(`${pictureDirectory}/${name}.png`, Buffer.from(dataUrl.split(',')[1], 'base64'));
+ }
+ console.log(JSON.stringify({ ...result.output, seed, gains: fit ? result.gains : undefined }));
+} finally {
+ await browser?.close();
+ server.kill();
+}
diff --git a/scripts/merge-tree-level-gains.mjs b/scripts/merge-tree-level-gains.mjs
new file mode 100644
index 00000000..b8c3ffb1
--- /dev/null
+++ b/scripts/merge-tree-level-gains.mjs
@@ -0,0 +1,49 @@
+// node scripts/merge-tree-level-gains.mjs <gains file> <fit json>... [--measured <measure json>...]
+// Merges the fits of `measure-tree-level-luminance.mjs --fit --seed N` (one per seed) into the gains file (src/tree-level-gains.js),
+// keeping its header and each species' `areaExponent` (issue #432):
+// - `color` and `sky` are the geometric mean over the fits;
+// - `area` is the mean log ratio of a level's leaf area to level 0's over the fitted seeds, the point where the leaf area
+// correction in src/vegetation.js is 1. Each tree's own correction then cancels out of the mean.
+// `--measured` takes plain runs of the probe (no --fit) drawn with the merged gains, and scales each colour gain so the geometric
+// mean of the measured ratios lands on TARGET. TARGET sits below 1 because trees spread about ±15% around it, and a far level
+// that is darker than level 0 by that much shows less than one that is brighter.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createTree } from '../src/vegetation.js';
+import { vertexCoverage } from '../src/tree-sky.js';
+
+const TARGET = 0.97;
+// Level 1 already draws within a few percent of level 0, so only the clump levels get gains.
+const MERGED_LEVELS = ['2', '3'];
+const argumentsGiven = process.argv.slice(2);
+const measuredFlag = argumentsGiven.indexOf('--measured');
+const [target, ...fitFiles] = measuredFlag >= 0 ? argumentsGiven.slice(0, measuredFlag) : argumentsGiven;
+const measuredFiles = measuredFlag >= 0 ? argumentsGiven.slice(measuredFlag + 1) : [];
+const fits = fitFiles.map(file => JSON.parse(readFileSync(file, 'utf8')));
+const measured = measuredFiles.map(file => JSON.parse(readFileSync(file, 'utf8')));
+const { TREE_LEVEL_GAINS: current } = await import(pathToFileURL(resolve(target)).href);
+
+const logMean = values => values.reduce((sum, value) => sum + Math.log(value), 0) / values.length;
+const leafArea = geometry => vertexCoverage(geometry.positions, geometry.indices).reduce((sum, share) => sum + share, 0);
+const foliageOf = (tree, level) => tree.levels[level].parts.find(part => part.role === 'foliage').geometry;
+
+const header = readFileSync(target, 'utf8').split('export const')[0];
+const rows = Object.keys(fits[0].gains).map(species => {
+ const trees = fits.map(fit => createTree(species, fit.seed));
+ const areaExponent = current[species]?.areaExponent;
+ const entries = MERGED_LEVELS.map(level => {
+ let color = Math.exp(logMean(fits.map(fit => fit.gains[species][level].color)));
+ const sky = Math.exp(logMean(fits.map(fit => fit.gains[species][level].sky)));
+ const area = trees.reduce((sum, tree) => sum + Math.log(leafArea(foliageOf(tree, level)) / leafArea(foliageOf(tree, 0))), 0) / trees.length;
+ if (measured.length) {
+ const ratios = measured.flatMap(run => run[species].levels.find(entry => entry.level === Number(level)).before);
+ color *= TARGET / Math.exp(logMean(ratios));
+ }
+ return `${level}: { color: ${Number(color.toFixed(3))}, sky: ${Number(sky.toFixed(3))}, area: ${Number(area.toFixed(4))} }`;
+ });
+ const exponent = areaExponent === undefined ? '' : `areaExponent: ${areaExponent}, `;
+ return ` ${species}: { ${exponent}${entries.join(', ')} },`;
+});
+writeFileSync(target, `${header}export const TREE_LEVEL_GAINS = {\n${rows.join('\n')}\n};\n`);
+console.log(rows.join('\n'));
diff --git a/src/tree-level-gains.js b/src/tree-level-gains.js
new file mode 100644
index 00000000..c99a1cc2
--- /dev/null
+++ b/src/tree-level-gains.js
@@ -0,0 +1,17 @@
+// Per species and level of detail: how much to scale the leaf colour (`color`) and the sky visibility (`sky`) of a lower level,
+// so its pure-leaf luminance matches level 0 under sky light and a sun behind and in front of the tree (issue #432). The colour
+// gain moves all three lights, the sky gain moves the sky share only, so two numbers per level fit three lights.
+// Trees of one species differ: a level whose clumps carry more leaf area against level 0 than usual draws darker, so the colour
+// gain of each tree also scales by exp(`areaExponent` * (its log area ratio - `area`)) (src/vegetation.js). The exponents
+// follow the slope of the measured log ratio over the log area ratio on seeds 1 to 8.
+// The gains come from seeds 1 to 6: run `node scripts/measure-tree-level-luminance.mjs --gpu --fit --seed N > fit-N.json`
+// for each, then `node scripts/merge-tree-level-gains.mjs src/tree-level-gains.js fit-1.json ... fit-6.json`, then measure
+// seeds 1 to 8 without --fit (`> measured-N.json`) and merge once more with `--measured measured-1.json ...` to recentre.
+// It is data, so run them again after any change to the leaf cards, clumps or shading instead of editing it by hand.
+export const TREE_LEVEL_GAINS = {
+ palm: { areaExponent: 0.6, 2: { color: 2.449, sky: 3.373, area: 0.8953 }, 3: { color: 2.492, sky: 3.613, area: 1.7062 } },
+ broadleaf: { areaExponent: 0.45, 2: { color: 1.832, sky: 1.644, area: 0.5478 }, 3: { color: 1.835, sky: 1.869, area: 1.3587 } },
+ conifer: { areaExponent: 0.8, 2: { color: 1.121, sky: 10.132, area: 0.1494 }, 3: { color: 1.21, sky: 11.362, area: 0.9604 } },
+ birch: { areaExponent: 0.7, 2: { color: 1.528, sky: 2.251, area: 0.7787 }, 3: { color: 1.615, sky: 2.49, area: 1.5896 } },
+ bush: { areaExponent: 0.35, 2: { color: 1.472, sky: 0.978, area: -1.4443 }, 3: { color: 1.418, sky: 1.47, area: -0.6334 } },
+};
diff --git a/src/tree-sky.js b/src/tree-sky.js
index 871c4b87..fa78c124 100644
--- a/src/tree-sky.js
+++ b/src/tree-sky.js
@@ -91,17 +91,45 @@ export function createCrownSkyField(positions) {
return { visibilityOf };
}
-function meanOf(values) {
- let sum = 0;
- for (const value of values) sum += value;
- return sum / values.length;
+// How much leaf each vertex stands for: a third of the area of every triangle it belongs to. A level of large clumps has few
+// vertices that each stand for a lot of leaf, so a plain mean over vertices does not say how much sky the leaf sees.
+export function vertexCoverage(positions, indices) {
+ const coverage = new Float32Array(positions.length / 3);
+ for (let corner = 0; corner < indices.length; corner += 3) {
+ const [first, second, third] = [indices[corner], indices[corner + 1], indices[corner + 2]];
+ const edgeX = [positions[second * 3] - positions[first * 3], positions[second * 3 + 1] - positions[first * 3 + 1], positions[second * 3 + 2] - positions[first * 3 + 2]];
+ const edgeY = [positions[third * 3] - positions[first * 3], positions[third * 3 + 1] - positions[first * 3 + 1], positions[third * 3 + 2] - positions[first * 3 + 2]];
+ const crossX = edgeX[1] * edgeY[2] - edgeX[2] * edgeY[1];
+ const crossY = edgeX[2] * edgeY[0] - edgeX[0] * edgeY[2];
+ const crossZ = edgeX[0] * edgeY[1] - edgeX[1] * edgeY[0];
+ const share = Math.hypot(crossX, crossY, crossZ) / 6;
+ coverage[first] += share;
+ coverage[second] += share;
+ coverage[third] += share;
+ }
+ return coverage;
+}
+
+export function coverageMean(values, coverage) {
+ let weighted = 0;
+ let total = 0;
+ for (let vertex = 0; vertex < values.length; vertex++) {
+ weighted += values[vertex] * coverage[vertex];
+ total += coverage[vertex];
+ }
+ return total > 0 ? weighted / total : 0;
}
/**
- * Scales `visibility` so its mean is `targetMean`, keeping the floor and 1 as the limits. The larger leaves of a thinner level
- * sit further out in the crown than the leaves of level 0, so a field lookup alone leaves them seeing more sky on average.
+ * Scales `visibility` so its mean over the leaf it stands for (`coverage`, from `vertexCoverage`) is `targetMean`, keeping the
+ * floor and 1 as the limits. The larger leaves of a thinner level sit further out in the crown than the leaves of level 0, so a field
+ * lookup alone leaves them seeing more sky on average.
*/
-export function matchMeanVisibility(visibility, targetMean) {
- const scale = targetMean / meanOf(visibility);
+export function matchMeanVisibility(visibility, targetMean, coverage) {
+ const scale = targetMean / coverageMean(visibility, coverage);
+ return scaleVisibility(visibility, scale);
+}
+
+export function scaleVisibility(visibility, scale) {
return visibility.map(value => Math.min(1, Math.max(MINIMUM_VISIBILITY, value * scale)));
}
diff --git a/src/vegetation-species.js b/src/vegetation-species.js
index 4910997c..a685a768 100644
--- a/src/vegetation-species.js
+++ b/src/vegetation-species.js
@@ -118,7 +118,8 @@ export const SPECIES = {
texture: 'sprig', color: [54, 104, 40], foliageColor: [0.06, 0.2, 0.045], tint: [1, 1, 0.9],
sitesPerMeter: 9, start: 0.1, upBias: 0.3,
meshLength: 0.22, meshWidth: 0.14, meshPerSite: 3, meshSpread: 0.9, profile: OVATE_LEAF, droop: 0.25, fold: 0.12,
- cardSize: [0.4, 0.42], cardsPerSite: 2, clumpScale: 0.5,
+ // The bush's small clumps keep some of the crown's normal, or a sun in front overshoots level 0 (issue #432).
+ cardSize: [0.4, 0.42], cardsPerSite: 2, clumpScale: 0.5, clumpCanopyBlend: 0.3,
},
},
};
diff --git a/src/vegetation.js b/src/vegetation.js
index 9e278951..de767291 100644
--- a/src/vegetation.js
+++ b/src/vegetation.js
@@ -14,7 +14,8 @@ import {
createMeshBuilder, createRandom, crossProduct, lerp, lerpVectors, normalized, randomInRange, scaleVector,
subtractVectors, valueNoise, vectorLength,
} from './vegetation-geometry.js';
-import { createCrownSkyField, matchMeanVisibility } from './tree-sky.js';
+import { coverageMean, createCrownSkyField, matchMeanVisibility, scaleVisibility, vertexCoverage } from './tree-sky.js';
+import { TREE_LEVEL_GAINS } from './tree-level-gains.js';
import { LEVEL_SETTINGS, SPECIES, TREE_LEVEL_DISTANCES } from './vegetation-species.js';
import { barkTextureDescriptor, leafTextureDescriptor } from './vegetation-textures.js';
import { pixelErrorScale, selectBlendedLevels } from './vegetation-impostors.js';
@@ -27,6 +28,7 @@ export { SPECIES };
const BARK_TILE_SIZE = 0.6;
const SCANNED_BARK_TILE_SIZE = 0.8;
const LEAF_MODES = ['cards', 'mesh'];
+const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5));
const GRASS_LEVEL_DISTANCES = [24];
const LEAF_COLOR_BASE = [0.85, 0.95, 0.8];
const LEAF_COLOR_TIP = [1.1, 1.05, 0.9];
@@ -324,8 +326,14 @@ function addCrownClumps(builder, skeleton, spec, mode, random, widthScale = 1) {
if (!cells.has(key)) cells.set(key, []);
cells.get(key).push(site);
}
+ // Two cards of a clump lie about flat and the third stands along the vertical. Each clump rolls its standing card by the
+ // golden angle from the last, so the standing cards of a crown face every way evenly and the crown looks as bright from every
+ // side (issue #432). Unrolled, they all faced one world direction, and the far levels were three times darker from one side.
+ let clumpIndex = 0;
for (const sites of cells.values()) {
const center = scaleVector(sites.reduce((sum, site) => addVectors(sum, site.position), [0, 0, 0]), 1 / sites.length);
+ const yaw = clumpIndex * GOLDEN_ANGLE;
+ clumpIndex++;
const shading = crownShading(skeleton, center);
const radius = cellSize * (0.55 + 0.1 * Math.min(sites.length, 5)) * widthScale * (spec.clumpScale ?? 1);
if (mode === 'mesh') {
@@ -336,13 +344,14 @@ function addCrownClumps(builder, skeleton, spec, mode, random, widthScale = 1) {
const direction = card === 2 ? WORLD_UP : [Math.cos(card * 1.9 + center[0]), 0.15, Math.sin(card * 1.9 + center[2])];
addLeafSurface(builder, {
origin: addScaled(center, normalized(direction), -radius),
- frame: createLeafFrame(normalized(direction), 0),
+ frame: createLeafFrame(normalized(direction), card === 2 ? yaw : 0),
length: radius * 2,
width: radius * 2,
rows: [[0, 1], [1, 1]],
backFaces: false,
canopyNormal: shading.canopyNormal,
- canopyBlend: 0.7,
+ // Their own normals: blended toward the crown's, a sun behind the tree left the far levels near black (issue #432).
+ canopyBlend: spec.clumpCanopyBlend ?? 0,
colorBase: LEAF_COLOR_BASE,
colorTip: LEAF_COLOR_TIP,
brightness: shading.brightness,
@@ -417,18 +426,20 @@ function createMaterials(preset, mode, scannedBark, scannedLeaves) {
// Every level describes the same crown, so every level reads one sky visibility field, measured on the leaves of level 0.
// `skyVisibility` is worked out the first time something reads it (the renderer, when it uploads the geometry), so a
// tree that is only measured or exported costs nothing extra, and a forest of distinct trees pays for the ones drawn.
-function meanOf(values) {
- let sum = 0;
- for (const value of values) sum += value;
- return sum / values.length;
-}
+// A level's mean is taken over the leaf its vertices stand for, not over the vertices, because a clump has few vertices for a lot of leaf.
-function bakeCrownSkyVisibility(levels) {
+function bakeCrownSkyVisibility(levels, species) {
const foliageOf = level => level.parts.find(part => part.role === 'foliage').geometry;
+ const coverageOf = geometry => vertexCoverage(geometry.positions, geometry.indices);
let field = null;
for (const [levelIndex, level] of levels.entries()) {
const geometry = foliageOf(level);
if (geometry.positions.length === 0) continue;
+ const gain = TREE_LEVEL_GAINS[species]?.[levelIndex];
+ if (gain) {
+ const colorGain = gain.color * leafAreaCorrection(geometry, foliageOf(levels[0]), gain.area, TREE_LEVEL_GAINS[species].areaExponent);
+ geometry.colors = geometry.colors.map(channel => channel * colorGain);
+ }
let skyVisibility = null;
Object.defineProperty(geometry, 'skyVisibility', {
enumerable: true,
@@ -437,7 +448,12 @@ function bakeCrownSkyVisibility(levels) {
field ??= createCrownSkyField(foliageOf(levels[0]).positions);
if (!skyVisibility) {
skyVisibility = field.visibilityOf(geometry.positions);
- if (levelIndex > 0) skyVisibility = matchMeanVisibility(skyVisibility, meanOf(foliageOf(levels[0]).skyVisibility));
+ if (levelIndex > 0) {
+ const levelZero = foliageOf(levels[0]);
+ const targetMean = coverageMean(levelZero.skyVisibility, coverageOf(levelZero));
+ skyVisibility = matchMeanVisibility(skyVisibility, targetMean, coverageOf(geometry));
+ if (gain) skyVisibility = scaleVisibility(skyVisibility, gain.sky);
+ }
}
return skyVisibility;
},
@@ -445,6 +461,15 @@ function bakeCrownSkyVisibility(levels) {
}
}
+// A tree whose lower level carries more leaf area against level 0 than the species usually does draws that level darker (its
+// clumps overlap and shade each other more), so the colour gain grows with the area ratio (issue #432). `meanLogArea` is the
+// species' usual log area ratio for that level, and the exponent how strongly the brightness follows it.
+function leafAreaCorrection(geometry, levelZero, meanLogArea, exponent) {
+ if (meanLogArea === undefined || !exponent) return 1;
+ const leafArea = foliage => vertexCoverage(foliage.positions, foliage.indices).reduce((sum, share) => sum + share, 0);
+ return Math.exp(exponent * (Math.log(leafArea(geometry) / leafArea(levelZero)) - meanLogArea));
+}
+
function boundsOf(geometries) {
const minimum = [Infinity, Infinity, Infinity];
const maximum = [-Infinity, -Infinity, -Infinity];
@@ -498,7 +523,7 @@ export function createTree(speciesOrOptions = 'broadleaf', seed = 1) {
},
]);
});
- bakeCrownSkyVisibility(levels);
+ bakeCrownSkyVisibility(levels, options.species);
return {
kind: 'tree', species: options.species, seed, height, leaves, levels, materials,
distances: TREE_LEVEL_DISTANCES,
diff --git a/tests/tree-sky-levels.test.js b/tests/tree-sky-levels.test.js
index 024dd5ba..d51d150c 100644
--- a/tests/tree-sky-levels.test.js
+++ b/tests/tree-sky-levels.test.js
@@ -1,37 +1,124 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createTree } from '../src/vegetation.js';
+import { TREE_LEVEL_GAINS } from '../src/tree-level-gains.js';
+import { coverageMean, matchMeanVisibility, vertexCoverage } from '../src/tree-sky.js';
// Issue #394: a lower level of detail worked out its own sky visibility from its few, large vertices, which put the
// far levels at the floor (0.04 to 0.06) where level 0 sees 0.08 to 0.12. Under sky light they drew near black.
+// Issue #432: the match is now a mean over the leaf each vertex stands for (its share of the triangle areas), not over the
+// vertices. A clump has few vertices for a lot of leaf, so the plain mean no longer says how much sky the leaf sees.
-function meanOf(values) {
- let sum = 0;
- for (const value of values) sum += value;
- return sum / values.length;
-}
+const SPECIES = ['broadleaf', 'birch', 'conifer', 'palm', 'bush'];
function foliageGeometry(level) {
return level.parts.find(part => part.role === 'foliage').geometry;
}
-for (const species of ['broadleaf', 'birch', 'conifer', 'palm', 'bush']) {
- test(`every level of a ${species} sees about as much sky as level 0`, () => {
+function coverageMeanSkyVisibility(geometry) {
+ return coverageMean(geometry.skyVisibility, vertexCoverage(geometry.positions, geometry.indices));
+}
+
+for (const species of SPECIES) {
+ test(`every level of a ${species} sees about as much sky as level 0, weighted by the leaf it stands for`, () => {
const tree = createTree(species, 3);
- const levelZeroMean = meanOf(foliageGeometry(tree.levels[0]).skyVisibility);
- // The floor of the visibility keeps a very dense crown from matching exactly, so a small absolute margin applies too.
- const allowedDifference = Math.max(0.1 * levelZeroMean, 0.02);
+ const levelZeroMean = coverageMeanSkyVisibility(foliageGeometry(tree.levels[0]));
+ const gains = TREE_LEVEL_GAINS[species] ?? {};
tree.levels.forEach((level, index) => {
const geometry = foliageGeometry(level);
assert.equal(geometry.skyVisibility.length, geometry.positions.length / 3);
- const difference = Math.abs(meanOf(geometry.skyVisibility) - levelZeroMean);
+ // The sky gain of a level moves its mean on purpose, and a vertex stops at full sky, so a large gain can fall short of
+ // level 0's mean times the gain. The floor of the visibility keeps a very dense crown from matching exactly too.
+ const gain = gains[index]?.sky ?? 1;
+ const levelMean = coverageMeanSkyVisibility(geometry);
+ if (gain > 1.5) {
+ assert.ok(levelMean >= levelZeroMean * 1.2 && levelMean <= 1, `${species} level ${index} has a mean of ${levelMean.toFixed(3)} against ${levelZeroMean.toFixed(3)} at level 0`);
+ return;
+ }
+ const expected = levelZeroMean * gain;
+ const allowedDifference = Math.max(0.1 * expected, 0.02);
+ const difference = Math.abs(levelMean - expected);
assert.ok(difference <= allowedDifference, `${species} level ${index} differs from level 0 by ${difference.toFixed(3)}`);
});
});
}
+test('the level match weights each vertex by its share of the leaf area', () => {
+ // Two triangles: a small one whose corners see little sky and a large one whose corners see a lot.
+ const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 10, 0, 0, 20, 0, 0, 10, 20, 0]);
+ const indices = new Uint32Array([0, 1, 2, 3, 4, 5]);
+ const coverage = vertexCoverage(positions, indices);
+ assert.ok(Math.abs(coverage[0] - 0.5 / 3) < 1e-6);
+ assert.ok(Math.abs(coverage[3] - 100 / 3) < 1e-4);
+ const visibility = new Float32Array([0.1, 0.1, 0.1, 0.5, 0.5, 0.5]);
+ const plainMean = 0.3;
+ const weightedMean = coverageMean(visibility, coverage);
+ assert.ok(weightedMean > 0.49, `weighted mean ${weightedMean}`);
+ const matched = matchMeanVisibility(visibility, 0.25, coverage);
+ assert.ok(Math.abs(coverageMean(matched, coverage) - 0.25) < 0.005);
+ assert.notEqual(Math.round(coverageMean(matched, coverage) * 1000), Math.round(plainMean * 1000));
+});
+
+test('a tree whose far level carries more leaf area than its species usually does gets a larger colour gain', () => {
+ // Seeds of one broadleaf differ in how much clump area level 2 has against level 0; the colour of level 2 follows it.
+ const leafArea = geometry => vertexCoverage(geometry.positions, geometry.indices).reduce((sum, share) => sum + share, 0);
+ const rows = [1, 2, 3, 4, 5, 6].map(seed => {
+ const tree = createTree('broadleaf', seed);
+ const zero = foliageGeometry(tree.levels[0]);
+ const two = foliageGeometry(tree.levels[2]);
+ const mean = values => values.reduce((sum, value) => sum + value, 0) / values.length;
+ return { logArea: Math.log(leafArea(two) / leafArea(zero)), colorRatio: mean(two.colors) / mean(zero.colors) };
+ }).sort((first, second) => first.logArea - second.logArea);
+ const smallest = rows[0];
+ const largest = rows[rows.length - 1];
+ const expected = Math.exp(TREE_LEVEL_GAINS.broadleaf.areaExponent * (largest.logArea - smallest.logArea));
+ // Leaf colours differ a little between seeds, so the measured step only has to land near the expected one.
+ assert.ok(Math.abs(largest.colorRatio / smallest.colorRatio / expected - 1) < 0.1, `colour step ${(largest.colorRatio / smallest.colorRatio).toFixed(3)} against ${expected.toFixed(3)}`);
+});
+
+test('the standing clump cards of a far level face every way, so the crown is as bright from every side', () => {
+ // Before #432 every standing card of a crown faced one world direction, and level 2 drew three times darker from one side.
+ // The facing comes from the triangles themselves, since the shading normals may be blended toward the crown.
+ for (const species of SPECIES) {
+ const { positions, indices } = foliageGeometry(createTree(species, 3).levels[2]);
+ let sumX = 0;
+ let sumZ = 0;
+ let count = 0;
+ for (let corner = 0; corner < indices.length; corner += 3) {
+ const point = index => [positions[index * 3], positions[index * 3 + 1], positions[index * 3 + 2]];
+ const [a, b, c] = [point(indices[corner]), point(indices[corner + 1]), point(indices[corner + 2])];
+ const u = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+ const v = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+ const normal = [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]];
+ const length = Math.hypot(...normal);
+ if (length === 0 || Math.abs(normal[1] / length) > 0.5) continue;
+ const horizontal = Math.hypot(normal[0], normal[2]);
+ sumX += normal[0] / horizontal;
+ sumZ += normal[2] / horizontal;
+ count++;
+ }
+ // The mean facing of the standing triangles: 1 when all face one way (main before this change), near 0 when they spread evenly.
+ const resultant = Math.hypot(sumX, sumZ) / count;
+ assert.ok(count > 0 && resultant < 0.3, `${species} standing cards lean one way (${resultant.toFixed(2)} of ${count})`);
+ }
+});
+
test('level 0 keeps the sky visibility it measures from its own leaves', () => {
const first = createTree('broadleaf', 5);
const second = createTree('broadleaf', 5);
assert.deepEqual(foliageGeometry(first.levels[0]).skyVisibility, foliageGeometry(second.levels[0]).skyVisibility);
});
+
+test('the fitted gains only touch levels 1 to 3 and stay in a sane range', () => {
+ for (const [species, { areaExponent, ...levels }] of Object.entries(TREE_LEVEL_GAINS)) {
+ assert.ok(SPECIES.includes(species), `${species} is not a tree species`);
+ assert.ok(areaExponent >= 0 && areaExponent <= 1, `${species} area exponent ${areaExponent}`);
+ for (const [level, gain] of Object.entries(levels)) {
+ assert.ok(Number.isFinite(gain.area), `${species} level ${level} has no mean leaf area ratio`);
+ assert.ok(Number(level) >= 1 && Number(level) <= 3, `${species} level ${level}`);
+ assert.ok(gain.color > 0.2 && gain.color < 5, `${species} level ${level} colour gain ${gain.color}`);
+ // A conifer's far clumps sit inside a dark cone, so its sky gain is large; a vertex still stops at full sky.
+ assert.ok(gain.sky >= 0.25 && gain.sky <= 16, `${species} level ${level} sky gain ${gain.sky}`);
+ }
+ }
+});