Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

WIP sun bounce (part of #462)

Nguyen Xuan Anc6c24a5a71a5
diff --git a/bench/reference/harness.js b/bench/reference/harness.js
index 8a92ea93..2b579e0a 100644
--- a/bench/reference/harness.js
+++ b/bench/reference/harness.js
@@ -18,6 +18,7 @@ import { applyLightLinks } from '/src/light-linking.js';
import { applyWaterReflection, attachWaterReflection } from '/src/water-reflection.js';
import { attachScreenSpaceWater } from './ssr-water.js';
import { groundBounceEnvironment } from '/src/ground-bounce.js';
+import { withSunBounce } from '/src/sun-bounce.js';
import { applyDefaultFloorSky, applyFloorSkyVisibility } from '/src/floor-sky-visibility.js';
import { installReversedDepth } from '/src/reversed-depth.js';
@@ -27,7 +28,10 @@ const GROUND_BOUNCE = new URLSearchParams(location.search).get('groundBounce') !
// The scene's environment with the light its floor bounces, when it has a plain one and nothing else gives that light (a bake, a closed room).
function withDerivedGroundBounce(scene, drawnParts) {
- return GROUND_BOUNCE ? groundBounceEnvironment(drawnParts, scene.environment) : scene.environment;
+ const lit = GROUND_BOUNCE ? groundBounceEnvironment(drawnParts, scene.environment) : scene.environment;
+ // ?sunBounce=<n> sets environment.sunBounce on every scene (default 1, 0 draws without the sunlit patches' lights).
+ const sunBounce = new URLSearchParams(location.search).get('sunBounce');
+ return withSunBounce(drawnParts, sunBounce === null ? lit : { ...lit, sunBounce: Number(sunBounce) });
}
// ?reversedDepth=on draws with reversed-Z (issue #310); the scenes draw with the standard depth buffer otherwise.
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index 423a36ff..50fc261e 100644
--- a/scripts/agent-preview-browser.js
+++ b/scripts/agent-preview-browser.js
@@ -187,7 +187,9 @@ function syncAutomaticGround(record) {
// The scene's environment lit by the sky map, with the light its floor bounces (src/ground-bounce.js): a floor part of the
// recipe gives its own colour, and the automatic floor gives its own.
function litEnvironment(parts, environment, hasAutomaticGround) {
- return groundBounceEnvironment(parts, { ...environment, map: agentEnvironmentMap(environment) }, { automaticAlbedo: hasAutomaticGround ? FLOOR_COLOR : null });
+ const lit = groundBounceEnvironment(parts, { ...environment, map: agentEnvironmentMap(environment) }, { automaticAlbedo: hasAutomaticGround ? FLOOR_COLOR : null });
+ // A closed room a sun lights gets the lights of its sunlit patches (src/sun-bounce.js), once a recipe that names a sun has loaded the module.
+ return agentSceneModuleLoaded('sunBounce') ? agentSceneModule('sunBounce').withSunBounce(parts, lit) : lit;
}
// A renderer takes its cascades at construction, so a change of the count (or of the extent that picks it) rebuilds.
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 89393bdf..027d8f40 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -227,6 +227,7 @@ const environment = z.strictObject({
lines: lines.nullable().optional(),
objectReflections: z.boolean().optional().describe("false turns off reflection probes on smooth metal parts."),
floorSkyTrace: z.boolean().optional().describe('false turns off the sky traced into floors of sun-lit closed rooms.'),
+ sunBounce: z.number().min(0).optional().describe('Light the sunlit patches of a sun-lit closed room bounce on to the room: 0 off, 1 default, above 1 stronger.'),
resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),
viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),
look: z.enum(LOOK_NAMES).nullable().optional().describe('Named look preset; null clears.'),
diff --git a/src/agent-look.js b/src/agent-look.js
index c9735d81..e89f7c3e 100644
--- a/src/agent-look.js
+++ b/src/agent-look.js
@@ -13,7 +13,7 @@ const MAX_LOOK_ARRAY_ENTRIES = Math.max(MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_A
const ENVIRONMENT_FIELDS = [
'world', 'ground', 'setup', 'environmentIntensity', 'environmentRotation', 'lightDirection', 'keyColor', 'keyIntensity', 'fillIntensity', 'ambientIntensity',
- 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',
+ 'daylight', 'pointLights', 'spotLights', 'areaLights', 'skyTop', 'skyBottom', 'fogColor', 'fogDensity', 'volumeFog', 'liquid', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'lines', 'resolveCoplanar', 'viewTransform', 'look', 'wind',
];
const EFFECT_FIELDS = ['exposure', 'saturation', 'contrast', 'temperature', 'vignette', 'grain', 'ambientOcclusion', 'ambientOcclusionRadius', 'bloom', 'depthOfField', 'motionBlur'];
const SHADOW_FIELDS = ['target', 'extent', 'distance', 'near', 'far'];
@@ -279,6 +279,13 @@ function environmentFrom(input = {}) {
}
environment.floorSkyTrace = input.floorSkyTrace;
}
+ // Scales the light the sunlit patches of a sun-lit closed room bounce on (src/sun-bounce.js); 0 turns it off.
+ if (input.sunBounce !== undefined) {
+ if (typeof input.sunBounce !== 'number' || !Number.isFinite(input.sunBounce) || input.sunBounce < 0) {
+ throw new TypeError('environment.sunBounce must be a number of 0 or more.');
+ }
+ environment.sunBounce = input.sunBounce;
+ }
// Outlines and line geometry; null clears them. The module checks the fields and loads on demand.
if (input.lines !== undefined && input.lines !== null) {
environment.lines = copiedJson(agentSceneModule('lineArt').resolveLineArt(input.lines));
diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.js
index f29f708e..ad84766c 100644
--- a/src/agent-scene-modules.js
+++ b/src/agent-scene-modules.js
@@ -32,6 +32,7 @@ const MODULE_LOADERS = {
viewTransform: () => import('./view-transform-shader.js'),
coplanar: () => import('./coplanar-overlap.js'),
floorSky: () => import('./floor-sky-visibility.js'),
+ sunBounce: () => import('./sun-bounce.js'),
userPass: () => import('./user-pass.js'),
materialSnippet: () => import('./material-snippet.js'),
};
@@ -75,6 +76,7 @@ const MODULE_MARKERS = {
coplanar: ['"resolveCoplanar"'],
// A closed room a sun lights gets the floor sky trace by default. The recipe text can not say whether a room is closed, so a recipe that names its sun loads it and the module skips an open scene.
floorSky: ['"keyColor"', '"keyIntensity"'],
+ sunBounce: ['"keyColor"', '"keyIntensity"'],
userPass: ['"postPasses"'],
materialSnippet: ['"snippet":{'],
};
diff --git a/src/agent-scene.js b/src/agent-scene.js
index ca153ed6..c4b6ea4e 100644
--- a/src/agent-scene.js
+++ b/src/agent-scene.js
@@ -1422,7 +1422,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {
knownKeys(operation, ['type', lookField], 'operation');
const patch = operation[lookField];
// Spot and area lights, cascades and sun links are absent from a recipe until it sets them.
- const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];
+ const optionalFields = lookField === 'environment' ? ['ground', 'spotLights', 'areaLights', 'shadowCascades', 'keyAffects', 'objectReflections', 'floorSkyTrace', 'sunBounce', 'lines', 'resolveCoplanar', 'viewTransform', 'look'] : [];
knownKeys(patch, [...Object.keys(candidate[lookField]), ...optionalFields], lookField);
const nestedField = lookField === 'environment' ? 'volumeFog' : lookField === 'effects' ? 'bloom' : null;
const merged = { ...candidate[lookField], ...(lookField === 'environment' ? environmentPatchWithSetup(patch) : patch) };
diff --git a/src/ground-bounce.js b/src/ground-bounce.js
index ae6836ae..cf3fb47e 100644
--- a/src/ground-bounce.js
+++ b/src/ground-bounce.js
@@ -184,7 +184,7 @@ function areaFacing(part, viewpoint) {
return area
}
-function partDiffuseAlbedo(material) {
+export function partDiffuseAlbedo(material) {
const known = groundAlbedo(material)
if (known) {
return known
diff --git a/src/sun-bounce.js b/src/sun-bounce.js
new file mode 100644
index 00000000..ae6b5190
--- /dev/null
+++ b/src/sun-bounce.js
@@ -0,0 +1,213 @@
+import { buildWorld, cosineDirection, hashUnit, radicalInverse, sceneScale } from './light-bake.js';
+import { createTracer } from './ray-query.js';
+import { CLOSED_ROOM_SHARE, closedRoomShare } from './closed-room.js';
+import { partDiffuseAlbedo } from './ground-bounce.js';
+import { MAX_POINT_LIGHTS } from './light-limits.js';
+
+// Light a sunlit patch sends on to the rest of a closed room. The patches are found once, when the scene is prepared: surfaces
+// of the room are sampled, the samples the sun reaches (a shadow ray) and that sit inside the room (most of a short cosine ray
+// fan hits something) are grouped into a few patches by position and facing, and each patch becomes a point light just above
+// it. Its flux is the sun's irradiance times the lit area times the surface's albedo, per colour channel, spread over the
+// half space the patch looks into. A wall near a patch then gets more of it than a wall across the room, and a red carpet
+// bounces red. It adds no shader code and nothing to the core entry; the cost is one trace when the parts are prepared, and
+// one more point light for each patch in every frame.
+
+export const SUN_BOUNCE_PATCH_LIGHTS = 6;
+export const SUN_BOUNCE_SAMPLES = 20_000;
+const ROOM_RAYS = 8;
+// Share of the room rays that must hit something for a lit sample to count as inside the room (a roof's outer side hits nothing).
+const ENCLOSED_SHARE = 0.5;
+const CLUSTER_PASSES = 6;
+// The light stands this many patch radii above its patch: close enough to light the patch's own surroundings, high enough not to
+// brighten the patch itself much.
+const LIFT_IN_RADII = 1;
+// Fitted against Cycles on the reference halls (docs/lighting.md); environment.sunBounce multiplies it.
+export const SUN_BOUNCE_GAIN = 1;
+const KEY_THRESHOLD = 1e-3;
+const EXCLUDED_TAGS = new Set(['liquid', 'foam', 'unlit', 'fire', 'smoke']);
+
+function isBounceSurface(part) {
+ return part.material?.alphaMode !== 'blend' && !((part.material?.emission ?? 0) > 0) && !EXCLUDED_TAGS.has(part.material?.tag);
+}
+
+function sunOf(environment) {
+ const keyColor = environment.keyColor ?? [1, 1, 1];
+ const keyIntensity = environment.keyIntensity ?? 1;
+ const length = Math.hypot(...environment.lightDirection);
+ return { irradiance: keyColor.map(channel => channel * keyIntensity), direction: environment.lightDirection.map(component => component / length) };
+}
+
+function hasSun(environment) {
+ const keyColor = environment.keyColor ?? [1, 1, 1];
+ return Boolean(environment.lightDirection) && (environment.keyIntensity ?? 1) * (keyColor[0] + keyColor[1] + keyColor[2]) > KEY_THRESHOLD;
+}
+
+// Lit, enclosed samples of the room's surfaces: position, outward normal and the flux the sample reflects, per channel.
+function sampleLitSurfaces(parts, sun) {
+ const world = buildWorld(parts);
+ const tracer = createTracer(world);
+ const offset = sceneScale(world.positions) * 1e-4;
+ const { positions, indices, triangleOwner } = world;
+ const albedoOfPart = parts.map(part => partDiffuseAlbedo(part.material ?? {}));
+ const triangleCount = indices.length / 3;
+ const corner = (triangle, slot, axis) => positions[indices[triangle * 3 + slot] * 3 + axis];
+ const normals = new Float32Array(triangleCount * 3);
+ const areas = new Float32Array(triangleCount);
+ let sunFacingArea = 0;
+ for (let triangle = 0; triangle < triangleCount; triangle++) {
+ const edgeOne = [0, 1, 2].map(axis => corner(triangle, 1, axis) - corner(triangle, 0, axis));
+ const edgeTwo = [0, 1, 2].map(axis => corner(triangle, 2, axis) - corner(triangle, 0, axis));
+ const cross = [edgeOne[1] * edgeTwo[2] - edgeOne[2] * edgeTwo[1], edgeOne[2] * edgeTwo[0] - edgeOne[0] * edgeTwo[2], edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0]];
+ const length = Math.hypot(...cross);
+ if (length < 1e-12) continue;
+ areas[triangle] = length / 2;
+ for (let axis = 0; axis < 3; axis++) normals[triangle * 3 + axis] = cross[axis] / length;
+ const cosine = normals[triangle * 3] * sun.direction[0] + normals[triangle * 3 + 1] * sun.direction[1] + normals[triangle * 3 + 2] * sun.direction[2];
+ if (cosine > 0 && isBounceSurface(parts[triangleOwner[triangle]])) sunFacingArea += areas[triangle];
+ }
+ const sampleArea = sunFacingArea / SUN_BOUNCE_SAMPLES;
+ const samples = [];
+ const fan = [0, 0, 0];
+ let carried = 0;
+ for (let triangle = 0; triangle < triangleCount; triangle++) {
+ const normal = [normals[triangle * 3], normals[triangle * 3 + 1], normals[triangle * 3 + 2]];
+ const cosine = normal[0] * sun.direction[0] + normal[1] * sun.direction[1] + normal[2] * sun.direction[2];
+ if (cosine <= 0 || areas[triangle] === 0 || !isBounceSurface(parts[triangleOwner[triangle]])) continue;
+ carried += areas[triangle] / sampleArea;
+ for (let slot = 0; carried >= 1; slot++, carried -= 1) {
+ let firstWeight = hashUnit(triangle, slot, 1);
+ let secondWeight = hashUnit(triangle, slot, 2);
+ if (firstWeight + secondWeight > 1) {
+ firstWeight = 1 - firstWeight;
+ secondWeight = 1 - secondWeight;
+ }
+ const point = [0, 1, 2].map(axis => corner(triangle, 0, axis) + firstWeight * (corner(triangle, 1, axis) - corner(triangle, 0, axis)) + secondWeight * (corner(triangle, 2, axis) - corner(triangle, 0, axis)));
+ const origin = point.map((value, axis) => value + normal[axis] * offset);
+ if (tracer.trace(origin[0], origin[1], origin[2], sun.direction[0], sun.direction[1], sun.direction[2], Infinity, true).nearestTriangle >= 0) continue;
+ let blocked = 0;
+ for (let ray = 0; ray < ROOM_RAYS; ray++) {
+ cosineDirection(normal, (ray + 0.5) / ROOM_RAYS, radicalInverse(ray + 1), fan);
+ if (tracer.trace(origin[0], origin[1], origin[2], fan[0], fan[1], fan[2], Infinity, true).nearestTriangle >= 0) blocked++;
+ }
+ if (blocked / ROOM_RAYS < ENCLOSED_SHARE) continue;
+ const albedo = albedoOfPart[triangleOwner[triangle]];
+ samples.push({ point, normal, flux: sun.irradiance.map((channel, index) => channel * cosine * sampleArea * albedo[index]) });
+ }
+ }
+ return samples;
+}
+
+function luminanceOf(flux) {
+ return flux[0] + flux[1] + flux[2];
+}
+
+// Groups samples into `count` patches by position and facing (weighted by flux), starting from the farthest-apart heavy samples.
+function clusterSamples(samples, count, scale) {
+ const features = samples.map(sample => [...sample.point, ...sample.normal.map(component => component * scale)]);
+ const distance = (first, second) => first.reduce((total, value, index) => total + (value - second[index]) ** 2, 0);
+ const centres = [features[samples.reduce((best, sample, index) => (luminanceOf(sample.flux) > luminanceOf(samples[best].flux) ? index : best), 0)]];
+ const nearest = features.map(feature => distance(feature, centres[0]));
+ while (centres.length < count) {
+ let best = 0;
+ for (let index = 1; index < samples.length; index++) {
+ if (nearest[index] * luminanceOf(samples[index].flux) > nearest[best] * luminanceOf(samples[best].flux)) best = index;
+ }
+ if (nearest[best] === 0) break;
+ centres.push(features[best]);
+ features.forEach((feature, index) => { nearest[index] = Math.min(nearest[index], distance(feature, features[best])); });
+ }
+ const assignment = new Int32Array(samples.length);
+ for (let pass = 0; pass < CLUSTER_PASSES; pass++) {
+ const sums = centres.map(() => ({ weight: 0, total: new Array(6).fill(0) }));
+ features.forEach((feature, index) => {
+ let closest = 0;
+ for (let centre = 1; centre < centres.length; centre++) {
+ if (distance(feature, centres[centre]) < distance(feature, centres[closest])) closest = centre;
+ }
+ assignment[index] = closest;
+ const weight = luminanceOf(samples[index].flux);
+ sums[closest].weight += weight;
+ feature.forEach((value, axis) => { sums[closest].total[axis] += value * weight; });
+ });
+ sums.forEach((sum, centre) => {
+ if (sum.weight > 0) centres[centre] = sum.total.map(value => value / sum.weight);
+ });
+ }
+ return centres.map((centre, index) => samples.filter((sample, sampleIndex) => assignment[sampleIndex] === index)).filter(group => group.length > 0);
+}
+
+function lightOfPatch(group, strength) {
+ const flux = [0, 0, 0];
+ const centre = [0, 0, 0];
+ const facing = [0, 0, 0];
+ let weight = 0;
+ for (const sample of group) {
+ const sampleWeight = luminanceOf(sample.flux);
+ weight += sampleWeight;
+ for (let axis = 0; axis < 3; axis++) {
+ flux[axis] += sample.flux[axis];
+ centre[axis] += sample.point[axis] * sampleWeight;
+ facing[axis] += sample.normal[axis] * sampleWeight;
+ }
+ }
+ const facingLength = Math.hypot(...facing) || 1;
+ const normal = facing.map(component => component / facingLength);
+ const middle = centre.map(component => component / weight);
+ const radius = Math.sqrt(group.reduce((total, sample) => total + luminanceOf(sample.flux) * sample.point.reduce((sum, value, axis) => sum + (value - middle[axis]) ** 2, 0), 0) / weight);
+ const lift = Math.max(radius * LIFT_IN_RADII, 0.05);
+ // Spread over the half space in front of the patch: intensity = flux / (2 pi).
+ const intensity = flux.map(channel => (strength * SUN_BOUNCE_GAIN * channel) / (2 * Math.PI));
+ const peak = Math.max(...intensity, 1e-9);
+ return { position: middle.map((value, axis) => value + normal[axis] * lift), color: intensity.map(channel => Math.min(channel / peak, 1)), intensity: Math.min(peak, 1e5), radius: lift };
+}
+
+/**
+ * The point lights that stand for the sunlit patches of a closed room: `[]` when the scene has no sun, is not a closed room,
+ * is drawn with a bake or has no lit, enclosed surface. `strength` multiplies every light (`environment.sunBounce`).
+ * `maximumLights` caps how many patches there are.
+ */
+export function findSunBounceLights(parts, environment, { strength = 1, maximumLights = SUN_BOUNCE_PATCH_LIGHTS } = {}) {
+ if (strength <= 0 || maximumLights <= 0 || !hasSun(environment) || parts.some(part => part.material?.lightMap)) return [];
+ const share = closedRoomShare(parts, new Map(parts.map(part => [part.name, part.matrix])));
+ if (share === null || share < CLOSED_ROOM_SHARE) return [];
+ const surfaces = parts.filter(isBounceSurface);
+ const sun = sunOf(environment);
+ let samples;
+ try {
+ samples = sampleLitSurfaces(surfaces, sun);
+ } catch {
+ return [];
+ }
+ if (samples.length === 0) return [];
+ const sceneSize = Math.max(...[0, 1, 2].map(axis => Math.max(...samples.map(sample => sample.point[axis])) - Math.min(...samples.map(sample => sample.point[axis]))), 1e-3);
+ return clusterSamples(samples, maximumLights, sceneSize).map(group => lightOfPatch(group, strength));
+}
+
+const lightsOfParts = new WeakMap();
+
+/**
+ * The environment with the sunlit patches' lights added to its point lights. `environment.sunBounce` (default 1) scales
+ * them; 0 returns the environment itself. The patches are found once for these parts and this sun and kept.
+ */
+export function withSunBounce(parts, environment) {
+ const strength = environment.sunBounce ?? 1;
+ if (strength <= 0 || !hasSun(environment)) return environment;
+ const existing = environment.pointLights ?? [];
+ const room = Math.min(SUN_BOUNCE_PATCH_LIGHTS, MAX_POINT_LIGHTS - existing.length);
+ const key = JSON.stringify([parts.length, environment.keyColor, environment.keyIntensity, environment.lightDirection, room]);
+ let remembered = lightsOfParts.get(parts);
+ if (remembered?.key !== key) {
+ remembered = { key, lights: findSunBounceLights(parts, environment, { strength: 1, maximumLights: room }), scaled: new Map() };
+ lightsOfParts.set(parts, remembered);
+ }
+ if (remembered.lights.length === 0) return environment;
+ if (!remembered.scaled.has(strength)) {
+ remembered.scaled.set(strength, remembered.lights.map(light => scaledLight(light, strength)));
+ }
+ return { ...environment, pointLights: [...existing, ...remembered.scaled.get(strength)] };
+}
+
+function scaledLight(light, strength) {
+ const peak = light.intensity * strength;
+ return { ...light, intensity: Math.min(peak, 1e5) };
+}