Files
gods-eye-view/src/render/cesium/drawLineAges.test.mjs
T
Sameh Khamis 7ff536299a Lines can fade with the age of their points, drawn by the renderer on the GPU (#1892)
* Lines can fade with the age of their points, drawn by the renderer on the GPU

A LineItem's ageFade gives each position a time, a window and floors; the
renderer fades the line's alpha (and optionally its width) by each point's
recency on the scene clock, so a moving trail is not re-sent each frame.
Capability lineAgeFade; the Cesium port draws it in its line materials from a
small float texture of the points' times and a per-frame uniform, and the
conformance check draw.lines.ageFade pins it.

* Changelog for line age fade (#1892)
2026-11-21 06:29:57 -08:00

327 lines
11 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import test, { after } from 'node:test';
import { createCesiumDraw, lineAgeData } from './draw.js';
// Node has no WebGL context to report line-width limits.
Cesium.ContextLimits._minimumAliasedLineWidth = 1;
Cesium.ContextLimits._maximumAliasedLineWidth = 10;
// A material's texture uniform is told from the browser's image classes, which
// Node lacks.
const IMAGE_CLASSES = [
'HTMLCanvasElement',
'HTMLImageElement',
'ImageBitmap',
'OffscreenCanvas',
];
const realClasses = IMAGE_CLASSES.map((name) => globalThis[name]);
for (const name of IMAGE_CLASSES) globalThis[name] ??= class {};
after(() =>
IMAGE_CLASSES.forEach((name, i) => (globalThis[name] = realClasses[i])),
);
/** A scene with what a line set touches: primitives, its events and its time. */
function fakeScene(ms = Date.UTC(2026, 0, 1)) {
const added = [];
return {
added,
postRender: new Cesium.Event(),
preRender: new Cesium.Event(),
camera: { positionWC: new Cesium.Cartesian3(2e7, 0, 0) },
frameState: {
mode: Cesium.SceneMode.SCENE3D,
time: Cesium.JulianDate.fromDate(new Date(ms)),
},
updateHeight: () => () => {},
getHeight: () => undefined,
primitives: {
add: (primitive) => (added.push(primitive), primitive),
remove: (primitive) => {
const at = added.indexOf(primitive);
if (at >= 0) added.splice(at, 1);
return at >= 0;
},
length: 0,
},
requestRender() {},
isDestroyed: () => false,
};
}
const T0 = Date.UTC(2026, 0, 1);
/** A port that fades lines with age, over `scene`, and its frames at a scene time. */
function agedDraw(scene = fakeScene(), capabilities = ['lineAgeFade']) {
const part = createCesiumDraw({
scene,
report: (error) => assert.fail(error),
capabilities: new Set(capabilities),
});
return {
part,
scene,
frameAt(ms) {
scene.frameState.time = Cesium.JulianDate.fromDate(new Date(ms));
part.beforeRender();
part.afterRender();
},
};
}
const along = (n, lat = 10) =>
Array.from({ length: n }, (_, i) =>
Cesium.Cartesian3.fromDegrees(i * 0.01, lat, 100),
);
const trail = (positions, times, extra = {}) => ({
id: 'trail',
positions,
widthPx: 3,
mode: '3d',
style: { kind: 'solid', color: [0.2, 0.8, 1, 0.9] },
ageFade: { times, windowMs: 60_000, alphaFloor: 0.06, ...extra },
pickable: false,
});
/** The polylines a line set's host draws in its collection. */
function collectionOf(scene) {
const host = scene.added.at(-1);
if (host instanceof Cesium.PolylineCollection) return host;
for (let i = 0; i < host.length; i++)
if (host.get(i) instanceof Cesium.PolylineCollection) return host.get(i);
return null;
}
test('a polyline’s age texels: a point at the place of the one before it is dropped, the rest even along it, times in seconds before the newest', () => {
const [a, b, c] = along(3);
const age = lineAgeData([a, a, b, c], [T0, T0 + 1000, T0 + 2000, T0 + 4000], {
times: [],
windowMs: 30_000,
alphaFloor: 0.06,
squaredAlphaFloor: 0.14,
});
assert.equal(age.count, 3);
assert.equal(age.base, T0 + 4000);
const texel = (i) => [age.data[i * 4], age.data[i * 4 + 1]];
assert.deepEqual(texel(0), [0, -4]);
assert.deepEqual(texel(1), [0.5, -2]);
assert.deepEqual(texel(2), [1, 0]);
assert.deepEqual(age.uniforms, {
ageCount: 3,
ageWidth: 3,
ageRows: 1,
ageByLength: 0,
ageWindow: 30,
ageAlphaFloor: 0.06,
ageSquaredFloor: 0.14,
ageWidthFloor: 1,
});
});
test('a draped line’s age texels lie along it by distance, and a long line takes more rows', () => {
const points = [
Cesium.Cartesian3.fromDegrees(0, 0),
Cesium.Cartesian3.fromDegrees(1, 0),
Cesium.Cartesian3.fromDegrees(4, 0),
];
const age = lineAgeData(
points,
[0, 1000, 2000],
{ times: [], windowMs: 1, alphaFloor: 0 },
true,
);
assert.equal(age.uniforms.ageByLength, 1);
assert.equal(age.data[0], 0);
assert.ok(
Math.abs(age.data[4] - 0.25) < 1e-6,
`a quarter along (${age.data[4]})`,
);
assert.equal(age.data[8], 1);
const long = along(2500);
const many = lineAgeData(
long,
long.map((_, i) => i),
{ times: [], windowMs: 1, alphaFloor: 0 },
);
assert.equal(many.width, 1024);
assert.equal(many.rows, 3);
assert.equal(many.data.length, 1024 * 3 * 4);
});
test('an aged line fades on the scene clock: time passing changes its material, never its line', () => {
const { part, scene, frameAt } = agedDraw();
const set = part.port.lines({ id: 'trails' });
const positions = along(4);
const times = [T0 - 30_000, T0 - 20_000, T0 - 10_000, T0];
set.set([
trail(positions, times, { squaredAlphaFloor: 0.14, widthFloor: 0.3 }),
]);
const polylines = collectionOf(scene);
const polyline = polylines.get(0);
const material = polyline.material;
assert.equal(material.type, 'DrawAgedLine_solid');
assert.ok(material.isTranslucent(), 'drawn in the translucent pass');
assert.equal(material.uniforms.ageWindow, 60);
assert.equal(material.uniforms.ageAlphaFloor, 0.06);
assert.equal(material.uniforms.ageSquaredFloor, 0.14);
assert.equal(material.uniforms.ageWidthFloor, 0.3);
assert.equal(material.uniforms.ageCount, 4);
assert.ok(
Cesium.Color.equals(
material.materials.aged.uniforms.color,
new Cesium.Color(0.2, 0.8, 1, 0.9),
),
'its style’s colour inside',
);
for (let k = 1; k <= 120; k++) {
frameAt(T0 + k * 1000);
assert.equal(
material.uniforms.ageNow,
k,
`seconds after its newest point, frame ${k}`,
);
}
assert.equal(collectionOf(scene), polylines, 'the same collection');
assert.equal(polylines.length, 1);
assert.equal(polylines.get(0), polyline, 'the same line');
assert.equal(polyline.material, material, 'the same material');
});
test('an aged line given new points and times moves in place and takes the new times', () => {
const { part, scene, frameAt } = agedDraw();
const set = part.port.lines({ id: 'trails' });
const positions = along(5);
const times = [0, 1, 2, 3, 4].map((i) => T0 + i * 10_000);
set.set([trail(positions.slice(0, 4), times.slice(0, 4))]);
const polyline = collectionOf(scene).get(0);
const material = polyline.material;
frameAt(T0 + 40_000);
assert.equal(material.uniforms.ageNow, 10);
set.upsert([trail(positions.slice(1), times.slice(1))]);
assert.equal(collectionOf(scene).get(0), polyline, 'moved in place');
assert.equal(polyline.material, material);
frameAt(T0 + 45_000);
assert.equal(material.uniforms.ageNow, 5, 'from its new newest point');
assert.ok(Cesium.Cartesian3.equals(polyline.positions[0], positions[1]));
// A new colour is taken in place too, inside the fade.
set.upsert([
{
...trail(positions.slice(1), times.slice(1)),
style: { kind: 'solid', color: '#ff0000' },
},
]);
assert.equal(collectionOf(scene).get(0), polyline, 'recoloured in place');
assert.ok(
Cesium.Color.equals(
material.materials.aged.uniforms.color,
Cesium.Color.RED,
),
);
});
test('segment colours fade with age too, each segment with its own two times', () => {
const { part, scene, frameAt } = agedDraw();
const set = part.port.lines({ id: 'trails' });
const times = [T0, T0 + 1000, T0 + 2000];
set.set([
{
...trail(along(3), times),
segmentColors: ['#ff0000', '#00ff00'],
},
]);
const pieces = [];
const visit = (primitive) => {
if (primitive instanceof Cesium.Primitive) pieces.push(primitive);
else if (primitive?.length !== undefined && primitive.get)
for (let i = 0; i < primitive.length; i++) visit(primitive.get(i));
};
visit(scene.added.at(-1));
assert.equal(pieces.length, 2);
frameAt(T0 + 3000);
const [first, second] = pieces.map((piece) => piece.appearance.material);
assert.equal(first.type, 'DrawAgedLine_solid');
assert.equal(
first.uniforms.ageNow,
2,
'its newer point a second after the first',
);
assert.equal(second.uniforms.ageNow, 1);
assert.ok(
Cesium.Color.equals(first.materials.aged.uniforms.color, Cesium.Color.RED),
);
assert.ok(
Cesium.Color.equals(
second.materials.aged.uniforms.color,
Cesium.Color.LIME,
),
);
});
test('a draped aged line draws by a ground primitive of its own, its times along its length', () => {
const { part, scene } = agedDraw();
const set = part.port.lines({ id: 'trails' });
const ground = [0, 1, 2].map((i) =>
Cesium.Cartesian3.fromDegrees(i * 0.01, 10),
);
set.set([{ ...trail(ground, [T0, T0 + 1, T0 + 2]), mode: 'draped' }]);
const host = scene.added.at(-1);
const primitives = [];
const visit = (primitive) => {
if (primitive instanceof Cesium.GroundPolylinePrimitive)
primitives.push(primitive);
else if (primitive?.length !== undefined && primitive.get)
for (let i = 0; i < primitive.length; i++) visit(primitive.get(i));
};
visit(host);
assert.equal(primitives.length, 1);
const material = primitives[0].appearance.material;
assert.equal(material.type, 'DrawAgedLine_solid');
assert.equal(material.uniforms.ageByLength, 1);
});
test('an aged line built anew lets its old material go once its primitive is gone', () => {
const { part, scene, frameAt } = agedDraw();
const set = part.port.lines({ id: 'trails' });
const deep = (times) => ({
...trail(along(3), times),
depthFail: { kind: 'solid', color: '#ffffff' },
});
set.set([deep([T0, T0 + 1, T0 + 2])]);
const record = part.sets.get('trails');
assert.equal(record.ages.size, 2, 'its line and the part behind the surface');
const [old] = record.ages.keys();
set.upsert([deep([T0 + 1, T0 + 2, T0 + 3])]);
frameAt(T0 + 10);
assert.ok(old.isDestroyed(), 'the old material went with its primitive');
assert.equal(record.ages.size, 2);
void scene;
});
test('without the capability a line ignores its age fade; with it a bad fade is refused', () => {
const plain = agedDraw(fakeScene(), []);
const lines = plain.part.port.lines({ id: 'trails' });
lines.set([trail(along(3), [T0])]);
const material = collectionOf(plain.scene).get(0).material;
assert.equal(material.type, 'Color', 'drawn as its style alone');
const { part } = agedDraw();
const set = part.port.lines({ id: 'trails' });
assert.throws(
() => set.set([trail(along(3), [T0, T0])]),
TypeError,
'one time a position',
);
assert.throws(
() => set.set([trail(along(2), [T0, T0], { windowMs: 0 })]),
TypeError,
'a positive window',
);
assert.throws(
() => set.set([trail(along(2), [T0, T0], { widthFloor: 2 })]),
TypeError,
'floors from 0 to 1',
);
assert.equal(set.size(), 0, 'nothing changed');
});