Files
gods-eye-view/src/render/cesium/drawStreamlines.js
T
Sameh Khamis 20138cb313 Wind streamlines over part of the globe on the Cesium renderer
A windStreamlines grid short of 360 degrees of longitude is no longer
refused: the paths seed inside its rectangle, equal-area, and stop at its
edges. The baker takes the rectangle as optional bounds; a grid round the
globe bakes as it did.
2026-11-11 17:14:56 -08:00

473 lines
16 KiB
JavaScript

/**
* @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();
// A grid round the whole globe wraps the wind east and west; one over
// part of it seeds inside it, and its paths stop at its edges.
const grid = windGridOf(current);
const { west, south, north } = current.rectangle;
const east =
current.rectangle.east < west
? current.rectangle.east + 360
: current.rectangle.east;
const bounds =
east - west >= 360 - 1e-9 ? null : { west, south, east, north };
const paths = bakeWindStreamlines(grid, {
count: current.pathBudget,
steps: current.steps,
bounds,
});
// 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,
}),
};
}