Complete phase 3 W1 acceptance and close T16 findings

Fix Navara model display tint, overlay ordering, follow gestures and resource cleanup.
Reduce repeated aircraft work and correct fixture enrichment responses.
Strengthen dev/preview QA, preserve failure history and document verified W1 results.

Validation: 7171 ordinary tests pass, one Windows-only skip; 15 allocation probes;
37 W1 acceptance steps; contracts, shell, four performance gates; 18 identical
Cesium baseline PNGs. Known pre-existing CCTV and live-source limits are recorded.
This commit is contained in:
German Khokhlov committed 2026-10-26 23:23:25 +04:00
1 parent 766c786093
commit 0600964249
59 files changed
+2334 -701

No files matched your search

+3 -5
View File
@@ -282,11 +282,9 @@
* - Cesium's viewer.clock: the app never animates it (shouldAnimate false,
* its time frozen at boot); Cesium's sun and lighting and every entity
* property read at viewer.clock.currentTime stay on that time;
* - launches: the replay timeline (replay.js, Date.now/performance.now),
* the mission orbit's GMST frame (orbitRendering.js new Date()), launch
* pad and panel throttles (phase 3 Task 15a);
* - wall-clock throttles and feed receipt stamps everywhere (they measure
* real elapsed time, not scene time).
* Launch replay, satellite propagation and orbit GMST now use this clock.
* @property {() => number} now The current app time.
* @property {() => number} frameTime The app time latched at the start of the
* engine's current frame: every reader in one frame gets the same value; it
@@ -374,8 +372,8 @@
* straight segments.
* @property {Matrix4} [modelMatrix] Applied to the positions (an orbit ring
* turned by GMST).
* @property {any} [pickId] What a Cesium pick of the line returns (Navara
* lines are not pickable yet).
* @property {any} [pickId] What a pick of the line returns (Navara uses
* CPU segment picks; lines do not participate in its GPU pass).
*
* @typedef {object} Line
* @property {(positions: Cartesian3[] | Float64Array) => void} setPositions
+3 -3
View File
@@ -5,8 +5,8 @@
// (ScreenSpaceCameraController rotate3D and zoom3D):
// - left drag: heading turns by rate × dx / width × 2π and the camera rises
// by rate × −dy / height × π, rate = 1.77 (Cesium's maximum rotate rate,
// which a tracked camera beyond a few metres always reaches); each move
// counts at most a tenth of the canvas (maximumMovementRatio); a drag
// which a tracked camera beyond a few metres always reaches); the signed
// window ratio uses Cesium's maximumMovementRatio cap; a drag
// right turns the heading clockwise;
// - right drag: a dolly by dy / height (down closes in);
// - wheel: one notch (deltaY 100) is 20 % of the range.
@@ -46,7 +46,7 @@ export function navaraFollowGestures(
return;
}
orbit(
ROTATE_RATE * Math.min(dx / width, MAX_MOVEMENT_RATIO) * 2 * Math.PI,
-ROTATE_RATE * Math.min(-dx / width, MAX_MOVEMENT_RATIO) * 2 * Math.PI,
ROTATE_RATE * Math.min(-dy / height, MAX_MOVEMENT_RATIO) * Math.PI,
);
};
+10 -2
View File
@@ -52,14 +52,22 @@ test('drag turns and right drag dollies as Cesium tracked camera; wheel scales;
win.dispatchEvent(event('pointerup', { button: 0 }));
assert.ok(calls[0][2] < 0, 'pitch down');
assert.ok(Math.abs(calls[0][2] + (1.77 * 40 * Math.PI) / 800) < 1e-12);
// Per move at most a tenth of the canvas counts (maximumMovementRatio).
// Cesium rotate3D caps (startX - endX) / width, before the sign
// reversal into heading. Large right and left drags are asymmetric.
calls.length = 0;
canvas.dispatchEvent(
event('pointerdown', { button: 0, clientX: 0, clientY: 0 }),
);
win.dispatchEvent(event('pointermove', { clientX: 640, clientY: 0 }));
win.dispatchEvent(event('pointerup', { button: 0 }));
assert.ok(Math.abs(calls[0][1] - 1.77 * 0.1 * 2 * Math.PI) < 1e-12);
assert.ok(Math.abs(calls[0][1] - 1.77 * 0.5 * 2 * Math.PI) < 1e-12);
calls.length = 0;
canvas.dispatchEvent(
event('pointerdown', { button: 0, clientX: 640, clientY: 0 }),
);
win.dispatchEvent(event('pointermove', { clientX: 0, clientY: 0 }));
win.dispatchEvent(event('pointerup', { button: 0 }));
assert.ok(Math.abs(calls[0][1] + 1.77 * 0.1 * 2 * Math.PI) < 1e-12);
// A right drag down: a dolly by the window ratio (Cesium zoom3D).
calls.length = 0;
const context = event('contextmenu');
+9 -2
View File
@@ -18,6 +18,7 @@ import { createNavaraLines } from './lines/index.js';
import { createNavaraOverlay } from './overlay.js';
import {
NAVARA_CONTEXT_ATTRIBUTES,
ACES_FILMIC,
navaraScenePlan,
navaraViewOptions,
resolveNavaraLook,
@@ -120,14 +121,20 @@ export async function createNavaraGlobe({
);
// The look's shadowed sun leaked a light per frame (internals.js).
keepCascadedLightIds(view);
// Sprites, points and lines, drawn after tone mapping (overlay.js).
// Screen overlays and model display colour after tone mapping (overlay.js).
overlay = createNavaraOverlay(view);
engine = createNavaraEngine(view, {
hooks: navaraHooks(view),
container,
...(appClock ? { appClock } : {}),
sharpen: createNavaraSharpen(view),
movers: createNavaraMovers(view, { overlay }),
movers: createNavaraMovers(view, {
overlay,
// Model colour follows the display-space stage, after the look's ACES.
aces: plan.effects.some(
({ toneMapping }) => toneMapping?.mode === ACES_FILMIC,
),
}),
lines: createNavaraLines(view, { overlay }),
});
const camera = engine.camera;
+78
View File
@@ -0,0 +1,78 @@
// One camera snapshot per Navara frame, shared by its mover sets. A camera
// command or resize within the frame invalidates it too. Nonstandard parented
// or manually managed cameras retain the uncached path.
const EARTH_RADIUS_M = 6_371_000;
export function createMoverFrameCamera(view) {
const frame = {
cameraPosition: { x: 0, y: 0, z: 0 },
cameraDirection: { x: 0, y: 0, z: -1 },
cameraHeight: 0,
fovDeg: 60,
viewportHeightPx: 0,
pixelRatio: 1,
};
const previous = {};
return (ctx, time) => {
const raw = view.camera.raw;
const renderer = ctx?.getRenderer();
const height = renderer?.domElement.clientHeight;
if (!raw || !(height > 0)) return null;
const p = raw.position,
q = raw.quaternion,
scale = raw.scale;
const dpr = renderer.getPixelRatio?.() ?? 1;
const cacheable =
Number.isFinite(time) &&
!raw.parent &&
raw.matrixAutoUpdate !== false &&
raw.matrixWorldAutoUpdate !== false &&
scale.x === 1 &&
scale.y === 1 &&
scale.z === 1;
if (
cacheable &&
previous.time === time &&
previous.raw === raw &&
previous.renderer === renderer &&
previous.x === p.x &&
previous.y === p.y &&
previous.z === p.z &&
previous.qx === q.x &&
previous.qy === q.y &&
previous.qz === q.z &&
previous.qw === q.w &&
frame.fovDeg === raw.fov &&
frame.viewportHeightPx === height &&
frame.pixelRatio === dpr
)
return frame;
raw.updateMatrixWorld();
const e = raw.matrixWorld.elements;
const position = frame.cameraPosition;
position.x = e[12];
position.y = e[13];
position.z = e[14];
const direction = frame.cameraDirection;
const length = Math.hypot(e[8], e[9], e[10]) || 1;
direction.x = -e[8] / length;
direction.y = -e[9] / length;
direction.z = -e[10] / length;
frame.cameraHeight =
Math.hypot(position.x, position.y, position.z) - EARTH_RADIUS_M;
frame.fovDeg = raw.fov;
frame.viewportHeightPx = height;
frame.pixelRatio = dpr;
previous.time = cacheable ? time : undefined;
previous.raw = raw;
previous.renderer = renderer;
previous.x = p.x;
previous.y = p.y;
previous.z = p.z;
previous.qx = q.x;
previous.qy = q.y;
previous.qz = q.z;
previous.qw = q.w;
return frame;
};
}
@@ -0,0 +1,103 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createMoverFrameCamera } from './frameCamera.js';
function setup() {
let updates = 0;
const raw = {
position: { x: 6372000, y: 2, z: 3 },
quaternion: { x: 0, y: 0, z: 0, w: 1 },
scale: { x: 1, y: 1, z: 1 },
parent: null,
matrixAutoUpdate: true,
fov: 60,
matrixWorld: { elements: new Float64Array(16) },
updateMatrixWorld() {
updates++;
const e = this.matrixWorld.elements;
e[12] = this.position.x;
e[13] = this.position.y;
e[14] = this.position.z;
e[8] = 0;
e[9] = this.quaternion.y;
e[10] = 2;
},
};
const renderer = {
domElement: { clientHeight: 800 },
getPixelRatio: () => 1,
};
const ctx = { getRenderer: () => renderer };
const read = createMoverFrameCamera({ camera: { raw } });
return { read, raw, renderer, ctx, updates: () => updates };
}
test('mover sets share one matrix update in a frame and refresh next frame', () => {
const f = setup();
const first = f.read(f.ctx, 100);
for (let i = 0; i < 30; i++) assert.equal(f.read(f.ctx, 100), first);
assert.equal(f.updates(), 1);
assert.deepEqual(first.cameraDirection, { x: -0, y: -0, z: -1 });
assert.equal(first.cameraPosition.x, 6372000);
f.read(f.ctx, 101);
assert.equal(f.updates(), 2);
});
test('same-frame camera moves, rotations, resize and DPR never reuse stale data', () => {
const f = setup();
f.read(f.ctx, 100);
f.raw.position.x += 100;
assert.equal(f.read(f.ctx, 100).cameraPosition.x, 6372100);
f.raw.quaternion.y = 2;
assert.ok(
Math.abs(f.read(f.ctx, 100).cameraDirection.y + Math.SQRT1_2) < 1e-12,
);
f.renderer.domElement.clientHeight = 600;
assert.equal(f.read(f.ctx, 100).viewportHeightPx, 600);
f.renderer.getPixelRatio = () => 2;
assert.equal(f.read(f.ctx, 100).pixelRatio, 2);
assert.equal(f.updates(), 5);
});
test('missing frames and nonstandard camera transforms keep the uncached path', () => {
for (const modify of [
() => {},
(f) => {
f.raw.parent = {};
},
(f) => {
f.raw.matrixAutoUpdate = false;
},
(f) => {
f.raw.scale.x = 2;
},
(f) => {
f.raw.matrixWorldAutoUpdate = false;
},
]) {
const f = setup();
modify(f);
const time =
f.raw.parent ||
!f.raw.matrixAutoUpdate ||
f.raw.scale.x !== 1 ||
f.raw.matrixWorldAutoUpdate === false
? 100
: undefined;
f.read(f.ctx, time);
f.read(f.ctx, time);
assert.equal(f.updates(), 2);
}
});
test('a hidden canvas has no snapshot and independent views do not share scratch state', () => {
const a = setup(),
b = setup();
a.renderer.domElement.clientHeight = 0;
assert.equal(a.read(a.ctx, 100), null);
a.renderer.domElement.clientHeight = 800;
const first = a.read(a.ctx, 100);
b.raw.position.x += 900;
assert.notEqual(first, b.read(b.ctx, 100));
assert.equal(first.cameraPosition.x, 6372000);
});
+20 -40
View File
@@ -2,7 +2,8 @@
// per set (moverMesh.js) in gev's overlay (overlay.js: drawn after tone
// mapping, so their colours are exact); models are a Navara mesh descriptor
// (public MeshDesc API) holding one InstancedMesh per glTF mesh
// (modelMover.js), lit and graded like the scene. Pickable sets register a
// (modelMover.js). In the cinematic look, depth stays in that scene and
// lit model colour resolves in the display pass. Pickable sets register a
// PickableInstancedMeshWrapper so Navara's pick pass sees each instance;
// pickIds.js turns its batch ids back into instances. commit() uploads and
// asks for one frame (view.forceUpdate); per-frame work runs only on frames
@@ -18,10 +19,10 @@ import { createMoverRegistry } from '../../movers.js';
import { createModelMover } from './modelMover.js';
import { createMoverMesh } from './moverMesh.js';
import { createPickIndex } from './pickIds.js';
import { createMoverFrameCamera } from './frameCamera.js';
const DESC_NAME = 'gevMoverSet';
const registered = new WeakSet();
const EARTH_RADIUS_M = 6_371_000;
class GevMoverSetDesc extends MeshDesc {
constructor(view, ctx, config) {
@@ -50,15 +51,15 @@ class GevMoverSetDesc extends MeshDesc {
if (this.destroyedByGev) return;
mover.group.meshes.forEach((mesh, index) => {
group.add(mesh);
register(mesh, `${this.id}#${index}`);
register(mover.group.pickMeshes[index], `${this.id}#${index}`);
});
this.view.forceUpdate();
});
return group;
}
update() {
updateMover(this.view, this.ctx, this.gev.mover);
update(time) {
updateMover(this.gev.readFrameCamera, this.ctx, this.gev.mover, time);
}
onDestroy() {
@@ -69,53 +70,25 @@ class GevMoverSetDesc extends MeshDesc {
}
}
// The camera a mover needs each drawn frame (scratch: no allocation).
const frameCamera = {
cameraPosition: { x: 0, y: 0, z: 0 },
cameraDirection: { x: 0, y: 0, z: -1 },
cameraHeight: 0,
fovDeg: 60,
viewportHeightPx: 0,
pixelRatio: 1,
};
function updateMover(view, ctx, mover) {
const raw = view.camera.raw;
const renderer = ctx?.getRenderer();
const height = renderer?.domElement.clientHeight;
if (!raw || !(height > 0)) return;
raw.updateMatrixWorld();
const e = raw.matrixWorld.elements;
const position = frameCamera.cameraPosition;
position.x = e[12];
position.y = e[13];
position.z = e[14];
// A three camera looks down its local −z.
const direction = frameCamera.cameraDirection;
const length = Math.hypot(e[8], e[9], e[10]) || 1;
direction.x = -e[8] / length;
direction.y = -e[9] / length;
direction.z = -e[10] / length;
frameCamera.cameraHeight =
Math.hypot(position.x, position.y, position.z) - EARTH_RADIUS_M;
frameCamera.fovDeg = raw.fov;
frameCamera.viewportHeightPx = height;
frameCamera.pixelRatio = renderer.getPixelRatio?.() ?? 1;
mover.update(frameCamera);
function updateMover(readFrameCamera, ctx, mover, time) {
const camera = readFrameCamera(ctx, time);
if (camera) mover.update(camera);
}
/**
* @param {object} view an initialised Navara ThreeView
* @param {{ overlay: ReturnType<import('../overlay.js').createNavaraOverlay> }} ports
* @param {{ overlay: ReturnType<import('../overlay.js').createNavaraOverlay>, aces?: boolean }} ports
* @returns {{ movers: import('../../contract.js').GlobeMovers,
* resolvePick: (batchId: number) => ({ set: string, instance: number, pickId: any } | null),
* destroy: () => void }}
*/
export function createNavaraMovers(view, { overlay }) {
export function createNavaraMovers(view, { overlay, aces = false }) {
if (!registered.has(view)) {
view.registerMesh(DESC_NAME, GevMoverSetDesc);
registered.add(view);
}
const pickIndex = createPickIndex();
const readFrameCamera = createMoverFrameCamera(view);
let loader = null;
const loadGltf = (url) => {
loader ??= createGltfLoader();
@@ -137,7 +110,9 @@ export function createNavaraMovers(view, { overlay }) {
overlay.registerPickable(key, wrapper);
pickIndex.add(options.id, wrapper, (index) => store.pickIds[index]);
}
overlay.add(mover.mesh, () => updateMover(view, overlay.ctx, mover));
overlay.add(mover.mesh, (time) =>
updateMover(readFrameCamera, overlay.ctx, mover, time),
);
return {
ready: mover.ready,
commit() {
@@ -158,10 +133,12 @@ export function createNavaraMovers(view, { overlay }) {
const mover = createModelMover(options, store, {
load: loadGltf,
onLoad: request,
overlay: aces ? overlay : null,
});
const handle = view.addMesh({
[DESC_NAME]: {
mover,
readFrameCamera,
kind: options.kind,
pickable: options.pickable,
onPickable: (wrapper) =>
@@ -178,6 +155,9 @@ export function createNavaraMovers(view, { overlay }) {
destroy() {
pickIndex.remove(options.id);
handle.delete();
// A descriptor deleted before its first update may never own a mesh.
// Release the pending load as well; dispose is idempotent.
mover.dispose();
request();
},
};
+93 -29
View File
@@ -18,14 +18,12 @@ import {
Vector3,
} from 'three';
import { footprintPerDepth, originFor } from './pack.js';
import { createModelTint } from './modelTint.js';
/**
* Ambient light on the tinted surface, as an emissive share of it: Cesium
* lights models with image-based lighting besides the sun, so a tinted
* aircraft reads near-white at any sun angle; Navara's sky light alone left
* them grey-brown at dawn. 0.5 matched Cesium's model luminance at the near
* pose (qa-flights-engines --models=on: median 190 vs 193 on Cesium; 139
* without it).
* Ambient share of the base surface: Cesium supplies image-based lighting
* besides the sun. Navara's sky light alone left it grey-brown at dawn.
* The instance colour is applied after lighting, independently of this share.
*/
export const MODEL_AMBIENT = 0.5;
@@ -47,13 +45,12 @@ const scratchTranslation = new Vector3();
const scratchScale = new Vector3();
/**
* Mixes the instance colour, decoded from sRGB (as Cesium takes colours;
* the material works in linear), into the material's colour by uGevBlend (the
* set's colorBlend, as Cesium's colorBlendAmount); the instance alpha is the
* model's opacity (Cesium: a model colour's alpha makes it translucent; the
* aircraft fade with distance through it), not a blend weight.
* Cesium's ModelFS applies modelColorStage after lightingStage in sRGB.
* Mix the lit output in that space, then return to linear for Navara's look.
* Alpha remains opacity before alpha testing, independently of the mix.
*/
function blendInstanceColor(material, uniforms) {
function blendInstanceColor(material, uniforms, displayTint) {
const alpha = 'diffuseColor.a *= vGevColor.a;';
material.onBeforeCompile = (shader) => {
Object.assign(shader.uniforms, uniforms);
shader.vertexShader = shader.vertexShader
@@ -68,29 +65,36 @@ function blendInstanceColor(material, uniforms) {
shader.fragmentShader = shader.fragmentShader
.replace(
'void main() {',
'uniform float uGevBlend;\nuniform float uGevAmbient;\nvarying vec4 vGevColor;\nvoid main() {',
`uniform float uGevBlend;\nuniform float uGevAmbient;\nvarying vec4 vGevColor;\nvoid main() {`,
)
.replace(
'#include <emissivemap_fragment>',
'#include <emissivemap_fragment>\ntotalEmissiveRadiance += diffuseColor.rgb * uGevAmbient;',
)
.replace('#include <map_fragment>', `#include <map_fragment>\n${alpha}`)
.replace(
'#include <map_fragment>',
'#include <map_fragment>\ndiffuseColor.rgb = mix(diffuseColor.rgb, sRGBTransferEOTF(vGevColor).rgb, uGevBlend);\ndiffuseColor.a *= vGevColor.a;',
'#include <opaque_fragment>',
`#include <opaque_fragment>\nif (!${displayTint} && uGevBlend > 0.0) {\nvec3 gevLitSrgb = sRGBTransferOETF(vec4(gl_FragColor.rgb, 1.0)).rgb;\nvec3 gevMixedColor = sRGBTransferEOTF(vec4(clamp(mix(gevLitSrgb, vGevColor.rgb, uGevBlend), 0.0, 1.0), 1.0)).rgb;\ngl_FragColor.rgb = gevMixedColor;\n}`,
);
};
material.customProgramCacheKey = () => 'gev-mover-model-blend';
material.customProgramCacheKey = () =>
`gev-mover-model-display-color-${displayTint ? 'overlay' : 'linear'}`;
}
/**
* @param {object} options normalized model set options
* @param {object} store the set's mover store
* @param {{ load: (url: string) => Promise<{ scene: object }>, onLoad?: () => void }} ports
* @param {{ load: (url: string) => Promise<{ scene: object }>, onLoad?: () => void, overlay?: object }} ports
*/
export function createModelMover(options, store, { load, onLoad = () => {} }) {
export function createModelMover(
options,
store,
{ load, onLoad = () => {}, overlay = null },
) {
const { capacity, model } = options;
const uniforms = {
uGevAmbient: { value: MODEL_AMBIENT },
uGevModelExposure: overlay?.uniforms.uGevModelExposure ?? { value: 1 },
uGevBlend: {
value: model.colorBlend
? model.colorBlend.mode === 'replace'
@@ -109,6 +113,13 @@ export function createModelMover(options, store, { load, onLoad = () => {} }) {
let disposed = false;
const colorAttributes = [];
const materials = [];
// GLTFLoader returns a fresh asset per load. Cloned materials still share
// its textures; Material.dispose() does not release their GPU allocations.
const textures = new Set();
const disposeTextures = () => {
for (const texture of textures) texture.dispose();
textures.clear();
};
// Each instance's drawn diameter (px) at its last write (CPU picks).
const drawnPx = new Float32Array(capacity);
// Translucent only while an instance is faded (opaque models keep the
@@ -175,18 +186,41 @@ export function createModelMover(options, store, { load, onLoad = () => {} }) {
index * 4,
);
}
for (const { mesh } of parts) {
for (const { mesh, tint } of parts) {
if (tint) {
tint.count = store.count;
tint.visible = store.count > 0;
}
mesh.count = store.count;
mesh.visible = store.count > 0;
mesh.instanceMatrix.needsUpdate = true;
}
for (const attribute of colorAttributes) attribute.needsUpdate = true;
syncTransparency();
};
const group = { meshes: [], ready: null };
group.ready = load(model.url).then((gltf) => {
if (disposed) return;
const group = { meshes: [], pickMeshes: [], ready: null };
const asset = load(model.url).catch(() => {
// A missing asset keeps the layer's glyph fallback. Do not leak the
// rejected loader promise (or its URL) through descriptor creation.
if (!disposed) console.warn('[globe] Model asset unavailable');
return null;
});
group.ready = asset.then((gltf) => {
if (!gltf) return;
const root = gltf.scene;
root.traverse((child) => {
for (const material of Array.isArray(child.material)
? child.material
: [child.material])
if (material)
for (const value of Object.values(material))
if (value?.isTexture) textures.add(value);
});
if (disposed) {
disposeTextures();
return;
}
root.updateMatrixWorld(true);
const sphere = new Box3()
.setFromObject(root)
@@ -201,8 +235,7 @@ export function createModelMover(options, store, { load, onLoad = () => {} }) {
color: material.color,
});
else material = material.clone();
blendInstanceColor(material, uniforms);
materials.push(material);
blendInstanceColor(material, uniforms, Boolean(overlay));
const geometry = child.geometry.clone();
const color = new InstancedBufferAttribute(
new Float32Array(capacity * 4).fill(1),
@@ -216,21 +249,37 @@ export function createModelMover(options, store, { load, onLoad = () => {} }) {
mesh.frustumCulled = false;
mesh.renderOrder = options.order;
mesh.count = 0;
parts.push({ mesh, local: child.matrixWorld.clone() });
mesh.visible = false;
const tint = overlay
? createModelTint(mesh, uniforms, overlay.uniforms)
: null;
if (tint) {
// Still present in the scene depth and GPU pick registry. Only colour
// moves to the display pass, where it is toned before raster resolve.
material.colorWrite = false;
overlay.add(tint);
}
materials.push(material);
if (tint) materials.push(tint.material);
parts.push({ mesh, tint, local: child.matrixWorld.clone() });
group.meshes.push(mesh);
group.pickMeshes.push(tint ?? mesh);
});
loaded = true;
if (origin)
for (const { mesh } of parts)
for (const { mesh, tint } of parts) {
mesh.position.set(origin.x, origin.y, origin.z);
tint?.position.copy(mesh.position);
}
write(0, store.count);
onLoad(group.meshes);
});
const placeAt = (next) => {
origin = { x: next.x, y: next.y, z: next.z };
for (const { mesh } of parts) {
for (const { mesh, tint } of parts) {
mesh.position.set(origin.x, origin.y, origin.z);
tint?.position.copy(mesh.position);
mesh.updateMatrix();
mesh.updateMatrixWorld(true);
}
@@ -258,7 +307,15 @@ export function createModelMover(options, store, { load, onLoad = () => {} }) {
z: store.positions[2],
});
if (range) write(range.from, Math.min(range.to, store.count));
for (const { mesh } of parts) mesh.count = store.count;
for (const { mesh, tint } of parts) {
if (tint) {
tint.count = store.count;
tint.visible = store.count > 0;
}
mesh.count = store.count;
// Retained empty banks must also skip three's material/uniform work.
mesh.visible = store.count > 0;
}
},
/** Each drawn frame: pixel limits need every instance rewritten. */
update({
@@ -278,12 +335,19 @@ export function createModelMover(options, store, { load, onLoad = () => {} }) {
return true;
},
dispose() {
if (disposed) return;
disposed = true;
for (const { mesh } of parts) {
for (const { mesh, tint } of parts) {
if (tint) {
overlay.remove(tint);
tint.material.dispose();
tint.dispose();
}
mesh.geometry.dispose();
mesh.material.dispose();
mesh.dispose?.();
}
disposeTextures();
},
};
}
+193 -4
View File
@@ -7,6 +7,7 @@ import {
Mesh,
MeshStandardMaterial,
Vector3,
Texture,
} from 'three';
import { createMoverStore, normalizeMoverSetOptions } from '../../movers.js';
import { createModelMover, modelPixelDistance } from './modelMover.js';
@@ -91,7 +92,7 @@ test('a far model keeps its minimum pixel size', async () => {
assert.equal(mover.pickRadiusPx(1), null);
});
test("the instance colour (sRGB, decoded) tints by the set's blend amount; its alpha is opacity, as Cesium's model colour", async () => {
test("the instance colour mixes after lighting in sRGB, as Cesium's model colour", async () => {
const store = createMoverStore(options);
const mover = createModelMover(options, store, {
load: async () => fakeGltf(),
@@ -108,14 +109,22 @@ test("the instance colour (sRGB, decoded) tints by the set's blend amount; its a
uniforms: {},
vertexShader: 'void main() {\n#include <begin_vertex>\n}',
fragmentShader:
'void main() {\n#include <map_fragment>\n#include <emissivemap_fragment>\n}',
'void main() {\n#include <map_fragment>\n#include <emissivemap_fragment>\n#include <opaque_fragment>\n}',
};
mesh.material.onBeforeCompile(shader);
assert.match(shader.fragmentShader, /diffuseColor\.a \*= vGevColor\.a;/);
// Cesium ModelFS runs modelColorStage after lightingStage, in sRGB.
assert.match(shader.fragmentShader, /vec3 gevLitSrgb = sRGBTransferOETF/);
assert.match(
shader.fragmentShader,
/diffuseColor\.rgb = mix\(diffuseColor\.rgb, sRGBTransferEOTF\(vGevColor\)\.rgb, uGevBlend\);\s*diffuseColor\.a \*= vGevColor\.a;/,
/mix\(gevLitSrgb, vGevColor\.rgb, uGevBlend\)/,
);
// Ambient light on the tinted surface (Cesium's image-based lighting).
assert.ok(
shader.fragmentShader.indexOf('vec3 gevLitSrgb') >
shader.fragmentShader.indexOf('#include <opaque_fragment>'),
);
assert.doesNotMatch(shader.fragmentShader, /diffuseColor\.rgb = mix/);
// Ambient light belongs to the original surface before the colour mix.
assert.match(
shader.fragmentShader,
/totalEmissiveRadiance \+= diffuseColor\.rgb \* uGevAmbient;/,
@@ -134,3 +143,183 @@ test("the minimum pixel size is taken at Cesium's distance: view depth less the
assert.equal(modelPixelDistance(0, 0, -10, ahead, 30), 0);
assert.equal(modelPixelDistance(4000, 0, -3000, null, 0), 5000);
});
test('disposing a model releases shared textures once, as well as each instanced mesh', async () => {
const gltf = fakeGltf();
const texture = new Texture();
gltf.scene.children[0].material.map = texture;
const second = gltf.scene.children[0].clone();
gltf.scene.add(second);
let released = 0;
texture.addEventListener('dispose', () => released++);
const mover = createModelMover(options, createMoverStore(options), {
load: async () => gltf,
});
await mover.group.ready;
let geometries = 0,
materials = 0;
for (const mesh of mover.group.meshes) {
mesh.geometry.addEventListener('dispose', () => geometries++);
mesh.material.addEventListener('dispose', () => materials++);
}
assert.equal(released, 0, 'textures remain live while the model draws');
mover.dispose();
mover.dispose();
assert.equal(released, 1);
assert.equal(geometries, 2);
assert.equal(materials, 2);
});
test('a model removed before its load completes releases the arriving textures', async () => {
let finish;
const gltf = fakeGltf();
const texture = new Texture();
gltf.scene.children[0].material.map = texture;
let released = 0,
loaded = 0;
texture.addEventListener('dispose', () => released++);
const mover = createModelMover(options, createMoverStore(options), {
load: () =>
new Promise((resolve) => {
finish = resolve;
}),
onLoad: () => loaded++,
});
mover.dispose();
finish(gltf);
await mover.group.ready;
assert.equal(released, 1);
assert.equal(loaded, 0);
assert.equal(mover.ready(), false);
assert.equal(mover.group.meshes.length, 0);
});
test('a failed model load stays not-ready without an unhandled rejection or leaking the URL', async (t) => {
const warnings = [];
t.mock.method(console, 'warn', (message) => warnings.push(message));
const mover = createModelMover(options, createMoverStore(options), {
load: async () => {
throw new Error('unavailable asset URL');
},
});
await mover.group.ready;
assert.equal(mover.ready(), false);
assert.equal(mover.group.meshes.length, 0);
assert.deepEqual(warnings, ['[globe] Model asset unavailable']);
mover.dispose();
});
test('an empty retained model bank leaves the render traversal and restores its cached instances', async () => {
const store = createMoverStore(options);
const mover = createModelMover(options, store, {
load: async () => fakeGltf(),
});
await mover.group.ready;
const [mesh] = mover.group.meshes;
assert.equal(mesh.visible, false, 'loaded before its first instance');
store.set(0, { position: { x: 6378137, y: 0, z: 0 } });
store.setCount(1);
mover.commit(store.dirty());
store.clean();
assert.equal(mesh.visible, true);
const before = mesh.instanceMatrix.array.slice();
store.setCount(0);
mover.commit(store.dirty());
store.clean();
assert.equal(mesh.visible, false);
assert.equal(mover.ready(), true, 'the asset remains cached');
store.setCount(1);
mover.commit(store.dirty());
assert.equal(mesh.visible, true);
assert.deepEqual(mesh.instanceMatrix.array, before);
mover.dispose();
});
test('display tint shares transforms, preserves fade opacity and leaves no overlay resource after destruction', async () => {
const children = new Set();
const overlay = {
uniforms: {
tGevSceneDepth: { value: null },
uGevResolution: { value: [1280, 800] },
},
add: (mesh) => children.add(mesh),
remove: (mesh) => children.delete(mesh),
};
const store = createMoverStore(options);
const mover = createModelMover(options, store, {
load: async () => fakeGltf(),
overlay,
});
store.set(0, {
position: { x: 6378137, y: 0, z: 0 },
color: [1, 0.2, 0.6, 0.4],
});
store.setCount(1);
mover.commit(store.dirty());
await mover.group.ready;
const [base] = mover.group.meshes;
const [tint] = children;
assert.equal(tint.geometry, base.geometry);
assert.equal(tint.instanceMatrix, base.instanceMatrix);
assert.deepEqual(tint.position, base.position);
assert.equal(tint.count, 1);
assert.equal(tint.material.toneMapped, false);
assert.equal(tint.material.depthWrite, false);
const shader = {
uniforms: {},
vertexShader: 'void main() {\n#include <begin_vertex>\n}',
fragmentShader:
'void main() {\n#include <logdepthbuf_fragment>\n#include <opaque_fragment>\n}',
};
tint.material.onBeforeCompile(shader);
assert.equal(shader.uniforms.tGevSceneDepth, overlay.uniforms.tGevSceneDepth);
assert.match(shader.fragmentShader, /if \(gevOverlayHidden\(\)\) discard/);
assert.match(
shader.fragmentShader,
/mix\(gevLitSrgb, vGevColor.rgb, uGevBlend\)/,
);
assert.equal(base.material.colorWrite, false);
assert.equal(
mover.group.pickMeshes[0],
tint,
'GPU picking keeps its color-writing material',
);
store.setCount(0);
mover.commit(store.dirty());
assert.equal(tint.count, 0);
assert.equal(tint.visible, false);
let disposed = 0;
tint.material.addEventListener('dispose', () => disposed++);
mover.dispose();
mover.dispose();
assert.equal(disposed, 1);
assert.equal(children.size, 0);
});
test('the display pass preserves unlit model colour without a lighting tone curve', async () => {
const children = new Set();
const overlay = {
uniforms: {},
add: (mesh) => children.add(mesh),
remove: (mesh) => children.delete(mesh),
};
const spec = { ...options, model: { ...options.model, unlit: true } };
const mover = createModelMover(spec, createMoverStore(spec), {
load: async () => fakeGltf(),
overlay,
});
await mover.group.ready;
const [mesh] = children;
assert.equal(mesh.material.isMeshBasicMaterial, true);
const shader = {
uniforms: {},
vertexShader: 'void main() {\n#include <begin_vertex>\n}',
fragmentShader: 'void main() {\n#include <opaque_fragment>\n}',
};
mesh.material.onBeforeCompile(shader);
assert.doesNotMatch(
shader.fragmentShader,
/gevModelAces\(gl_FragColor.rgb\)/,
);
mover.dispose();
});
+73
View File
@@ -0,0 +1,73 @@
// Models use the scene's depth, but their lit display colour is resolved after
// the view's HDR effects. This keeps MSAA from spreading HDR tint into edges.
import { InstancedMesh } from 'three';
import { OVERLAY_DEPTH_FRAGMENT } from '../overlayDepth.js';
// three's pinned ACESFilmicToneMapping, with the view's public exposure.
const ACES = `
uniform float uGevModelExposure;
vec3 gevModelAces(vec3 color) {
const mat3 inputMatrix = mat3(0.59719,0.076,0.0284, 0.35458,0.90834,0.13383, 0.04823,0.01566,0.83777);
const mat3 outputMatrix = mat3(1.60475,-0.10208,-0.00327, -0.53108,1.10813,-0.07276, -0.07367,-0.00605,1.07602);
color = inputMatrix * (color * uGevModelExposure / 0.6);
color = (color * (color + 0.0245786) - 0.000090537) /
(color * (0.983729 * color + 0.432951) + 0.238081);
return clamp(outputMatrix * color, 0.0, 1.0);
}
`;
export function createModelTint(mesh, uniforms, overlayUniforms) {
const material = mesh.material.clone();
material.depthTest = false;
material.depthWrite = false;
material.toneMapped = false;
const lit = material.isMeshBasicMaterial
? 'gl_FragColor.rgb'
: 'gevModelAces(gl_FragColor.rgb)';
material.onBeforeCompile = (shader) => {
Object.assign(shader.uniforms, uniforms, overlayUniforms, {
uGevDepthMode: { value: 1 },
});
shader.vertexShader = shader.vertexShader
.replace(
'void main() {',
'attribute vec4 gevColor;\nvarying vec4 vGevColor;\nvarying float vGevDepthFree;\nvoid main() {',
)
.replace(
'#include <begin_vertex>',
'#include <begin_vertex>\nvGevColor = gevColor;\nvGevDepthFree = 0.0;',
);
shader.fragmentShader = shader.fragmentShader
.replace(
'void main() {',
`uniform float uGevBlend;\nuniform float uGevAmbient;\nvarying vec4 vGevColor;\n${ACES}\n${OVERLAY_DEPTH_FRAGMENT}\nvoid main() {`,
)
.replace(
'#include <logdepthbuf_fragment>',
'#include <logdepthbuf_fragment>\nif (gevOverlayHidden()) discard;',
)
.replace(
'#include <map_fragment>',
'#include <map_fragment>\ndiffuseColor.a *= vGevColor.a;',
)
.replace(
'#include <emissivemap_fragment>',
'#include <emissivemap_fragment>\ntotalEmissiveRadiance += diffuseColor.rgb * uGevAmbient;',
)
.replace(
'#include <opaque_fragment>',
`#include <opaque_fragment>\nvec3 gevLitSrgb = sRGBTransferOETF(vec4(${lit}, 1.0)).rgb;\ngl_FragColor.rgb = sRGBTransferEOTF(vec4(mix(gevLitSrgb, vGevColor.rgb, uGevBlend), 1.0)).rgb;`,
);
};
material.customProgramCacheKey = () => 'gev-model-lit-display-color';
const tint = new InstancedMesh(
mesh.geometry,
material,
mesh.instanceMatrix.count,
);
tint.userData.gevModelTint = true;
tint.instanceMatrix = mesh.instanceMatrix;
tint.frustumCulled = false;
tint.renderOrder = mesh.renderOrder;
return tint;
}
+52 -27
View File
@@ -1,44 +1,26 @@
// gev's screen overlays on Navara: sprites, points and lines (engine.movers
// and engine.lines) drawn into the frame after Navara's tone mapping and
// before its anti-aliasing (SMAA/FXAA) and the gev sharpening, so their
// and engine.lines) drawn into the frame after Navara's tone mapping,
// anti-aliasing (SMAA/FXAA) and the gev sharpening, so their
// colours are the colours asked for (as Cesium draws billboards and
// polylines), not tone-mapped or graded with the look. A public Navara
// EffectDesc whose pass renders one three scene over the input buffer; the
// post-processing chain has no depth buffer, so each overlay material tests
// the scene depth from Navara's MRT pass itself (overlayDepth.js). The
// pass costs nothing while the scene is empty. Models stay in Navara's
// scene, lit and graded like the 3D tiles.
// pass costs nothing while no geometry is visible. Models retain scene
// depth; their lit display colour is resolved here so HDR effects and MSAA
// cannot spread a tint into neighbouring pixels.
import { EffectDesc, Pass as NavaraPass } from '@navaramap/three';
import { Pass } from 'postprocessing';
import { GevOverlayPass } from './overlayPass.js';
import { RGBADepthPacking, Scene } from 'three';
export const OVERLAY_EFFECT_KEY = 'gevOverlay';
class GevOverlayPass extends Pass {
constructor(scene, camera, overlay) {
super('GevOverlayPass', scene, camera);
this.needsSwap = false;
this.overlay = overlay;
}
render(renderer, inputBuffer) {
if (!this.scene.children.length) return;
const resolution = this.overlay.uniforms.uGevResolution.value;
resolution[0] = inputBuffer?.width ?? 0;
resolution[1] = inputBuffer?.height ?? 0;
const autoClear = renderer.autoClear;
renderer.autoClear = false;
renderer.setRenderTarget(this.renderToScreen ? null : inputBuffer);
renderer.render(this.scene, this.camera);
renderer.autoClear = autoClear;
}
}
class GevOverlayEffectDesc extends EffectDesc {
static key = OVERLAY_EFFECT_KEY;
static insertAfter = ['toneMapping'];
static insertBefore = ['gevSharpen', 'smaa', 'fxaa', 'final'];
// Navara takes the first existing anchor, so the latest pass comes first.
static insertAfter = ['fxaa', 'smaa', 'gevSharpen', 'toneMapping'];
static insertBefore = ['final'];
constructor(view, ctx, config) {
super(view, ctx, config);
@@ -77,11 +59,14 @@ export function createNavaraOverlay(view) {
view.registerEffect(OVERLAY_EFFECT_KEY, GevOverlayEffectDesc);
const scene = new Scene();
const frameHooks = new Map();
const lights = new Map();
let ctx = null;
const pendingPicks = new Map();
const overlay = {
scene,
modelTints: new Set(),
uniforms: {
uGevModelExposure: { value: 1 },
tGevSceneDepth: { value: null },
uGevResolution: { value: [0, 0] },
},
@@ -91,7 +76,42 @@ export function createNavaraOverlay(view) {
ctx.registerPickableMesh(key, wrapper);
pendingPicks.clear();
},
hasDrawables() {
for (const child of scene.children)
if (
!child.isLight &&
child.visible &&
(child.count === undefined || child.count > 0)
)
return true;
return false;
},
beforeFrame(time) {
overlay.uniforms.uGevModelExposure.value = view.toneMappingExposure ?? 1;
// Public descriptor lights are copied, never reparented from Navara.
if (overlay.modelTints.size && ctx) {
for (const light of ctx.scenes.light.children) {
if (!light.isLight) continue;
let copy = lights.get(light);
if (!copy) {
copy = light.clone(false);
copy.castShadow = false;
copy.matrixAutoUpdate = false;
lights.set(light, copy);
scene.add(copy);
}
copy.color.copy(light.color);
copy.intensity = light.intensity;
copy.matrix.copy(light.matrixWorld);
copy.sh?.copy(light.sh);
copy.groundColor?.copy(light.groundColor);
if (copy.target && light.target) {
copy.target.matrixAutoUpdate = false;
copy.target.matrix.copy(light.target.matrixWorld);
copy.target.updateMatrixWorld(true);
}
}
}
for (const hook of frameHooks.values()) hook(time);
},
get ctx() {
@@ -107,10 +127,12 @@ export function createNavaraOverlay(view) {
uniforms: overlay.uniforms,
add(object, onFrame) {
scene.add(object);
if (object.userData.gevModelTint) overlay.modelTints.add(object);
if (onFrame) frameHooks.set(object, onFrame);
},
remove(object) {
scene.remove(object);
overlay.modelTints.delete(object);
frameHooks.delete(object);
},
registerPickable(key, wrapper) {
@@ -127,6 +149,9 @@ export function createNavaraOverlay(view) {
destroy() {
handle.delete();
scene.clear();
overlay.modelTints.clear();
for (const light of lights.values()) light.dispose?.();
lights.clear();
frameHooks.clear();
},
};
+23
View File
@@ -0,0 +1,23 @@
import { Pass } from 'postprocessing';
export class GevOverlayPass extends Pass {
constructor(scene, camera, overlay) {
super('GevOverlayPass', scene, camera);
this.needsSwap = false;
this.overlay = overlay;
}
render(renderer, inputBuffer) {
if (!this.overlay.hasDrawables()) return;
const resolution = this.overlay.uniforms.uGevResolution.value;
resolution[0] = inputBuffer?.width ?? 0;
resolution[1] = inputBuffer?.height ?? 0;
const autoClear = renderer.autoClear;
renderer.autoClear = false;
try {
renderer.setRenderTarget(this.renderToScreen ? null : inputBuffer);
renderer.render(this.scene, this.camera);
} finally {
renderer.autoClear = autoClear;
}
}
}
+43
View File
@@ -0,0 +1,43 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { Scene, PerspectiveCamera } from 'three';
import { GevOverlayPass } from './overlayPass.js';
test('overlay draws in place only with visible objects and restores renderer state on failure', () => {
let active = false;
const overlay = {
hasDrawables: () => active,
uniforms: { uGevResolution: { value: [0, 0] } },
};
const pass = new GevOverlayPass(
new Scene(),
new PerspectiveCamera(),
overlay,
);
const input = { width: 1280, height: 800 };
let target,
renders = 0;
const renderer = {
autoClear: true,
setRenderTarget: (value) => {
target = value;
},
render: () => {
renders++;
},
};
pass.render(renderer, input);
assert.equal(renders, 0);
active = true;
pass.render(renderer, input);
assert.equal(target, input);
assert.equal(renders, 1);
assert.equal(pass.needsSwap, false);
assert.equal(renderer.autoClear, true);
assert.deepEqual(overlay.uniforms.uGevResolution.value, [1280, 800]);
renderer.render = () => {
throw new Error('render failed');
};
assert.throws(() => pass.render(renderer, input), /render failed/);
assert.equal(renderer.autoClear, true);
pass.dispose();
});
+2 -2
View File
@@ -86,8 +86,8 @@ class UnsharpMaskEffect extends Effect {
/** config.gevSharpen: { amount } (Cesium's `amount` uniform). */
export class SharpenEffectDesc extends EffectDesc {
static key = SHARPEN_EFFECT_KEY;
static insertAfter = ['gevOverlay', 'toneMapping'];
static insertBefore = ['smaa', 'fxaa', 'final'];
static insertAfter = ['toneMapping'];
static insertBefore = ['smaa', 'fxaa', 'gevOverlay', 'final'];
constructor(view, ctx, config) {
super(view, ctx, config);
+1 -1
View File
@@ -49,7 +49,7 @@ export function resolveNavaraLook(search = '') {
}
// postprocessing's ToneMappingMode.ACES_FILMIC (Navara's default is AGX, 7).
const ACES_FILMIC = 6;
export const ACES_FILMIC = 6;
// Camera heights (m) where the cinematic look switches the globe to
// atmosphere lighting (night side and terminator) and back. The gap keeps a