Draw clamped points, draped lines and ground fills through the Cesium draw port

Clamped items now follow the ground the way Cesium's own entities do: a
clamped point is a billboard of a drawn dot, a draped line a ground
polyline, and a clamped fill a ground primitive, packed so no two fills in
one overlap. A rebuilt set keeps its old ground primitives until the new
ones are ready and swaps them in one frame, and whenSettled waits for
them. Sets with horizonCull hide their points and icons past the horizon
before each frame, and a change to what a set clamps to rebuilds it.
This commit is contained in:
Sameh Khamis committed 2026-11-06 19:15:01 -08:00
1 parent 99ad51048f
commit 8b2859e501
3 files changed
+644 -31

No files matched your search

+254
View File
@@ -4,6 +4,10 @@ import test from 'node:test';
import { bindRenderer, drawOf, findDraw } from '../rendererOf.js';
import './draw.js';
// Node has no WebGL context to report line-width limits.
Cesium.ContextLimits._minimumAliasedLineWidth = 1;
Cesium.ContextLimits._maximumAliasedLineWidth = 10;
/** A scene with what the draw port touches: primitives and its events. */
function fakeScene() {
const added = [];
@@ -14,6 +18,14 @@ function fakeScene() {
postRender,
preRender,
camera: { positionWC: new Cesium.Cartesian3(2e7, 0, 0) },
frameState: { mode: Cesium.SceneMode.SCENE3D },
// Clamped billboards ask the scene to follow the ground.
clamped: [],
updateHeight(position, update, heightReference) {
this.clamped.push(heightReference);
return () => {};
},
getHeight: () => undefined,
primitives: {
add: (primitive) => (added.push(primitive), primitive),
remove: (primitive) => {
@@ -68,3 +80,245 @@ test('nothing to draw into, no port', () => {
assert.equal(findDraw({ scene: {} }), null);
assert.throws(() => drawOf({}), /no renderer to draw with/);
});
/** A draw port over a fake scene, with its frame hooks. */
function drawOver(scene = fakeScene()) {
const viewer = { scene };
const draw = drawOf(viewer);
return {
scene,
draw,
frame() {
scene.preRender.raiseEvent();
scene.postRender.raiseEvent();
},
};
}
test('a clamped point is a billboard dot that follows the ground; others stay points', () => {
const { scene, draw } = drawOver();
const set = draw.points({ id: 'dots', clampTo: 'both' });
set.set([
{
id: 'ground',
pos: { lon: 10, lat: 20 },
height: 'clampGround',
pixelSize: 9,
color: '#7fe6ed',
outlineColor: '#000',
outlineWidth: 2,
disableDepthTest: Infinity,
},
{ id: 'free', pos: { lon: 0, lat: 0 }, pixelSize: 4, color: '#fff' },
]);
const host = scene.added[0];
assert.ok(host instanceof Cesium.PrimitiveCollection, 'both kinds');
const points = host.get(0);
const dots = host.get(1);
assert.ok(points instanceof Cesium.PointPrimitiveCollection);
assert.ok(dots instanceof Cesium.BillboardCollection);
const dot = dots.get(0);
assert.equal(dot.heightReference, Cesium.HeightReference.CLAMP_TO_GROUND);
assert.equal(dot.disableDepthTestDistance, Infinity);
assert.equal(dot.scale, 1, 'an outlined dot is drawn at its size');
assert.deepEqual(scene.clamped, [Cesium.HeightReference.CLAMP_TO_GROUND]);
assert.deepEqual(dot.id, {
set: 'dots',
id: 'ground',
meta: undefined,
lodGroup: undefined,
});
set.dispose();
});
test('horizonCull hides points past the horizon each frame, and shows them again', () => {
const { scene, draw, frame } = drawOver();
const set = draw.points({ id: 'cull', horizonCull: true });
const near = { lon: 0, lat: 0 };
const far = { lon: 180, lat: 0 };
set.set([
{ id: 'near', pos: near, pixelSize: 4, color: '#fff' },
{ id: 'far', pos: far, pixelSize: 4, color: '#fff' },
{ id: 'hidden', pos: near, pixelSize: 4, color: '#fff', show: false },
]);
const host = scene.added[0];
frame();
assert.deepEqual(
[0, 1, 2].map((i) => host.get(i).show),
[true, false, false],
);
scene.camera.positionWC = new Cesium.Cartesian3(-2e7, 0, 0);
frame();
assert.deepEqual(
[0, 1, 2].map((i) => host.get(i).show),
[false, true, false],
'the eye moved round',
);
set.setOptions({ horizonCull: false });
assert.deepEqual(
[0, 1, 2].map((i) => host.get(i).show),
[true, true, false],
'uncull shows what the cull hid, not what was hidden',
);
set.dispose();
});
test('draped lines are ground polylines; a rebuild keeps the old ones until the new are ready', () => {
const { scene, draw, frame } = drawOver();
const set = draw.lines({ id: 'tracks' });
const line = (id) => ({
id,
positions: [
{ lon: 0, lat: 0 },
{ lon: 1, lat: 1 },
],
widthPx: 2.5,
mode: 'draped',
style: { kind: 'solid', color: '#7fe6ed' },
});
set.set([line('a')]);
const first = scene.added[0];
const ground = first.get(1);
assert.ok(ground instanceof Cesium.GroundPolylinePrimitive);
assert.equal(ground.classificationType, Cesium.ClassificationType.BOTH);
assert.equal(ground.geometryInstances[0].geometry.width, 2.5);
assert.deepEqual(ground.geometryInstances[0].id.id, 'a');
// Still not ready: the first build is all there is.
set.set([line('a'), line('b')]);
assert.deepEqual(scene.added.length, 1, 'an unready host is dropped');
const second = scene.added[0];
Object.defineProperty(second.get(1), 'ready', { value: true });
frame();
assert.equal(second.get(1).show, true, 'shown once ready');
set.set([line('c')]);
assert.equal(scene.added.length, 2, 'the ready one stays until…');
const third = scene.added[1].get(1);
assert.equal(third.show, false, 'the new one hidden while it builds');
frame();
assert.equal(scene.added.length, 2);
Object.defineProperty(third, 'ready', { value: true });
frame();
assert.equal(scene.added.length, 1, '…the new one is ready');
assert.equal(third.show, true, 'and they swap in one frame');
set.dispose();
assert.equal(scene.added.length, 0);
});
test('clamped fills are ground primitives packed so none overlap within one', () => {
const { scene, draw } = drawOver();
const set = draw.shapes({ id: 'discs' });
const disc = (id, lon, fill = [1, 0, 0, 0.3]) => ({
id,
geometry: {
kind: 'ellipse',
center: { lon, lat: 0 },
semiMajor: 100_000,
semiMinor: 100_000,
},
fill,
height: 'clampGround',
});
set.set([disc('a', 0), disc('b', 0.5), disc('c', 30, '#ff0'), disc('x', 60)]);
const host = scene.added[0];
const grounds = [];
for (let i = 0; i < host.length; i++)
if (host.get(i) instanceof Cesium.GroundPrimitive)
grounds.push(host.get(i));
assert.deepEqual(
grounds.map((g) => g.geometryInstances.map((instance) => instance.id.id)),
[['a', 'c', 'x'], ['b']],
);
assert.throws(
() => set.set([{ ...disc('o', 0), outline: '#fff' }]),
/no clamped outlines/,
);
set.dispose();
});
test('changing what a set clamps to rebuilds its items', () => {
const { scene, draw } = drawOver();
const set = draw.points({ id: 'reclamp', clampTo: 'terrain' });
set.set([
{
id: 'p',
pos: { lon: 0, lat: 0 },
height: 'clampGround',
pixelSize: 4,
color: '#fff',
},
]);
assert.equal(
scene.added[0].get(0).heightReference,
Cesium.HeightReference.CLAMP_TO_TERRAIN,
);
set.setOptions({ clampTo: 'tiles' });
assert.equal(
scene.added[0].get(0).heightReference,
Cesium.HeightReference.CLAMP_TO_3D_TILE,
);
set.dispose();
});
test('while a rebuild builds, only the old ground waits: the rest goes at once', () => {
const { scene, draw, frame } = drawOver();
const set = draw.shapes({ id: 'mixed' });
const disc = (id, height) => ({
id,
geometry: {
kind: 'ellipse',
center: { lon: 0, lat: 0 },
semiMajor: 1000,
semiMinor: 1000,
},
fill: '#fff',
...(height ? { height } : {}),
});
const items = [disc('ground', 'clampGround'), disc('raised')];
set.set(items);
const first = scene.added[0];
const ground = first.get(1);
assert.ok(ground instanceof Cesium.GroundPrimitive);
Object.defineProperty(ground, 'ready', { value: true });
frame();
set.set(items);
assert.equal(scene.added.length, 2);
assert.equal(first.length, 1, 'the old raised fill is gone');
assert.equal(first.get(0), ground, 'its ground fill waits');
set.dispose();
assert.equal(scene.added.length, 0);
});
test('clamped shapes refuse what they cannot draw', () => {
const { draw } = drawOver();
const set = draw.shapes({ id: 'refuse' });
const disc = {
id: 'a',
geometry: {
kind: 'ellipse',
center: { lon: 0, lat: 0 },
semiMajor: 1000,
semiMinor: 1000,
},
fill: '#fff',
height: 'clampGround',
};
assert.throws(
() => set.set([{ ...disc, fill: { preset: 'radialRim' } }]),
/colours only/,
);
assert.throws(
() =>
set.set([
{
...disc,
geometry: {
...disc.geometry,
semiMajor: { byCameraHeight: { factor: 1, min: 1, max: 2 } },
},
},
]),
/fixed ellipse radii/,
);
set.dispose();
});