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.mdnew file mode 100644index 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.mdnew file mode 100644index 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` changesdiff --git a/scripts/measure-tree-level-luminance.mjs b/scripts/measure-tree-level-luminance.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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}`);+ }+ }+});