render: Cesium draws wind-streamline fields; the wind layer's flow uses the draw port

The Cesium draw port now implements draw.field for the windStreamlines
kind (src/render/cesium/drawStreamlines.js). It carries the flow shader,
the 30-degree cells, horizon and frustum culling and the path tracing over
from the wind layer. It moves the highlight on the page's own frames, at
most every 32 ms, and only while the field shows, is unpaused, has alpha
and some cell is in view on a visible page. A grid no path runs through,
or one short of the whole globe, is refused. A rebuild that fails draws
nothing and is never told drawn.

The wind layer's GPU flow (src/layers/wind/gpuRendering.js) now builds the
spec, fades it by camera height and pauses it through the draw, camera and
frame ports, and no longer reaches Cesium, so it leaves the Cesium allow
list. The layer runs no animation loop of its own while the renderer draws
the flow; the canvas fallback is unchanged and still takes over wherever
the field is refused. A new conformance check covers the field's 'drawn'
events.
This commit is contained in:
Sameh Khamis committed 2026-11-09 07:38:06 -08:00
1 parent 50cb7bd5f4
commit fcd1c09565
12 files changed
+1414 -701

No files matched your search

+146 -371
View File
@@ -1,147 +1,18 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createWindGpuRendering } from './gpuRendering.js';
import {
BoundingSphere,
Cartesian3,
Ellipsoid,
Intersect,
Occluder,
PerspectiveFrustum,
} from 'cesium';
import { bakeWindStreamlines } from './streamlines.js';
createWindGpuRendering,
windHeightFade,
windStreamlineSpec,
} from './gpuRendering.js';
import {
WIND_DISPLAY_HEIGHT_METERS,
WIND_NARROW_PATH_LIMIT,
WIND_PATH_LIMIT,
WIND_PATH_STEPS,
} from './streamlines.js';
function harness({ width = 1000 } = {}) {
const members = new Set();
let geometryBuilds = 0;
const spheres = [];
const visibility = {
horizon: () => true,
frustum: () => Intersect.INSIDE,
horizonTests: 0,
frustumTests: 0,
};
let occluderBuilds = 0;
class Material {
constructor(options) {
this.uniforms = options.fabric.uniforms;
this.source = options.fabric.source;
}
destroy() {
assert.ok(!this.destroyed, 'owned resource destroyed once');
this.destroyed = true;
}
}
class Appearance {
static VERTEX_FORMAT = {};
constructor(options) {
Object.assign(this, options);
this.vertexShaderSource ??=
'in vec3 position3DHigh; in vec3 position3DLow; void main() { gl_Position = vec4(0.0); v_st.s = st.s; }';
}
}
class Polyline {
constructor(options) {
Object.assign(this, options);
}
static createGeometry(options) {
geometryBuilds++;
const st = new Float32Array(options.positions.length * 2);
for (let i = 0; i < options.positions.length; i++)
st[i * 2] = i / (options.positions.length - 1);
return { attributes: { st: { values: st } } };
}
}
class Primitive {
constructor(options) {
Object.assign(this, options);
this.ready = true;
}
destroy() {
assert.ok(!this.destroyed, 'owned resource destroyed once');
this.destroyed = true;
}
isDestroyed() {
return Boolean(this.destroyed);
}
}
const C = {
ComponentDatatype: { FLOAT: 5126 },
GeometryInstanceAttribute: class {
constructor(options) {
Object.assign(this, options);
}
},
Material,
PolylineMaterialAppearance: Appearance,
PolylineGeometry: Polyline,
Primitive,
GeometryInstance: class {
constructor(options) {
Object.assign(this, options);
}
},
Cartesian3,
Ellipsoid,
Intersect,
BoundingSphere: class extends BoundingSphere {
static fromPoints(points) {
const sphere = BoundingSphere.fromPoints(points);
spheres.push({ sphere, points });
return sphere;
}
},
Occluder: class {
constructor(sphere, cameraPosition) {
occluderBuilds++;
this.cameraPosition = cameraPosition;
}
isBoundingSphereVisible(sphere) {
visibility.horizonTests++;
return visibility.horizon(sphere, this.cameraPosition);
}
},
ArcType: { NONE: 0 },
};
const volume = {
computeVisibility(sphere) {
visibility.frustumTests++;
return visibility.frustum(sphere);
},
};
const scene = {
globe: { show: false },
camera: {
positionWC: Cartesian3.fromDegrees(0, 0, 1e7),
positionCartographic: { height: 1e7 },
directionWC: new Cartesian3(-1, 0, 0),
upWC: new Cartesian3(0, 0, 1),
frustum: { computeCullingVolume: () => volume },
},
canvas: { clientWidth: width },
primitives: {
add(item) {
members.add(item);
},
remove(item) {
const removed = members.delete(item);
if (removed) item.destroy();
return removed;
},
},
};
return {
C,
scene,
members,
builds: () => geometryBuilds,
spheres,
visibility,
occluderBuilds: () => occluderBuilds,
owner: createWindGpuRendering({ cesium: C, getViewer: () => ({ scene }) }),
};
}
const field = () => ({
const wind = () => ({
nx: 4,
ny: 3,
lo1: -180,
@@ -152,248 +23,152 @@ const field = () => ({
v: new Float32Array(12),
});
test('GPU owner builds regional native batches; ticks update uniforms without rebuilding geometry', () => {
const h = harness();
assert.equal(h.owner.setField(field()), true);
assert.equal(h.members.size, 72);
const batch = [...h.members][0];
assert.equal(batch.allowPicking, false);
assert.equal(batch.asynchronous, true);
assert.ok(batch.appearance.vertexShaderSource.includes('v_windFacing = dot'));
assert.ok(
batch.appearance.material.source.includes(
'smoothstep(0.0, 0.065, v_windFacing)',
),
);
const builds = h.builds();
assert.equal(builds, 0, 'expanded geometry is deferred to Cesium workers');
assert.ok(
batch.appearance.vertexShaderSource.includes(
'czm_batchTable_windSeed(batchId)',
),
);
h.owner.tick(3);
assert.equal(batch.appearance.material.uniforms.phaseTime, 3);
h.owner.setOptions({ paused: true });
h.owner.tick(8);
assert.equal(batch.appearance.material.uniforms.phaseTime, 3);
h.owner.setOptions({ paused: false });
h.owner.tick(9);
assert.equal(batch.appearance.material.uniforms.phaseTime, 9);
assert.equal(h.builds(), builds);
const diagnostics = h.owner.getDiagnostics();
assert.ok(diagnostics.pathCount <= 7200);
assert.ok(
diagnostics.pathCount > 7000,
'desktop retains the requested doubled global density',
);
assert.ok(diagnostics.vertexCount > 0);
assert.ok(
diagnostics.vertexCount <= 7200 * 128,
'expanded geometry remains bounded',
);
assert.equal(diagnostics.ready, true);
assert.equal(diagnostics.displayHeightMeters, 12000);
assert.equal(diagnostics.cellCount, 72);
assert.equal(h.spheres.length, 72);
assert.equal(new Set([...h.members].map((p) => p.appearance)).size, 72);
for (const cell of h.members) {
assert.equal(cell.appearance.material, batch.appearance.material);
assert.equal(cell.appearance.material.uniforms.phaseTime, 9);
assert.equal(cell.appearance.material.uniforms.ghostAlpha, 0.25);
assert.equal(cell.compressVertices, false);
assert.equal(cell.releaseGeometryInstances, true);
}
batch.ready = false;
assert.equal(
h.owner.getDiagnostics().ready,
false,
'every cell must be ready',
);
batch.ready = true;
const instances = [...h.members].flatMap((p) => p.geometryInstances);
const baked = bakeWindStreamlines(field());
assert.equal(instances.length, baked.length);
const bySeed = new Map(
instances.map((i) => [i.attributes.windSeed.value[0], i]),
);
for (const path of baked) {
assert.deepEqual(
bySeed.get(path.seed).geometry.positions,
path.coordinates.map(([lon, lat]) =>
Cartesian3.fromDegrees(lon, lat, 12000),
),
);
}
for (const { sphere, points } of h.spheres) {
assert.deepEqual(sphere, BoundingSphere.fromPoints(points));
for (const point of points)
assert.ok(
Cartesian3.distance(point, sphere.center) <= sphere.radius + 1e-6,
);
}
for (const instance of instances) {
assert.ok(instance.geometry instanceof h.C.PolylineGeometry);
assert.equal(instance.geometry.width, 2.4);
assert.equal(instance.attributes.windSeed.componentsPerAttribute, 1);
assert.ok(Number.isInteger(instance.attributes.windSeed.value[0]));
}
// A draw port whose fields record what they were asked, a camera at
// `height` and a canvas `width` wide.
function harness({ width = 1000, height = 2_000_000, refuse = null } = {}) {
const fields = [];
const camera = { height };
const viewer = { canvas: { clientWidth: width } };
const draw = {
field(spec) {
if (refuse) throw refuse;
const listeners = [];
const handle = {
spec,
updates: [],
disposed: false,
show: true,
update(patch) {
this.updates.push(patch);
},
on(event, cb) {
assert.equal(event, 'drawn');
listeners.push(cb);
return () => {};
},
dispose() {
assert.equal(this.disposed, false, 'disposed once');
this.disposed = true;
},
tell: () => listeners.forEach((cb) => cb()),
};
fields.push(handle);
return handle;
},
};
const frames = [];
const owner = createWindGpuRendering({
getViewer: () => viewer,
drawOf: () => draw,
cameraOf: () => ({ pose: () => ({ height: camera.height }) }),
frameOf: () => ({ requestRender: (reason) => frames.push(reason) }),
});
return { owner, fields, camera, viewer, draw, frames };
}
test('the fade by camera height is none below 15 km and full from 60 km', () => {
assert.equal(windHeightFade(10_000), 0);
assert.equal(windHeightFade(15_000), 0);
assert.equal(windHeightFade(37_500), 0.5);
assert.equal(windHeightFade(60_000), 1);
assert.equal(windHeightFade(2e7), 1);
});
test('replacement, clear and destroy dispose every owned cell and the shared material', () => {
const h = harness();
const assertDisposed = (batches) => {
assert.equal(batches.length, 72);
for (const batch of batches) {
assert.equal(batch.destroyed, true);
assert.equal(batch.appearance.material.destroyed, true);
}
};
h.owner.setField(field());
const first = [...h.members];
h.owner.setField(field());
assertDisposed(first);
const second = [...h.members];
test('a wind grid becomes a windStreamlines spec over the rectangle its samples span', () => {
const field = wind();
const spec = windStreamlineSpec(field, {
id: 'w',
pathBudget: 100,
alpha: 0.5,
paused: true,
});
assert.equal(spec.kind, 'windStreamlines');
assert.deepEqual(spec.rectangle, {
west: -180,
south: -90,
east: 180,
north: 90,
});
assert.equal(spec.width, 4);
assert.equal(spec.height, 3);
assert.equal(spec.steps, WIND_PATH_STEPS);
assert.equal(spec.heightM, WIND_DISPLAY_HEIGHT_METERS);
assert.equal(spec.alpha, 0.5);
assert.equal(spec.paused, true);
assert.equal(spec.u, field.u);
assert.equal(spec.v, field.v);
const regional = windStreamlineSpec(
{ ...field, nx: 4, ny: 4, lo1: -100, la1: 50, dx: 10, dy: 10 },
{ id: 'r', pathBudget: 1 },
);
assert.deepEqual(
regional.rectangle,
{ west: -100, south: 20, east: -70, north: 50 },
'a regional grid spans its samples and does not wrap',
);
});
test('streamlines draw through the port, faded by height, paused and ready once drawn', () => {
const h = harness({ height: 37_500 });
assert.equal(h.owner.supported(), true);
assert.equal(h.owner.setField(wind()), true);
const [field] = h.fields;
assert.equal(field.spec.pathBudget, WIND_PATH_LIMIT);
assert.equal(field.spec.alpha, 0.5);
assert.equal(field.spec.paused, false);
assert.equal(h.owner.getDiagnostics().ready, false);
assert.equal(h.owner.getDiagnostics().mode, 'gpu-streamlines');
assert.equal(h.owner.getParticleCount(), WIND_PATH_LIMIT);
field.tell();
assert.equal(h.owner.getDiagnostics().ready, true);
assert.deepEqual(h.frames, ['wind'], 'a still scene draws the ready state');
assert.equal(h.owner.updateVisibility(), true);
assert.deepEqual(field.updates, [], 'an unchanged fade asks nothing');
h.camera.height = 10_000;
assert.equal(h.owner.updateVisibility(), false, 'nothing draws low down');
assert.deepEqual(field.updates, [{ alpha: 0 }]);
assert.equal(h.owner.getDiagnostics().heightFade, 0);
h.camera.height = 100_000;
assert.equal(h.owner.updateVisibility(), true);
h.owner.setOptions({ paused: true });
h.owner.setOptions({ paused: true });
h.owner.setOptions({ overlay: 'speed' });
assert.deepEqual(field.updates, [
{ alpha: 0 },
{ alpha: 1 },
{ paused: true },
]);
h.owner.setField(wind());
assert.equal(field.disposed, true, 'a new grid replaces the field');
assert.equal(h.fields[1].spec.paused, true, 'and keeps the pause');
assert.notEqual(h.fields[1].spec.id, field.spec.id);
h.owner.clear();
assertDisposed(second);
assert.equal(h.members.size, 0);
assert.equal(h.fields[1].disposed, true);
assert.equal(h.owner.getParticleCount(), 0);
assert.equal(h.owner.getDiagnostics().ready, false);
h.owner.setField(field());
const third = [...h.members];
h.owner.destroy();
assertDisposed(third);
assert.equal(h.members.size, 0);
assert.equal(h.owner.supported(), false);
assert.equal(h.owner.setField(field()), false);
});
test('unsupported or failed geometry cleanly requests the existing fallback', () => {
const missing = createWindGpuRendering({
cesium: {},
getViewer: () => ({ scene: {} }),
});
assert.equal(missing.setField(field()), false);
const h = harness();
h.C.PolylineGeometry = class {
constructor() {
throw new Error('test build failure');
}
};
assert.equal(h.owner.setField(field()), false);
assert.equal(h.members.size, 0);
assert.match(h.owner.getDiagnostics().error, /test build failure/);
assert.equal(h.owner.setField(wind()), false);
});
test('narrow canvases use a lower bounded path budget', () => {
const h = harness({ width: 390 });
assert.equal(h.owner.setField(field()), true);
assert.ok(h.owner.getParticleCount() <= 1200);
assert.ok(h.owner.getParticleCount() > 1000);
const h = harness({ width: 600 });
assert.equal(h.owner.setField(wind()), true);
assert.equal(h.fields[0].spec.pathBudget, WIND_NARROW_PATH_LIMIT);
});
test('cell visibility combines horizon, frustum and height with shared fade uniforms', () => {
const h = harness();
h.owner.setField(field());
const batches = [...h.members];
const camera = h.scene.camera;
h.visibility.horizon = (sphere) =>
h.spheres.findIndex((s) => s.sphere === sphere) % 2 === 0;
h.visibility.frustum = (sphere) =>
h.spheres.findIndex((s) => s.sphere === sphere) % 3 === 0
? Intersect.INTERSECTING
: Intersect.OUTSIDE;
assert.equal(h.owner.updateVisibility(camera), true);
assert.equal(h.owner.getDiagnostics().visibleCells, 12);
let vertices = 0;
for (let i = 0; i < batches.length; i++) {
assert.equal(batches[i].show, i % 6 === 0);
if (batches[i].show)
vertices += batches[i].geometryInstances.reduce(
(sum, p) => sum + p.geometry.positions.length * 4 - 4,
0,
);
}
assert.equal(h.owner.getDiagnostics().visibleVertexCount, vertices);
assert.equal(h.visibility.horizonTests, 72);
assert.equal(h.visibility.frustumTests, 36);
for (const [height, fade] of [
[60000, 1],
[37500, 0.5],
[15000, 0],
[1200, 0],
]) {
camera.positionCartographic.height = height;
assert.equal(h.owner.updateVisibility(camera), fade > 0);
assert.equal(h.owner.getDiagnostics().heightFade, fade);
for (const batch of batches) {
assert.equal(batch.appearance.material.uniforms.heightFade, fade);
assert.match(batch.appearance.material.source, /horizon \* heightFade/);
if (!fade) assert.equal(batch.show, false);
}
}
assert.equal(h.owner.getDiagnostics().visibleVertexCount, 0);
assert.equal(h.owner.getDiagnostics().visibleCells, 0);
assert.equal(
h.visibility.horizonTests,
216,
'zero fade skips all sphere tests',
);
assert.equal(h.visibility.frustumTests, 108);
assert.equal(
h.occluderBuilds(),
1,
'occluder is reused across camera updates',
);
});
test('real Cesium sphere culling hides far hemisphere with globe hidden and rejects a sky-facing view', () => {
const h = harness();
h.C.Occluder = Occluder;
h.owner.setField(field());
const camera = h.scene.camera;
camera.frustum = new PerspectiveFrustum({
fov: Math.PI / 3,
aspectRatio: 1.5,
near: 1,
far: 5e7,
test('a refused or missing field falls back to the canvas', () => {
const refused = harness({ refuse: new TypeError('no streamlines here') });
assert.equal(refused.owner.setField(wind()), false);
assert.equal(refused.owner.getDiagnostics().error, 'no streamlines here');
assert.equal(refused.owner.getParticleCount(), 0);
const none = createWindGpuRendering({
getViewer: () => ({}),
drawOf: () => ({}),
cameraOf: () => null,
});
assert.equal(h.owner.updateVisibility(camera), true);
const facingEarth = h.owner.getDiagnostics();
assert.ok(facingEarth.visibleCells > 0 && facingEarth.visibleCells < 72);
for (let i = 0; i < h.spheres.length; i++) {
const sphere = h.spheres[i].sphere;
if (sphere.center.x < -5e6) assert.equal([...h.members][i].show, false);
}
camera.directionWC.x = 1;
assert.equal(h.owner.updateVisibility(camera), false);
assert.equal(h.owner.getDiagnostics().visibleCells, 0);
camera.positionWC = Cartesian3.fromDegrees(180, 0, 1e7);
assert.equal(
h.owner.updateVisibility(camera),
true,
'camera position updates the owned horizon test',
);
h.owner.destroy();
});
test('a failed later cell build releases already installed cells and shared material', () => {
const h = harness();
const NativePrimitive = h.C.Primitive;
const built = [];
h.C.Primitive = class extends NativePrimitive {
constructor(options) {
if (built.length === 2) throw new Error('later cell failed');
super(options);
built.push(this);
}
};
assert.equal(h.owner.setField(field()), false);
assert.equal(h.members.size, 0);
assert.equal(built.length, 2);
for (const batch of built) {
assert.equal(batch.destroyed, true);
assert.equal(batch.appearance.material.destroyed, true);
}
assert.match(h.owner.getDiagnostics().error, /later cell failed/);
assert.equal(none.supported(), false);
assert.equal(none.setField(wind()), false);
const absent = createWindGpuRendering({ getViewer: () => null });
assert.equal(absent.supported(), false);
});