From 20138cb31381e9a710f4578b3aaf62315b8d63fe Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Wed, 11 Nov 2026 17:14:56 -0800 Subject: [PATCH] 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. --- docs/RENDERER-CONTRACT.md | 10 +++--- src/layers/wind/streamlines.js | 42 +++++++++++++++++----- src/render/cesium/drawStreamlines.js | 17 +++++---- src/render/cesium/drawStreamlines.test.mjs | 39 +++++++++++++++----- 4 files changed, 79 insertions(+), 29 deletions(-) diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 2c1478f3b..04058271b 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -74,11 +74,11 @@ optional, so a renderer written before it still conforms: 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. The Cesium adapter lists `fields` and - draws `rasterShell` and `windStreamlines`. 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. + draws `rasterShell` and `windStreamlines`. It reads the grid's samples as + points, the first column at `rectangle.west` and the first row at + `rectangle.north`, rows running south. Over the whole globe its paths + wrap east and west; over part of it they seed inside the rectangle, + equal-area, and stop at its edges. - `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/src/layers/wind/streamlines.js b/src/layers/wind/streamlines.js index 16272896f..81acf2a99 100644 --- a/src/layers/wind/streamlines.js +++ b/src/layers/wind/streamlines.js @@ -10,8 +10,19 @@ export const WIND_CELL_DEGREES = 30; const DEGREE_METERS = 111320; const GOLDEN_ANGLE = 137.50776405003785; +/** + * Whether a point is inside `bounds` (a rectangle in degrees, east of west; + * east may run past 180°), or there are none. + */ +function within(bounds, lon, lat) { + if (!bounds) return true; + if (lat < bounds.south || lat > bounds.north) return false; + const span = bounds.east - bounds.west; + return (((lon - bounds.west) % 360) + 360) % 360 <= span; +} + /** One bounded midpoint step. The integration interval is field time, not playback time. */ -function advance(field, point, seconds, scratch) { +function advance(field, point, seconds, scratch, bounds = null) { sampleWind(field, point[0], point[1], scratch); if ( !Number.isFinite(scratch.u + scratch.v) || @@ -37,6 +48,7 @@ function advance(field, point, seconds, scratch) { const lat = point[1] + (scratch.v * dt) / DEGREE_METERS; if (Math.abs(lat) > 88.5 || Math.abs(lon - point[0]) > 180) return null; if (Math.abs(lon - point[0]) + Math.abs(lat - point[1]) < 1e-8) return null; + if (!within(bounds, lon, lat)) return null; return [lon, lat]; } @@ -44,10 +56,18 @@ function advance(field, point, seconds, scratch) { * Bake geographic streamlines once from an immutable forecast snapshot. * Equal-area seeds avoid polar overpopulation. Increasing path position always * follows the wind; paths stop at the map seam, poles, calm or missing samples. + * With `bounds` (a field over part of the globe: degrees, east of west, east + * past 180° across the antimeridian), seeds fall inside it, equal-area, and + * paths stop at its edges. */ export function bakeWindStreamlines( field, - { count = WIND_PATH_LIMIT, steps = WIND_PATH_STEPS, stepSeconds = 1800 } = {}, + { + count = WIND_PATH_LIMIT, + steps = WIND_PATH_STEPS, + stepSeconds = 1800, + bounds = null, + } = {}, ) { if ( !field || @@ -73,14 +93,18 @@ export function bakeWindStreamlines( ); const paths = []; const scratch = { u: 0, v: 0 }; + const rad = Math.PI / 180; + const south = Math.max(-88, bounds ? bounds.south : -88) * rad; + const north = Math.min(88, bounds ? bounds.north : 88) * rad; + const lonSpan = bounds ? bounds.east - bounds.west : 360; for (let seed = 0; seed < budget; seed++) { - const lon = normalizeLongitude(seed * GOLDEN_ANGLE); + const lon = bounds + ? normalizeLongitude(bounds.west + ((seed * GOLDEN_ANGLE) % lonSpan)) + : normalizeLongitude(seed * GOLDEN_ANGLE); + const share = (seed + 0.5) / budget; const lat = - (Math.asin( - (((seed + 0.5) / budget) * 2 - 1) * Math.sin((88 * Math.PI) / 180), - ) * - 180) / - Math.PI; + Math.asin(Math.sin(south) + share * (Math.sin(north) - Math.sin(south))) / + rad; const center = [lon, lat]; sampleWind(field, lon, lat, scratch); const speed = Math.hypot(scratch.u, scratch.v); @@ -93,7 +117,7 @@ export function bakeWindStreamlines( ]) { let point = center; for (let step = 0; step < halfSteps; step++) { - point = advance(field, point, direction * interval, scratch); + point = advance(field, point, direction * interval, scratch, bounds); if (!point) break; points.push(point); } diff --git a/src/render/cesium/drawStreamlines.js b/src/render/cesium/drawStreamlines.js index d39e4b9b7..ceb031276 100644 --- a/src/render/cesium/drawStreamlines.js +++ b/src/render/cesium/drawStreamlines.js @@ -177,17 +177,20 @@ export function createWindStreamlines({ 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. + // 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, 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 { 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. diff --git a/src/render/cesium/drawStreamlines.test.mjs b/src/render/cesium/drawStreamlines.test.mjs index 58d8e3aeb..449e50d01 100644 --- a/src/render/cesium/drawStreamlines.test.mjs +++ b/src/render/cesium/drawStreamlines.test.mjs @@ -381,15 +381,13 @@ test('the Cesium fields draw wind streamlines under their id until disposed', () assert.equal(h.members.size, 0); }); -test('a grid short of the whole globe is refused, not drawn wrapped', () => { +test('a grid over part of the globe draws inside it, not 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 part = h.make({ + rectangle: { west: -100, south: -40, east: 80, north: 60 }, + }); + assert.ok(h.members.size > 0, 'drawn'); + part.dispose(); const across = h.make({ rectangle: { west: 0, south: -90, east: -0.000000000001, north: 90 }, }); @@ -397,6 +395,31 @@ test('a grid short of the whole globe is refused, not drawn wrapped', () => { across.dispose(); }); +test('paths over part of the globe seed and stay inside it', () => { + const bounds = { west: 170, south: -20, east: 230, north: 30 }; + const field = { + nx: 7, + ny: 6, + lo1: 170, + la1: 30, + dx: 10, + dy: 10, + u: new Float32Array(42).fill(40), + v: new Float32Array(42).fill(5), + }; + const paths = bakeWindStreamlines(field, { count: 400, bounds }); + assert.ok(paths.length > 100, `${paths.length} paths`); + for (const path of paths) + for (const [lon, lat] of path.coordinates) { + assert.ok(lat >= bounds.south && lat <= bounds.north, `lat ${lat}`); + const east = (((lon - bounds.west) % 360) + 360) % 360; + assert.ok(east <= bounds.east - bounds.west, `lon ${lon}`); + } + // Without bounds, seeds fill the globe as they did. + const global = bakeWindStreamlines(grid(), { count: 50 }); + assert.ok(global.some((p) => Math.abs(p.coordinates[0][1]) > 60)); +}); + test('a rebuild that fails draws nothing and is never told drawn', () => { const reported = []; const h = harness();