diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5f1d1211e..7bca0a38e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
## [Unreleased]
+- `gods-eye-view/application/layers` and `gods-eye-view/standalone/catalog`
+ no longer reach Cesium: the weather shells and the wind layer's colour
+ shell and flow draw through the renderer's `draw.field` (`rasterShell` and
+ `windStreamlines`, which the Cesium renderer now draws), and the wind
+ relief is the globe port's `hillshade` surface shading. The flow animates
+ as before, and still falls back to the canvas where the renderer refuses
+ it. A viewer with no renderer bound needs
+ `gods-eye-view/render/cesium/unbound` loaded once first (samehkhamis).
- `gods-eye-view/input` no longer reaches Cesium: the dispatcher takes its
pointer events from the renderer's input port and its picks from the query
port. A click's `hit`, `topHit`, `drawHit` and `drill()` hits, and
diff --git a/dev/conformance/main.js b/dev/conformance/main.js
index 2d32b806c..f577614c5 100644
--- a/dev/conformance/main.js
+++ b/dev/conformance/main.js
@@ -137,67 +137,76 @@ async function runScenes({ record = false, only } = {}) {
continue;
}
status(`${scene.id}…`);
- await drawScene(renderer, scene, ctx, async (view, capture, settle) => {
- const name = referenceName(scene.id, view.name);
- const figure = document.createElement('figure');
- $('views').append(figure);
- if (settle.state !== 'settled') {
- const detail = `${settle.state}: ${settle.blockers.join(', ')}`;
+ // A scene the renderer refuses fails alone; the others still draw.
+ try {
+ await drawScene(renderer, scene, ctx, async (view, capture, settle) => {
+ const name = referenceName(scene.id, view.name);
+ const figure = document.createElement('figure');
+ $('views').append(figure);
+ if (settle.state !== 'settled') {
+ const detail = `${settle.state}: ${settle.blockers.join(', ')}`;
+ results.push({
+ scene: scene.id,
+ view: view.name,
+ status: 'fail',
+ detail,
+ });
+ figure.innerHTML = `
${name}: ${escape(detail)}`;
+ return;
+ }
+ if (record) {
+ const res = await fetch(SAVE + name, {
+ method: 'PUT',
+ body: capture,
+ });
+ results.push({
+ scene: scene.id,
+ view: view.name,
+ status: res.ok ? 'recorded' : 'fail',
+ detail: res.ok ? undefined : `save ${res.status}`,
+ });
+ figure.innerHTML = `
${name}: recorded`;
+ return;
+ }
+ const refBlob = await reference(name);
+ if (!refBlob) {
+ results.push({
+ scene: scene.id,
+ view: view.name,
+ status: 'fail',
+ detail: 'no reference',
+ });
+ figure.innerHTML = `
${name}: no reference`;
+ return;
+ }
+ const [actual, expected] = await Promise.all([
+ pixels(capture),
+ pixels(refBlob),
+ ]);
+ const diff = new Uint8ClampedArray(actual.data.length);
+ const outcome = compareImages(actual, expected, { diff });
results.push({
scene: scene.id,
view: view.name,
- status: 'fail',
- detail,
+ status: outcome.match ? 'pass' : 'fail',
+ diffFraction: outcome.diffFraction,
+ solidPixels: outcome.solidPixels,
+ mismatchedPixels: outcome.mismatchedPixels,
+ ...(outcome.reason ? { detail: outcome.reason } : {}),
});
- figure.innerHTML = `
${name}: ${escape(detail)}`;
- return;
- }
- if (record) {
- const res = await fetch(SAVE + name, {
- method: 'PUT',
- body: capture,
- });
- results.push({
- scene: scene.id,
- view: view.name,
- status: res.ok ? 'recorded' : 'fail',
- detail: res.ok ? undefined : `save ${res.status}`,
- });
- figure.innerHTML = `
${name}: recorded`;
- return;
- }
- const refBlob = await reference(name);
- if (!refBlob) {
- results.push({
- scene: scene.id,
- view: view.name,
- status: 'fail',
- detail: 'no reference',
- });
- figure.innerHTML = `
${name}: no reference`;
- return;
- }
- const [actual, expected] = await Promise.all([
- pixels(capture),
- pixels(refBlob),
- ]);
- const diff = new Uint8ClampedArray(actual.data.length);
- const outcome = compareImages(actual, expected, { diff });
+ const diffUrl = outcome.reason
+ ? ''
+ : await toUrl(new ImageData(diff, actual.width, actual.height));
+ figure.innerHTML = `
+ ${name}: ${outcome.solidPixels} solid, ${outcome.mismatchedPixels} unexcused, ${(outcome.diffFraction * 100).toFixed(3)}% differ ${outcome.reason ?? ''}`;
+ });
+ } catch (error) {
results.push({
scene: scene.id,
- view: view.name,
- status: outcome.match ? 'pass' : 'fail',
- diffFraction: outcome.diffFraction,
- solidPixels: outcome.solidPixels,
- mismatchedPixels: outcome.mismatchedPixels,
- ...(outcome.reason ? { detail: outcome.reason } : {}),
+ status: 'fail',
+ detail: String(error?.message ?? error),
});
- const diffUrl = outcome.reason
- ? ''
- : await toUrl(new ImageData(diff, actual.width, actual.height));
- figure.innerHTML = `
- ${name}: ${outcome.solidPixels} solid, ${outcome.mismatchedPixels} unexcused, ${(outcome.diffFraction * 100).toFixed(3)}% differ ${outcome.reason ?? ''}`;
- });
+ }
}
if (record) {
// A partial recording keeps the other scenes' entries.
diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index c4476d2bd..f765849d7 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -363,9 +363,10 @@ resources and subscriptions. The globe relief helper is enabled with Wind and
released when Wind is disabled. It uses terrain vertex normals
for view-directed shading, falling back to global globe-curvature shading when
normals are unavailable; the fallback does not show local hillshade. Neither mode
-adds elevation data or represents sunlight. Relief declines to replace an
-existing globe material, restores the prior empty material only while still
-owning it, and leaves later owners intact.
+adds elevation data or represents sunlight. Relief is the globe port's
+`hillshade` surface shading: the renderer never replaces a globe material
+someone else holds (it waits until that one is gone), gives the globe back
+when Wind is disabled, and leaves later owners intact.
Source acquisition retains deadlines, body budgets, disconnect cancellation,
per-model/field singleflight caching and one-minute failure backoff. Application
catalog construction owns each instance.
diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md
index 5cbaf5e09..2b8fee12b 100644
--- a/docs/RENDERER-CONTRACT.md
+++ b/docs/RENDERER-CONTRACT.md
@@ -65,8 +65,12 @@ optional, so a renderer written before it still conforms:
one, and says how shells stack, blend and update. `FieldHandle.on('drawn')`
says once per spec or `update` that it is drawn, never while hidden. These
change `fields` itself rather than add to it, so the renderer follows
- `fields` before must follow them; only the stub lists it, and the Cesium
- adapter has no `fields` yet.
+ `fields` before must follow them. The Cesium adapter lists `fields` and
+ draws `rasterShell` and `windStreamlines`; it refuses `scalarRaster`. It
+ draws streamlines only over the whole globe: it reads the grid's samples
+ as points, the first column at `rectangle.west` and the first row at
+ `rectangle.north`, rows running south, and traces paths that wrap east
+ and west, so it refuses a grid short of 360° of longitude.
- `ModulationSector` gains `radius` and `floor` and says what it modulates:
icons, points and models dimmed toward `floor` outside the band, the map,
lines and shapes as they are, picks unchanged. Its pass is named
diff --git a/scripts/format-scope.json b/scripts/format-scope.json
index b7ca37fd3..e998893e2 100644
--- a/scripts/format-scope.json
+++ b/scripts/format-scope.json
@@ -871,6 +871,10 @@
"src/layers/weather/rendering.js",
"src/layers/weather/shellRendering.js",
"src/layers/weather/shellRendering.test.mjs",
+ "src/render/cesium/drawFields.js",
+ "src/render/cesium/drawFields.test.mjs",
+ "src/render/cesium/drawStreamlines.js",
+ "src/render/cesium/drawStreamlines.test.mjs",
"src/layers/weather/infraredAlpha.js",
"src/layers/weather/infraredAlpha.test.mjs",
"src/layers/weather/infraredImage.js",
diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json
index 08a5326bf..1a4e5ca21 100644
--- a/scripts/package-boundaries.json
+++ b/scripts/package-boundaries.json
@@ -1070,6 +1070,10 @@
"src/render/cesium/heights.js",
"src/queries/heights.js",
"src/render/cesium/draw.js",
+ "src/render/cesium/drawFields.js",
+ "src/render/cesium/drawStreamlines.js",
+ "src/layers/wind/streamlines.js",
+ "src/layers/wind/model.js",
"src/render/cesium/drawQuads.js",
"src/render/cesium/drawMeshes.js",
"src/render/cesium/drawModels.js",
@@ -1854,6 +1858,10 @@
"src/render/cesium/effects.js",
"src/render/cesium/screenModulation.js",
"src/render/cesium/draw.js",
+ "src/render/cesium/drawFields.js",
+ "src/render/cesium/drawStreamlines.js",
+ "src/layers/wind/streamlines.js",
+ "src/layers/wind/model.js",
"src/render/cesium/drawQuads.js",
"src/render/cesium/drawMeshes.js",
"src/render/cesium/drawModels.js",
@@ -3056,6 +3064,10 @@
"src/render/cesium/credits.js",
"src/render/cesium/tileRequests.js",
"src/render/cesium/draw.js",
+ "src/render/cesium/drawFields.js",
+ "src/render/cesium/drawStreamlines.js",
+ "src/layers/wind/streamlines.js",
+ "src/layers/wind/model.js",
"src/render/cesium/drawQuads.js",
"src/render/cesium/drawMeshes.js",
"src/render/cesium/drawModels.js",
@@ -3296,6 +3308,8 @@
"src/render/baseTilesets.js",
"src/render/cesium/drawHit.js",
"src/render/cesium/draw.js",
+ "src/render/cesium/drawFields.js",
+ "src/render/cesium/drawStreamlines.js",
"src/render/cesium/drawMeshes.js",
"src/render/cesium/drawQuads.js",
"src/render/cesium/drawModels.js",
@@ -4308,6 +4322,8 @@
"src/render/cesium/query.js",
"src/render/cesium/heights.js",
"src/render/cesium/draw.js",
+ "src/render/cesium/drawFields.js",
+ "src/render/cesium/drawStreamlines.js",
"src/render/cesium/drawQuads.js",
"src/render/cesium/drawMeshes.js",
"src/render/cesium/drawModels.js",
diff --git a/src/layers/weather/shellFixture.mjs b/src/layers/weather/shellFixture.mjs
index 18e5de788..6cbe9e3a8 100644
--- a/src/layers/weather/shellFixture.mjs
+++ b/src/layers/weather/shellFixture.mjs
@@ -1,4 +1,6 @@
import * as Cesium from 'cesium';
+import { createCesiumFields } from '../../render/cesium/drawFields.js';
+import { bindRenderer } from '../../render/rendererOf.js';
/** Test double for the Cesium classes a weather shell constructs. */
export function createShellCesium({ maximumTextureSize = 0 } = {}) {
@@ -154,3 +156,45 @@ export function renderShells(cesium, scene, count = 4) {
scene.postRender.emit();
}
}
+
+/**
+ * Bind to `viewer` a renderer whose draw port draws raster-shell fields
+ * with the Cesium adapter's code over these doubles, whose camera port reads
+ * the viewer's Cesium-shaped camera double (its view rectangle, `moveEnd`
+ * and height) and whose frame port runs on the scene's own events.
+ * @returns {{fields: object, unbind: () => void}}
+ */
+export function bindShellFields(viewer, cesium) {
+ const scene = viewer.scene;
+ const fields = createCesiumFields({ scene, cesium });
+ const camera = () => viewer.camera ?? scene.camera;
+ const deg = 180 / Math.PI;
+ const unbind = bindRenderer(viewer, {
+ draw: { field: (spec) => fields.field(spec) },
+ camera: {
+ pose: () => ({ height: camera()?.positionCartographic?.height }),
+ viewRectangle() {
+ const rect = camera()?.computeViewRectangle?.();
+ return rect
+ ? {
+ west: rect.west * deg,
+ south: rect.south * deg,
+ east: rect.east * deg,
+ north: rect.north * deg,
+ }
+ : null;
+ },
+ on(event, cb) {
+ if (event !== 'moveEnd') return () => {};
+ return camera()?.moveEnd?.addEventListener(cb) ?? (() => {});
+ },
+ },
+ frame: {
+ on(phase, cb) {
+ return scene[phase]?.addEventListener?.(cb) ?? (() => {});
+ },
+ requestRender: () => scene.requestRender(),
+ },
+ });
+ return { fields, unbind };
+}
diff --git a/src/layers/weather/shellRendering.js b/src/layers/weather/shellRendering.js
index 71ad2fca7..2031e88c4 100644
--- a/src/layers/weather/shellRendering.js
+++ b/src/layers/weather/shellRendering.js
@@ -1,9 +1,12 @@
-import * as Cesium from 'cesium';
-// The weather layers fly through `cameraOf`, drape through `findGlobe` and
-// read `findCamera` and `findQuery`; this module is their Cesium side, so it
-// brings the factories a viewer with no renderer bound gets those ports from.
-import '../../render/cesium/camera.js';
-import '../../render/cesium/globe.js';
+// The shell draws through the draw port's raster-shell field; its detail
+// window follows the camera port and its lift the frame port.
+import {
+ findCamera,
+ findDraw,
+ findFrame,
+ findGlobe,
+ rendererOf,
+} from '../../render/rendererOf.js';
import { acquireWeatherImage } from './infraredImage.js';
import { imageryHostStatus } from './imageryHost.js';
import { WEATHER_DETAIL_SIZE, WEATHER_IMAGE_SIZES } from './source.js';
@@ -11,12 +14,13 @@ import { msg } from '../../i18n/index.js';
/**
* The viewer's own globe imagery, as a weather imagery host: where a layer
- * drapes when the application shell names no host of its own.
- * @param {object|null|undefined} viewer A Cesium viewer.
- * @returns {{collection: object|undefined, kind: 'globe'}}
+ * drapes when the application shell names no host of its own. Its globe
+ * port's imagery stands for it, one object per port.
+ * @param {object|null|undefined} viewer The scene object the layer holds.
+ * @returns {{collection: object|null, kind: 'globe'}}
*/
export function globeImageryHost(viewer) {
- return { collection: viewer?.imageryLayers, kind: 'globe' };
+ return { collection: findGlobe(viewer)?.imagery ?? null, kind: 'globe' };
}
/** Metres above the ellipsoid. Lower shells draw first, so lightning draws last. */
@@ -29,64 +33,19 @@ export const WEATHER_SHELL_HEIGHTS = Object.freeze({
});
// Decoded canvases per renderer, full-extent and detail images alike: the shown
// frame and the warmed next frame, each full-extent and detail (four 4096×2048
-// canvases); nothing older survives them. Cesium holds the shown canvases
-// through the material uniforms in any case.
+// canvases); nothing older survives them. The renderer holds the shown
+// canvases in any case.
export const WEATHER_SHELL_CACHE_BYTES = 128 * 1024 * 1024;
const MAX_IMAGE_BYTES = 16 * 1024 * 1024;
-const MATERIAL_TYPE = 'WeatherFrame';
-// Renders after an image swap: one queues the upload, one uploads and draws, one spare.
-const UPLOAD_FRAMES = 3;
-// An empty detail window: the full-extent image shows everywhere.
-const NO_WINDOW = Object.freeze({ west: 0, south: 0, east: -1, north: -1 });
// Detail windows, in degrees.
const DETAIL_MIN_WIDTH = 6;
const DETAIL_GRID = 0.5;
-const shellHeights = new WeakMap();
// From far away Google's coarse 3D tiles rise tens of kilometres above the
// ground and hide the shells, so the shells rise with the camera: 4 m per
// kilometre of camera height, at most 60 km, in 500 m steps.
const LIFT_PER_METRE = 0.004;
const MAX_LIFT = 60_000;
const LIFT_STEP = 500;
-// Cesium binds a 1×1 white texture to an image uniform until its first upload:
-// draw nothing until the full-extent image has arrived, and sample the detail
-// image only once it has arrived. The window is west, south, east, north in the
-// full-extent image's texture coordinates.
-const MATERIAL_SOURCE = `czm_material czm_getMaterial(czm_materialInput materialInput)
-{
- czm_material material = czm_getDefaultMaterial(materialInput);
- vec2 st = materialInput.st;
- vec4 coarse = texture(image, st);
- vec2 dst = (st - window.xy) / max(window.zw - window.xy, vec2(1e-6));
- float inside = float(all(greaterThanEqual(st, window.xy)) && all(lessThanEqual(st, window.zw)));
- float useDetail = inside * step(1.5, float(detailDimensions.x));
- vec4 c = mix(coarse, texture(detail, clamp(dst, 0.0, 1.0)), useDetail);
- material.diffuse = czm_gammaCorrect(c.rgb);
- material.alpha = c.a * alpha * step(1.5, float(imageDimensions.x));
- return material;
-}
-`;
-
-function registerMaterial(cesium) {
- const cache = cesium.Material._materialCache;
- if (cache.getMaterial(MATERIAL_TYPE)) return;
- // A plain template: building the first material from a fabric would make that
- // instance Cesium's shared template and keep its last image alive.
- cache.addMaterial(MATERIAL_TYPE, {
- fabric: {
- type: MATERIAL_TYPE,
- uniforms: {
- image: cesium.Material.DefaultImageId,
- detail: cesium.Material.DefaultImageId,
- alpha: 1,
- window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 },
- },
- // Diffuse and alpha share these samples, so one source, not components.
- source: MATERIAL_SOURCE,
- },
- translucent: false,
- });
-}
const sameEdges = (a, b) =>
a.west === b.west &&
@@ -101,239 +60,31 @@ export function shellLift(cameraHeight) {
return Math.round(lift / LIFT_STEP) * LIFT_STEP;
}
-/** Keep weather shells first in the primitive collection, in ascending height:
- * higher shells draw over lower ones and other opaque content draws over both. */
-export function orderWeatherShells(primitives, primitive, height) {
- shellHeights.set(primitive, height);
- if (typeof primitives.lowerToBottom !== 'function') return;
- const shells = [];
- for (let i = 0; i < primitives.length; i++) {
- const item = primitives.get(i);
- if (shellHeights.has(item)) shells.push(item);
- }
- const ordered = [...shells].sort(
- (a, b) => shellHeights.get(a) - shellHeights.get(b),
- );
- if (ordered.every((item, i) => primitives.get(i) === item)) return;
- for (const item of ordered.reverse()) primitives.lowerToBottom(item);
-}
-
-/** One raised rectangle drawing one full-extent image and, inside a window of
- * it, an optional detail image. The owner calls destroy(). */
-export function createShellSurface({
+/**
+ * Tell `apply` the shell lift for the camera's height now and, each frame
+ * before it draws, whenever it changes.
+ * @param {object} viewer
+ * @param {(liftM: number) => void} apply
+ * @param {{cameraOf?: Function, frameOf?: Function}} [ports]
+ * @returns {() => void} Stops.
+ */
+export function followShellLift(
viewer,
- cesium,
- rectangle,
- height,
- onSettled = () => {},
-}) {
- registerMaterial(cesium);
- const scene = viewer.scene;
- const primitives = scene.primitives;
- const material = new cesium.Material({
- fabric: { type: MATERIAL_TYPE },
- translucent: false,
- });
- // Flat shading keeps the product colours independent of the viewing angle.
- const appearance = new cesium.EllipsoidSurfaceAppearance({
- aboveGround: true,
- flat: true,
- translucent: false,
- material,
- });
- // Cesium orders its translucent pass itself (weighted OIT or distance), which
- // cannot honour stacked heights. Draw in the opaque pass in scene.primitives
- // order, alpha-blended and without depth writes, so higher shells draw over
- // lower ones and nothing is hidden or picked through a shell.
- appearance.getRenderState = () => ({
- depthTest: { enabled: true },
- depthMask: false,
- blending: cesium.BlendingState.ALPHA_BLEND,
- });
- const primitive = new cesium.Primitive({
- geometryInstances: new cesium.GeometryInstance({
- geometry: new cesium.RectangleGeometry({
- rectangle,
- height,
- granularity: cesium.Math.toRadians(0.5),
- vertexFormat: cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT,
- }),
- }),
- appearance,
- asynchronous: true,
- allowPicking: false,
- });
- primitives.add(primitive);
- orderWeatherShells(primitives, primitive, height);
- // A uniform scale about the Earth's centre lifts every shell alike and keeps
- // their order.
- let lift = 0;
- const offLift = scene.preRender?.addEventListener(() => {
- const next = shellLift(scene.camera?.positionCartographic?.height);
+ apply,
+ { cameraOf = findCamera, frameOf = findFrame } = {},
+) {
+ let lift = null;
+ const read = () => {
+ const next = shellLift(cameraOf(viewer)?.pose?.().height);
if (next === lift) return;
lift = next;
- primitive.modelMatrix = cesium.Matrix4.fromUniformScale(
- 1 + lift / cesium.Ellipsoid.WGS84.maximumRadius,
- );
- });
- let image = null;
- let frames = 0;
- // The detail image, its own upload count and a window waiting for it to draw.
- let detail = null;
- let detailFrames = 0;
- let pendingWindow = null;
- let offRender = null;
- let destroyed = false;
-
- const fits = (size, value) =>
- !size || (size.x === value.width && size.y === value.height);
- const uploaded = () =>
- image !== null && fits(material.uniforms.imageDimensions, image);
- const detailDrawn = () =>
- detail !== null &&
- detailFrames === 0 &&
- fits(material.uniforms.detailDimensions, detail);
- const drawn = () =>
- primitive.ready &&
- uploaded() &&
- frames === 0 &&
- (detail === null || (detailDrawn() && pendingWindow === null));
- function appliedWindow() {
- const { x, y, z, w } = material.uniforms.window;
- return z < x ? null : { west: x, south: y, east: z, north: w };
- }
- function setWindow(rect) {
- const next = rect ?? NO_WINDOW;
- const { x, y, z, w } = material.uniforms.window;
- if (
- x === next.west &&
- y === next.south &&
- z === next.east &&
- w === next.north
- )
- return;
- material.uniforms.window = new cesium.Cartesian4(
- next.west,
- next.south,
- next.east,
- next.north,
- );
- scene.requestRender();
- }
- // The render governor may idle the scene; request frames only until the
- // asynchronous geometry is ready and the latest images have been drawn.
- function tick() {
- // Cesium updates a material only while its primitive is shown, so hidden
- // frames upload nothing and count for nothing.
- if (primitive.ready && primitive.show) {
- if (frames > 0) frames--;
- if (detailFrames > 0) detailFrames--;
- // A texture is never shown at another window's place.
- if (pendingWindow && detailDrawn()) {
- setWindow(pendingWindow);
- pendingWindow = null;
- }
- }
- if (primitive.show && !drawn()) {
- scene.requestRender();
- return;
- }
- offRender?.();
- offRender = null;
- if (drawn()) onSettled();
- }
- function wake() {
- if (destroyed || !primitive.show || image === null || drawn()) return;
- offRender ??= scene.postRender.addEventListener(tick);
- scene.requestRender();
- }
-
- return {
- setImage(next) {
- if (destroyed || next === image) return;
- image = next;
- material.uniforms.image = next;
- frames = UPLOAD_FRAMES;
- wake();
- },
- setAlpha(value) {
- if (destroyed || material.uniforms.alpha === value) return;
- material.uniforms.alpha = value;
- scene.requestRender();
- },
- /** Draw `next` inside `rect` (west, south, east, north in the full-extent
- * image's texture coordinates, 0–1); null clears it. In the same window only
- * the image changes, and Cesium keeps drawing the previous texture until
- * this one is uploaded. A different window applies once its image has
- * drawn; until then the full-extent image covers it. */
- setDetail(next, rect) {
- if (destroyed) return;
- if (!next) {
- if (detail === null) return;
- detail = null;
- detailFrames = 0;
- pendingWindow = null;
- material.uniforms.detail = cesium.Material.DefaultImageId;
- setWindow(null);
- scene.requestRender();
- return;
- }
- if (next !== detail) {
- detail = next;
- material.uniforms.detail = next;
- detailFrames = UPLOAD_FRAMES;
- }
- const applied = appliedWindow();
- if (applied && sameEdges(applied, rect)) {
- pendingWindow = null;
- } else {
- setWindow(null);
- pendingWindow = rect;
- }
- wake();
- },
- /** Returns whether visibility changed. */
- setShow(value) {
- const show = Boolean(value);
- if (destroyed || primitive.show === show) return false;
- primitive.show = show;
- wake();
- scene.requestRender();
- return true;
- },
- destroy() {
- if (destroyed) return;
- destroyed = true;
- offRender?.();
- offRender = null;
- offLift?.();
- if (!primitives.isDestroyed?.() && primitives.contains(primitive))
- primitives.remove(primitive);
- if (!primitive.isDestroyed()) primitive.destroy();
- // Primitive.destroy leaves the material and its texture alive.
- if (!material.isDestroyed()) material.destroy();
- image = null;
- detail = null;
- pendingWindow = null;
- scene.requestRender();
- },
- getDiagnostics() {
- return {
- height,
- ready: Boolean(primitive.ready),
- uploaded: uploaded(),
- show: primitive.show,
- alpha: material.uniforms.alpha,
- rendering: offRender !== null,
- // `uploaded` once the detail image has drawn; the window applies after.
- detail: { uploaded: detailDrawn(), window: appliedWindow() },
- };
- },
+ apply(next);
};
+ read();
+ return frameOf(viewer)?.on('preRender', read) ?? (() => {});
}
-function fitTexture(cesium, { width, height }) {
- const limit = cesium.ContextLimits?.maximumTextureSize;
+function fitTexture({ width, height }, limit) {
// Halve, down to 1024 px wide, on devices with a smaller texture limit.
while (limit > 0 && width > limit && width > 1024) {
width /= 2;
@@ -404,13 +155,14 @@ export function detailWindow(footprint, bounds, previous = null) {
return previous && sameEdges(previous, next) ? previous : next;
}
+let weatherShells = 0;
+
/** Observed weather on 3D Tiles: one raised shell per product and one
* full-extent image per frame. The previous image stays until the next is ready.
* Inside a window around the view the same surface samples a sharper image of
* that area, so the two images share one mesh and never blend. */
export function createWeatherShell({
viewer,
- cesium = Cesium,
product,
height = WEATHER_SHELL_HEIGHTS[product],
getHost = () => ({ collection: null, kind: 'tileset' }),
@@ -421,17 +173,35 @@ export function createWeatherShell({
decodeImage,
createCanvas = () => document.createElement('canvas'),
cacheBytes = WEATHER_SHELL_CACHE_BYTES,
+ drawOf = findDraw,
+ cameraOf = findCamera,
+ frameOf = findFrame,
+ maxTextureSize = rendererOf(viewer)?.quality?.device?.().maxTextureSize ?? 0,
}) {
if (!Object.hasOwn(WEATHER_IMAGE_SIZES, product))
throw new TypeError('Unknown weather product');
- const scene = viewer.scene;
- const size = fitTexture(cesium, WEATHER_IMAGE_SIZES[product]);
- const detailSize = fitTexture(cesium, WEATHER_DETAIL_SIZE);
+ const size = fitTexture(WEATHER_IMAGE_SIZES[product], maxTextureSize);
+ const detailSize = fitTexture(WEATHER_DETAIL_SIZE, maxTextureSize);
const infrared = product === 'clouds' || product === 'clouds-regional';
// Global infrared contrast depends on the requested extent, so a window would
// not match the image around it; the globe host also shows one mosaic.
const detailed = product !== 'clouds';
- let surface = null;
+ const requestRender = () => frameOf(viewer)?.requestRender('weather');
+ // The shell's field, and what it was last given: the committed frame's
+ // bounds and image, and the detail.
+ let field = null;
+ let offLift = null;
+ let fieldBounds = null;
+ let fieldImage = null;
+ let fieldRect = null;
+ let fieldDetail = null;
+ let fieldAlpha = 0;
+ // What its 'drawn' has told: anything yet, the image and the detail it
+ // was last given, and whether a change waits for it.
+ let everDrawn = false;
+ let imageDrawn = false;
+ let detailDrawn = false;
+ let owed = false;
let current = null;
let incoming = null;
let alpha = 0.7;
@@ -456,6 +226,72 @@ export function createWeatherShell({
`${time}|${infrared ? mode : 'none'}${box ? `|${boundsKey(box)}` : ''}`;
const wantedDetail = () =>
current && view ? cacheKey(current.time, current.infrared, view) : null;
+ const imageRef = (canvas, key) => ({ canvas, key });
+
+ function update(patch) {
+ owed = true;
+ field.update(patch);
+ }
+ function onDrawn() {
+ owed = false;
+ everDrawn = true;
+ imageDrawn = true;
+ detailDrawn = fieldDetail !== null;
+ if (incoming?.staged) commit(incoming);
+ }
+ function makeField(rectangle, image) {
+ field = drawOf(viewer).field({
+ kind: 'rasterShell',
+ id: `weather-shell:${product}:${(weatherShells += 1)}`,
+ image,
+ rectangle,
+ heightM: height,
+ alpha,
+ detail: null,
+ });
+ fieldAlpha = alpha;
+ owed = true;
+ field.on('drawn', onDrawn);
+ offLift = followShellLift(viewer, (liftM) => update({ liftM }), {
+ cameraOf,
+ frameOf,
+ });
+ }
+ function dropField() {
+ offLift?.();
+ offLift = null;
+ field?.dispose();
+ field = null;
+ fieldBounds = null;
+ fieldImage = null;
+ fieldRect = null;
+ fieldDetail = null;
+ everDrawn = false;
+ imageDrawn = false;
+ detailDrawn = false;
+ owed = false;
+ }
+ /** Give the field `next` for its detail, unless it has it already. */
+ function giveDetail(next) {
+ if (!field) return;
+ const given = incoming?.staged ? incoming.keptDetail : fieldDetail;
+ const same =
+ next === given ||
+ (next &&
+ given &&
+ next.image.canvas === given.image.canvas &&
+ sameEdges(next.rectangle, given.rectangle));
+ if (same) return;
+ // A frame being staged takes its detail once it is committed; until
+ // then the detail is what the field goes back to if it is given up.
+ if (incoming?.staged) {
+ incoming.keptDetail = next;
+ return;
+ }
+ fieldDetail = next;
+ detailDrawn = false;
+ update({ detail: next });
+ }
function evict(keep = []) {
const kept = new Set([...keep, current?.key, detail?.key]);
@@ -517,11 +353,19 @@ export function createWeatherShell({
};
}
function syncDetail() {
- if (detail && current) surface?.setDetail(detail.image, detailRect());
- else surface?.setDetail(null);
+ if (detail && current)
+ giveDetail({
+ image: imageRef(detail.image, detail.key),
+ rectangle: { ...detail.box },
+ });
+ else giveDetail(null);
}
function applyVisibility() {
- return surface?.setShow(visible()) ?? false;
+ if (!field) return false;
+ const show = visible();
+ if (field.show === show) return false;
+ field.show = show;
+ return true;
}
function cancelDetail() {
clearTimeout(detailJob?.timeout);
@@ -531,7 +375,7 @@ export function createWeatherShell({
function dropDetail() {
detail = null;
// The full-extent image covers the window in the same turn.
- surface?.setDetail(null);
+ giveDetail(null);
}
function installDetail(job, image) {
if (detailJob !== job) return;
@@ -540,14 +384,14 @@ export function createWeatherShell({
detail = { box: job.box, key: job.key, image, stale: false };
syncDetail();
evict();
- scene.requestRender();
+ requestRender();
}
function failDetail(job) {
if (detailJob !== job) return;
clearTimeout(job.timeout);
detailJob = null;
if (detail?.stale) dropDetail();
- scene.requestRender();
+ requestRender();
}
/** Bring the detail to the shown frame and window. The previous detail image
* stays until the next is decoded unless the window itself moved, and over at
@@ -585,16 +429,9 @@ export function createWeatherShell({
}
/** Recompute the window from the camera's ground footprint; returns whether it changed. */
function computeView() {
- const rectangle = detailed
- ? viewer.camera?.computeViewRectangle?.(scene.globe?.ellipsoid)
+ const footprint = detailed
+ ? (cameraOf(viewer)?.viewRectangle?.() ?? null)
: null;
- const degrees = cesium.Math.toDegrees;
- const footprint = rectangle && {
- west: degrees(rectangle.west),
- south: degrees(rectangle.south),
- east: degrees(rectangle.east),
- north: degrees(rectangle.north),
- };
const next = detailWindow(
footprint,
current.extent,
@@ -608,7 +445,7 @@ export function createWeatherShell({
function watchCamera() {
if (offCamera || !detailed) return;
offCamera =
- viewer.camera?.moveEnd?.addEventListener(() => {
+ cameraOf(viewer)?.on?.('moveEnd', () => {
if (current && computeView()) refreshDetail();
}) ?? null;
}
@@ -623,18 +460,30 @@ export function createWeatherShell({
frame.owned = true;
const abort = () => {
if (incoming === frame) cancelIncoming();
- scene.requestRender();
+ requestRender();
};
signal.addEventListener('abort', abort, { once: true });
frame.offAbort = () => signal.removeEventListener('abort', abort);
}
+ /** A staged frame given up: the field goes back to what it drew. */
+ function unstage(frame) {
+ if (!frame.staged) return;
+ frame.staged = false;
+ if (fieldBounds === null) {
+ dropField();
+ return;
+ }
+ fieldDetail = frame.keptDetail ?? null;
+ detailDrawn = false;
+ imageDrawn = false;
+ update({ image: fieldImage, rectangle: fieldRect, detail: fieldDetail });
+ }
function close(frame) {
frame.closed = true;
frame.controller.abort();
clearTimeout(frame.timeout);
frame.offAbort?.();
- frame.surface?.destroy();
- frame.surface = null;
+ unstage(frame);
}
function cancelIncoming() {
if (!incoming) return;
@@ -649,7 +498,7 @@ export function createWeatherShell({
close(frame);
lastError = msg('Weather tiles unavailable · previous frame retained');
frame.resolve(false);
- scene.requestRender();
+ requestRender();
onChange();
}
function commit(frame) {
@@ -657,12 +506,13 @@ export function createWeatherShell({
incoming = null;
clearTimeout(frame.timeout);
frame.offAbort?.();
- if (frame.surface) {
- surface?.destroy();
- surface = frame.surface;
- frame.surface = null;
- }
const { west, south, east, north } = frame.snapshot.bounds;
+ if (frame.staged) {
+ frame.staged = false;
+ fieldBounds = frame.bounds;
+ fieldRect = { west, south, east, north };
+ }
+ fieldImage = frame.image;
current = {
time: frame.time,
product: frame.product,
@@ -673,7 +523,10 @@ export function createWeatherShell({
mosaic: frame.mosaic,
loadMs: now() - frame.startedAt,
};
- surface.setAlpha(alpha);
+ if (fieldAlpha !== alpha) {
+ fieldAlpha = alpha;
+ update({ alpha });
+ }
applyVisibility();
lastError = null;
evict();
@@ -684,31 +537,35 @@ export function createWeatherShell({
if (detail?.stale && detail.key !== wantedDetail()) dropDetail();
refreshDetail();
frame.resolve(true);
- scene.requestRender();
+ requestRender();
onChange();
}
- function install(frame, image) {
+ function install(frame, texture) {
if (frame.closed || incoming !== frame) return;
- if (surface?.bounds === frame.bounds) {
- // Cesium keeps drawing the previous texture until this one is uploaded.
- surface.setImage(image);
+ frame.image = imageRef(texture, frame.key);
+ if (field && fieldBounds === frame.bounds) {
+ // The renderer keeps drawing the previous image until this one is drawn.
+ imageDrawn = false;
+ update({ image: frame.image });
commit(frame);
return;
}
- // First frame or a new extent: stage an invisible surface and keep the
- // previous one until the new geometry and texture are drawable.
+ // First frame or a new extent: the field keeps what it draws until the
+ // new rectangle and image can be drawn, then the frame commits.
const { west, south, east, north } = frame.snapshot.bounds;
- const next = createShellSurface({
- viewer,
- cesium,
- height,
- rectangle: cesium.Rectangle.fromDegrees(west, south, east, north),
- onSettled: () => commit(frame),
- });
- next.bounds = frame.bounds;
- frame.surface = next;
- next.setAlpha(0);
- next.setImage(image);
+ const rectangle = { west, south, east, north };
+ frame.staged = true;
+ imageDrawn = false;
+ if (!field) makeField(rectangle, frame.image);
+ else {
+ frame.keptDetail = fieldDetail;
+ fieldDetail = null;
+ detailDrawn = false;
+ update({ image: frame.image, rectangle, detail: null });
+ }
+ // A hidden field tells nothing drawn: the renderer readies the new
+ // content unseen and shows it, not the old, once the field shows.
+ if (!visible()) commit(frame);
}
return {
@@ -724,7 +581,7 @@ export function createWeatherShell({
computeView();
refreshDetail();
}
- if (changed) scene.requestRender();
+ if (changed) requestRender();
return changed;
},
cancelPrefetch,
@@ -799,7 +656,9 @@ export function createWeatherShell({
mosaic: { fetched: false, decodeMs: null, cached: false },
controller: new AbortController(),
startedAt: now(),
- surface: null,
+ image: null,
+ staged: false,
+ keptDetail: null,
owned: false,
closed: false,
resolve: null,
@@ -821,7 +680,7 @@ export function createWeatherShell({
install(frame, texture);
})
.catch(() => fail(frame));
- scene.requestRender();
+ requestRender();
onChange();
return frame.result;
},
@@ -834,12 +693,15 @@ export function createWeatherShell({
}
applyVisibility();
if (!hidden) refreshDetail();
- scene.requestRender();
+ requestRender();
},
setAlpha(value) {
alpha = value;
- surface?.setAlpha(alpha);
- scene.requestRender();
+ if (field && fieldAlpha !== alpha) {
+ fieldAlpha = alpha;
+ update({ alpha });
+ }
+ requestRender();
},
clear() {
cancelPrefetch();
@@ -848,8 +710,7 @@ export function createWeatherShell({
offCamera?.();
offCamera = null;
dropDetail();
- surface?.destroy();
- surface = null;
+ dropField();
current = null;
view = null;
viewBounds = null;
@@ -857,11 +718,21 @@ export function createWeatherShell({
lastError = null;
images.clear();
imageBytes = 0;
- scene.requestRender();
+ requestRender();
},
getDiagnostics() {
- const drawn = surface?.getDiagnostics();
- const applied = drawn?.detail.window;
+ // The detail is drawn once its image has drawn in its window.
+ const window =
+ current && detail && detailDrawn && fieldDetail ? detailRect() : null;
+ const drawn = field && {
+ height,
+ ready: everDrawn,
+ uploaded: imageDrawn,
+ show: field.show,
+ alpha: fieldAlpha,
+ rendering: owed && field.show,
+ detail: { uploaded: detailDrawn, window },
+ };
return {
host: 'shell',
height,
@@ -882,8 +753,8 @@ export function createWeatherShell({
drawn.ready &&
drawn.show &&
drawn.detail.uploaded &&
- applied &&
- sameEdges(applied, detailRect()),
+ window &&
+ !owed,
),
enabled: view !== null,
},
@@ -894,7 +765,7 @@ export function createWeatherShell({
bytes: imageBytes,
prefetching: !!prefetchJob,
},
- imageryCount: Number(!!surface) + Number(!!incoming?.surface),
+ imageryCount: Number(fieldBounds !== null) + Number(!!incoming?.staged),
mosaic: (incoming || current)?.mosaic,
infrared: (incoming || current)?.infrared ?? 'filtered',
loading: !!incoming,
diff --git a/src/layers/weather/shellRendering.test.mjs b/src/layers/weather/shellRendering.test.mjs
index ad65dcef2..f1f755f1c 100644
--- a/src/layers/weather/shellRendering.test.mjs
+++ b/src/layers/weather/shellRendering.test.mjs
@@ -2,16 +2,16 @@ import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
- createShellSurface,
createWeatherShell,
detailWindow,
- orderWeatherShells,
+ followShellLift,
shellLift,
WEATHER_SHELL_CACHE_BYTES,
WEATHER_SHELL_HEIGHTS,
} from './shellRendering.js';
import { NO_IMAGERY_HOST } from './imageryHost.js';
import {
+ bindShellFields,
createShellCesium,
createShellScene,
renderShells,
@@ -72,10 +72,12 @@ function harness({ product = 'radar', camera, ...options } = {}) {
const fetches = [];
const decoded = [];
let host = { collection: null, kind: 'tileset' };
+ const viewer = { scene, camera };
+ bindShellFields(viewer, cesium);
const shell = createWeatherShell({
- viewer: { scene, camera },
- cesium,
+ viewer,
product,
+ maxTextureSize: cesium.ContextLimits.maximumTextureSize,
getHost: () => host,
fetchImpl: async (url, init) => {
fetches.push({ url, signal: init.signal });
@@ -131,317 +133,36 @@ test('shell heights stack every product with lightning highest', () => {
assert.equal(WEATHER_SHELL_CACHE_BYTES, 128 * 1024 * 1024);
});
-test('surface builds a flat raised rectangle drawn in primitive order without depth writes', () => {
- const cesium = createShellCesium();
- const scene = createShellScene();
- const rectangle = Cesium.Rectangle.fromDegrees(-130, 20, -60, 55);
- const surface = createShellSurface({
- viewer: { scene },
- cesium,
- rectangle,
- height: 6_200,
- });
- const template = cesium.templates.get('WeatherFrame');
- assert.ok(!(template instanceof cesium.Material), 'plain template');
- assert.deepEqual(template.fabric.uniforms, {
- image: Cesium.Material.DefaultImageId,
- detail: Cesium.Material.DefaultImageId,
- alpha: 1,
- window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 },
- });
- const { source } = template.fabric;
- assert.match(
- source,
- /material\.alpha = c\.a \* alpha \* step\(1\.5, float\(imageDimensions\.x\)\);/,
- 'nothing draws before the full-extent image',
- );
- assert.match(
- source,
- /float useDetail = inside \* step\(1\.5, float\(detailDimensions\.x\)\);/,
- 'the detail image is sampled only once it has arrived',
- );
- assert.match(
- source,
- /all\(greaterThanEqual\(st, window\.xy\)\) && all\(lessThanEqual\(st, window\.zw\)\)/,
- );
- assert.match(
- source,
- /mix\(coarse, texture\(detail, clamp\(dst, 0\.0, 1\.0\)\), useDetail\)/,
- );
- assert.match(source, /material\.diffuse = czm_gammaCorrect\(c\.rgb\);/);
- const [primitive] = scene.primitives.items;
- const appearance = primitive.appearance;
- assert.equal(appearance.material.options.translucent, false);
- assert.deepEqual(
- { ...appearance.options, material: undefined },
- {
- aboveGround: true,
- flat: true,
- translucent: false,
- material: undefined,
- },
- );
- assert.deepEqual(appearance.getRenderState(), {
- depthTest: { enabled: true },
- depthMask: false,
- blending: Cesium.BlendingState.ALPHA_BLEND,
- });
- const geometry = primitive.options.geometryInstances.geometry.options;
- assert.equal(geometry.rectangle, rectangle);
- assert.equal(geometry.height, 6_200);
- assert.equal(geometry.granularity, Cesium.Math.toRadians(0.5));
- assert.equal(
- geometry.vertexFormat,
- Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT,
- );
- assert.equal(primitive.options.asynchronous, true);
- assert.equal(primitive.options.allowPicking, false);
- const lower = createShellSurface({
- viewer: { scene },
- cesium,
- rectangle,
- height: 5_000,
- });
- assert.equal(cesium.templates.size, 1, 'the template registers once');
- assert.deepEqual(
- scene.primitives.items.map(
- (item) => item.options.geometryInstances.geometry.options.height,
- ),
- [5_000, 6_200],
- );
- lower.destroy();
- surface.destroy();
-});
-
-test('a surface applies a new detail window only once its image has drawn; the same window swaps only the image', () => {
- const cesium = createShellCesium();
- const scene = createShellScene();
- const surface = createShellSurface({
- viewer: { scene },
- cesium,
- rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
- height: 6_200,
- });
- const [primitive] = scene.primitives.items;
- const { uniforms } = primitive.appearance.material;
- const render = (count) => renderShells(cesium, scene, count);
- const image = () => ({ width: 4096, height: 2048 });
- surface.setImage(image());
- render();
- assert.deepEqual(surface.getDiagnostics().detail, {
- uploaded: false,
- window: null,
- });
- const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 };
- const first = image();
- surface.setDetail(first, a);
- assert.equal(uniforms.detail, first);
- assert.deepEqual(windowOf(primitive), NONE, 'the full-extent image covers');
- assert.equal(scene.postRender.size, 1, 'renders until the detail has drawn');
- render(2);
- assert.deepEqual(windowOf(primitive), NONE);
- render(1);
- assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
- assert.ok(uniforms.window instanceof Cesium.Cartesian4);
- assert.deepEqual(surface.getDiagnostics().detail, {
- uploaded: true,
- window: a,
- });
- assert.equal(scene.postRender.size, 0);
-
- // A time change in the same window: Cesium keeps drawing the previous
- // texture until the new one is uploaded, so the window stays.
- const applied = uniforms.window;
- const second = image();
- surface.setDetail(second, { ...a });
- assert.equal(uniforms.detail, second);
- assert.equal(uniforms.window, applied, 'only the image is written');
- assert.equal(surface.getDiagnostics().detail.uploaded, false);
- render();
- assert.equal(surface.getDiagnostics().detail.uploaded, true);
- assert.equal(uniforms.window, applied);
- const renders = scene.renders;
- surface.setDetail(second, { ...a });
- assert.equal(scene.renders, renders, 'an unchanged detail costs nothing');
- assert.equal(scene.postRender.size, 0);
-
- // A different window empties at once and applies once its image has drawn.
- const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 };
- surface.setDetail(image(), b);
- assert.deepEqual(windowOf(primitive), NONE);
- render(2);
- assert.deepEqual(windowOf(primitive), NONE);
- render(1);
- assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 });
-
- surface.setDetail(null);
- assert.equal(uniforms.detail, Cesium.Material.DefaultImageId);
- assert.deepEqual(windowOf(primitive), NONE);
- assert.deepEqual(surface.getDiagnostics().detail, {
- uploaded: false,
- window: null,
- });
- render();
- assert.deepEqual(
- { ...uniforms.detailDimensions },
- { type: 'ivec3', x: 1, y: 1 },
- );
- // Counted renders alone are not enough: the bound texture must be this image.
- surface.setDetail(image(), a);
- for (let i = 0; i < 4; i++) scene.postRender.emit();
- assert.deepEqual(windowOf(primitive), NONE, 'still the 1×1 default');
- render(1);
- assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
- surface.destroy();
- surface.setDetail(image(), b);
- assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
- assert.equal(scene.postRender.size, 0);
-});
-
test('shells rise with the camera over coarse 3D tiles, in steps, up to 60 km', () => {
assert.equal(shellLift(undefined), 0);
assert.equal(shellLift(1_200), 0, 'city views keep the shell heights');
assert.equal(shellLift(3_000_000), 12_000);
assert.equal(shellLift(8_000_000), 32_000);
assert.equal(shellLift(18_500_000), 60_000);
- const camera = { positionCartographic: { height: 1_200 } };
- const scene = {
- primitives: new Cesium.PrimitiveCollection(),
- preRender: new Cesium.Event(),
- postRender: new Cesium.Event(),
- camera,
- requestRender() {},
- };
- const surface = createShellSurface({
- viewer: { scene },
- cesium: Cesium,
- rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
- height: 5_800,
+ let height = 1_200;
+ const preRender = new Set();
+ const lifts = [];
+ const off = followShellLift({}, (lift) => lifts.push(lift), {
+ cameraOf: () => ({ pose: () => ({ height }) }),
+ frameOf: () => ({
+ on(phase, cb) {
+ assert.equal(phase, 'preRender');
+ preRender.add(cb);
+ return () => preRender.delete(cb);
+ },
+ }),
});
- const primitive = scene.primitives.get(0);
- const identity = primitive.modelMatrix;
- scene.preRender.raiseEvent();
- assert.equal(primitive.modelMatrix, identity, 'no lift, no new matrix');
- camera.positionCartographic.height = 8_000_000;
- scene.preRender.raiseEvent();
- const radius = Cesium.Ellipsoid.WGS84.maximumRadius;
- assert.ok(
- Math.abs(primitive.modelMatrix[0] * radius - (radius + 32_000)) < 1e-3,
- );
- const lifted = primitive.modelMatrix;
- camera.positionCartographic.height = 8_010_000;
- scene.preRender.raiseEvent();
- assert.equal(primitive.modelMatrix, lifted, 'the same step keeps the matrix');
- surface.destroy();
- assert.equal(scene.preRender.numberOfListeners, 0);
-});
-
-test('real Cesium builds the two-texture material, the opaque-pass appearance and the rectangle primitive', () => {
- const scene = {
- primitives: new Cesium.PrimitiveCollection(),
- postRender: new Cesium.Event(),
- requestRender() {},
- };
- const surface = createShellSurface({
- viewer: { scene },
- cesium: Cesium,
- rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
- height: 6_600,
- });
- const cached = Cesium.Material._materialCache.getMaterial('WeatherFrame');
- assert.ok(cached && !(cached instanceof Cesium.Material));
- const primitive = scene.primitives.get(0);
- const material = primitive.appearance.material;
- assert.ok(primitive instanceof Cesium.Primitive);
- assert.equal(material.type, 'WeatherFrame');
- assert.equal(material.isTranslucent(), false);
- assert.equal(primitive.appearance.isTranslucent(), false, 'opaque pass');
- assert.equal(primitive.appearance.getRenderState().depthMask, false);
- assert.equal(
- Cesium.Appearance.prototype.getRenderState.call(primitive.appearance)
- .depthMask,
- true,
- 'the default opaque render state would write depth',
- );
- assert.deepEqual(
- [material.uniforms.imageDimensions.x, material.uniforms.detailDimensions.x],
- [1, 1],
- 'Cesium tracks both bound texture sizes',
- );
- const shader = material.shaderSource;
- for (const declaration of [
- /uniform sampler2D image_\d+;/,
- /uniform sampler2D detail_\d+;/,
- /uniform float alpha_\d+;/,
- /uniform vec4 window_\d+;/,
- /uniform ivec3 imageDimensions_\d+;/,
- /uniform ivec3 detailDimensions_\d+;/,
- ])
- assert.match(shader, declaration);
- assert.match(shader, /texture\(image_\d+, st\)/);
- assert.match(shader, /texture\(detail_\d+, clamp\(dst, 0\.0, 1\.0\)\)/);
- assert.match(shader, /lessThanEqual\(st, window_\d+\.zw\)/);
- assert.match(shader, /step\(1\.5, float\(detailDimensions_\d+\.x\)\)/);
- assert.match(
- shader,
- /material\.alpha = c\.a \* alpha_\d+ \* step\(1\.5, float\(imageDimensions_\d+\.x\)\);/,
- 'the uniform is renamed, the material field is not',
- );
- assert.match(shader, /float useDetail = inside \* step/, 'locals keep names');
- const detail = { width: 4096, height: 2048 };
- surface.setDetail(detail, { west: 0.1, south: 0.2, east: 0.3, north: 0.4 });
- assert.equal(material.uniforms.detail, detail);
- assert.deepEqual(
- [material.uniforms.window.z, material.uniforms.window.w],
- [-1, -1],
- 'no window before the image has drawn',
- );
- surface.setDetail(null);
- assert.equal(material.uniforms.detail, Cesium.Material.DefaultImageId);
- surface.setAlpha(0.4);
- assert.equal(material.uniforms.alpha, 0.4);
- surface.destroy();
- assert.equal(scene.primitives.length, 0);
- assert.equal(primitive.isDestroyed(), true);
- assert.equal(material.isDestroyed(), true);
- assert.equal(scene.postRender.numberOfListeners, 0);
-});
-
-test('shells draw first, in height order, regardless of add order', () => {
- const scene = createShellScene();
- const other = { name: 'other' };
- scene.primitives.add(other);
- const add = (name, height) => {
- const primitive = { name };
- scene.primitives.add(primitive);
- orderWeatherShells(scene.primitives, primitive, height);
- return primitive;
- };
- add('lightning', 6_600);
- add('radar', 6_200);
- add('wind', 5_000);
- const later = { name: 'later' };
- scene.primitives.add(later);
- add('regional', 5_800);
- assert.deepEqual(
- scene.primitives.items.map(({ name }) => name),
- ['wind', 'regional', 'radar', 'lightning', 'other', 'later'],
- );
- const primitives = new Cesium.PrimitiveCollection({
- destroyPrimitives: false,
- });
- const real = (name) => ({ name, update() {}, isDestroyed: () => false });
- const tileset = primitives.add(real('tileset'));
- const lightning = primitives.add(real('lightning'));
- orderWeatherShells(primitives, lightning, 6_600);
- const radar = primitives.add(real('radar'));
- orderWeatherShells(primitives, radar, 6_200);
- assert.deepEqual(
- [0, 1, 2].map((i) => primitives.get(i).name),
- ['radar', 'lightning', 'tileset'],
- 'real Cesium collection order',
- );
- assert.equal(tileset.name, 'tileset');
+ const frame = () => [...preRender].forEach((cb) => cb());
+ assert.deepEqual(lifts, [0], 'told at once');
+ frame();
+ assert.deepEqual(lifts, [0], 'no change, nothing told');
+ height = 8_000_000;
+ frame();
+ height = 8_010_000;
+ frame();
+ assert.deepEqual(lifts, [0, 32_000], 'the same step is told once');
+ off();
+ assert.equal(preRender.size, 0);
});
test('first frame stages invisibly, requests renders until drawable and then commits', async () => {
@@ -871,40 +592,6 @@ test('an unowned restage is joined by the next request for the same frame', asyn
const footprint = (west, south, east, north) => ({ west, south, east, north });
const box = (west, south, east, north) => ({ west, south, east, north });
-test('hidden frames do not count towards a pending detail window', () => {
- const cesium = createShellCesium();
- const scene = createShellScene();
- const surface = createShellSurface({
- viewer: { scene },
- cesium,
- rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
- height: 6_200,
- });
- const [primitive] = scene.primitives.items;
- const render = (count) => renderShells(cesium, scene, count);
- const image = () => ({ width: 4096, height: 2048 });
- surface.setImage(image());
- const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 };
- surface.setDetail(image(), a);
- render();
- assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
- // A different window with a same-sized image: the dimensions alone cannot
- // tell the textures apart, so only shown frames may count.
- const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 };
- surface.setDetail(image(), b);
- assert.deepEqual(windowOf(primitive), NONE);
- for (let i = 0; i < 3; i++) {
- surface.setShow(false);
- scene.postRender.emit();
- surface.setShow(true);
- }
- assert.deepEqual(windowOf(primitive), NONE, 'hidden frames counted nothing');
- render(2);
- assert.deepEqual(windowOf(primitive), NONE);
- render(1);
- assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 });
-});
-
test('detail windows are sized from the footprint, snapped to 0.5° and clamped inside the product', () => {
// max(2 × the longitude span, 6°) wide, half as tall.
assert.deepEqual(
diff --git a/src/layers/weather/weather.test.mjs b/src/layers/weather/weather.test.mjs
index d4a2a726d..cf341f31f 100644
--- a/src/layers/weather/weather.test.mjs
+++ b/src/layers/weather/weather.test.mjs
@@ -7,6 +7,7 @@ import * as Cesium from 'cesium';
import { Color, ImageryLayerCollection, GeographicTilingScheme } from 'cesium';
import { NO_IMAGERY_HOST } from './imageryHost.js';
import { createWeatherShell } from './shellRendering.js';
+import { createCesiumFields } from '../../render/cesium/drawFields.js';
import { WEATHER_IMAGERY_Z } from './imageryOrder.js';
import { fakeGlobePort } from '../../testSupport/fakeGlobePort.mjs';
import { fakeSceneFrame } from '../../testSupport/fakeCesiumScene.mjs';
@@ -222,6 +223,9 @@ function renderingHarness(options = {}) {
Credit: Cesium.Credit,
Rectangle: Cesium.Rectangle,
};
+ // The Cesium draw port's raster shells, over the doubles.
+ const fields = createCesiumFields({ scene: viewer.scene, cesium });
+ const draw = { field: (spec) => fields.field(spec) };
const rendering = createWeatherRendering({
viewer,
globeOf: () => globe,
@@ -230,7 +234,12 @@ function renderingHarness(options = {}) {
frameOf: () => frame,
toBitmap: (canvas) => canvas,
createShell: (shellOptions) =>
- createWeatherShell({ ...shellOptions, cesium }),
+ createWeatherShell({
+ ...shellOptions,
+ drawOf: () => draw,
+ cameraOf: cameraOver,
+ frameOf: () => frame,
+ }),
fetchImpl: async () => mockResponse(),
decodeImage: async () => ({ width: 2048, height: 1024, close() {} }),
createCanvas,
diff --git a/src/layers/wind/gpuRendering.js b/src/layers/wind/gpuRendering.js
index 0873fa63b..ec9ea018d 100644
--- a/src/layers/wind/gpuRendering.js
+++ b/src/layers/wind/gpuRendering.js
@@ -1,266 +1,172 @@
import {
- bakeWindStreamlines,
- groupWindPaths,
WIND_DISPLAY_HEIGHT_METERS,
- WIND_PATH_LIMIT,
WIND_NARROW_PATH_LIMIT,
+ WIND_PATH_LIMIT,
+ WIND_PATH_STEPS,
} from './streamlines.js';
+import {
+ canvasOf,
+ findCamera,
+ findDraw,
+ findFrame,
+ rendererOf,
+} from '../../render/rendererOf.js';
const WIND_FADE_LOW_METERS = 15000;
const WIND_FADE_HIGH_METERS = 60000;
+// The streamlines' colour: the ghost and the trail; the moving tip brightens it.
+const WIND_STREAMLINE_COLOR = '#80c9e6';
+const WIND_STREAMLINE_WIDTH_PX = 2.4;
-// Original material: a persistent fine curve plus a moving, tapered highlight.
-// The integer part of s identifies a path; its fractional part follows the wind.
-const FLOW_MATERIAL = `
-in float v_windFacing;
-czm_material czm_getMaterial(czm_materialInput materialInput)
-{
- czm_material material = czm_getDefaultMaterial(materialInput);
- float pathId = floor(materialInput.st.s);
- float along = fract(materialInput.st.s);
- float offset = fract((pathId + 1.0) * 0.61803398875);
- float behind = fract(phaseTime * 0.16 + offset - along);
- float tail = (1.0 - smoothstep(0.0, 0.32, behind));
- float tip = 1.0 - smoothstep(0.0, 0.045, behind);
- float ends = smoothstep(0.0, 0.055, along) * (1.0 - smoothstep(0.945, 1.0, along));
- float edge = 1.0 - smoothstep(0.26, 0.5, abs(materialInput.st.t - 0.5));
- float horizon = smoothstep(0.0, 0.065, v_windFacing);
- material.diffuse = mix(vec3(0.50, 0.79, 0.90), vec3(0.91, 0.99, 1.0), tip);
- material.alpha = (ghostAlpha + 0.64 * tail + 0.16 * tip) * ends * edge * horizon * heightFade;
- return material;
-}`;
+let fieldIds = 0;
-/** Native Cesium geometry/material owner. No animation loop or DOM ownership. */
-export function createWindGpuRendering({ cesium: C, getViewer }) {
- const cells = [];
- let occluder = null;
- let collection = null;
- let material = null;
+/** The streamline fade for a camera this high: none low down, full from 60 km. */
+export function windHeightFade(height) {
+ return Math.max(
+ 0,
+ Math.min(
+ 1,
+ (height - WIND_FADE_LOW_METERS) /
+ (WIND_FADE_HIGH_METERS - WIND_FADE_LOW_METERS),
+ ),
+ );
+}
+
+/**
+ * A wind grid as the draw port's `windStreamlines` field: samples are
+ * points, the first column at `lo1` and the first row at `la1`, rows
+ * running south; a grid that wraps the globe spans 360° of longitude.
+ */
+export function windStreamlineSpec(field, { id, pathBudget, alpha, paused }) {
+ const span = field.nx * field.dx;
+ const wraps = span >= 360 - 1e-9;
+ const west = field.lo1;
+ const north = field.la1;
+ return {
+ kind: 'windStreamlines',
+ id,
+ u: field.u,
+ v: field.v,
+ width: field.nx,
+ height: field.ny,
+ rectangle: {
+ west,
+ south: north - (field.ny - 1) * field.dy,
+ east: west + (wraps ? span : (field.nx - 1) * field.dx),
+ north,
+ },
+ pathBudget,
+ steps: WIND_PATH_STEPS,
+ style: { color: WIND_STREAMLINE_COLOR, widthPx: WIND_STREAMLINE_WIDTH_PX },
+ heightM: WIND_DISPLAY_HEIGHT_METERS,
+ alpha,
+ paused,
+ };
+}
+
+/**
+ * Streamlines through the draw port's `windStreamlines` field (capability
+ * `fields`): the renderer traces, draws, culls and animates them; this
+ * fades them by camera height and pauses them. Where the renderer has no
+ * such field, or refuses this one, `setField` answers false and the layer
+ * paints on its canvas instead. No animation loop or DOM ownership.
+ */
+export function createWindGpuRendering({
+ getViewer,
+ drawOf = findDraw,
+ cameraOf = findCamera,
+ frameOf = findFrame,
+} = {}) {
+ let handle = null;
let paused = false;
let destroyed = false;
+ let heightFade = 0;
+ let drawn = false;
const emptyDiagnostics = () => ({
pathCount: 0,
- vertexCount: 0,
buildMs: 0,
error: null,
- cellCount: 0,
- visibleCells: 0,
- visibleVertexCount: 0,
heightFade: 0,
});
let diagnostics = emptyDiagnostics();
+ const viewer = () => getViewer?.() ?? null;
function supported() {
- const scene = getViewer?.()?.scene;
- return (
- !destroyed &&
- Boolean(
- scene?.primitives &&
- C?.Primitive &&
- C?.GeometryInstance &&
- C?.GeometryInstanceAttribute &&
- C?.ComponentDatatype?.FLOAT !== undefined &&
- C?.PolylineGeometry &&
- C?.PolylineMaterialAppearance &&
- C?.Material &&
- C?.BoundingSphere?.fromPoints &&
- C?.Occluder &&
- C?.Ellipsoid?.WGS84 &&
- C?.Intersect &&
- C?.Cartesian3?.fromDegrees,
- ) &&
- (C.SceneMode?.SCENE3D === undefined ||
- scene.mode === undefined ||
- scene.mode === C.SceneMode.SCENE3D)
- );
+ const host = viewer();
+ if (destroyed || !host) return false;
+ const capabilities = rendererOf(host)?.capabilities;
+ if (capabilities && !capabilities.has('fields')) return false;
+ return typeof drawOf(host)?.field === 'function';
}
function clear() {
- for (const cell of cells) {
- collection?.remove(cell.primitive);
- if (!cell.primitive.isDestroyed?.()) cell.primitive.destroy?.();
- }
- cells.length = 0;
- occluder = null;
- collection = null;
- material?.destroy?.();
- material = null;
+ handle?.dispose();
+ handle = null;
+ drawn = false;
diagnostics = emptyDiagnostics();
}
+ function readFade() {
+ const height = cameraOf(viewer())?.pose?.().height;
+ return Number.isFinite(height) ? windHeightFade(height) : heightFade;
+ }
+
function setField(field) {
clear();
if (!supported() || !field) return false;
const started = globalThis.performance?.now?.() ?? Date.now();
+ const width = canvasOf(viewer())?.clientWidth;
+ const pathBudget =
+ width > 0 && width < 700 ? WIND_NARROW_PATH_LIMIT : WIND_PATH_LIMIT;
+ heightFade = readFade();
try {
- const width = getViewer().scene.canvas?.clientWidth;
- const budget =
- width > 0 && width < 700 ? WIND_NARROW_PATH_LIMIT : WIND_PATH_LIMIT;
- const paths = bakeWindStreamlines(field, { count: budget });
- if (!paths.length) return false;
- let vertexCount = 0;
- material = new C.Material({
- fabric: {
- type: 'GevWindStreamline',
- uniforms: {
- phaseTime: 0,
- ghostAlpha: paused ? 0.34 : 0.25,
- heightFade: 0,
- },
- source: FLOW_MATERIAL,
- },
- translucent: () => true,
- });
- const base = new C.PolylineMaterialAppearance({ material });
- // Extend the public default shader rather than duplicate Cesium's polyline
- // expansion/precision code. Explicit facing also masks the far hemisphere
- // when a scene chooses not to preserve globe depth for translucent objects.
- const source = base.vertexShaderSource;
- if (
- !/void\s+main\s*\(\s*\)/.test(source) ||
- !/v_st\.s\s*=\s*st\.s\s*;/.test(source)
- )
- throw new Error('Wind polyline shader entry unavailable');
- const seededSource = source.replace(
- /v_st\.s\s*=\s*st\.s\s*;/,
- 'v_st.s = st.s * 0.999 + czm_batchTable_windSeed(batchId);',
+ handle = drawOf(viewer()).field(
+ windStreamlineSpec(field, {
+ id: `wind-streamlines:${(fieldIds += 1)}`,
+ pathBudget,
+ alpha: heightFade,
+ paused,
+ }),
);
- const vertexShaderSource =
- `out float v_windFacing;\n${seededSource}`.replace(
- /void\s+main\s*\(\s*\)\s*\{/,
- `void main() {\nvec3 windWorld = (czm_model * vec4(position3DHigh + position3DLow, 1.0)).xyz;\nv_windFacing = dot(normalize(windWorld), normalize(czm_viewerPositionWC - windWorld));\n`,
- );
- const scene = getViewer().scene;
- collection = scene.primitives;
- // EllipsoidalOccluder only tests points. Use Cesium's sphere occluder
- // with an inscribed Earth sphere, independent of scene.globe.show.
- occluder = new C.Occluder(
- new C.BoundingSphere(
- C.Cartesian3.ZERO,
- C.Ellipsoid.WGS84.minimumRadius,
- ),
- scene.camera.positionWC,
- );
- for (const group of groupWindPaths(paths)) {
- const cellPositions = [];
- let cellVertexCount = 0;
- const instances = group.paths.map((path) => {
- const positions = path.coordinates.map(([lon, lat]) =>
- C.Cartesian3.fromDegrees(lon, lat, WIND_DISPLAY_HEIGHT_METERS),
- );
- // Pass the native description to Cesium's worker. Per-instance seed
- // attributes avoid touching the expanded vertex buffer on the UI thread.
- const geometry = new C.PolylineGeometry({
- positions,
- width: 2.4,
- arcType: C.ArcType?.NONE,
- vertexFormat: C.PolylineMaterialAppearance.VERTEX_FORMAT,
- });
- cellPositions.push(...positions);
- cellVertexCount += positions.length * 4 - 4;
- return new C.GeometryInstance({
- geometry,
- attributes: {
- windSeed: new C.GeometryInstanceAttribute({
- componentDatatype: C.ComponentDatatype.FLOAT,
- componentsPerAttribute: 1,
- value: [path.seed],
- }),
- },
- });
- });
- const appearance = new C.PolylineMaterialAppearance({
- material,
- vertexShaderSource,
- translucent: true,
- renderState: { depthTest: { enabled: true }, depthMask: false },
- });
- const primitive = new C.Primitive({
- show: false,
- geometryInstances: instances,
- appearance,
- asynchronous: true,
- allowPicking: false,
- releaseGeometryInstances: true,
- compressVertices: false,
- });
- const cell = {
- primitive,
- sphere: C.BoundingSphere.fromPoints(cellPositions),
- vertexCount: cellVertexCount,
- };
- cells.push(cell);
- collection.add(primitive);
- vertexCount += cellVertexCount;
- }
- diagnostics = {
- ...emptyDiagnostics(),
- cellCount: cells.length,
- pathCount: paths.length,
- vertexCount,
- buildMs: (globalThis.performance?.now?.() ?? Date.now()) - started,
- error: null,
- };
- return true;
} catch (error) {
- clear();
+ handle = null;
diagnostics.error =
// i18n-ignore: GPU diagnostics only; the panel never shows this field
error instanceof Error ? error.message : 'Wind geometry unavailable';
return false;
}
+ handle.on('drawn', () => {
+ drawn = true;
+ // One more frame, so a still scene shows the layer ready.
+ frameOf(viewer())?.requestRender?.('wind');
+ });
+ diagnostics = {
+ ...emptyDiagnostics(),
+ pathCount: pathBudget,
+ buildMs: (globalThis.performance?.now?.() ?? Date.now()) - started,
+ heightFade,
+ };
+ return true;
}
- // Cesium reuses its frustum culling volume and the occluder's scratch vectors.
- // This loop creates no positions, spheres, appearances or per-cell temporaries.
- function updateVisibility(camera) {
- const height = camera.positionCartographic.height;
- const heightFade = Math.max(
- 0,
- Math.min(
- 1,
- (height - WIND_FADE_LOW_METERS) /
- (WIND_FADE_HIGH_METERS - WIND_FADE_LOW_METERS),
- ),
- );
- diagnostics.heightFade = heightFade;
- if (material) material.uniforms.heightFade = heightFade;
- diagnostics.visibleCells = 0;
- diagnostics.visibleVertexCount = 0;
- let volume;
- if (heightFade > 0 && cells.length) {
- occluder.cameraPosition = camera.positionWC;
- volume = camera.frustum.computeCullingVolume(
- camera.positionWC,
- camera.directionWC,
- camera.upWC,
- );
- }
- for (let i = 0; i < cells.length; i++) {
- const cell = cells[i];
- cell.primitive.show =
- heightFade > 0 &&
- occluder.isBoundingSphereVisible(cell.sphere) &&
- volume.computeVisibility(cell.sphere) !== C.Intersect.OUTSIDE;
- if (cell.primitive.show) {
- diagnostics.visibleCells++;
- diagnostics.visibleVertexCount += cell.vertexCount;
- }
- }
- return diagnostics.visibleCells > 0 && heightFade > 0;
+ /** Fade by camera height; whether anything can draw. */
+ function updateVisibility() {
+ const fade = readFade();
+ diagnostics.heightFade = fade;
+ if (handle && fade !== heightFade) handle.update({ alpha: fade });
+ heightFade = fade;
+ return Boolean(handle) && fade > 0;
}
return {
supported,
setField,
updateVisibility,
- tick(elapsedSeconds) {
- if (material && !paused && Number.isFinite(elapsedSeconds))
- material.uniforms.phaseTime = Math.max(0, elapsedSeconds) % 10000;
- },
setOptions(options = {}) {
- if (typeof options.paused === 'boolean') paused = options.paused;
- if (material) material.uniforms.ghostAlpha = paused ? 0.34 : 0.25;
+ if (typeof options.paused !== 'boolean' || options.paused === paused)
+ return;
+ paused = options.paused;
+ handle?.update({ paused });
},
clear,
destroy() {
@@ -270,7 +176,7 @@ export function createWindGpuRendering({ cesium: C, getViewer }) {
getParticleCount: () => diagnostics.pathCount,
getDiagnostics: () => ({
...diagnostics,
- ready: cells.length > 0 && cells.every((cell) => cell.primitive.ready),
+ ready: Boolean(handle) && drawn,
mode: 'gpu-streamlines',
displayHeightMeters: WIND_DISPLAY_HEIGHT_METERS,
}),
diff --git a/src/layers/wind/gpuRendering.test.mjs b/src/layers/wind/gpuRendering.test.mjs
index 1a420e23b..0723c1711 100644
--- a/src/layers/wind/gpuRendering.test.mjs
+++ b/src/layers/wind/gpuRendering.test.mjs
@@ -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);
});
diff --git a/src/layers/wind/relief.js b/src/layers/wind/relief.js
index 5d80e3b8d..3ef1cf721 100644
--- a/src/layers/wind/relief.js
+++ b/src/layers/wind/relief.js
@@ -1,98 +1,63 @@
-// View-directed display lighting over existing terrain normals. This does not
-// represent the Sun, change terrain geometry, or supply missing elevation data.
-function reliefSource(terrainNormals) {
- const normal = terrainNormals
- ? 'vec3 normal = normalize(materialInput.normalEC);'
- : `vec3 worldPosition = (czm_inverseView * vec4(-materialInput.positionToEyeEC, 1.0)).xyz;
- vec3 geodeticNormal = normalize(worldPosition * czm_ellipsoidInverseRadii * czm_ellipsoidInverseRadii);
- vec3 normal = normalize(czm_viewRotation * geodeticNormal);`;
- return `
-czm_material czm_getMaterial(czm_materialInput materialInput)
-{
- czm_material material = czm_getDefaultMaterial(materialInput);
- ${normal}
- vec3 displayLight = normalize(vec3(-0.45, 0.55, 0.8));
- float shade = clamp((1.0 - dot(normal, displayLight)) * 0.32, 0.0, 0.28);
- material.diffuse = vec3(0.0);
- material.alpha = shade;
- return material;
-}
-`;
-}
+import { findGlobe } from '../../render/rendererOf.js';
-/** Optional, exclusive globe-material owner; no animation or source acquisition. */
-export function createWindRelief({ cesium, getViewer } = {}) {
+/** The darkest the relief shading gets, as an opacity. */
+export const WIND_RELIEF_STRENGTH = 0.28;
+
+/**
+ * View-directed display shading of the globe's relief while the wind layer
+ * shows: the globe port's `hillshade` surface shading (capability
+ * `surfaceShading`), over the terrain's own normals or, without them, the
+ * ellipsoid's curvature. It stands for no sun, changes no geometry and asks
+ * for no data. The renderer owns the material: it never takes one someone
+ * else holds, and gives it back when cleared. No animation or source
+ * acquisition.
+ */
+export function createWindRelief({ getViewer, globeOf = findGlobe } = {}) {
+ // The globe port shading for this layer, and the viewer it belongs to.
let globe = null;
- let scene = null;
- let owned = null;
- let previous = undefined;
+ let viewer = null;
let destroyed = false;
let reason = 'Not attached';
- let mode = null;
const alive = (value) => value && !value.isDestroyed?.();
- const active = () =>
- Boolean(owned && alive(globe) && globe.material === owned);
function clear() {
- const changed = active();
- if (changed) globe.material = previous;
- if (owned && !owned.isDestroyed?.()) owned.destroy?.();
- if (changed && alive(scene)) scene.requestRender?.();
- owned = null;
- mode = null;
+ if (globe && alive(viewer)) globe.setSurfaceShading(null);
globe = null;
- scene = null;
- previous = undefined;
+ viewer = null;
reason = destroyed ? 'Destroyed' : 'Not attached';
}
return {
attach() {
if (destroyed) return false;
- const viewer = getViewer?.();
- const nextScene = alive(viewer) ? viewer.scene : null;
- const nextGlobe = nextScene?.globe;
- const nextMode =
- nextGlobe?.terrainProvider?.hasVertexNormals === true
- ? 'terrain relief'
- : 'globe curvature';
- if (active() && globe === nextGlobe && mode === nextMode) return true;
+ const next = getViewer?.();
+ const port = alive(next) ? globeOf(next) : null;
+ if (globe && globe === port) return true;
clear();
- if (!alive(nextGlobe) || typeof cesium?.Material !== 'function') {
+ if (typeof port?.setSurfaceShading !== 'function') {
reason = 'Globe material unavailable';
return false;
}
- if (nextGlobe.material != null) {
- reason = 'Globe material already owned';
- return false;
- }
- // Cesium excludes normal-dependent materials without terrain normals.
- // The fallback uses existing position/ellipsoid uniforms: curvature only,
- // never an invented terrain normal or an additional provider request.
try {
- owned = new cesium.Material({
- fabric: {
- type:
- nextMode === 'terrain relief'
- ? 'GEVWindTerrainRelief'
- : 'GEVWindGlobeCurvature',
- source: reliefSource(nextMode === 'terrain relief'),
- },
- translucent: true,
+ port.setSurfaceShading({
+ kind: 'hillshade',
+ strength: WIND_RELIEF_STRENGTH,
});
- mode = nextMode;
- globe = nextGlobe;
- scene = nextScene;
- previous = globe.material;
- globe.material = owned;
- scene.requestRender?.();
- reason = null;
- return true;
} catch {
- clear();
+ // The port may hold the request even though it could not draw it;
+ // take it back so it never shows up later, after Wind is off.
+ try {
+ port.setSurfaceShading(null);
+ } catch {
+ // Nothing was kept.
+ }
reason = 'Relief material unavailable';
return false;
}
+ globe = port;
+ viewer = next;
+ reason = null;
+ return true;
},
clear,
destroy() {
@@ -102,11 +67,11 @@ export function createWindRelief({ cesium, getViewer } = {}) {
},
getDiagnostics() {
return {
- active: active(),
- reason: owned && !active() ? 'Globe material replaced' : reason,
+ active: globe !== null,
+ reason,
lighting: 'View-directed display shading',
- mode: active() ? mode : null,
- maxOpacity: 0.28,
+ mode: globe ? 'hillshade' : null,
+ maxOpacity: WIND_RELIEF_STRENGTH,
};
},
};
diff --git a/src/layers/wind/relief.test.mjs b/src/layers/wind/relief.test.mjs
index 9e1b94b33..448aee21a 100644
--- a/src/layers/wind/relief.test.mjs
+++ b/src/layers/wind/relief.test.mjs
@@ -1,101 +1,103 @@
import test from 'node:test';
import assert from 'node:assert/strict';
-import { createWindRelief } from './relief.js';
+import { createWindRelief, WIND_RELIEF_STRENGTH } from './relief.js';
-function fixture({ material = undefined, normals = true } = {}) {
- const materials = [];
- class Material {
- constructor(options) {
- this.options = options;
- this.destroyed = false;
- materials.push(this);
- }
- isDestroyed() {
- return this.destroyed;
- }
- destroy() {
- assert.equal(this.destroyed, false);
- this.destroyed = true;
- }
- }
- let renders = 0;
- const globe = { material, terrainProvider: { hasVertexNormals: normals } };
- const scene = { globe, requestRender: () => renders++ };
- const viewer = { scene };
- const relief = createWindRelief({
- cesium: { Material },
- getViewer: () => viewer,
+// A viewer whose globe port records the shading it is asked for.
+function fixture({ shading = true } = {}) {
+ const calls = [];
+ const port = (name) => ({
+ name,
+ ...(shading
+ ? {
+ setSurfaceShading(next) {
+ calls.push([name, next]);
+ },
+ }
+ : {}),
});
- return { relief, globe, scene, viewer, materials, renders: () => renders };
+ const ports = new Map();
+ const viewer = { isDestroyed: () => false };
+ ports.set(viewer, port('first'));
+ let current = viewer;
+ const relief = createWindRelief({
+ getViewer: () => current,
+ globeOf: (given) => ports.get(given) ?? null,
+ });
+ return {
+ relief,
+ calls,
+ viewer,
+ ports,
+ port,
+ use: (next) => (current = next),
+ };
}
-test('relief acquires once and restores the exact prior empty material on clear', () => {
- for (const material of [null, undefined]) {
- const f = fixture({ material });
- f.globe.material = material;
- assert.equal(f.relief.attach(), true);
- assert.equal(f.relief.attach(), true);
- assert.equal(f.materials.length, 1);
- assert.equal(f.globe.material, f.materials[0]);
- assert.equal(f.relief.getDiagnostics().active, true);
- f.relief.clear();
- assert.equal(f.globe.material, material);
- assert.equal(f.materials[0].destroyed, true);
- assert.equal(f.renders(), 2);
- f.relief.clear();
- assert.equal(f.renders(), 2);
- assert.equal(f.relief.attach(), true);
- f.relief.destroy();
- assert.equal(f.materials[1].destroyed, true);
- assert.equal(f.relief.attach(), false);
- }
-});
-
-test('pre-existing and replacement material owners are never overwritten', () => {
- const other = { name: 'other-owner' };
- const f = fixture({ material: other });
- assert.equal(f.relief.attach(), false);
- assert.equal(f.globe.material, other);
- assert.equal(f.materials.length, 0);
- f.globe.material = undefined;
+test('relief asks the globe port for hillshade once and gives it back on clear', () => {
+ const f = fixture();
assert.equal(f.relief.attach(), true);
- f.globe.material = other;
- assert.equal(f.relief.getDiagnostics().reason, 'Globe material replaced');
+ assert.equal(f.relief.attach(), true);
+ assert.deepEqual(f.calls, [
+ ['first', { kind: 'hillshade', strength: WIND_RELIEF_STRENGTH }],
+ ]);
+ assert.equal(WIND_RELIEF_STRENGTH, 0.28);
+ assert.equal(f.relief.getDiagnostics().active, true);
+ assert.equal(f.relief.getDiagnostics().maxOpacity, 0.28);
f.relief.clear();
- assert.equal(f.globe.material, other);
- assert.equal(f.materials[0].destroyed, true);
+ assert.deepEqual(f.calls.at(-1), ['first', null]);
+ f.relief.clear();
+ assert.equal(f.calls.length, 2, 'a second clear asks nothing');
+ assert.equal(f.relief.getDiagnostics().active, false);
+ assert.equal(f.relief.attach(), true);
+ f.relief.destroy();
+ assert.deepEqual(f.calls.at(-1), ['first', null]);
assert.equal(f.relief.attach(), false);
- f.relief.destroy();
- assert.equal(f.globe.material, other);
+ assert.equal(f.relief.getDiagnostics().reason, 'Destroyed');
});
-test('missing terrain normals uses curvature only and upgrades when normals exist', () => {
- const f = fixture({ normals: false });
- assert.equal(f.relief.attach(), true);
- assert.equal(f.relief.getDiagnostics().mode, 'globe curvature');
- const source = f.materials[0].options.fabric.source;
- assert.doesNotMatch(source, /normalEC|slope/);
- assert.match(source, /materialInput.positionToEyeEC/);
- assert.match(source, /czm_ellipsoidInverseRadii/);
- f.globe.terrainProvider.hasVertexNormals = true;
- assert.equal(f.relief.attach(), true);
- assert.equal(f.materials[0].destroyed, true);
- assert.equal(f.relief.getDiagnostics().mode, 'terrain relief');
- assert.match(f.materials[1].options.fabric.source, /materialInput.normalEC/);
- f.relief.destroy();
- assert.equal(f.globe.material, undefined);
+test('a globe with no surface shading, or one that refuses it, is reported', () => {
+ const f = fixture({ shading: false });
+ assert.equal(f.relief.attach(), false);
+ assert.equal(f.relief.getDiagnostics().reason, 'Globe material unavailable');
+ const refusing = fixture();
+ const asked = [];
+ refusing.ports.get(refusing.viewer).setSurfaceShading = (next) => {
+ asked.push(next);
+ if (next) throw new TypeError('no hillshade');
+ };
+ assert.equal(refusing.relief.attach(), false);
+ assert.equal(
+ refusing.relief.getDiagnostics().reason,
+ 'Relief material unavailable',
+ );
+ assert.equal(refusing.relief.getDiagnostics().active, false);
+ assert.deepEqual(
+ asked.at(-1),
+ null,
+ 'a refused request is taken back so it never shows later',
+ );
});
-test('moving to a new viewer releases the old globe and owns only the new one', () => {
+test('moving to a new viewer releases the old globe and shades only the new one', () => {
const f = fixture();
f.relief.attach();
- const old = f.globe;
- const next = { material: null, terrainProvider: { hasVertexNormals: true } };
- f.viewer.scene = { globe: next, requestRender() {} };
+ const next = { isDestroyed: () => false };
+ f.ports.set(next, f.port('second'));
+ f.use(next);
assert.equal(f.relief.attach(), true);
- assert.equal(old.material, undefined);
- assert.equal(f.materials[0].destroyed, true);
- assert.equal(next.material, f.materials[1]);
+ assert.deepEqual(f.calls, [
+ ['first', { kind: 'hillshade', strength: 0.28 }],
+ ['first', null],
+ ['second', { kind: 'hillshade', strength: 0.28 }],
+ ]);
f.relief.destroy();
- assert.equal(next.material, null);
+ assert.deepEqual(f.calls.at(-1), ['second', null]);
+});
+
+test('a destroyed viewer is never asked to give the shading back', () => {
+ const f = fixture();
+ f.relief.attach();
+ f.viewer.isDestroyed = () => true;
+ f.relief.clear();
+ assert.equal(f.calls.length, 1);
});
diff --git a/src/layers/wind/rendering.js b/src/layers/wind/rendering.js
index 21735a93e..c18f931c4 100644
--- a/src/layers/wind/rendering.js
+++ b/src/layers/wind/rendering.js
@@ -1,16 +1,19 @@
-import * as Cesium from 'cesium';
-// The renderer drapes through `findGlobe`, and the layer's inspection marker
-// reads `findQuery` and `findFrame`; a viewer with no renderer bound gets
-// those ports from the factories these modules provide.
-import '../../render/cesium/globe.js';
-import '../../render/cesium/camera.js';
import {
- createShellSurface,
+ followShellLift,
+ globeImageryHost,
WEATHER_SHELL_HEIGHTS,
} from '../weather/shellRendering.js';
import { createWindRelief } from './relief.js';
import { WEATHER_IMAGERY_Z } from '../weather/imageryOrder.js';
-import { findGlobe } from '../../render/rendererOf.js';
+import {
+ canvasOf,
+ findCamera,
+ findDraw,
+ findFrame,
+ findGlobe,
+ findQuery,
+} from '../../render/rendererOf.js';
+import { fromDegreesInto } from '../../geo/ellipsoid.js';
import { NO_IMAGERY_HOST } from '../weather/imageryHost.js';
import { msg } from '../../i18n/index.js';
import { createWindGpuRendering } from './gpuRendering.js';
@@ -63,25 +66,79 @@ function sameWind(previous, next, previousField, nextField) {
return true;
}
+let windShells = 0;
+
+/** The colour field as a raised shell over the whole globe, through the
+ * draw port's raster-shell field; it rises with the camera. */
+function createWindShell(viewer, draw, texture, alpha, ports) {
+ const seq = (windShells += 1);
+ const height = WEATHER_SHELL_HEIGHTS.wind;
+ const field = draw.field({
+ kind: 'rasterShell',
+ id: `wind-shell:${seq}`,
+ image: { canvas: texture, key: `wind-shell:${seq}` },
+ rectangle: { west: -180, south: -90, east: 180, north: 90 },
+ heightM: height,
+ alpha,
+ });
+ let shownAlpha = alpha;
+ let drawn = false;
+ let owed = true;
+ field.on('drawn', () => {
+ drawn = true;
+ owed = false;
+ });
+ const offLift = followShellLift(
+ viewer,
+ (liftM) => {
+ owed = true;
+ field.update({ liftM });
+ },
+ ports,
+ );
+ return {
+ setAlpha(value) {
+ if (value === shownAlpha) return;
+ shownAlpha = value;
+ owed = true;
+ field.update({ alpha: value });
+ },
+ setShow(value) {
+ field.show = Boolean(value);
+ },
+ destroy() {
+ offLift();
+ field.dispose();
+ },
+ getDiagnostics: () => ({
+ height,
+ ready: drawn,
+ uploaded: drawn,
+ show: field.show,
+ alpha: shownAlpha,
+ rendering: owed && field.show,
+ detail: { uploaded: false, window: null },
+ }),
+ };
+}
+
/** Globe-projected surface flow plus one owned, static colour field: globe
* imagery on the globe host, a raised shell on the 3D Tiles host. */
export function createWindRendering({
- cesium = Cesium,
container,
getViewer,
getHost: hostOf,
eventTarget = globalThis.window,
createGpuRendering = createWindGpuRendering,
globeOf = findGlobe,
+ drawOf = findDraw,
+ cameraOf = findCamera,
+ frameOf = findFrame,
+ queryOf = findQuery,
onStatusChange,
} = {}) {
// The host the shell names, else the viewer's globe imagery.
- const getHost = () =>
- hostOf?.() ?? {
- collection:
- getViewer?.()?.imageryLayers ?? getViewer?.()?.scene?.imageryLayers,
- kind: 'globe',
- };
+ const getHost = () => hostOf?.() ?? globeImageryHost(getViewer?.());
let canvas = null;
let context = null;
let snapshot = null;
@@ -106,22 +163,15 @@ export function createWindRendering({
let bounds = null;
let cameraChanged = true;
let painted = 0;
- const gpu = createGpuRendering({ cesium, getViewer });
+ const gpu = createGpuRendering({ getViewer, drawOf });
let gpuActive = false;
- let gpuVisible = false;
let reportedGpuReady = null;
let gpuNarrow = false;
- let flowTime = 0;
- const relief = createWindRelief({ cesium, getViewer });
+ const relief = createWindRelief({ getViewer, globeOf });
const signature = Array(8).fill(null);
const wind = { u: 0, v: 0 };
const before = { lon: 0, lat: 0 };
- const world =
- typeof cesium.Cartesian3 === 'function' ? new cesium.Cartesian3() : {};
- const screenA =
- typeof cesium.Cartesian2 === 'function' ? new cesium.Cartesian2() : {};
- const screenB =
- typeof cesium.Cartesian2 === 'function' ? new cesium.Cartesian2() : {};
+ const world = { x: 0, y: 0, z: 0 };
const degree = Math.PI / 180;
const hidden = () => globalThis.document?.hidden === true;
const still = () => paused || reducedMotion;
@@ -137,6 +187,19 @@ export function createWindRendering({
const viewer = getViewer?.();
return viewer && !viewer.isDestroyed?.() ? viewer : null;
};
+ const poseOf = (viewer) => cameraOf(viewer)?.pose?.() ?? null;
+ // The camera's height, or undefined where there is none (or the eye sits
+ // at the earth's centre and it is not a number).
+ const heightOf = (viewer) => {
+ const height = viewer ? poseOf(viewer)?.height : undefined;
+ return Number.isFinite(height) ? height : undefined;
+ };
+ const requestRender = (viewer) => frameOf(viewer)?.requestRender?.('wind');
+ // What a paint projects with: the query port and the eye's position.
+ const viewOf = (viewer) => ({
+ query: queryOf(viewer),
+ eye: poseOf(viewer)?.position ?? null,
+ });
function cancel() {
if (frame !== null) globalThis.cancelAnimationFrame(frame);
@@ -149,7 +212,7 @@ export function createWindRendering({
canvas &&
!hidden() &&
!still() &&
- (!gpuActive || gpuVisible) &&
+ !gpuActive &&
frame === null
)
frame = globalThis.requestAnimationFrame(draw);
@@ -160,10 +223,9 @@ export function createWindRendering({
function resize(viewer) {
const ratio = Math.min(2, globalThis.devicePixelRatio || 1);
- cssWidth =
- viewer?.scene?.canvas?.clientWidth || container?.clientWidth || 1;
- cssHeight =
- viewer?.scene?.canvas?.clientHeight || container?.clientHeight || 1;
+ const surface = canvasOf(viewer);
+ cssWidth = surface?.clientWidth || container?.clientWidth || 1;
+ cssHeight = surface?.clientHeight || container?.clientHeight || 1;
const width = Math.max(1, Math.floor(cssWidth * ratio));
const height = Math.max(1, Math.floor(cssHeight * ratio));
// Assigning even unchanged dimensions erases a real canvas.
@@ -176,16 +238,16 @@ export function createWindRendering({
return true;
}
- function checkCamera(scene) {
- const camera = scene.camera;
- const position = camera?.positionWC;
+ function checkCamera(viewer) {
+ const pose = poseOf(viewer);
+ const position = pose?.position;
const values = [
position?.x,
position?.y,
position?.z,
- camera?.heading,
- camera?.pitch,
- camera?.roll,
+ pose?.heading,
+ pose?.pitch,
+ pose?.roll,
cssWidth,
cssHeight,
];
@@ -197,16 +259,17 @@ export function createWindRendering({
return changed;
}
- function updateBounds(scene) {
+ function updateBounds(viewer) {
bounds = null;
- if (!scene.camera?.computeViewRectangle || !cesium.Ellipsoid) return;
+ const camera = cameraOf(viewer);
+ if (!camera?.viewRectangle) return;
try {
- const rect = scene.camera.computeViewRectangle(cesium.Ellipsoid.WGS84);
+ const rect = camera.viewRectangle();
if (!rect) return;
- const west = rect.west / degree;
- let east = rect.east / degree;
- const south = Math.max(-89, rect.south / degree);
- const north = Math.min(89, rect.north / degree);
+ const west = rect.west;
+ let east = rect.east;
+ const south = Math.max(-89, rect.south);
+ const north = Math.min(89, rect.north);
if (east < west) east += 360;
if (
[west, east, south, north].every(Number.isFinite) &&
@@ -224,34 +287,12 @@ export function createWindRendering({
}
}
- function makeOccluder(scene) {
- if (
- !cesium.EllipsoidalOccluder ||
- !cesium.Ellipsoid ||
- !scene.camera?.positionWC
- )
+ function project(view, lon, lat) {
+ if (!Number.isFinite(lon) || !Number.isFinite(lat) || !view.query)
return null;
- return new cesium.EllipsoidalOccluder(
- cesium.Ellipsoid.WGS84,
- scene.camera.positionWC,
- );
- }
-
- function project(scene, occluder, lon, lat, result) {
- if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null;
- const point = cesium.Cartesian3.fromDegrees(
- lon,
- lat,
- 0,
- cesium.Ellipsoid?.WGS84,
- world,
- );
- if (occluder && !occluder.isPointVisible(point)) return null;
- const projected = cesium.SceneTransforms.worldToWindowCoordinates(
- scene,
- point,
- result,
- );
+ const point = fromDegreesInto(lon, lat, 0, world);
+ if (view.eye && view.query.isOccluded?.(point)) return null;
+ const projected = view.query.project(point);
if (
!projected ||
!Number.isFinite(projected.x) ||
@@ -259,7 +300,7 @@ export function createWindRendering({
)
return null;
// A perspective surface normal dims the limb instead of accumulating a bright rim.
- const camera = scene.camera?.positionWC;
+ const camera = view.eye;
const dx = camera?.x - point.x;
const dy = camera?.y - point.y;
const dz = camera?.z - point.z;
@@ -281,7 +322,7 @@ export function createWindRendering({
point.x <= cssWidth &&
point.y <= cssHeight;
- function spawn(particle, scene, occluder) {
+ function spawn(particle, view) {
for (let attempt = 0; attempt < 6; attempt++) {
const west = bounds?.west ?? -180;
const east = bounds?.east ?? 180;
@@ -291,17 +332,16 @@ export function createWindRendering({
particle.lat = Math.asin(low + Math.random() * (high - low)) / degree;
particle.age = 1 + Math.random() * 7;
particle.life = 8 + Math.random() * 4;
- if (inView(project(scene, occluder, particle.lon, particle.lat, screenA)))
- return;
+ if (inView(project(view, particle.lon, particle.lat))) return;
}
}
- function seed(scene, occluder) {
+ function seed(viewer, view = viewOf(viewer)) {
const count = budget();
if (particles.length > count) particles.length = count;
while (particles.length < count)
particles.push({ lon: 0, lat: 0, age: 0, life: 10 });
- updateBounds(scene);
- for (const particle of particles) spawn(particle, scene, occluder);
+ updateBounds(viewer);
+ for (const particle of particles) spawn(particle, view);
}
function removeImagery() {
@@ -313,16 +353,15 @@ export function createWindRendering({
shell = null;
imageryKind = null;
}
- function updateImageryFade(camera, settled = false) {
+ function updateImageryFade(height, settled = false) {
// The tileset shell keeps the quantised move-end fade; globe imagery keeps
// its smooth per-frame fade.
if (
(!imagery && !shell) ||
- !camera?.positionCartographic ||
+ !Number.isFinite(height) ||
(imageryKind === 'tileset' && !settled)
)
return;
- const height = camera.positionCartographic.height;
const fade = !gpuActive
? 1
: height <= WIND_FIELD_FADE_LOW_METERS
@@ -362,7 +401,8 @@ export function createWindRendering({
imageryError = fieldUnavailableText(overlay);
return;
}
- if (kind === 'tileset' ? !cesium.Primitive : !globe) {
+ const draw = kind === 'tileset' ? drawOf(viewer) : null;
+ if (kind === 'tileset' ? !draw?.field : !globe) {
imageryError = msg('Globe imagery unavailable');
return;
}
@@ -375,17 +415,16 @@ export function createWindRendering({
pixels.data.set(raster.rgba);
ctx.putImageData(pixels, 0, 0);
if (kind === 'tileset') {
- shell = createShellSurface({
+ shell = createWindShell(
viewer,
- cesium,
- rectangle: cesium.Rectangle.MAX_VALUE,
- height: WEATHER_SHELL_HEIGHTS.wind,
- });
- shell.setImage(texture);
+ draw,
+ texture,
+ overlay === 'temperature' ? 1 : 0.85,
+ { cameraOf, frameOf },
+ );
imageryKind = kind;
- shell.setAlpha(overlay === 'temperature' ? 1 : 0.85);
- updateImageryFade(viewer.scene.camera, true);
- viewer.scene?.requestRender?.();
+ updateImageryFade(heightOf(viewer), true);
+ requestRender(viewer);
return;
}
imagery = globe.imagery.add({
@@ -399,11 +438,11 @@ export function createWindRendering({
// Temperature colors carry quantitative meaning; double transparency
// blends orange heat into blue ocean and obscures useful gradients.
imagery.alpha = overlay === 'temperature' ? 1 : 0.85;
- if (gpuActive) updateImageryFade(viewer.scene.camera, true);
+ if (gpuActive) updateImageryFade(heightOf(viewer), true);
imageryErrorRemove = imagery.on('tileError', () => {
imageryError = msg('Globe field image unavailable');
});
- viewer.scene?.requestRender?.();
+ requestRender(viewer);
} catch {
removeImagery();
imageryError = msg('Globe field image unavailable');
@@ -426,10 +465,10 @@ export function createWindRendering({
const show = kind !== 'none' && imagery?.alpha > 0;
if (imagery && imagery.show !== show) {
imagery.show = show;
- viewerReady()?.scene?.requestRender?.();
+ requestRender(viewerReady());
}
if ((gpuActive || kind === 'tileset') && kind !== 'none')
- updateImageryFade(viewerReady()?.scene?.camera, true);
+ updateImageryFade(heightOf(viewerReady()), true);
if (kind === 'none') imageryError = NO_IMAGERY_HOST;
else if (wasHidden) {
imageryError = null;
@@ -442,39 +481,33 @@ export function createWindRendering({
function viewChanged() {
if (gpuActive) {
const viewer = viewerReady();
- if (viewer) updateImageryFade(viewer.scene.camera);
- const narrow = (viewer?.scene?.canvas?.clientWidth || 800) < 700;
+ if (viewer) updateImageryFade(heightOf(viewer));
+ const narrow = (canvasOf(viewer)?.clientWidth || 800) < 700;
let visibilityUpdated = false;
if (running && field && !hidden() && narrow !== gpuNarrow) {
gpuNarrow = narrow;
gpuActive = gpu.setField(field);
if (!gpuActive && viewer) {
resize(viewer);
- seed(viewer.scene, makeOccluder(viewer.scene));
+ seed(viewer);
}
motionChanged();
visibilityUpdated = true;
}
- if (gpuActive && viewer && !visibilityUpdated) {
- gpuVisible = gpu.updateVisibility(viewer.scene.camera);
- if (gpuVisible) schedule();
- else {
- cancel();
- lastTime = null;
- }
- }
+ // The renderer culls and animates the streamlines; this fades them.
+ if (gpuActive && viewer && !visibilityUpdated) gpu.updateVisibility();
const ready = gpuActive ? gpu.getDiagnostics().ready : null;
if (ready !== reportedGpuReady) {
reportedGpuReady = ready;
onStatusChange?.();
}
- return; // Cesium projects persistent curves; only a responsive budget change rebuilds them.
+ return; // The renderer projects persistent curves; only a responsive budget change rebuilds them.
}
if (!running || !field || hidden() || !canvas) return;
const viewer = viewerReady();
if (!viewer) return;
const resized = resize(viewer);
- if (resized || checkCamera(viewer.scene)) {
+ if (resized || checkCamera(viewer)) {
cameraChanged = true;
if (still()) paint(viewer, 0, true);
else schedule();
@@ -489,13 +522,8 @@ export function createWindRendering({
if (!running || !field || hidden()) return;
const viewer = viewerReady();
if (gpuActive) {
- if (viewer) updateImageryFade(viewer.scene.camera);
- gpuVisible = viewer ? gpu.updateVisibility(viewer.scene.camera) : false;
- if (gpuVisible) {
- gpu.tick(flowTime);
- viewer.scene.requestRender();
- schedule();
- }
+ if (viewer) updateImageryFade(heightOf(viewer));
+ if (viewer) gpu.updateVisibility();
return;
}
if (still() && viewer) paint(viewer, 0, true);
@@ -508,23 +536,18 @@ export function createWindRendering({
}
function cameraSettled() {
if (gpuActive || imageryKind === 'tileset')
- updateImageryFade(viewerReady()?.scene?.camera, true);
+ updateImageryFade(heightOf(viewerReady()), true);
cameraMoved();
}
function cameraMoved() {
viewChanged();
// A parked request-render scene may never run preRender until we wake it.
if (gpuActive && running && field && !hidden())
- viewerReady()?.scene?.requestRender?.();
+ requestRender(viewerReady());
}
- function listenScene(event, callback) {
- if (!event?.addEventListener) return;
- const remove = event.addEventListener(callback);
- removers.push(
- typeof remove === 'function'
- ? remove
- : () => event.removeEventListener(callback),
- );
+ function listenPort(port, event, callback) {
+ const off = port?.on?.(event, () => callback());
+ if (typeof off === 'function') removers.push(off);
}
function attachListeners() {
if (removers.length) return;
@@ -535,9 +558,9 @@ export function createWindRendering({
listen(globalThis, 'resize', cameraMoved);
listen(eventTarget, 'gev:map-stack-changed', rehome);
const viewer = viewerReady();
- const camera = viewer?.scene?.camera;
- listenScene(viewer?.scene?.preRender, viewChanged);
- listenScene(camera?.moveEnd, cameraSettled);
+ if (!viewer) return;
+ listenPort(frameOf(viewer), 'preRender', viewChanged);
+ listenPort(cameraOf(viewer), 'moveEnd', cameraSettled);
}
function detachListeners() {
for (const remove of removers) remove();
@@ -546,16 +569,15 @@ export function createWindRendering({
}
function paint(viewer, dt, staticFrame, fadeSeconds = dt) {
- const scene = viewer.scene;
const resized = resize(viewer);
- const changed = checkCamera(scene) || cameraChanged || resized;
- const occluder = makeOccluder(scene);
+ const changed = checkCamera(viewer) || cameraChanged || resized;
+ const view = viewOf(viewer);
if (changed) {
clearPixels();
- updateBounds(scene);
+ updateBounds(viewer);
cameraChanged = false;
}
- if (particles.length !== budget()) seed(scene, occluder);
+ if (particles.length !== budget()) seed(viewer, view);
if (staticFrame) clearPixels();
context.globalAlpha = 1;
context.globalCompositeOperation = 'destination-out';
@@ -563,7 +585,7 @@ export function createWindRendering({
context.fillRect(0, 0, cssWidth, cssHeight);
context.globalCompositeOperation = 'source-over';
context.lineCap = 'round';
- const cameraHeight = scene.camera?.positionCartographic?.height ?? 1e6;
+ const cameraHeight = heightOf(viewer) ?? 1e6;
const speedScale = Math.max(0.002, Math.min(4000, cameraHeight / 400));
const advection = { speedScale };
// Stroke length is a display sample of the local field, not frame travel.
@@ -577,27 +599,21 @@ export function createWindRendering({
advectParticle(particle, wind, dt, advection);
particle.age += dt;
}
- let point = project(scene, occluder, particle.lon, particle.lat, screenB);
+ let point = project(view, particle.lon, particle.lat);
if (changed && !inView(point)) {
// Refill newly exposed regions while retaining world anchors still in view.
- spawn(particle, scene, occluder);
+ spawn(particle, view);
sampleWind(field, particle.lon, particle.lat, wind);
- point = project(scene, occluder, particle.lon, particle.lat, screenB);
+ point = project(view, particle.lon, particle.lat);
}
if (particle.age > particle.life || !inView(point)) {
- spawn(particle, scene, occluder);
+ spawn(particle, view);
continue;
}
before.lon = particle.lon;
before.lat = particle.lat;
advectParticle(before, wind, -strokeSeconds, advection);
- const previous = project(
- scene,
- occluder,
- before.lon,
- before.lat,
- screenA,
- );
+ const previous = project(view, before.lon, before.lat);
if (!inView(previous)) continue;
const startX = previous.x;
const startY = previous.y;
@@ -653,26 +669,17 @@ export function createWindRendering({
function draw(time) {
frame = null;
- if (!running || !field || hidden() || still()) return;
- if (gpuActive && !gpuVisible) {
- lastTime = null;
- return;
- }
+ if (!running || !field || hidden() || still() || gpuActive) return;
const viewer = viewerReady();
if (!viewer) return;
try {
- const resized = !gpuActive && resize(viewer);
+ const resized = resize(viewer);
if (resized) cameraChanged = true;
const elapsed =
lastTime === null ? 1 / 60 : Math.max(0, (time - lastTime) / 1000);
// Limit full particle paints to 30 Hz while preserving elapsed-time motion/fading.
if (lastTime === null || elapsed >= 0.032 || cameraChanged) {
- if (gpuActive) {
- flowTime += elapsed;
- gpu.tick(flowTime);
- viewer.scene.requestRender();
- cameraChanged = false;
- } else paint(viewer, Math.min(0.1, elapsed), false, elapsed);
+ paint(viewer, Math.min(0.1, elapsed), false, elapsed);
lastTime = time;
}
} catch (error) {
@@ -705,7 +712,7 @@ export function createWindRendering({
? { ...next.grid, u: next.u, v: next.v }
: next;
const viewer = viewerReady();
- const nextNarrow = (viewer?.scene?.canvas?.clientWidth || 800) < 700;
+ const nextNarrow = (canvasOf(viewer)?.clientWidth || 800) < 700;
const reuseGeometry =
gpuActive &&
gpuNarrow === nextNarrow &&
@@ -721,13 +728,12 @@ export function createWindRendering({
if (!reuseGeometry) {
gpuActive = gpu.supported() && gpu.setField(field);
reportedGpuReady = gpuActive ? gpu.getDiagnostics().ready : null;
- flowTime = 0;
}
clearPixels();
particles = [];
if (viewer && !gpuActive) {
resize(viewer);
- seed(viewer.scene, makeOccluder(viewer.scene));
+ seed(viewer);
}
installImagery();
relief.attach();
@@ -775,9 +781,7 @@ export function createWindRendering({
gpu.clear();
relief.clear();
gpuActive = false;
- gpuVisible = false;
reportedGpuReady = null;
- flowTime = 0;
removeImagery();
imageryError = null;
clearPixels();
diff --git a/src/layers/wind/rendering.test.mjs b/src/layers/wind/rendering.test.mjs
index f34825527..0976da15e 100644
--- a/src/layers/wind/rendering.test.mjs
+++ b/src/layers/wind/rendering.test.mjs
@@ -1,14 +1,15 @@
import test from 'node:test';
import assert from 'node:assert/strict';
-import * as Cesium from 'cesium';
-
import { createWindRendering } from './rendering.js';
import { NO_IMAGERY_HOST } from '../weather/imageryHost.js';
import { WEATHER_IMAGERY_Z } from '../weather/imageryOrder.js';
import {
createShellCesium,
createShellScene,
+ renderShells,
} from '../weather/shellFixture.mjs';
+import { createCesiumFields } from '../../render/cesium/drawFields.js';
+import { toLonLatH } from '../../geo/ellipsoid.js';
function event() {
const listeners = new Set();
@@ -177,6 +178,7 @@ function harness({
const viewer = {
container,
imageryLayers,
+ canvas,
scene: {
canvas,
camera: {
@@ -197,34 +199,49 @@ function harness({
},
isDestroyed: () => false,
};
- const cesium = {
- ...(shell ? createShellCesium() : {}),
- GeographicTilingScheme: Cesium.GeographicTilingScheme,
- Credit: Cesium.Credit,
- Event: Cesium.Event,
- Cartesian3: { fromDegrees: (lon, lat) => ({ lon, lat }) },
- Ellipsoid: { WGS84: {} },
- Rectangle: { MAX_VALUE: {} },
- EllipsoidalOccluder: class {
- isPointVisible() {
- return !occluded;
- }
- },
- SceneTransforms: {
- worldToWindowCoordinates: projected ?? (() => ({ x: 100, y: 100 })),
- },
- SingleTileImageryProvider: class {
- constructor(options) {
- this.options = options;
- this.errorEvent = event();
- }
+ const shellCesium = shell ? createShellCesium() : null;
+ // The camera, frame and query ports over the doubles above, read live.
+ const cameraPort = {
+ pose() {
+ const camera = viewer.scene.camera;
+ return {
+ position: camera.positionWC,
+ heading: camera.heading,
+ pitch: camera.pitch,
+ roll: camera.roll,
+ height: camera.positionCartographic?.height,
+ };
},
+ viewRectangle: () => viewer.scene.camera.viewRectangle?.() ?? null,
+ on: (name, cb) =>
+ name === 'moveEnd'
+ ? viewer.scene.camera.moveEnd.addEventListener(cb)
+ : () => {},
};
+ const framePort = {
+ on: (name, cb) =>
+ name === 'preRender' ? preRender.addEventListener(cb) : () => {},
+ requestRender: () => viewer.scene.requestRender(),
+ };
+ // Projections see the point as degrees, as the doubles above were written.
+ const project = projected ?? (() => ({ x: 100, y: 100 }));
+ const queryPort = {
+ isOccluded: () => occluded,
+ project: (point) => project(viewer.scene, toLonLatH(point)),
+ };
+ const fields = shellCesium
+ ? createCesiumFields({ scene: viewer.scene, cesium: shellCesium })
+ : null;
+ const draw = fields && { field: (spec) => fields.field(spec) };
const rendering = createWindRendering({
- cesium,
container,
getViewer: () => viewer,
globeOf: (given) => (given === viewer ? globe : null),
+ // The Cesium draw port's raster shells, over the doubles.
+ drawOf: (given) => (given === viewer ? draw : null),
+ cameraOf: (given) => (given === viewer ? cameraPort : null),
+ frameOf: (given) => (given === viewer ? framePort : null),
+ queryOf: (given) => (given === viewer ? queryPort : null),
createGpuRendering,
onStatusChange,
getHost,
@@ -245,7 +262,7 @@ function harness({
motion,
preRender,
viewer,
- cesium,
+ cesium: shellCesium,
imagery,
removed,
primitives: () => shellScene?.primitives.items ?? [],
@@ -444,11 +461,11 @@ test('scalar imagery builds once, survives pause, replaces cleanly, and releases
for (const overlay of ['speed', 'pressure', 'temperature']) {
test(`${overlay} imagery fades with log camera height and resumes from idle`, () => {
+ let camera = null;
const gpu = {
supported: () => true,
setField: () => true,
- updateVisibility: (camera) => camera.positionCartographic.height > 15000,
- tick() {},
+ updateVisibility: () => camera.positionCartographic.height > 15000,
setOptions() {},
clear() {},
destroy() {},
@@ -456,7 +473,7 @@ for (const overlay of ['speed', 'pressure', 'temperature']) {
getDiagnostics: () => ({ ready: true }),
};
const h = harness({ createGpuRendering: () => gpu });
- const camera = h.viewer.scene.camera;
+ camera = h.viewer.scene.camera;
const baseAlpha = overlay === 'temperature' ? 1 : 0.85;
const snapshot = {
grid: FIELD,
@@ -586,11 +603,11 @@ test('a large camera move immediately refills the newly visible region', () => {
y: 300 + point.lat * 20,
}),
});
- h.viewer.scene.camera.computeViewRectangle = () => ({
- west: ((center - 10) * Math.PI) / 180,
- east: ((center + 10) * Math.PI) / 180,
- south: (-10 * Math.PI) / 180,
- north: (10 * Math.PI) / 180,
+ h.viewer.scene.camera.viewRectangle = () => ({
+ west: center - 10,
+ east: center + 10,
+ south: -10,
+ north: 10,
});
h.rendering.attach();
h.rendering.setField(FIELD);
@@ -615,11 +632,11 @@ test('world-anchored wind glyphs remain readable at low FPS without accelerating
y: 300 + point.lat * 20,
}),
});
- h.viewer.scene.camera.computeViewRectangle = () => ({
- west: (-5 * Math.PI) / 180,
- east: (5 * Math.PI) / 180,
- south: (-0.001 * Math.PI) / 180,
- north: (0.001 * Math.PI) / 180,
+ h.viewer.scene.camera.viewRectangle = () => ({
+ west: -5,
+ east: 5,
+ south: -0.001,
+ north: 0.001,
});
h.rendering.attach();
h.rendering.setField(FIELD);
@@ -664,11 +681,11 @@ test('world-anchored wind glyphs remain readable at low FPS without accelerating
h.rendering.destroy();
});
-test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pauses cleanly', () => {
+test('GPU flow leaves animation to the renderer, rebuilds only across viewport budgets, and pauses cleanly', () => {
let builds = 0,
- ticks = 0,
cleared = 0,
destroyed = 0;
+ const options = [];
const gpu = {
supported: () => true,
updateVisibility: () => true,
@@ -677,10 +694,9 @@ test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pa
builds++;
return true;
},
- tick() {
- ticks++;
+ setOptions(value) {
+ options.push(value.paused);
},
- setOptions() {},
clear() {
cleared++;
},
@@ -691,16 +707,12 @@ test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pa
getDiagnostics: () => ({ ready: true, pathCount: 1 }),
};
const h = harness({ createGpuRendering: () => gpu });
- let renders = 0;
- h.viewer.scene.requestRender = () => {
- renders++;
- };
h.rendering.attach();
h.rendering.setField({ grid: FIELD, u: FIELD.u, v: FIELD.v });
h.rendering.start();
- h.callbacks.shift()(16);
assert.equal(h.rendering.getDiagnostics().renderMode, 'gpu-streamlines');
- assert.ok(ticks > 0 && renders > 0);
+ assert.equal(h.pending.size, 0, 'the renderer moves the highlight');
+ assert.equal(options.at(-1), false);
assert.equal(h.strokes.length, 0);
h.viewer.scene.camera.positionWC.x = 10;
h.preRender.emit();
@@ -710,7 +722,7 @@ test('GPU flow uses one scheduler, rebuilds only across viewport budgets, and pa
'camera changes project geometry without rebuilding paths',
);
h.rendering.setOptions({ paused: true });
- assert.equal(h.pending.size, 0);
+ assert.equal(options.at(-1), true, 'the pause reaches the renderer');
h.canvas.clientWidth = 390;
h.preRender.emit();
assert.equal(builds, 2, 'crossing the narrow viewport boundary rebakes once');
@@ -735,7 +747,6 @@ for (const paused of [false, true]) {
ready = false;
return true;
},
- tick() {},
setOptions() {},
clear() {},
destroy() {},
@@ -787,9 +798,8 @@ for (const paused of [false, true]) {
});
}
-test('scalar snapshots retain identical GPU wind geometry and animation phase', () => {
+test('scalar snapshots retain identical GPU wind geometry, and so its animation phase', () => {
let builds = 0;
- const times = [];
const gpu = {
supported: () => true,
updateVisibility: () => true,
@@ -797,9 +807,6 @@ test('scalar snapshots retain identical GPU wind geometry and animation phase',
builds++;
return true;
},
- tick(time) {
- times.push(time);
- },
setOptions() {},
clear() {},
destroy() {},
@@ -824,9 +831,6 @@ test('scalar snapshots retain identical GPU wind geometry and animation phase',
h.rendering.attach();
h.rendering.setField(snapshot());
h.rendering.start();
- h.callbacks.shift()(16);
- h.callbacks.shift()(1016);
- const phase = times.at(-1);
h.rendering.setOptions({ overlay: 'temperature' });
h.rendering.setField(
snapshot({
@@ -843,11 +847,6 @@ test('scalar snapshots retain identical GPU wind geometry and animation phase',
'freshly decoded equal arrays reuse the worker-built primitive',
);
assert.equal(h.imagery.length, 1, 'new scalar field is still installed');
- h.callbacks.shift()(1032);
- assert.ok(
- times.at(-1) >= phase,
- 'scalar acquisition does not reset travelling highlights',
- );
h.rendering.setField(
snapshot({
scalar: {
@@ -890,7 +889,6 @@ for (const [label, change] of Object.entries({
builds++;
return true;
},
- tick() {},
setOptions() {},
clear() {},
destroy() {},
@@ -918,25 +916,25 @@ for (const [label, change] of Object.entries({
}
for (const eventName of ['preRender', 'moveEnd']) {
- test(`GPU height suspension resumes from camera ${eventName} without preRender`, () => {
- const times = [];
+ test(`GPU height fade follows camera ${eventName} with no frames of its own`, () => {
let visible = false;
- let inFrustum = true;
+ let fades = 0;
+ const options = [];
const gpu = {
supported: () => true,
setField: () => true,
- updateVisibility(camera) {
- visible = camera.positionCartographic.height > 15000 && inFrustum;
+ updateVisibility() {
+ fades++;
+ visible = camera.positionCartographic.height > 15000;
return visible;
},
- tick(time) {
- times.push(time);
+ setOptions(value) {
+ options.push(value.paused);
},
- setOptions() {},
clear() {},
destroy() {},
getParticleCount: () => 1,
- getDiagnostics: () => ({ ready: true, visibleCells: Number(visible) }),
+ getDiagnostics: () => ({ ready: true }),
};
const h = harness({ createGpuRendering: () => gpu });
const camera = h.viewer.scene.camera;
@@ -949,52 +947,27 @@ for (const eventName of ['preRender', 'moveEnd']) {
h.preRender.emit();
assert.equal(h.pending.size, 0);
assert.equal(renders, 0);
- assert.equal(times.length, 0);
+ assert.equal(visible, false);
assert.equal(camera.percentageChanged, 0.5);
assert.equal(camera.changed.size, 0);
camera.positionCartographic.height = 60000;
+ const before = fades;
(eventName === 'preRender' ? h.preRender : camera.moveEnd).emit();
+ assert.ok(fades > before, 'the fade follows the camera');
+ assert.equal(visible, true);
assert.equal(
renders,
eventName === 'preRender' ? 0 : 1,
'moveEnd wakes the parked scene',
);
- assert.equal(h.pending.size, 1);
- h.callbacks.shift()(16);
- assert.equal(times.length, 1);
- const phase = times.at(-1);
- const queued = h.callbacks.shift();
- camera.positionCartographic.height = 15000;
- h.preRender.emit();
- const parkedRenders = renders;
- queued(100000);
- assert.equal(h.pending.size, 0);
- assert.equal(renders, parkedRenders);
- assert.equal(times.length, 1, 'parked draw cannot tick or advance phase');
-
- camera.positionCartographic.height = 60000;
- (eventName === 'preRender' ? h.preRender : camera.moveEnd).emit();
- h.callbacks.shift()(200000);
- assert.ok(
- times.at(-1) - phase < 0.1,
- 'idle time does not jump animation phase',
- );
- inFrustum = false;
- h.preRender.emit();
- assert.equal(h.pending.size, 0, 'frustum-hidden cells also park');
- inFrustum = true;
+ assert.equal(h.pending.size, 0, 'the renderer animates, not the layer');
h.rendering.setOptions({ paused: true });
- (eventName === 'preRender' ? h.preRender : camera.moveEnd).emit();
- assert.equal(h.pending.size, 0, 'camera events respect pause');
+ assert.equal(options.at(-1), true);
h.rendering.setOptions({ paused: false });
- globalThis.document.hidden = true;
- h.visibility.emit();
- (eventName === 'preRender' ? h.preRender : camera.moveEnd).emit();
- assert.equal(h.pending.size, 0, 'camera events respect hidden documents');
- globalThis.document.hidden = false;
- h.visibility.emit();
- assert.equal(h.pending.size, 1);
+ assert.equal(options.at(-1), false);
+ h.rendering.stop();
+ assert.equal(options.at(-1), true, 'a stopped layer holds the flow still');
h.rendering.destroy();
assert.equal(h.pending.size, 0);
assert.equal(camera.changed.size, 0);
@@ -1028,10 +1001,14 @@ test('scalar field becomes a raised shell on 3D Tiles and survives no-host event
eventTarget.dispatchEvent(new Event('gev:map-stack-changed'));
assert.equal(h.imagery.length, 0);
assert.equal(h.removed[0].destroy, true);
+ // It shows once its geometry and image are ready.
+ renderShells(h.cesium, h.viewer.scene);
const [primitive] = h.primitives();
const geometry = primitive.options.geometryInstances.geometry.options;
assert.equal(geometry.height, 5_000);
- assert.equal(geometry.rectangle, h.cesium.Rectangle.MAX_VALUE);
+ assert.ok(
+ h.cesium.Rectangle.equals(geometry.rectangle, h.cesium.Rectangle.MAX_VALUE),
+ );
const material = primitive.appearance.material;
assert.equal(h.textures.length, 2);
assert.equal(material.uniforms.image, h.textures[1]);
@@ -1094,7 +1071,6 @@ for (const overlay of ['speed', 'temperature', 'pressure']) {
supported: () => true,
setField: () => true,
updateVisibility: () => true,
- tick() {},
setOptions() {},
clear() {},
destroy() {},
@@ -1121,6 +1097,7 @@ for (const overlay of ['speed', 'temperature', 'pressure']) {
h.rendering.setOptions({ overlay });
h.rendering.setField(field);
h.rendering.start();
+ renderShells(h.cesium, h.viewer.scene);
assert.equal(h.imagery.length, 0);
const [primitive] = h.primitives();
const { uniforms } = primitive.appearance.material;
@@ -1185,6 +1162,7 @@ for (const overlay of ['speed', 'temperature', 'pressure']) {
},
});
h.rendering.start();
+ renderShells(h.cesium, h.viewer.scene);
const [primitive] = h.primitives();
const textures = h.textures.length;
const baseAlpha = overlay === 'temperature' ? 1 : 0.85;
diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js
index 43b008259..1f9e63ad2 100644
--- a/src/render/cesium/draw.js
+++ b/src/render/cesium/draw.js
@@ -40,6 +40,7 @@ import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js';
import { createModelSets } from './drawModels.js';
import { createMeshSets } from './drawMeshes.js';
import { createQuadSets } from './drawQuads.js';
+import { createCesiumFields } from './drawFields.js';
/** The contract's colour as Cesium's. */
export function toColor(color, alpha = 1) {
@@ -358,6 +359,8 @@ export function createCesiumDraw({
requestRender: requestFrame = null,
}) {
const sets = new Map();
+ // Fields share the sets' ids.
+ const fieldPart = createCesiumFields({ scene, report });
let setSeq = 0;
// Bumped whenever what height queries see through may have changed: a
// set made, rebuilt, restyled or gone, or items added or removed (icons
@@ -371,7 +374,8 @@ export function createCesiumDraw({
};
function makeSet(kind, spec, build) {
- if (sets.has(spec.id)) throw new Error(`a set with id ${spec.id} is live`);
+ if (sets.has(spec.id) || fieldPart.has(spec.id))
+ throw new Error(`a set with id ${spec.id} is live`);
const items = new Map();
const listeners = {
ready: listenerList(report),
@@ -3868,6 +3872,15 @@ export function createCesiumDraw({
makeSet('quads', { ...spec }, (record) => quadSets.build(record)),
meshes: (spec) =>
makeSet('meshes', { ...spec }, (record) => meshSets.build(record)),
+ ...(capabilities.has('fields')
+ ? {
+ field(spec) {
+ if (sets.has(spec?.id))
+ throw new Error(`a set with id ${spec.id} is live`);
+ return fieldPart.field(spec);
+ },
+ }
+ : {}),
clampState,
on(event, cb) {
if (event !== 'clampState') return () => {};
@@ -3950,6 +3963,8 @@ export function createCesiumDraw({
*/
dispose({ removeHosts = false } = {}) {
clampListeners.clear();
+ // Fields go with the port, and their frame listeners with them.
+ fieldPart.dispose();
// Late model loads find no host and destroy themselves.
for (const record of sets.values()) {
if (removeHosts && !scene.isDestroyed?.()) {
@@ -3989,7 +4004,11 @@ provideUnboundDraw((viewer) => {
typeof scene.requestRender !== 'function'
)
return null;
- const part = createCesiumDraw({ scene, report: uncaught });
+ const part = createCesiumDraw({
+ scene,
+ report: uncaught,
+ capabilities: new Set([...GPU_ICON_CAPABILITIES, 'fields']),
+ });
unboundParts.set(part.port, part);
const offs = [
scene.preRender?.addEventListener?.(() => part.beforeRender()),
diff --git a/src/render/cesium/drawFields.js b/src/render/cesium/drawFields.js
new file mode 100644
index 000000000..5a44f8dc4
--- /dev/null
+++ b/src/render/cesium/drawFields.js
@@ -0,0 +1,659 @@
+/**
+ * @module render/cesium/drawFields
+ * @description The Cesium draw port's `field` handles. It draws two kinds:
+ * `windStreamlines` (drawStreamlines.js) and `rasterShell`, a raster on a
+ * rectangle raised above the ellipsoid, drawn flat in the opaque pass in
+ * the scene's primitive order (ascending height), alpha-blended, without
+ * depth writes and never picked. Other kinds (`scalarRaster`) are refused
+ * loudly.
+ *
+ * Choices the contract leaves open, taken conservatively:
+ * - An image is read when it is first named, as a Cesium material reads
+ * one: to show new pixels, name another canvas. URL, SVG and blob images
+ * are decoded before they are handed over, so the frame they replace
+ * stays until they can be drawn; atlas slots are refused.
+ * - An `update` of `image` alone, inside the same rectangle and height,
+ * swaps the texture on the drawn surface: Cesium keeps drawing the old
+ * one until the new one is uploaded. A new `rectangle` or `heightM` is
+ * built as a second surface, drawn invisibly until its geometry and
+ * images are ready, and then takes the first one's place in one frame.
+ * - A `detail` in a new rectangle shows the full image there until the
+ * detail image has drawn, never the old detail at the new place; one in
+ * the same rectangle swaps only the image, the old one drawing until the
+ * new is uploaded.
+ * - `liftM` scales the shell about the Earth's centre, so every shell
+ * rises alike and keeps its order.
+ */
+import * as Cesium from 'cesium';
+import { listenerList, uncaught } from './common.js';
+import { createWindStreamlines } from './drawStreamlines.js';
+
+const MATERIAL_TYPE = 'DrawRasterShell';
+// Renders after an image swap: one queues the upload, one uploads and draws, one spare.
+const UPLOAD_FRAMES = 3;
+// An empty detail window: the full-extent image shows everywhere.
+const NO_WINDOW = Object.freeze({ west: 0, south: 0, east: -1, north: -1 });
+const shellHeights = new WeakMap();
+// Cesium binds a 1×1 white texture to an image uniform until its first upload:
+// draw nothing until the full-extent image has arrived, and sample the detail
+// image only once it has arrived. The window is west, south, east, north in the
+// full-extent image's texture coordinates.
+const MATERIAL_SOURCE = `czm_material czm_getMaterial(czm_materialInput materialInput)
+{
+ czm_material material = czm_getDefaultMaterial(materialInput);
+ vec2 st = materialInput.st;
+ vec4 coarse = texture(image, st);
+ vec2 dst = (st - window.xy) / max(window.zw - window.xy, vec2(1e-6));
+ float inside = float(all(greaterThanEqual(st, window.xy)) && all(lessThanEqual(st, window.zw)));
+ float useDetail = inside * step(1.5, float(detailDimensions.x));
+ vec4 c = mix(coarse, texture(detail, clamp(dst, 0.0, 1.0)), useDetail);
+ material.diffuse = czm_gammaCorrect(c.rgb);
+ material.alpha = c.a * alpha * step(1.5, float(imageDimensions.x));
+ return material;
+}
+`;
+
+function registerMaterial(cesium) {
+ const cache = cesium.Material._materialCache;
+ if (cache.getMaterial(MATERIAL_TYPE)) return;
+ // A plain template: building the first material from a fabric would make that
+ // instance Cesium's shared template and keep its last image alive.
+ cache.addMaterial(MATERIAL_TYPE, {
+ fabric: {
+ type: MATERIAL_TYPE,
+ uniforms: {
+ image: cesium.Material.DefaultImageId,
+ detail: cesium.Material.DefaultImageId,
+ alpha: 1,
+ window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 },
+ },
+ // Diffuse and alpha share these samples, so one source, not components.
+ source: MATERIAL_SOURCE,
+ },
+ translucent: false,
+ });
+}
+
+const sameEdges = (a, b) =>
+ a.west === b.west &&
+ a.south === b.south &&
+ a.east === b.east &&
+ a.north === b.north;
+
+/** Keep raster shells first in the primitive collection, in ascending height:
+ * higher shells draw over lower ones and other opaque content draws over both. */
+export function orderShells(primitives, primitive, height) {
+ shellHeights.set(primitive, height);
+ if (typeof primitives.lowerToBottom !== 'function') return;
+ const shells = [];
+ for (let i = 0; i < primitives.length; i++) {
+ const item = primitives.get(i);
+ if (shellHeights.has(item)) shells.push(item);
+ }
+ const ordered = [...shells].sort(
+ (a, b) => shellHeights.get(a) - shellHeights.get(b),
+ );
+ if (ordered.every((item, i) => primitives.get(i) === item)) return;
+ for (const item of ordered.reverse()) primitives.lowerToBottom(item);
+}
+
+/** One raised rectangle drawing one full-extent image and, inside a window of
+ * it, an optional detail image. The owner calls destroy(). `onSettled` is
+ * told each time what it was last given has drawn. With `onWake` its owner
+ * runs its frames: it is told when the surface needs them, and calls
+ * `tick()` after each render while `awake()`; without, it listens itself. */
+export function createShellSurface({
+ scene,
+ cesium = Cesium,
+ rectangle,
+ height,
+ onSettled = () => {},
+ onWake = null,
+}) {
+ registerMaterial(cesium);
+ const primitives = scene.primitives;
+ // A scene destroyed under it asks for nothing.
+ const ask = () => {
+ if (!scene.isDestroyed?.()) scene.requestRender();
+ };
+ const material = new cesium.Material({
+ fabric: { type: MATERIAL_TYPE },
+ translucent: false,
+ });
+ // Flat shading keeps the product colours independent of the viewing angle.
+ const appearance = new cesium.EllipsoidSurfaceAppearance({
+ aboveGround: true,
+ flat: true,
+ translucent: false,
+ material,
+ });
+ // Cesium orders its translucent pass itself (weighted OIT or distance), which
+ // cannot honour stacked heights. Draw in the opaque pass in scene.primitives
+ // order, alpha-blended and without depth writes, so higher shells draw over
+ // lower ones and nothing is hidden or picked through a shell.
+ appearance.getRenderState = () => ({
+ depthTest: { enabled: true },
+ depthMask: false,
+ blending: cesium.BlendingState.ALPHA_BLEND,
+ });
+ const primitive = new cesium.Primitive({
+ geometryInstances: new cesium.GeometryInstance({
+ geometry: new cesium.RectangleGeometry({
+ rectangle,
+ height,
+ granularity: cesium.Math.toRadians(0.5),
+ vertexFormat: cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT,
+ }),
+ }),
+ appearance,
+ asynchronous: true,
+ allowPicking: false,
+ });
+ primitives.add(primitive);
+ orderShells(primitives, primitive, height);
+ let lift = 0;
+ let image = null;
+ let frames = 0;
+ // The detail image, its own upload count and a window waiting for it to draw.
+ let detail = null;
+ let detailFrames = 0;
+ let pendingWindow = null;
+ let offRender = null;
+ let awake = false;
+ let destroyed = false;
+
+ const fits = (size, value) =>
+ !size || (size.x === value.width && size.y === value.height);
+ const uploaded = () =>
+ image !== null && fits(material.uniforms.imageDimensions, image);
+ const detailDrawn = () =>
+ detail !== null &&
+ detailFrames === 0 &&
+ fits(material.uniforms.detailDimensions, detail);
+ const drawn = () =>
+ primitive.ready &&
+ uploaded() &&
+ frames === 0 &&
+ (detail === null || (detailDrawn() && pendingWindow === null));
+ function appliedWindow() {
+ const { x, y, z, w } = material.uniforms.window;
+ return z < x ? null : { west: x, south: y, east: z, north: w };
+ }
+ function setWindow(rect) {
+ const next = rect ?? NO_WINDOW;
+ const { x, y, z, w } = material.uniforms.window;
+ if (
+ x === next.west &&
+ y === next.south &&
+ z === next.east &&
+ w === next.north
+ )
+ return;
+ material.uniforms.window = new cesium.Cartesian4(
+ next.west,
+ next.south,
+ next.east,
+ next.north,
+ );
+ ask();
+ }
+ // The render governor may idle the scene; request frames only until the
+ // asynchronous geometry is ready and the latest images have been drawn.
+ function tick() {
+ // Cesium updates a material only while its primitive is shown, so hidden
+ // frames upload nothing and count for nothing.
+ if (primitive.ready && primitive.show) {
+ if (frames > 0) frames--;
+ if (detailFrames > 0) detailFrames--;
+ // A texture is never shown at another window's place.
+ if (pendingWindow && detailDrawn()) {
+ setWindow(pendingWindow);
+ pendingWindow = null;
+ }
+ }
+ if (primitive.show && !drawn()) {
+ ask();
+ return;
+ }
+ awake = false;
+ offRender?.();
+ offRender = null;
+ if (drawn()) onSettled();
+ }
+ function wake() {
+ if (destroyed || !primitive.show || image === null || drawn()) return;
+ awake = true;
+ if (onWake) onWake();
+ else offRender ??= scene.postRender.addEventListener(tick);
+ ask();
+ }
+
+ return {
+ setImage(next) {
+ if (destroyed || next === image) return;
+ image = next;
+ material.uniforms.image = next;
+ frames = UPLOAD_FRAMES;
+ wake();
+ },
+ setAlpha(value) {
+ if (destroyed || material.uniforms.alpha === value) return;
+ material.uniforms.alpha = value;
+ ask();
+ },
+ /** Metres the surface rises, by a uniform scale about the Earth's centre. */
+ setLift(value) {
+ const next = Number(value) || 0;
+ if (destroyed || next === lift) return;
+ lift = next;
+ primitive.modelMatrix = cesium.Matrix4.fromUniformScale(
+ 1 + lift / cesium.Ellipsoid.WGS84.maximumRadius,
+ );
+ ask();
+ },
+ /** Draw `next` inside `rect` (west, south, east, north in the full-extent
+ * image's texture coordinates, 0–1); null clears it. In the same window only
+ * the image changes, and Cesium keeps drawing the previous texture until
+ * this one is uploaded. A different window applies once its image has
+ * drawn; until then the full-extent image covers it. */
+ setDetail(next, rect) {
+ if (destroyed) return;
+ if (!next) {
+ if (detail === null) return;
+ detail = null;
+ detailFrames = 0;
+ pendingWindow = null;
+ material.uniforms.detail = cesium.Material.DefaultImageId;
+ setWindow(null);
+ ask();
+ return;
+ }
+ if (next !== detail) {
+ detail = next;
+ material.uniforms.detail = next;
+ detailFrames = UPLOAD_FRAMES;
+ }
+ const applied = appliedWindow();
+ if (applied && sameEdges(applied, rect)) {
+ pendingWindow = null;
+ } else {
+ setWindow(null);
+ pendingWindow = rect;
+ }
+ wake();
+ },
+ /** Returns whether visibility changed. */
+ setShow(value) {
+ const show = Boolean(value);
+ if (destroyed || primitive.show === show) return false;
+ primitive.show = show;
+ wake();
+ ask();
+ return true;
+ },
+ /** Whether what it was last given has drawn. */
+ isDrawn: () => !destroyed && drawn(),
+ /** Whether it needs frames until what it was given has drawn. */
+ awake: () => awake && !destroyed,
+ tick,
+ getDiagnostics() {
+ return {
+ height,
+ lift,
+ ready: Boolean(primitive.ready),
+ uploaded: uploaded(),
+ show: primitive.show,
+ alpha: material.uniforms.alpha,
+ rendering: awake,
+ // `uploaded` once the detail image has drawn; the window applies after.
+ detail: { uploaded: detailDrawn(), window: appliedWindow() },
+ };
+ },
+ destroy() {
+ if (destroyed) return;
+ destroyed = true;
+ awake = false;
+ offRender?.();
+ offRender = null;
+ if (!primitives.isDestroyed?.() && primitives.contains(primitive))
+ primitives.remove(primitive);
+ if (!primitive.isDestroyed()) primitive.destroy();
+ // Primitive.destroy leaves the material and its texture alive.
+ if (!material.isDestroyed()) material.destroy();
+ image = null;
+ detail = null;
+ pendingWindow = null;
+ ask();
+ },
+ };
+}
+
+/** A rectangle's place inside another, in the outer one's texture coordinates. */
+function placeIn(outer, inner) {
+ const x = outer.east - outer.west;
+ const y = outer.north - outer.south;
+ return {
+ west: (inner.west - outer.west) / x,
+ south: (inner.south - outer.south) / y,
+ east: (inner.east - outer.west) / x,
+ north: (inner.north - outer.south) / y,
+ };
+}
+
+/** Whether `ref` is drawn as it is, with no decode first. */
+const immediate = (ref) => Boolean(ref?.canvas);
+
+/** An image reference decoded into something a material uploads. */
+async function decode(ref) {
+ if (ref?.atlas) throw new TypeError('a raster shell takes no atlas images');
+ const url = ref?.blob
+ ? URL.createObjectURL(ref.blob)
+ : ref?.svg
+ ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(ref.svg)}`
+ : String(ref);
+ try {
+ const image = new Image();
+ image.crossOrigin = 'anonymous';
+ image.src = url;
+ await image.decode();
+ return image;
+ } finally {
+ if (ref?.blob) URL.revokeObjectURL(url);
+ }
+}
+
+/**
+ * The fields part of a Cesium draw port.
+ * @param {{scene: object, report?: (error: unknown) => void,
+ * cesium?: object}} options `cesium` is for test doubles.
+ * @returns {{field: (spec: object) => object, has: (id: string) => boolean,
+ * dispose: () => void}}
+ */
+export function createCesiumFields({
+ scene,
+ report = uncaught,
+ cesium = Cesium,
+}) {
+ const fields = new Map();
+ const live = () => !scene.isDestroyed?.();
+ const requestRender = () => {
+ if (live()) scene.requestRender();
+ };
+ function rasterShell(spec) {
+ const id = spec.id;
+ // The frame a change was put on the surface, so 'drawn' waits for the
+ // render after it. Scenes without a frame state count this field's
+ // renders.
+ let renders = 0;
+ const frameNumber = () => scene.frameState?.frameNumber ?? renders;
+ let content = {
+ image: spec.image,
+ rectangle: { ...spec.rectangle },
+ heightM: Number(spec.heightM) || 0,
+ detail: spec.detail ? { ...spec.detail } : null,
+ };
+ let liftM = Number(spec.liftM) || 0;
+ let alpha = spec.alpha ?? 1;
+ let shown = true;
+ let disposed = false;
+ // The surface drawn, and one being built for a new rectangle or height.
+ let drawing = null;
+ let staged = null;
+ // Each content change, so a late decode of an older one is dropped.
+ let contentSeq = 0;
+ let placedSeq = -1;
+ // 'drawn' is owed for the latest change, put on the surface at `placedAt`.
+ let owed = true;
+ let placedAt = Infinity;
+ let offRender = null;
+ const drawnListeners = listenerList(report);
+
+ const keyOf = (c) =>
+ `${c.rectangle.west},${c.rectangle.south},${c.rectangle.east},${c.rectangle.north}|${c.heightM}`;
+
+ function make(c) {
+ const entry = { key: keyOf(c), rectangle: c.rectangle, surface: null };
+ const { west, south, east, north } = c.rectangle;
+ entry.surface = createShellSurface({
+ scene,
+ cesium,
+ rectangle: cesium.Rectangle.fromDegrees(west, south, east, north),
+ height: c.heightM,
+ onSettled: () => settled(entry),
+ onWake: () => watch(),
+ });
+ entry.surface.setLift(liftM);
+ // Staged surfaces draw, invisibly, even while the field is hidden, so
+ // the new content is ready when it shows.
+ return entry;
+ }
+ function drop(entry) {
+ entry?.surface.destroy();
+ return null;
+ }
+ // A staged surface takes the drawn one's place once it has drawn.
+ function settled(entry) {
+ if (disposed) return;
+ if (entry === staged) {
+ drop(drawing);
+ drawing = staged;
+ staged = null;
+ drawing.surface.setAlpha(alpha);
+ drawing.surface.setShow(shown);
+ // It has drawn already, invisibly, so it shows from the next frame on,
+ // the frame the one it replaces stops: told now, so nothing comes
+ // between the swap and 'drawn'.
+ if (owed && shown && placedSeq === contentSeq) {
+ owed = false;
+ drawnListeners.fire();
+ return;
+ }
+ placed();
+ return;
+ }
+ // What it last applied (a detail window, say) draws in the next frame.
+ if (entry === drawing) placed();
+ else watch();
+ }
+ function placed() {
+ placedAt = frameNumber();
+ watch();
+ }
+ function put(entry, c, image, detailImage) {
+ entry.surface.setImage(image);
+ if (c.detail && detailImage)
+ entry.surface.setDetail(
+ detailImage,
+ placeIn(entry.rectangle, c.detail.rectangle),
+ );
+ else entry.surface.setDetail(null);
+ }
+ /** Draw `c` with its images decoded. */
+ function place(c, image, detailImage) {
+ const key = keyOf(c);
+ if (drawing?.key === key) {
+ staged = drop(staged);
+ put(drawing, c, image, detailImage);
+ placed();
+ return;
+ }
+ if (staged?.key !== key) {
+ staged = drop(staged);
+ staged = make(c);
+ // Invisible until it takes the drawn one's place.
+ staged.surface.setAlpha(0);
+ }
+ put(staged, c, image, detailImage);
+ // Its own settling promotes it.
+ watch();
+ }
+ function load(c) {
+ const seq = (contentSeq += 1);
+ const refs = [c.image, c.detail?.image];
+ if (refs.every((ref) => ref == null || immediate(ref))) {
+ placedSeq = seq;
+ place(c, c.image.canvas, c.detail?.image.canvas ?? null);
+ return;
+ }
+ // A stage of older content must not take the drawn one's place while
+ // this decodes.
+ staged = drop(staged);
+ Promise.all(
+ refs.map((ref) =>
+ ref == null ? null : immediate(ref) ? ref.canvas : decode(ref),
+ ),
+ ).then(
+ ([image, detailImage]) => {
+ if (disposed || seq !== contentSeq || !live()) return;
+ placedSeq = seq;
+ place(c, image, detailImage);
+ },
+ (error) => {
+ // What it drew stays.
+ if (disposed || seq !== contentSeq) return;
+ report(error);
+ if (!busy()) unwatch();
+ },
+ );
+ }
+
+ // One listener runs the surfaces' frames and tells 'drawn'.
+ const busy = () =>
+ Boolean(drawing?.surface.awake() || staged?.surface.awake());
+ function notify() {
+ if (!owed || !shown || staged || placedSeq !== contentSeq || !drawing)
+ return;
+ if (!drawing.surface.isDrawn()) return;
+ // A frame number that has moved on (it wraps) has drawn the change.
+ if (frameNumber() === placedAt) {
+ requestRender();
+ return;
+ }
+ owed = false;
+ drawnListeners.fire();
+ }
+ function tick() {
+ renders += 1;
+ for (const entry of [drawing, staged])
+ if (entry?.surface.awake()) entry.surface.tick();
+ if (!disposed) notify();
+ if (disposed || (!busy() && !(owed && shown))) unwatch();
+ }
+ function watch() {
+ if (disposed || (!(owed && shown) && !busy())) return;
+ offRender ??= scene.postRender.addEventListener(tick);
+ requestRender();
+ }
+ function unwatch() {
+ offRender?.();
+ offRender = null;
+ }
+
+ const handle = {
+ id,
+ get show() {
+ return shown;
+ },
+ set show(value) {
+ const next = Boolean(value);
+ if (disposed || next === shown) return;
+ shown = next;
+ drawing?.surface.setShow(shown);
+ // A stage in progress keeps building, so it is ready when shown.
+ if (shown) watch();
+ else if (!busy()) unwatch();
+ requestRender();
+ },
+ update(patch = {}) {
+ if (disposed) return;
+ if (patch.kind !== undefined && patch.kind !== 'rasterShell')
+ throw new TypeError('a field keeps its kind');
+ const next = { ...content };
+ let reload = false;
+ if ('image' in patch && patch.image !== content.image) {
+ next.image = patch.image;
+ reload = true;
+ }
+ if (patch.rectangle && !sameEdges(patch.rectangle, content.rectangle)) {
+ next.rectangle = { ...patch.rectangle };
+ reload = true;
+ }
+ if ('heightM' in patch && Number(patch.heightM) !== content.heightM) {
+ next.heightM = Number(patch.heightM) || 0;
+ reload = true;
+ }
+ if ('detail' in patch) {
+ const was = content.detail;
+ const now = patch.detail ? { ...patch.detail } : null;
+ if (
+ (was === null) !== (now === null) ||
+ (now &&
+ (now.image !== was.image ||
+ !sameEdges(now.rectangle, was.rectangle)))
+ ) {
+ next.detail = now;
+ reload = true;
+ }
+ }
+ if ('liftM' in patch) {
+ liftM = Number(patch.liftM) || 0;
+ drawing?.surface.setLift(liftM);
+ staged?.surface.setLift(liftM);
+ }
+ if ('alpha' in patch) {
+ alpha = patch.alpha ?? 1;
+ drawing?.surface.setAlpha(alpha);
+ }
+ owed = true;
+ content = next;
+ if (reload) load(content);
+ else placed();
+ requestRender();
+ },
+ on(event, cb) {
+ if (event !== 'drawn') return () => {};
+ return drawnListeners.on(cb);
+ },
+ dispose() {
+ if (disposed) return;
+ disposed = true;
+ unwatch();
+ drawnListeners.clear();
+ drawing = drop(drawing);
+ staged = drop(staged);
+ if (fields.get(id) === handle) fields.delete(id);
+ },
+ };
+ fields.set(id, handle);
+ load(content);
+ return handle;
+ }
+
+ return {
+ field(spec) {
+ if (fields.has(spec?.id))
+ throw new Error(`a field with id ${spec.id} is live`);
+ if (spec?.kind === 'rasterShell') return rasterShell(spec);
+ if (spec?.kind === 'windStreamlines') {
+ const handle = createWindStreamlines({
+ scene,
+ spec,
+ report,
+ cesium,
+ onDispose: () => {
+ if (fields.get(spec.id) === handle) fields.delete(spec.id);
+ },
+ });
+ fields.set(spec.id, handle);
+ return handle;
+ }
+ throw new TypeError(
+ `the Cesium renderer draws no ${spec?.kind} fields yet`,
+ );
+ },
+ has: (id) => fields.has(id),
+ dispose() {
+ for (const handle of [...fields.values()]) handle.dispose();
+ },
+ };
+}
diff --git a/src/render/cesium/drawFields.test.mjs b/src/render/cesium/drawFields.test.mjs
new file mode 100644
index 000000000..ededeaacd
--- /dev/null
+++ b/src/render/cesium/drawFields.test.mjs
@@ -0,0 +1,645 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import {
+ createCesiumFields,
+ createShellSurface,
+ orderShells,
+} from './drawFields.js';
+import {
+ createShellCesium,
+ createShellScene,
+ renderShells,
+} from '../../layers/weather/shellFixture.mjs';
+
+// The detail window uniform; NONE is the empty window.
+const NONE = { x: 0, y: 0, z: -1, w: -1 };
+const windowOf = (primitive) => {
+ const { x, y, z, w } = primitive.appearance.material.uniforms.window;
+ return { x, y, z, w };
+};
+
+test('surface builds a flat raised rectangle drawn in primitive order without depth writes', () => {
+ const cesium = createShellCesium();
+ const scene = createShellScene();
+ const rectangle = Cesium.Rectangle.fromDegrees(-130, 20, -60, 55);
+ const surface = createShellSurface({
+ scene,
+ cesium,
+ rectangle,
+ height: 6_200,
+ });
+ const template = cesium.templates.get('DrawRasterShell');
+ assert.ok(!(template instanceof cesium.Material), 'plain template');
+ assert.deepEqual(template.fabric.uniforms, {
+ image: Cesium.Material.DefaultImageId,
+ detail: Cesium.Material.DefaultImageId,
+ alpha: 1,
+ window: { type: 'vec4', x: 0, y: 0, z: -1, w: -1 },
+ });
+ const { source } = template.fabric;
+ assert.match(
+ source,
+ /material\.alpha = c\.a \* alpha \* step\(1\.5, float\(imageDimensions\.x\)\);/,
+ 'nothing draws before the full-extent image',
+ );
+ assert.match(
+ source,
+ /float useDetail = inside \* step\(1\.5, float\(detailDimensions\.x\)\);/,
+ 'the detail image is sampled only once it has arrived',
+ );
+ assert.match(
+ source,
+ /all\(greaterThanEqual\(st, window\.xy\)\) && all\(lessThanEqual\(st, window\.zw\)\)/,
+ );
+ assert.match(
+ source,
+ /mix\(coarse, texture\(detail, clamp\(dst, 0\.0, 1\.0\)\), useDetail\)/,
+ );
+ assert.match(source, /material\.diffuse = czm_gammaCorrect\(c\.rgb\);/);
+ const [primitive] = scene.primitives.items;
+ const appearance = primitive.appearance;
+ assert.equal(appearance.material.options.translucent, false);
+ assert.deepEqual(
+ { ...appearance.options, material: undefined },
+ {
+ aboveGround: true,
+ flat: true,
+ translucent: false,
+ material: undefined,
+ },
+ );
+ assert.deepEqual(appearance.getRenderState(), {
+ depthTest: { enabled: true },
+ depthMask: false,
+ blending: Cesium.BlendingState.ALPHA_BLEND,
+ });
+ const geometry = primitive.options.geometryInstances.geometry.options;
+ assert.equal(geometry.rectangle, rectangle);
+ assert.equal(geometry.height, 6_200);
+ assert.equal(geometry.granularity, Cesium.Math.toRadians(0.5));
+ assert.equal(
+ geometry.vertexFormat,
+ Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT,
+ );
+ assert.equal(primitive.options.asynchronous, true);
+ assert.equal(primitive.options.allowPicking, false);
+ const lower = createShellSurface({
+ scene,
+ cesium,
+ rectangle,
+ height: 5_000,
+ });
+ assert.equal(cesium.templates.size, 1, 'the template registers once');
+ assert.deepEqual(
+ scene.primitives.items.map(
+ (item) => item.options.geometryInstances.geometry.options.height,
+ ),
+ [5_000, 6_200],
+ );
+ lower.destroy();
+ surface.destroy();
+});
+
+test('a surface applies a new detail window only once its image has drawn; the same window swaps only the image', () => {
+ const cesium = createShellCesium();
+ const scene = createShellScene();
+ const surface = createShellSurface({
+ scene,
+ cesium,
+ rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
+ height: 6_200,
+ });
+ const [primitive] = scene.primitives.items;
+ const { uniforms } = primitive.appearance.material;
+ const render = (count) => renderShells(cesium, scene, count);
+ const image = () => ({ width: 4096, height: 2048 });
+ surface.setImage(image());
+ render();
+ assert.deepEqual(surface.getDiagnostics().detail, {
+ uploaded: false,
+ window: null,
+ });
+ const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 };
+ const first = image();
+ surface.setDetail(first, a);
+ assert.equal(uniforms.detail, first);
+ assert.deepEqual(windowOf(primitive), NONE, 'the full-extent image covers');
+ assert.equal(scene.postRender.size, 1, 'renders until the detail has drawn');
+ render(2);
+ assert.deepEqual(windowOf(primitive), NONE);
+ render(1);
+ assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
+ assert.ok(uniforms.window instanceof Cesium.Cartesian4);
+ assert.deepEqual(surface.getDiagnostics().detail, {
+ uploaded: true,
+ window: a,
+ });
+ assert.equal(scene.postRender.size, 0);
+
+ // A time change in the same window: Cesium keeps drawing the previous
+ // texture until the new one is uploaded, so the window stays.
+ const applied = uniforms.window;
+ const second = image();
+ surface.setDetail(second, { ...a });
+ assert.equal(uniforms.detail, second);
+ assert.equal(uniforms.window, applied, 'only the image is written');
+ assert.equal(surface.getDiagnostics().detail.uploaded, false);
+ render();
+ assert.equal(surface.getDiagnostics().detail.uploaded, true);
+ assert.equal(uniforms.window, applied);
+ const renders = scene.renders;
+ surface.setDetail(second, { ...a });
+ assert.equal(scene.renders, renders, 'an unchanged detail costs nothing');
+ assert.equal(scene.postRender.size, 0);
+
+ // A different window empties at once and applies once its image has drawn.
+ const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 };
+ surface.setDetail(image(), b);
+ assert.deepEqual(windowOf(primitive), NONE);
+ render(2);
+ assert.deepEqual(windowOf(primitive), NONE);
+ render(1);
+ assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 });
+
+ surface.setDetail(null);
+ assert.equal(uniforms.detail, Cesium.Material.DefaultImageId);
+ assert.deepEqual(windowOf(primitive), NONE);
+ assert.deepEqual(surface.getDiagnostics().detail, {
+ uploaded: false,
+ window: null,
+ });
+ render();
+ assert.deepEqual(
+ { ...uniforms.detailDimensions },
+ { type: 'ivec3', x: 1, y: 1 },
+ );
+ // Counted renders alone are not enough: the bound texture must be this image.
+ surface.setDetail(image(), a);
+ for (let i = 0; i < 4; i++) scene.postRender.emit();
+ assert.deepEqual(windowOf(primitive), NONE, 'still the 1×1 default');
+ render(1);
+ assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
+ surface.destroy();
+ surface.setDetail(image(), b);
+ assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
+ assert.equal(scene.postRender.size, 0);
+});
+
+test("a surface rises by a uniform scale about the Earth's centre", () => {
+ const scene = {
+ primitives: new Cesium.PrimitiveCollection(),
+ postRender: new Cesium.Event(),
+ requestRender() {},
+ };
+ const surface = createShellSurface({
+ scene,
+ cesium: Cesium,
+ rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
+ height: 5_800,
+ });
+ const primitive = scene.primitives.get(0);
+ const identity = primitive.modelMatrix;
+ surface.setLift(0);
+ assert.equal(primitive.modelMatrix, identity, 'no lift, no new matrix');
+ surface.setLift(32_000);
+ const radius = Cesium.Ellipsoid.WGS84.maximumRadius;
+ assert.ok(
+ Math.abs(primitive.modelMatrix[0] * radius - (radius + 32_000)) < 1e-3,
+ );
+ const lifted = primitive.modelMatrix;
+ surface.setLift(32_000);
+ assert.equal(primitive.modelMatrix, lifted, 'the same lift keeps the matrix');
+ surface.destroy();
+});
+
+test('real Cesium builds the two-texture material, the opaque-pass appearance and the rectangle primitive', () => {
+ const scene = {
+ primitives: new Cesium.PrimitiveCollection(),
+ postRender: new Cesium.Event(),
+ requestRender() {},
+ };
+ const surface = createShellSurface({
+ scene,
+ cesium: Cesium,
+ rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
+ height: 6_600,
+ });
+ const cached = Cesium.Material._materialCache.getMaterial('DrawRasterShell');
+ assert.ok(cached && !(cached instanceof Cesium.Material));
+ const primitive = scene.primitives.get(0);
+ const material = primitive.appearance.material;
+ assert.ok(primitive instanceof Cesium.Primitive);
+ assert.equal(material.type, 'DrawRasterShell');
+ assert.equal(material.isTranslucent(), false);
+ assert.equal(primitive.appearance.isTranslucent(), false, 'opaque pass');
+ assert.equal(primitive.appearance.getRenderState().depthMask, false);
+ assert.equal(
+ Cesium.Appearance.prototype.getRenderState.call(primitive.appearance)
+ .depthMask,
+ true,
+ 'the default opaque render state would write depth',
+ );
+ assert.deepEqual(
+ [material.uniforms.imageDimensions.x, material.uniforms.detailDimensions.x],
+ [1, 1],
+ 'Cesium tracks both bound texture sizes',
+ );
+ const shader = material.shaderSource;
+ for (const declaration of [
+ /uniform sampler2D image_\d+;/,
+ /uniform sampler2D detail_\d+;/,
+ /uniform float alpha_\d+;/,
+ /uniform vec4 window_\d+;/,
+ /uniform ivec3 imageDimensions_\d+;/,
+ /uniform ivec3 detailDimensions_\d+;/,
+ ])
+ assert.match(shader, declaration);
+ assert.match(shader, /texture\(image_\d+, st\)/);
+ assert.match(shader, /texture\(detail_\d+, clamp\(dst, 0\.0, 1\.0\)\)/);
+ assert.match(shader, /lessThanEqual\(st, window_\d+\.zw\)/);
+ assert.match(shader, /step\(1\.5, float\(detailDimensions_\d+\.x\)\)/);
+ assert.match(
+ shader,
+ /material\.alpha = c\.a \* alpha_\d+ \* step\(1\.5, float\(imageDimensions_\d+\.x\)\);/,
+ 'the uniform is renamed, the material field is not',
+ );
+ assert.match(shader, /float useDetail = inside \* step/, 'locals keep names');
+ const detail = { width: 4096, height: 2048 };
+ surface.setDetail(detail, { west: 0.1, south: 0.2, east: 0.3, north: 0.4 });
+ assert.equal(material.uniforms.detail, detail);
+ assert.deepEqual(
+ [material.uniforms.window.z, material.uniforms.window.w],
+ [-1, -1],
+ 'no window before the image has drawn',
+ );
+ surface.setDetail(null);
+ assert.equal(material.uniforms.detail, Cesium.Material.DefaultImageId);
+ surface.setAlpha(0.4);
+ assert.equal(material.uniforms.alpha, 0.4);
+ surface.destroy();
+ assert.equal(scene.primitives.length, 0);
+ assert.equal(primitive.isDestroyed(), true);
+ assert.equal(material.isDestroyed(), true);
+ assert.equal(scene.postRender.numberOfListeners, 0);
+});
+
+test('shells draw first, in height order, regardless of add order', () => {
+ const scene = createShellScene();
+ const other = { name: 'other' };
+ scene.primitives.add(other);
+ const add = (name, height) => {
+ const primitive = { name };
+ scene.primitives.add(primitive);
+ orderShells(scene.primitives, primitive, height);
+ return primitive;
+ };
+ add('lightning', 6_600);
+ add('radar', 6_200);
+ add('wind', 5_000);
+ const later = { name: 'later' };
+ scene.primitives.add(later);
+ add('regional', 5_800);
+ assert.deepEqual(
+ scene.primitives.items.map(({ name }) => name),
+ ['wind', 'regional', 'radar', 'lightning', 'other', 'later'],
+ );
+ const primitives = new Cesium.PrimitiveCollection({
+ destroyPrimitives: false,
+ });
+ const real = (name) => ({ name, update() {}, isDestroyed: () => false });
+ const tileset = primitives.add(real('tileset'));
+ const lightning = primitives.add(real('lightning'));
+ orderShells(primitives, lightning, 6_600);
+ const radar = primitives.add(real('radar'));
+ orderShells(primitives, radar, 6_200);
+ assert.deepEqual(
+ [0, 1, 2].map((i) => primitives.get(i).name),
+ ['radar', 'lightning', 'tileset'],
+ 'real Cesium collection order',
+ );
+ assert.equal(tileset.name, 'tileset');
+});
+
+test('hidden frames do not count towards a pending detail window', () => {
+ const cesium = createShellCesium();
+ const scene = createShellScene();
+ const surface = createShellSurface({
+ scene,
+ cesium,
+ rectangle: Cesium.Rectangle.fromDegrees(-130, 20, -60, 55),
+ height: 6_200,
+ });
+ const [primitive] = scene.primitives.items;
+ const render = (count) => renderShells(cesium, scene, count);
+ const image = () => ({ width: 4096, height: 2048 });
+ surface.setImage(image());
+ const a = { west: 0.25, south: 0.5, east: 0.5, north: 0.75 };
+ surface.setDetail(image(), a);
+ render();
+ assert.deepEqual(windowOf(primitive), { x: 0.25, y: 0.5, z: 0.5, w: 0.75 });
+ // A different window with a same-sized image: the dimensions alone cannot
+ // tell the textures apart, so only shown frames may count.
+ const b = { west: 0.5, south: 0.25, east: 0.75, north: 0.5 };
+ surface.setDetail(image(), b);
+ assert.deepEqual(windowOf(primitive), NONE);
+ for (let i = 0; i < 3; i++) {
+ surface.setShow(false);
+ scene.postRender.emit();
+ surface.setShow(true);
+ }
+ assert.deepEqual(windowOf(primitive), NONE, 'hidden frames counted nothing');
+ render(2);
+ assert.deepEqual(windowOf(primitive), NONE);
+ render(1);
+ assert.deepEqual(windowOf(primitive), { x: 0.5, y: 0.25, z: 0.75, w: 0.5 });
+});
+
+function fieldHarness() {
+ const cesium = createShellCesium();
+ const scene = createShellScene();
+ const fields = createCesiumFields({ scene, cesium });
+ const image = () => ({ canvas: { width: 64, height: 32 }, key: 'k' });
+ const render = (count = 4) => renderShells(cesium, scene, count);
+ const live = () => scene.primitives.items.filter((p) => !p.destroyed);
+ return { cesium, scene, fields, image, render, live };
+}
+const RECT = { west: -100, south: 20, east: -60, north: 40 };
+
+test("a raster shell tells 'drawn' once its content is drawn, once per change", () => {
+ const h = fieldHarness();
+ const field = h.fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: h.image(),
+ rectangle: RECT,
+ heightM: 6_000,
+ alpha: 0.5,
+ });
+ let drawn = 0;
+ field.on('drawn', () => (drawn += 1));
+ const [primitive] = h.live();
+ const { uniforms } = primitive.appearance.material;
+ assert.equal(uniforms.alpha, 0, 'invisible until drawable');
+ h.render();
+ assert.equal(drawn, 1);
+ assert.equal(uniforms.alpha, 0.5);
+ assert.equal(h.scene.postRender.size, 0, 'no frames once drawn');
+ field.update({ alpha: 0.3, liftM: 1_000 });
+ assert.equal(uniforms.alpha, 0.3);
+ assert.notEqual(primitive.modelMatrix, undefined, 'lifted');
+ assert.deepEqual(h.live(), [primitive], 'alpha and lift never rebuild');
+ h.render();
+ assert.equal(drawn, 2);
+ field.show = false;
+ field.update({ alpha: 0.4 });
+ h.render();
+ assert.equal(drawn, 2, 'never while hidden');
+ field.show = true;
+ h.render();
+ assert.equal(drawn, 3, 'told once shown');
+ h.render();
+ assert.equal(drawn, 3);
+ field.dispose();
+ assert.equal(h.live().length, 0);
+ assert.equal(h.scene.postRender.size, 0);
+});
+
+test('a raster shell keeps drawing its rectangle until a new one is drawn whole', () => {
+ const h = fieldHarness();
+ const first = h.image();
+ const field = h.fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: first,
+ rectangle: RECT,
+ heightM: 6_000,
+ });
+ let drawn = 0;
+ field.on('drawn', () => (drawn += 1));
+ h.render();
+ const [old] = h.live();
+ const second = h.image();
+ field.update({
+ image: second,
+ rectangle: { west: -120, south: 10, east: -50, north: 50 },
+ });
+ const [, staged] = h.live();
+ assert.equal(old.appearance.material.uniforms.alpha, 1, 'the old one draws');
+ assert.equal(staged.appearance.material.uniforms.alpha, 0);
+ assert.equal(staged.appearance.material.uniforms.image, second.canvas);
+ h.render();
+ assert.equal(old.destroyed, true, 'swapped in one frame');
+ assert.deepEqual(h.live(), [staged]);
+ assert.equal(staged.appearance.material.uniforms.alpha, 1);
+ assert.equal(drawn, 2);
+ // Back to the drawn rectangle before a staged one is drawn: it goes.
+ field.update({ rectangle: RECT });
+ assert.equal(h.live().length, 2);
+ field.update({ rectangle: { west: -120, south: 10, east: -50, north: 50 } });
+ assert.deepEqual(h.live(), [staged]);
+ field.dispose();
+});
+
+test('a raster shell draws its detail in its own rectangle, in texture coordinates', () => {
+ const h = fieldHarness();
+ const field = h.fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: h.image(),
+ rectangle: RECT,
+ heightM: 6_000,
+ });
+ h.render();
+ const [primitive] = h.live();
+ const detail = h.image();
+ field.update({
+ detail: {
+ image: detail,
+ rectangle: { west: -90, south: 25, east: -80, north: 30 },
+ },
+ });
+ assert.deepEqual(windowOf(primitive), NONE, 'the full image covers it');
+ h.render();
+ assert.equal(primitive.appearance.material.uniforms.detail, detail.canvas);
+ assert.deepEqual(windowOf(primitive), {
+ x: 0.25,
+ y: 0.25,
+ z: 0.5,
+ w: 0.5,
+ });
+ field.update({ detail: null });
+ assert.deepEqual(windowOf(primitive), NONE);
+ field.dispose();
+});
+
+test('a raster shell hidden while a new rectangle stages still swaps it in', () => {
+ const h = fieldHarness();
+ const field = h.fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: h.image(),
+ rectangle: RECT,
+ heightM: 6_000,
+ });
+ let drawn = 0;
+ field.on('drawn', () => (drawn += 1));
+ h.render();
+ const [old] = h.live();
+ field.show = false;
+ field.update({
+ image: h.image(),
+ rectangle: { west: -120, south: 10, east: -50, north: 50 },
+ });
+ h.render();
+ const [staged] = h.live();
+ assert.equal(old.destroyed, true, 'drawn invisibly and swapped in');
+ assert.notEqual(staged, old);
+ assert.equal(staged.show, false, 'and kept hidden');
+ assert.equal(drawn, 1, 'never told while hidden');
+ field.show = true;
+ h.render();
+ assert.equal(staged.show, true);
+ assert.equal(drawn, 2);
+ field.dispose();
+});
+
+test("a raster shell tells 'drawn' for a detail only once its window is placed", () => {
+ const h = fieldHarness();
+ const field = h.fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: h.image(),
+ rectangle: RECT,
+ heightM: 6_000,
+ });
+ h.render();
+ const [primitive] = h.live();
+ const windows = [];
+ field.on('drawn', () => windows.push(windowOf(primitive)));
+ field.update({
+ detail: {
+ image: h.image(),
+ rectangle: { west: -90, south: 25, east: -80, north: 30 },
+ },
+ });
+ h.render();
+ assert.deepEqual(windows, [{ x: 0.25, y: 0.25, z: 0.5, w: 0.5 }]);
+ field.dispose();
+});
+
+test("a raster shell tells 'drawn' in the frame its new rectangle replaces the old", () => {
+ const h = fieldHarness();
+ const field = h.fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: h.image(),
+ rectangle: RECT,
+ heightM: 6_000,
+ });
+ h.render();
+ const [old] = h.live();
+ let drawnAt = null;
+ let render = 0;
+ field.on('drawn', () => (drawnAt = render));
+ field.update({ rectangle: { west: -120, south: 10, east: -50, north: 50 } });
+ let swappedAt = null;
+ for (render = 1; render <= 6; render++) {
+ h.render(1);
+ if (old.destroyed && swappedAt === null) swappedAt = render;
+ }
+ assert.ok(swappedAt > 1, 'staged while uploading');
+ assert.equal(drawnAt, swappedAt, 'nothing comes between the swap and drawn');
+ field.dispose();
+});
+
+test('a raster shell hidden after a new rectangle stages still builds and swaps it', () => {
+ const h = fieldHarness();
+ const field = h.fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: h.image(),
+ rectangle: RECT,
+ heightM: 6_000,
+ });
+ let drawn = 0;
+ field.on('drawn', () => (drawn += 1));
+ h.render();
+ const [old] = h.live();
+ field.update({ rectangle: { west: -120, south: 10, east: -50, north: 50 } });
+ field.show = false;
+ h.render();
+ const [staged] = h.live();
+ assert.equal(old.destroyed, true);
+ assert.notEqual(staged, old);
+ assert.equal(staged.show, false);
+ assert.equal(h.scene.postRender.size, 0, 'no frames once built');
+ assert.equal(drawn, 1);
+ field.show = true;
+ h.render();
+ assert.equal(drawn, 2);
+ field.dispose();
+});
+
+test('a raster shell never swaps in a stage superseded by content still decoding', async (t) => {
+ const pending = [];
+ const Image = globalThis.Image;
+ globalThis.Image = class {
+ decode() {
+ return new Promise((resolve, reject) =>
+ pending.push({ resolve, reject }),
+ );
+ }
+ };
+ t.after(() => (globalThis.Image = Image));
+ const reported = [];
+ const cesium = createShellCesium();
+ const scene = createShellScene();
+ const fields = createCesiumFields({
+ scene,
+ cesium,
+ report: (error) => reported.push(error),
+ });
+ const live = () => scene.primitives.items.filter((p) => !p.destroyed);
+ const field = fields.field({
+ kind: 'rasterShell',
+ id: 'shell',
+ image: { canvas: { width: 64, height: 32 } },
+ rectangle: RECT,
+ heightM: 6_000,
+ });
+ renderShells(cesium, scene);
+ const [old] = live();
+ field.update({
+ image: { canvas: { width: 64, height: 32 } },
+ rectangle: { west: -120, south: 10, east: -50, north: 50 },
+ });
+ assert.equal(live().length, 2);
+ field.update({ image: 'https://example.test/next.png' });
+ assert.deepEqual(live(), [old], 'the superseded stage goes');
+ pending[0].reject(new Error('no image'));
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ renderShells(cesium, scene);
+ assert.deepEqual(live(), [old], 'what it drew stays');
+ assert.equal(reported.length, 1);
+ field.dispose();
+});
+
+test('the Cesium fields refuse kinds they cannot draw and live ids', () => {
+ const h = fieldHarness();
+ assert.throws(
+ () => h.fields.field({ kind: 'scalarRaster', id: 'x' }),
+ /no scalarRaster fields/,
+ );
+ const spec = {
+ kind: 'rasterShell',
+ id: 'shell',
+ image: h.image(),
+ rectangle: RECT,
+ heightM: 1,
+ };
+ const field = h.fields.field(spec);
+ assert.throws(() => h.fields.field(spec), /is live/);
+ field.dispose();
+ h.fields.field(spec).dispose();
+});
diff --git a/src/render/cesium/drawStreamlines.js b/src/render/cesium/drawStreamlines.js
new file mode 100644
index 000000000..d39e4b9b7
--- /dev/null
+++ b/src/render/cesium/drawStreamlines.js
@@ -0,0 +1,469 @@
+/**
+ * @module render/cesium/drawStreamlines
+ * @description The Cesium draw port's `windStreamlines` fields: paths
+ * traced once through the wind grid (`bakeWindStreamlines`), drawn as
+ * polylines at `heightM` in 30° cells, each a primitive of its own. A
+ * highlight moves along each path in the wind's direction; a faint ghost
+ * of the whole path stays. Cells the eye cannot see (behind the Earth or
+ * outside the view) are not drawn, and nothing animates while no cell is.
+ *
+ * Choices the contract leaves open, taken conservatively:
+ * - The grid's samples are points: the first column at `rectangle.west`
+ * and the first row at `rectangle.north`, rows running south. A grid
+ * whose rectangle spans 360° of longitude wraps (`width` columns over
+ * the whole circle); any other is `width - 1` steps from west to east.
+ * - `style.color` is the ghost's and the trail's colour; the moving tip
+ * brightens it towards white. `speedFactor` scales how fast the tip
+ * moves (1 by default).
+ * - The highlight moves on the page's own clock, at most 30 times a
+ * second, asking for the frames it needs; `paused` holds it where it is
+ * and raises the ghost. `alpha` scales everything, and 0 draws nothing.
+ * - Without `heightM` the paths are drawn at the ellipsoid's surface.
+ * - Any change but `alpha`, `paused` and `style` traces the paths again.
+ * - Scenes not in 3D refuse the field, as does a grid no path runs through.
+ */
+import * as Cesium from 'cesium';
+import {
+ bakeWindStreamlines,
+ groupWindPaths,
+} from '../../layers/wind/streamlines.js';
+import { listenerList, uncaught } from './common.js';
+
+// How fast the highlight runs along a path, in path lengths per second.
+const TIP_SPEED = 0.16;
+const GHOST_ALPHA = 0.25;
+const GHOST_ALPHA_PAUSED = 0.34;
+// The highlight moves at most this often (seconds between frames).
+const STEP_SECONDS = 0.032;
+
+// A persistent fine curve plus a moving, tapered highlight. The integer part
+// of s identifies a path; its fractional part follows the wind.
+const FLOW_MATERIAL = `
+in float v_windFacing;
+czm_material czm_getMaterial(czm_materialInput materialInput)
+{
+ czm_material material = czm_getDefaultMaterial(materialInput);
+ float pathId = floor(materialInput.st.s);
+ float along = fract(materialInput.st.s);
+ float offset = fract((pathId + 1.0) * 0.61803398875);
+ float behind = fract(phaseTime * tipSpeed + offset - along);
+ float tail = (1.0 - smoothstep(0.0, 0.32, behind));
+ float tip = 1.0 - smoothstep(0.0, 0.045, behind);
+ float ends = smoothstep(0.0, 0.055, along) * (1.0 - smoothstep(0.945, 1.0, along));
+ float edge = 1.0 - smoothstep(0.26, 0.5, abs(materialInput.st.t - 0.5));
+ float horizon = smoothstep(0.0, 0.065, v_windFacing);
+ material.diffuse = mix(baseColor.rgb, vec3(0.91, 0.99, 1.0), tip);
+ material.alpha = (ghostAlpha + 0.64 * tail + 0.16 * tip) * ends * edge * horizon * heightFade;
+ return material;
+}`;
+
+const DEFAULT_COLOR = '#80c9e6';
+
+/** A contract colour as Cesium's; one Cesium cannot read is the default. */
+function toColor(C, color) {
+ const Color = C.Color ?? Cesium.Color;
+ if (Array.isArray(color))
+ return new Color(color[0], color[1], color[2], color[3] ?? 1);
+ return (
+ Color.fromCssColorString(String(color ?? DEFAULT_COLOR)) ??
+ Color.fromCssColorString(DEFAULT_COLOR)
+ );
+}
+
+/**
+ * The spec's grid as the wind sampler reads it. A rectangle across the
+ * antimeridian (west east of east) runs east past 180°.
+ */
+export function windGridOf(spec) {
+ const { west, south, north } = spec.rectangle;
+ let { east } = spec.rectangle;
+ if (east < west) east += 360;
+ const span = east - west;
+ const wraps = span >= 360 - 1e-9;
+ return {
+ u: spec.u,
+ v: spec.v,
+ nx: spec.width,
+ ny: spec.height,
+ lo1: west,
+ la1: north,
+ dx: span / (wraps ? spec.width : spec.width - 1),
+ dy: (north - south) / (spec.height - 1),
+ };
+}
+
+/**
+ * One `windStreamlines` field over `scene`.
+ * @param {{scene: object, spec: object, report?: (error: unknown) => void,
+ * cesium?: object,
+ * requestFrame?: (cb: (time: number) => void) => number,
+ * cancelFrame?: (id: number) => void, onDispose?: () => void}} options
+ */
+export function createWindStreamlines({
+ scene,
+ spec,
+ report = uncaught,
+ cesium: C = Cesium,
+ requestFrame = (cb) => globalThis.requestAnimationFrame(cb),
+ cancelFrame = (id) => globalThis.cancelAnimationFrame(id),
+ onDispose = () => {},
+}) {
+ if (
+ C.SceneMode?.SCENE3D !== undefined &&
+ scene.mode !== undefined &&
+ scene.mode !== C.SceneMode.SCENE3D
+ )
+ throw new TypeError(
+ 'the Cesium renderer draws wind streamlines in 3D only',
+ );
+
+ const live = () => !scene.isDestroyed?.();
+ const requestRender = () => {
+ if (live()) scene.requestRender();
+ };
+ let current = { ...spec, style: { ...spec.style } };
+ let alpha = spec.alpha ?? 1;
+ let paused = spec.paused === true;
+ let shown = true;
+ let disposed = false;
+ const cells = [];
+ let material = null;
+ let occluder = null;
+ let phaseTime = 0;
+ let visibleCells = 0;
+ let diagnostics = { pathCount: 0, vertexCount: 0, buildMs: 0, cellCount: 0 };
+ // The animation frame asked for, and when the highlight last moved.
+ let frameId = null;
+ let lastTime = null;
+ // 'drawn' is owed for the latest change, made at `changedAt`.
+ let owed = true;
+ let renders = 0;
+ let changedAt = 0;
+ const frameNumber = () => scene.frameState?.frameNumber ?? renders;
+ const drawnListeners = listenerList(report);
+
+ function clear() {
+ for (const cell of cells) {
+ if (live() && scene.primitives && !scene.primitives.isDestroyed?.())
+ scene.primitives.remove(cell.primitive);
+ if (!cell.primitive.isDestroyed?.()) cell.primitive.destroy?.();
+ }
+ cells.length = 0;
+ if (material && !material.isDestroyed?.()) material.destroy?.();
+ material = null;
+ occluder = null;
+ visibleCells = 0;
+ }
+
+ function styleUniforms() {
+ if (!material) return;
+ const color = toColor(C, current.style?.color);
+ material.uniforms.baseColor = color;
+ material.uniforms.tipSpeed = TIP_SPEED * (current.style?.speedFactor ?? 1);
+ material.uniforms.ghostAlpha = paused ? GHOST_ALPHA_PAUSED : GHOST_ALPHA;
+ material.uniforms.heightFade = alpha;
+ }
+
+ /** Trace and build; a failure leaves nothing built and throws. */
+ function build() {
+ try {
+ buildCells();
+ } catch (error) {
+ clear();
+ diagnostics = { pathCount: 0, vertexCount: 0, buildMs: 0, cellCount: 0 };
+ throw error;
+ }
+ }
+ function buildCells() {
+ clear();
+ const started = performance.now();
+ // The paths are traced round the whole globe, the wind wrapping east and
+ // west: a grid that does not span it is refused, not drawn wrapped.
+ const grid = windGridOf(current);
+ const { west, east } = current.rectangle;
+ if ((east < west ? east + 360 : east) - west < 360 - 1e-9)
+ throw new RangeError(
+ 'the Cesium renderer draws wind streamlines over the whole globe only',
+ );
+ const paths = bakeWindStreamlines(grid, {
+ count: current.pathBudget,
+ steps: current.steps,
+ });
+ // A grid no path runs through is refused, so its caller can draw it
+ // some other way.
+ if (!paths.length)
+ throw new RangeError('no wind streamlines run through this grid');
+ let vertexCount = 0;
+ material = new C.Material({
+ fabric: {
+ type: 'DrawWindStreamline',
+ uniforms: {
+ phaseTime,
+ ghostAlpha: GHOST_ALPHA,
+ heightFade: 0,
+ tipSpeed: TIP_SPEED,
+ baseColor: toColor(C, DEFAULT_COLOR),
+ },
+ source: FLOW_MATERIAL,
+ },
+ translucent: () => true,
+ });
+ styleUniforms();
+ const base = new C.PolylineMaterialAppearance({ material });
+ // Extend Cesium's own polyline shader rather than duplicate its
+ // expansion and precision code. Explicit facing also masks the far
+ // hemisphere when a scene keeps no globe depth for translucent objects.
+ const source = base.vertexShaderSource;
+ if (
+ !/void\s+main\s*\(\s*\)/.test(source) ||
+ !/v_st\.s\s*=\s*st\.s\s*;/.test(source)
+ )
+ throw new Error('Wind polyline shader entry unavailable');
+ const seededSource = source.replace(
+ /v_st\.s\s*=\s*st\.s\s*;/,
+ 'v_st.s = st.s * 0.999 + czm_batchTable_windSeed(batchId);',
+ );
+ const vertexShaderSource =
+ `out float v_windFacing;\n${seededSource}`.replace(
+ /void\s+main\s*\(\s*\)\s*\{/,
+ `void main() {\nvec3 windWorld = (czm_model * vec4(position3DHigh + position3DLow, 1.0)).xyz;\nv_windFacing = dot(normalize(windWorld), normalize(czm_viewerPositionWC - windWorld));\n`,
+ );
+ // EllipsoidalOccluder only tests points: a sphere occluder with an
+ // inscribed Earth sphere, whether or not the globe shows.
+ occluder = new C.Occluder(
+ new C.BoundingSphere(C.Cartesian3.ZERO, C.Ellipsoid.WGS84.minimumRadius),
+ scene.camera.positionWC,
+ );
+ const height = Number(current.heightM) || 0;
+ const width = current.style?.widthPx ?? 2.4;
+ for (const group of groupWindPaths(paths)) {
+ const cellPositions = [];
+ let cellVertexCount = 0;
+ const instances = group.paths.map((path) => {
+ const positions = path.coordinates.map(([lon, lat]) =>
+ C.Cartesian3.fromDegrees(lon, lat, height),
+ );
+ // Cesium's worker expands the lines; per-instance seeds keep the
+ // expanded vertex buffer off the main thread.
+ const geometry = new C.PolylineGeometry({
+ positions,
+ width,
+ arcType: C.ArcType?.NONE,
+ vertexFormat: C.PolylineMaterialAppearance.VERTEX_FORMAT,
+ });
+ cellPositions.push(...positions);
+ cellVertexCount += positions.length * 4 - 4;
+ return new C.GeometryInstance({
+ geometry,
+ attributes: {
+ windSeed: new C.GeometryInstanceAttribute({
+ componentDatatype: C.ComponentDatatype.FLOAT,
+ componentsPerAttribute: 1,
+ value: [path.seed],
+ }),
+ },
+ });
+ });
+ const appearance = new C.PolylineMaterialAppearance({
+ material,
+ vertexShaderSource,
+ translucent: true,
+ renderState: { depthTest: { enabled: true }, depthMask: false },
+ });
+ const primitive = new C.Primitive({
+ show: false,
+ geometryInstances: instances,
+ appearance,
+ asynchronous: true,
+ allowPicking: false,
+ releaseGeometryInstances: true,
+ compressVertices: false,
+ });
+ cells.push({
+ primitive,
+ sphere: C.BoundingSphere.fromPoints(cellPositions),
+ vertexCount: cellVertexCount,
+ });
+ scene.primitives.add(primitive);
+ vertexCount += cellVertexCount;
+ }
+ diagnostics = {
+ pathCount: paths.length,
+ vertexCount,
+ buildMs: performance.now() - started,
+ cellCount: cells.length,
+ };
+ }
+
+ // Which cells the eye can see, before each frame draws.
+ function cull() {
+ visibleCells = 0;
+ const camera = scene.camera;
+ const draws = shown && alpha > 0 && cells.length > 0 && camera;
+ let volume;
+ if (draws) {
+ occluder.cameraPosition = camera.positionWC;
+ volume = camera.frustum.computeCullingVolume(
+ camera.positionWC,
+ camera.directionWC,
+ camera.upWC,
+ );
+ }
+ for (const cell of cells) {
+ cell.primitive.show = Boolean(
+ draws &&
+ occluder.isBoundingSphereVisible(cell.sphere) &&
+ volume.computeVisibility(cell.sphere) !== C.Intersect.OUTSIDE,
+ );
+ if (cell.primitive.show) visibleCells += 1;
+ }
+ }
+ const page = globalThis.document;
+ const animating = () =>
+ !disposed &&
+ shown &&
+ !paused &&
+ alpha > 0 &&
+ visibleCells > 0 &&
+ page?.hidden !== true;
+ function step(time) {
+ frameId = null;
+ if (!animating()) {
+ lastTime = null;
+ return;
+ }
+ const elapsed = lastTime === null ? null : (time - lastTime) / 1000;
+ // A first frame (after a pause, a hidden page or nothing in view) moves
+ // one tick; otherwise the highlight moves by the time passed, and a frame
+ // is drawn, at most every STEP_SECONDS.
+ let moved = true;
+ if (elapsed === null) phaseTime += 1 / 60;
+ else if (elapsed >= STEP_SECONDS) phaseTime += elapsed;
+ else moved = false;
+ if (moved) {
+ lastTime = time;
+ if (material) material.uniforms.phaseTime = phaseTime % 10000;
+ requestRender();
+ }
+ frameId = requestFrame(step);
+ }
+ function animate() {
+ if (animating()) frameId ??= requestFrame(step);
+ else if (frameId !== null) {
+ cancelFrame(frameId);
+ frameId = null;
+ lastTime = null;
+ }
+ }
+
+ const ready = () => cells.every((cell) => cell.primitive.ready);
+ function changed() {
+ owed = true;
+ changedAt = frameNumber();
+ requestRender();
+ }
+ // A field that cannot be built is refused, holding nothing.
+ build();
+ const offPreRender = scene.preRender.addEventListener(() => {
+ cull();
+ animate();
+ });
+ // A hidden page stops the highlight; shown again, it starts afresh rather
+ // than jumping by the time it was hidden.
+ const onVisibility = () => {
+ lastTime = null;
+ animate();
+ };
+ page?.addEventListener?.('visibilitychange', onVisibility);
+ const offPostRender = scene.postRender.addEventListener(() => {
+ renders += 1;
+ // Nothing built (a rebuild failed) is never told drawn.
+ if (!owed || !shown || disposed || !cells.length) return;
+ if (!ready() || frameNumber() <= changedAt) {
+ requestRender();
+ return;
+ }
+ owed = false;
+ drawnListeners.fire();
+ });
+
+ changed();
+
+ return {
+ id: spec.id,
+ get show() {
+ return shown;
+ },
+ set show(value) {
+ const next = Boolean(value);
+ if (disposed || next === shown) return;
+ shown = next;
+ if (!shown) {
+ for (const cell of cells) cell.primitive.show = false;
+ visibleCells = 0;
+ animate();
+ }
+ changedAt = frameNumber();
+ requestRender();
+ },
+ update(patch = {}) {
+ if (disposed) return;
+ if (patch.kind !== undefined && patch.kind !== 'windStreamlines')
+ throw new TypeError('a field keeps its kind');
+ const retrace =
+ ['u', 'v', 'width', 'height', 'pathBudget', 'steps', 'heightM'].some(
+ (key) => key in patch && patch[key] !== current[key],
+ ) ||
+ (patch.rectangle !== undefined &&
+ ['west', 'south', 'east', 'north'].some(
+ (edge) => patch.rectangle[edge] !== current.rectangle?.[edge],
+ ));
+ const restroke =
+ patch.style?.widthPx !== undefined &&
+ patch.style.widthPx !== current.style?.widthPx;
+ current = {
+ ...current,
+ ...patch,
+ style: { ...current.style, ...patch.style },
+ };
+ if ('alpha' in patch) alpha = patch.alpha ?? 1;
+ if ('paused' in patch) paused = patch.paused === true;
+ if (retrace || restroke)
+ try {
+ build();
+ } catch (error) {
+ // It draws nothing until a change builds again.
+ report(error);
+ }
+ else styleUniforms();
+ cull();
+ animate();
+ changed();
+ },
+ on(event, cb) {
+ if (event !== 'drawn') return () => {};
+ return drawnListeners.on(cb);
+ },
+ dispose() {
+ if (disposed) return;
+ disposed = true;
+ if (frameId !== null) cancelFrame(frameId);
+ frameId = null;
+ offPreRender();
+ offPostRender();
+ page?.removeEventListener?.('visibilitychange', onVisibility);
+ drawnListeners.clear();
+ clear();
+ requestRender();
+ onDispose();
+ },
+ /** For tests and diagnostics: what it built and draws. */
+ diagnostics: () => ({
+ ...diagnostics,
+ visibleCells,
+ ready: ready(),
+ animating: frameId !== null,
+ phaseTime,
+ }),
+ };
+}
diff --git a/src/render/cesium/drawStreamlines.test.mjs b/src/render/cesium/drawStreamlines.test.mjs
new file mode 100644
index 000000000..58d8e3aeb
--- /dev/null
+++ b/src/render/cesium/drawStreamlines.test.mjs
@@ -0,0 +1,547 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ BoundingSphere,
+ Cartesian3,
+ Ellipsoid,
+ Event,
+ Intersect,
+ Occluder,
+ PerspectiveFrustum,
+} from 'cesium';
+import { createWindStreamlines, windGridOf } from './drawStreamlines.js';
+import { createCesiumFields } from './drawFields.js';
+import { bakeWindStreamlines } from '../../layers/wind/streamlines.js';
+
+const grid = () => ({
+ nx: 4,
+ ny: 3,
+ lo1: -180,
+ la1: 90,
+ dx: 90,
+ dy: 90,
+ u: new Float32Array(12).fill(15),
+ v: new Float32Array(12),
+});
+// The grid above as a field spec: 4 columns wrapping the globe, 3 rows.
+const SPEC = Object.freeze({
+ kind: 'windStreamlines',
+ id: 'wind',
+ u: new Float32Array(12).fill(15),
+ v: new Float32Array(12),
+ width: 4,
+ height: 3,
+ rectangle: { west: -180, south: -90, east: 180, north: 90 },
+ pathBudget: 7200,
+ steps: 16,
+ style: { color: '#80c9e6', widthPx: 2.4 },
+ heightM: 12000,
+});
+
+function harness() {
+ 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 frames = [];
+ const preRender = new Event();
+ const postRender = new Event();
+ let renders = 0;
+ const scene = {
+ preRender,
+ postRender,
+ requestRender() {
+ renders += 1;
+ },
+ get renders() {
+ return renders;
+ },
+ 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 },
+ },
+ 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,
+ frames,
+ make: (patch = {}) =>
+ createWindStreamlines({
+ scene,
+ cesium: C,
+ spec: { ...SPEC, ...patch },
+ requestFrame: (cb) => {
+ frames.push(cb);
+ return frames.length;
+ },
+ cancelFrame: (id) => {
+ frames[id - 1] = null;
+ },
+ }),
+ /** One render: the frame events around it. */
+ render() {
+ preRender.raiseEvent();
+ postRender.raiseEvent();
+ },
+ };
+}
+const field = () => ({
+ nx: 4,
+ ny: 3,
+ lo1: -180,
+ la1: 90,
+ dx: 90,
+ dy: 90,
+ u: new Float32Array(12).fill(15),
+ v: new Float32Array(12),
+});
+
+test('the spec reads back as the wind grid it came from', () => {
+ const { u, v, ...rest } = windGridOf(SPEC);
+ const { u: gu, v: gv, ...want } = grid();
+ assert.deepEqual(rest, want);
+ assert.deepEqual([...u], [...gu]);
+ const regional = windGridOf({
+ ...SPEC,
+ rectangle: { west: -100, south: 20, east: -70, north: 50 },
+ });
+ assert.equal(regional.dx, 10, 'a regional grid does not wrap');
+ assert.equal(regional.dy, 15);
+ const across = windGridOf({
+ ...SPEC,
+ rectangle: { west: 170, south: 20, east: -170, north: 50 },
+ });
+ assert.equal(across.lo1, 170);
+ assert.equal(across.dx, 20 / 3, 'across the antimeridian it runs east');
+});
+
+test('streamlines build native cells; the highlight moves without rebuilding', () => {
+ const h = harness();
+ const field = h.make();
+ 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.vertexShaderSource.includes(
+ 'czm_batchTable_windSeed(batchId)',
+ ),
+ );
+ const { uniforms, source } = batch.appearance.material;
+ assert.ok(source.includes('smoothstep(0.0, 0.065, v_windFacing)'));
+ assert.ok(source.includes('mix(baseColor.rgb'));
+ assert.equal(
+ h.builds(),
+ 0,
+ 'expanded geometry is deferred to Cesium workers',
+ );
+ const diagnostics = field.diagnostics();
+ assert.ok(diagnostics.pathCount > 7000 && diagnostics.pathCount <= 7200);
+ assert.ok(diagnostics.vertexCount > 0);
+ assert.equal(diagnostics.cellCount, 72);
+ const instances = [...h.members].flatMap((p) => p.geometryInstances);
+ const baked = bakeWindStreamlines(grid());
+ 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 instance of instances) assert.equal(instance.geometry.width, 2.4);
+ for (const cell of h.members) {
+ assert.equal(cell.appearance.material, batch.appearance.material);
+ assert.equal(cell.compressVertices, false);
+ assert.equal(cell.releaseGeometryInstances, true);
+ }
+ assert.equal(uniforms.ghostAlpha, 0.25);
+ assert.equal(uniforms.heightFade, 1);
+ assert.ok(Math.abs(uniforms.tipSpeed - 0.16) < 1e-12);
+ // A render culls the cells and starts the highlight on the page's frames.
+ h.render();
+ assert.equal(h.frames.length, 1);
+ h.frames.at(-1)(1000);
+ const first = uniforms.phaseTime;
+ assert.ok(first > 0);
+ const asked = h.scene.renders;
+ h.frames.at(-1)(1010);
+ assert.equal(uniforms.phaseTime, first, 'at most 30 steps a second');
+ assert.equal(h.scene.renders, asked, 'and no frame drawn between them');
+ h.frames.at(-1)(1040);
+ assert.ok(Math.abs(uniforms.phaseTime - first - 0.04) < 1e-9);
+ assert.equal(h.scene.renders, asked + 1);
+ field.update({ paused: true });
+ assert.equal(uniforms.ghostAlpha, 0.34, 'paused raises the ghost');
+ const held = uniforms.phaseTime;
+ assert.equal(h.frames.at(-1), null, 'paused stops the frames');
+ field.update({ paused: false, alpha: 0.5, style: { speedFactor: 2 } });
+ assert.equal(uniforms.heightFade, 0.5);
+ assert.ok(Math.abs(uniforms.tipSpeed - 0.32) < 1e-12);
+ assert.equal(uniforms.phaseTime, held);
+ assert.equal(h.members.size, 72, 'style, alpha and pause never rebuild');
+ field.dispose();
+ assert.equal(h.members.size, 0);
+ assert.equal(h.scene.preRender.numberOfListeners, 0);
+ assert.equal(h.scene.postRender.numberOfListeners, 0);
+});
+
+test("streamlines tell 'drawn' once every cell is ready, never while hidden", () => {
+ const h = harness();
+ const field = h.make();
+ let drawn = 0;
+ field.on('drawn', () => (drawn += 1));
+ const [batch] = h.members;
+ batch.ready = false;
+ h.render();
+ h.render();
+ assert.equal(drawn, 0, 'every cell must be ready');
+ batch.ready = true;
+ h.render();
+ assert.equal(drawn, 1);
+ h.render();
+ assert.equal(drawn, 1);
+ field.show = false;
+ field.update({ alpha: 0.4 });
+ h.render();
+ h.render();
+ assert.equal(drawn, 1, 'never while hidden');
+ assert.equal(batch.show, false);
+ field.show = true;
+ h.render();
+ h.render();
+ assert.equal(drawn, 2, 'told once shown');
+ field.update({ u: new Float32Array(12).fill(10) });
+ assert.equal(batch.destroyed, true, 'a new grid traces again');
+ h.render();
+ h.render();
+ assert.equal(drawn, 3);
+ field.dispose();
+});
+
+test('a failed build is refused, holding nothing', () => {
+ 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.throws(() => h.make(), /later cell failed/);
+ assert.equal(h.members.size, 0);
+ for (const batch of built) {
+ assert.equal(batch.destroyed, true);
+ assert.equal(batch.appearance.material.destroyed, true);
+ }
+ assert.equal(h.scene.preRender.numberOfListeners, 0);
+});
+
+test('a grid no path runs through is refused, holding nothing', () => {
+ const h = harness();
+ assert.throws(
+ () => h.make({ u: new Float32Array(12), v: new Float32Array(12) }),
+ /no wind streamlines/,
+ );
+ assert.equal(h.members.size, 0);
+ assert.equal(h.scene.preRender.numberOfListeners, 0);
+});
+
+test('the Cesium fields draw wind streamlines under their id until disposed', () => {
+ const h = harness();
+ const fields = createCesiumFields({ scene: h.scene, cesium: h.C });
+ const field = fields.field({ ...SPEC });
+ assert.ok(h.members.size > 0);
+ assert.equal(fields.has('wind'), true);
+ assert.throws(() => fields.field({ ...SPEC }), /is live/);
+ field.dispose();
+ assert.equal(fields.has('wind'), false);
+ assert.equal(h.members.size, 0);
+ fields.field({ ...SPEC });
+ fields.dispose();
+ assert.equal(fields.has('wind'), false);
+ assert.equal(h.members.size, 0);
+});
+
+test('a grid short of the whole globe is refused, not drawn wrapped', () => {
+ const h = harness();
+ for (const rectangle of [
+ { west: -100, south: -90, east: 80, north: 90 },
+ // Four columns over 300°: its samples nearly span the globe; it does not.
+ { west: -150, south: -90, east: 150, north: 90 },
+ ])
+ assert.throws(() => h.make({ rectangle }), /whole globe only/);
+ assert.equal(h.members.size, 0);
+ const across = h.make({
+ rectangle: { west: 0, south: -90, east: -0.000000000001, north: 90 },
+ });
+ assert.ok(h.members.size > 0, 'a rectangle across the antimeridian wraps');
+ across.dispose();
+});
+
+test('a rebuild that fails draws nothing and is never told drawn', () => {
+ const reported = [];
+ const h = harness();
+ const field = createWindStreamlines({
+ scene: h.scene,
+ cesium: h.C,
+ spec: { ...SPEC },
+ report: (error) => reported.push(error),
+ requestFrame: () => 1,
+ cancelFrame() {},
+ });
+ let drawn = 0;
+ field.on('drawn', () => (drawn += 1));
+ h.render();
+ h.render();
+ assert.equal(drawn, 1);
+ const asked = h.scene.renders;
+ field.update({ u: new Float32Array(12), v: new Float32Array(12) });
+ assert.equal(reported.length, 1);
+ assert.equal(h.members.size, 0);
+ h.render();
+ h.render();
+ assert.equal(drawn, 1, 'nothing drawn is never told');
+ assert.ok(h.scene.renders - asked <= 1, 'and asks no frames for it');
+ field.dispose();
+});
+
+test('the highlight stops when hidden, transparent or out of view, and starts again', () => {
+ const h = harness();
+ const field = h.make();
+ const live = () => h.frames.filter(Boolean).length;
+ h.render();
+ assert.equal(live(), 1);
+ field.show = false;
+ assert.equal(live(), 0, 'hidden');
+ field.show = true;
+ h.render();
+ assert.equal(live(), 1);
+ field.update({ alpha: 0 });
+ assert.equal(live(), 0, 'transparent');
+ field.update({ alpha: 1 });
+ h.render();
+ assert.equal(live(), 1);
+ h.visibility.horizon = () => false;
+ h.render();
+ assert.equal(live(), 0, 'every cell behind the Earth');
+ h.visibility.horizon = () => true;
+ h.render();
+ assert.equal(live(), 1, 'the next render in view starts it');
+ field.dispose();
+ assert.equal(live(), 0, 'dispose cancels the frame it asked for');
+});
+
+test('a hidden page stops the highlight; shown again, it starts afresh', () => {
+ const listeners = new Set();
+ const document = globalThis.document;
+ const page = {
+ hidden: false,
+ addEventListener: (type, cb) => listeners.add(cb),
+ removeEventListener: (type, cb) => listeners.delete(cb),
+ };
+ globalThis.document = page;
+ try {
+ const h = harness();
+ const field = h.make();
+ // Whether the frame asked for last is still pending.
+ const pending = () => h.frames.at(-1) !== null;
+ const { uniforms } = [...h.members][0].appearance.material;
+ h.render();
+ h.frames.at(-1)(1000);
+ h.frames.at(-1)(1100);
+ const before = uniforms.phaseTime;
+ assert.ok(Math.abs(before - 1 / 60 - 0.1) < 1e-9, 'time passed moves it');
+ h.frames.at(-1)(1400);
+ assert.ok(
+ Math.abs(uniforms.phaseTime - before - 0.3) < 1e-9,
+ 'a stall still moves it by the time passed',
+ );
+ page.hidden = true;
+ for (const cb of listeners) cb();
+ assert.equal(pending(), false, 'a hidden page asks no frames');
+ page.hidden = false;
+ for (const cb of listeners) cb();
+ assert.equal(pending(), true);
+ const shown = uniforms.phaseTime;
+ h.frames.at(-1)(60_000);
+ assert.ok(Math.abs(uniforms.phaseTime - shown - 1 / 60) < 1e-9);
+ field.dispose();
+ assert.equal(listeners.size, 0);
+ } finally {
+ globalThis.document = document;
+ }
+});
+
+test('a scene not in 3D refuses streamlines', () => {
+ const h = harness();
+ h.C.SceneMode = { SCENE3D: 3 };
+ h.scene.mode = 2;
+ assert.throws(() => h.make(), /3D only/);
+});
+
+test('cell visibility combines horizon, frustum and alpha', () => {
+ const h = harness();
+ const field = h.make();
+ const batches = [...h.members];
+ 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;
+ h.render();
+ assert.equal(field.diagnostics().visibleCells, 12);
+ for (let i = 0; i < batches.length; i++)
+ assert.equal(batches[i].show, i % 6 === 0);
+ assert.equal(h.visibility.horizonTests, 72);
+ assert.equal(h.visibility.frustumTests, 36);
+ field.update({ alpha: 0 });
+ h.render();
+ assert.equal(field.diagnostics().visibleCells, 0);
+ for (const batch of batches) assert.equal(batch.show, false);
+ assert.equal(h.visibility.horizonTests, 72, 'alpha 0 tests nothing');
+ assert.equal(h.occluderBuilds(), 1, 'the occluder is reused');
+ field.dispose();
+});
+
+test('real Cesium sphere culling hides the far hemisphere and a sky-facing view', () => {
+ const h = harness();
+ h.C.Occluder = Occluder;
+ const field = h.make();
+ const camera = h.scene.camera;
+ camera.frustum = new PerspectiveFrustum({
+ fov: Math.PI / 3,
+ aspectRatio: 1.5,
+ near: 1,
+ far: 5e7,
+ });
+ h.render();
+ const facing = field.diagnostics().visibleCells;
+ assert.ok(facing > 0 && facing < 72);
+ for (let i = 0; i < h.spheres.length; i++)
+ if (h.spheres[i].sphere.center.x < -5e6)
+ assert.equal([...h.members][i].show, false);
+ camera.directionWC.x = 1;
+ h.render();
+ assert.equal(field.diagnostics().visibleCells, 0);
+ field.dispose();
+});
diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js
index 8f59ccd12..00ef48dd7 100644
--- a/src/render/cesium/globe.js
+++ b/src/render/cesium/globe.js
@@ -639,6 +639,8 @@ provideUnboundGlobe((viewer) => {
]);
if (typeof viewer.scene.globe?.show === 'boolean')
capabilities.add('globeVisibility');
+ // The globe's surface shading needs a globe to shade.
+ if (viewer.scene.globe) capabilities.add('surfaceShading');
const { port, dispose } = createCesiumGlobe(viewer, {
capabilities,
requestRender: () => viewer.scene.requestRender?.(),
diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js
index dedc020e7..7b7c5e0d4 100644
--- a/src/render/cesium/harness.js
+++ b/src/render/cesium/harness.js
@@ -40,6 +40,8 @@ export const CESIUM_CHECKS = new Set([
'draw.columns.shown',
'draw.drawOrder',
'draw.drillPick',
+ 'draw.field.rasterShell',
+ 'draw.field.windStreamlines',
'draw.icons.distance',
'draw.icons.update',
'draw.lines.depthFailDash',
diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js
index 2a115b3f7..1747fb371 100644
--- a/src/render/cesium/ports.js
+++ b/src/render/cesium/ports.js
@@ -66,6 +66,8 @@ export function cesiumCapabilities(scene, only) {
'models',
'quads',
'meshes',
+ // Raster shells; other field kinds are refused.
+ 'fields',
'followFrame',
'cameraChangeThreshold',
...GPU_ICON_CAPABILITIES,
diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs
index 722b96208..6a8b3d995 100644
--- a/src/render/cesium/ports.test.mjs
+++ b/src/render/cesium/ports.test.mjs
@@ -29,7 +29,7 @@ test('capabilities follow what the scene supports', () => {
'surfaceShading',
];
const globe = { show: true };
- const draw = ['models', 'quads', 'meshes'];
+ const draw = ['models', 'quads', 'meshes', 'fields'];
assert.deepEqual(cesiumCapabilities({}), [...draw, ...effects]);
// A scene with a globe reads its visibility back.
assert.deepEqual(cesiumCapabilities({ globe }), [
diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json
index 6198d24d7..3a7a147d0 100644
--- a/src/render/cesiumAllowList.json
+++ b/src/render/cesiumAllowList.json
@@ -5,10 +5,6 @@
"src/app/scene.js",
"src/app/viewer.js",
"src/data/geoImportPins.js",
- "src/layers/weather/shellRendering.js",
- "src/layers/wind/gpuRendering.js",
- "src/layers/wind/relief.js",
- "src/layers/wind/rendering.js",
"src/maps/catalog.js",
"src/maps/controller.js",
"src/maps/google3d.js",
diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js
index 450abc3d2..258fc71df 100644
--- a/src/render/conformance/checks/ports.js
+++ b/src/render/conformance/checks/ports.js
@@ -786,6 +786,64 @@ export function portChecks() {
},
{ capability: 'fields' },
),
+ check(
+ 'draw.field.windStreamlines',
+ "streamlines' 'drawn' comes once per change, never while hidden",
+ async (h, r) => {
+ await overAustin(h, r, 2000000);
+ const width = 8;
+ const height = 5;
+ const errors = [];
+ const offError = r.on('error', (e) => errors.push(e));
+ const field = r.draw.field({
+ kind: 'windStreamlines',
+ id: 'conf:wind',
+ u: new Float32Array(width * height).fill(12),
+ v: new Float32Array(width * height).fill(4),
+ width,
+ height,
+ rectangle: { west: -180, south: -80, east: 180, north: 80 },
+ pathBudget: 200,
+ steps: 8,
+ style: { color: '#80c9e6', widthPx: 2 },
+ heightM: 12000,
+ alpha: 1,
+ });
+ let drawnCount = 0;
+ const off = field.on('drawn', () => (drawnCount += 1));
+ // Frames until 'drawn' has come `want` times, for at most 20 s.
+ const until = async (want) => {
+ const deadline = Date.now() + 20000;
+ while (drawnCount < want && Date.now() < deadline)
+ await drawn(h, r, 1);
+ };
+ try {
+ await until(1);
+ equal(drawnCount, 1, 'drawn once made');
+ await drawn(h, r, 4);
+ equal(drawnCount, 1, 'not again while nothing changes');
+ field.update({ alpha: 0.5 });
+ await until(2);
+ equal(drawnCount, 2, 'drawn after a new alpha');
+ field.update({ paused: true });
+ await until(3);
+ equal(drawnCount, 3, 'drawn once paused');
+ field.show = false;
+ field.update({ alpha: 0.4 });
+ await drawn(h, r, 6);
+ equal(drawnCount, 3, 'never while hidden');
+ field.show = true;
+ await until(4);
+ equal(drawnCount, 4, 'drawn once shown again');
+ deepEqual(errors, [], 'no errors');
+ } finally {
+ off();
+ offError();
+ field.dispose();
+ }
+ },
+ { capability: 'fields' },
+ ),
check(
'draw.drawOrder',
'of sets drawn over depth, the higher draw order is on top and picked',
diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs
index 808235462..67a73aaf7 100644
--- a/src/render/unboundCamera.test.mjs
+++ b/src/render/unboundCamera.test.mjs
@@ -133,6 +133,11 @@ const DRAW_FROM_CALLER = new Set([
// It configures the sources of layers, the traffic layer's among them,
// that draw and read the surface through the ports alone.
'./application/sources',
+ // The layer catalog and the standalone catalog over it: their layers, the
+ // weather shells and the wind flow and relief among them, draw, read the
+ // eye and shade the globe through the ports alone.
+ './application/layers',
+ './standalone/catalog',
]);
/**