Draw submarine cables through the renderer's draw and camera ports

Cable lines, landing pins, polygon fills, reference stems and reference
points are now five draw sets per layer (submarine-cables:N:lines and so
on) instead of GeoJSON data sources and entities. Clicks resolve through
the draw hit; flights and the sweep's eye go through the camera port.
The layer keeps the styling the GeoJSON loader gave it: cable colours,
widths and alphas, simplestyle stroke, fill and marker properties, fills
that keep the source's alpha, raised polygons at their heights, the
default pin image, and features without a reference drawn but neither
picked nor culled. Lines are densified along rhumb lines at the
renderer's own granularity, so the draped geodesic arcs land on the same
vertices the rhumb-line polylines did.

Supporting pieces:
- geo/rhumb, geo/horizon and geo/geodesic port the default renderer's
  rhumb line, ellipsoidal occluder and Vincenty inverse; the stub
  renderer now uses the shared horizon test and Vincenty inverse
  instead of its own copies. render/color gains cssColor, which reads
  CSS colours as the renderer does (hex, rgb, hsl; not named colours).
- The Cesium draw port changes a line in place when only whether it
  shows changes (draped, on its ground primitive, waiting for it to be
  ready rather than restarting its build) or where an undraped line
  runs; anything else still rebuilds. Icon sets honour their blend.

Ingestion, interaction, overlay, policy, rendering, state and surface no
longer import Cesium and leave the allow-list. Pins are culled at the
horizon each frame by the draw port instead of on the sweep, and
marker-symbol glyphs are not drawn inside pins.
This commit is contained in:
Sameh Khamis committed 2026-11-06 22:10:53 -08:00
1 parent f24b66d80d
commit e74c7c1f44
29 files changed
+2260 -2064

No files matched your search

+150
View File
@@ -0,0 +1,150 @@
/**
* @module geo/geodesic
* @description Surface distance along the WGS84 geodesic between two
* points, by the default renderer's own method (`EllipsoidGeodesic`,
* Vincenty's inverse formula): the same series in the same order, so the
* distance agrees with the renderer's to floating-point noise. Angles in
* radians, distances in metres.
*/
import { WGS84 } from './ellipsoid.js';
const MAJOR = WGS84.radii.x;
const MINOR = WGS84.radii.z;
const FLATTENING = (MAJOR - MINOR) / MAJOR;
const EPSILON12 = 1e-12;
/**
* Vincenty converges in a handful of steps except between nearly antipodal
* points, where it may not converge at all; stop there instead of hanging.
*/
const MAX_ITERATIONS = 200;
/** Vincenty's longitude correction, shared with the direct series. */
export function deltaLambda(
sineAlpha,
cosineSquaredAlpha,
sigma,
sineSigma,
cosineSigma,
cosineTwiceSigmaMidpoint,
) {
const f = FLATTENING;
const C =
(f * cosineSquaredAlpha * (4.0 + f * (4.0 - 3.0 * cosineSquaredAlpha))) /
16.0;
return (
(1.0 - C) *
f *
sineAlpha *
(sigma +
C *
sineSigma *
(cosineTwiceSigmaMidpoint +
C *
cosineSigma *
(2.0 * cosineTwiceSigmaMidpoint * cosineTwiceSigmaMidpoint - 1.0)))
);
}
/**
* Vincenty's inverse: the geodesic from (lon1, lat1) to (lon2, lat2),
* radians, as its length in metres, its start heading and its u².
*/
export function geodesicInverse(lon1, lat1, lon2, lat2) {
const l = lon2 - lon1;
const u1 = Math.atan((1 - FLATTENING) * Math.tan(lat1));
const u2 = Math.atan((1 - FLATTENING) * Math.tan(lat2));
const cosineU1 = Math.cos(u1);
const sineU1 = Math.sin(u1);
const cosineU2 = Math.cos(u2);
const sineU2 = Math.sin(u2);
const cc = cosineU1 * cosineU2;
const cs = cosineU1 * sineU2;
const ss = sineU1 * sineU2;
const sc = sineU1 * cosineU2;
let lambda = l;
let lambdaDot;
let cosineLambda;
let sineLambda;
let sigma;
let cosineSigma;
let sineSigma;
let cosineSquaredAlpha;
let cosineTwiceSigmaMidpoint;
let iterations = 0;
do {
cosineLambda = Math.cos(lambda);
sineLambda = Math.sin(lambda);
const temp = cs - sc * cosineLambda;
sineSigma = Math.sqrt(
cosineU2 * cosineU2 * sineLambda * sineLambda + temp * temp,
);
cosineSigma = ss + cc * cosineLambda;
sigma = Math.atan2(sineSigma, cosineSigma);
let sineAlpha;
if (sineSigma === 0.0) {
sineAlpha = 0.0;
cosineSquaredAlpha = 1.0;
} else {
sineAlpha = (cc * sineLambda) / sineSigma;
cosineSquaredAlpha = 1.0 - sineAlpha * sineAlpha;
}
lambdaDot = lambda;
cosineTwiceSigmaMidpoint = cosineSigma - (2.0 * ss) / cosineSquaredAlpha;
if (!isFinite(cosineTwiceSigmaMidpoint)) cosineTwiceSigmaMidpoint = 0.0;
lambda =
l +
deltaLambda(
sineAlpha,
cosineSquaredAlpha,
sigma,
sineSigma,
cosineSigma,
cosineTwiceSigmaMidpoint,
);
} while (
Math.abs(lambda - lambdaDot) > EPSILON12 &&
++iterations < MAX_ITERATIONS
);
const uSquared =
(cosineSquaredAlpha * (MAJOR * MAJOR - MINOR * MINOR)) / (MINOR * MINOR);
const A =
1.0 +
(uSquared *
(4096.0 + uSquared * (uSquared * (320.0 - 175.0 * uSquared) - 768.0))) /
16384.0;
const B =
(uSquared *
(256.0 + uSquared * (uSquared * (74.0 - 47.0 * uSquared) - 128.0))) /
1024.0;
const cosineSquaredTwiceSigmaMidpoint =
cosineTwiceSigmaMidpoint * cosineTwiceSigmaMidpoint;
const deltaSigma =
B *
sineSigma *
(cosineTwiceSigmaMidpoint +
(B *
(cosineSigma * (2.0 * cosineSquaredTwiceSigmaMidpoint - 1.0) -
(B *
cosineTwiceSigmaMidpoint *
(4.0 * sineSigma * sineSigma - 3.0) *
(4.0 * cosineSquaredTwiceSigmaMidpoint - 3.0)) /
6.0)) /
4.0);
return {
distance: MINOR * A * (sigma - deltaSigma),
startHeading: Math.atan2(cosineU2 * sineLambda, cs - sc * cosineLambda),
uSquared,
};
}
/**
* Geodesic surface distance between two points; heights are ignored.
* @param {{lon: number, lat: number}} start Radians.
* @param {{lon: number, lat: number}} end Radians.
* @returns {number} Metres.
*/
export function surfaceDistance(start, end) {
return geodesicInverse(start.lon, start.lat, end.lon, end.lat).distance;
}
+47
View File
@@ -0,0 +1,47 @@
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import test from 'node:test';
import { surfaceDistance } from './geodesic.js';
test('surface distance matches the default renderer’s geodesic', () => {
let seed = 11;
const random = () => (seed = (seed * 16807) % 2147483647) / 2147483647;
const d = Math.PI / 180;
const geodesic = new Cesium.EllipsoidGeodesic();
for (let i = 0; i < 400; i++) {
const start = {
lon: (random() * 360 - 180) * d,
lat: (random() * 170 - 85) * d,
};
// Near pairs, as a nearby-sites query asks, and far ones short of antipodal.
const reach = i % 2 ? 2 : 120;
const end = {
lon: start.lon + (random() * 2 - 1) * reach * d,
lat:
Math.max(
-89,
Math.min(89, start.lat / d + (random() * 2 - 1) * reach),
) * d,
};
geodesic.setEndPoints(
new Cesium.Cartographic(start.lon, start.lat, 0),
new Cesium.Cartographic(end.lon, end.lat, 0),
);
const expected = geodesic.surfaceDistance;
assert.ok(
Math.abs(surfaceDistance(start, end) - expected) <=
1e-9 * Math.max(1, expected),
`${i}: ${surfaceDistance(start, end)} vs ${expected}`,
);
}
});
test('the same point is no distance away, and nearly antipodal points still answer', () => {
const p = { lon: 0.3, lat: 0.7 };
assert.equal(surfaceDistance(p, p), 0);
const far = surfaceDistance(
{ lon: 0, lat: 0 },
{ lon: Math.PI - 1e-9, lat: 0 },
);
assert.ok(Number.isFinite(far) && far > 1.9e7);
});
+34
View File
@@ -0,0 +1,34 @@
/**
* @module geo/horizon
* @description Whether a point is beyond the WGS84 ellipsoid's horizon from
* an eye, by the default renderer's own test (`EllipsoidalOccluder`), so
* code that culls by it agrees with what the renderer culls.
*/
import { WGS84 } from './ellipsoid.js';
/**
* A horizon test from `eye` (ECEF): `isPointVisible(p)` is false for a
* point the ellipsoid hides from it.
*/
export function horizonFrom(eye) {
const o = WGS84.oneOverRadii;
const cx = eye.x * o.x;
const cy = eye.y * o.y;
const cz = eye.z * o.z;
const limbSquared = cx * cx + cy * cy + cz * cz - 1;
return {
isPointVisible(p) {
const tx = p.x * o.x - cx;
const ty = p.y * o.y - cy;
const tz = p.z * o.z - cz;
const along = -(tx * cx + ty * cy + tz * cz);
// Inside the ellipsoid the plane through the eye culls instead.
const occluded =
limbSquared < 0
? along > 0
: along > limbSquared &&
(along * along) / (tx * tx + ty * ty + tz * tz) > limbSquared;
return !occluded;
},
};
}
+33
View File
@@ -0,0 +1,33 @@
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import test from 'node:test';
import { fromDegrees } from './ellipsoid.js';
import { horizonFrom } from './horizon.js';
test('the horizon hides what the default renderer’s occluder hides', () => {
let seed = 3;
const random = () => (seed = (seed * 16807) % 2147483647) / 2147483647;
for (let i = 0; i < 30; i++) {
const eye = fromDegrees(
random() * 360 - 180,
random() * 170 - 85,
i === 0 ? -100 : random() * 2e7,
);
const occluder = new Cesium.EllipsoidalOccluder(
Cesium.Ellipsoid.WGS84,
new Cesium.Cartesian3(eye.x, eye.y, eye.z),
);
const horizon = horizonFrom(eye);
for (let k = 0; k < 50; k++) {
const p = fromDegrees(
random() * 360 - 180,
random() * 180 - 90,
random() * 1e5,
);
assert.equal(
horizon.isPointVisible(p),
occluder.isPointVisible(new Cesium.Cartesian3(p.x, p.y, p.z)),
);
}
}
});
+221
View File
@@ -0,0 +1,221 @@
/**
* @module geo/rhumb
* @description Rhumb lines on the WGS84 ellipsoid, by the default
* renderer's own method (`EllipsoidRhumbLine`): the same series in the same
* order, so points along one land where the renderer put them. Angles in
* radians, distances in metres.
*/
import { WGS84 } from './ellipsoid.js';
import { negativePiToPi } from './vector.js';
const MAJOR = WGS84.radii.x;
const MINOR = WGS84.radii.z;
const E2 = (MAJOR * MAJOR - MINOR * MINOR) / (MAJOR * MAJOR);
const E = Math.sqrt(E2);
const HALF_PI = Math.PI / 2;
const EPSILON8 = 1e-8;
const EPSILON10 = 1e-10;
/** Meridian distance from the equator to `phi`. */
function meridian(phi) {
const e2 = E2;
const e4 = e2 * e2;
const e6 = e4 * e2;
const e8 = e6 * e2;
const e10 = e8 * e2;
const e12 = e10 * e2;
return (
MAJOR *
((1 -
e2 / 4 -
(3 * e4) / 64 -
(5 * e6) / 256 -
(175 * e8) / 16384 -
(441 * e10) / 65536 -
(4851 * e12) / 1048576) *
phi -
((3 * e2) / 8 +
(3 * e4) / 32 +
(45 * e6) / 1024 +
(105 * e8) / 4096 +
(2205 * e10) / 131072 +
(6237 * e12) / 524288) *
Math.sin(2 * phi) +
((15 * e4) / 256 +
(45 * e6) / 1024 +
(525 * e8) / 16384 +
(1575 * e10) / 65536 +
(155925 * e12) / 8388608) *
Math.sin(4 * phi) -
((35 * e6) / 3072 +
(175 * e8) / 12288 +
(3675 * e10) / 262144 +
(13475 * e12) / 1048576) *
Math.sin(6 * phi) +
((315 * e8) / 131072 + (2205 * e10) / 524288 + (43659 * e12) / 8388608) *
Math.sin(8 * phi) -
((693 * e10) / 1310720 + (6237 * e12) / 5242880) * Math.sin(10 * phi) +
((1001 * e12) / 8388608) * Math.sin(12 * phi))
);
}
/** The latitude a meridian distance `m` reaches. */
function inverseMeridian(m) {
const d = m / MAJOR;
const d2 = d * d;
const d3 = d2 * d;
const d4 = d3 * d;
const e2 = E2;
const e4 = e2 * e2;
const e6 = e4 * e2;
const e8 = e6 * e2;
const e10 = e8 * e2;
const e12 = e10 * e2;
return (
d +
(d * e2) / 4 +
(7 * d * e4) / 64 +
(15 * d * e6) / 256 +
(579 * d * e8) / 16384 +
(1515 * d * e10) / 65536 +
(16837 * d * e12) / 1048576 +
((3 * d * e4) / 16 +
(45 * d * e6) / 256 -
(d * (32 * d2 - 561) * e8) / 4096 -
(d * (232 * d2 - 1677) * e10) / 16384 +
(d * (399985 - 90560 * d2 + 512 * d4) * e12) / 5242880) *
Math.cos(2 * d) +
((21 * d * e6) / 256 +
(483 * d * e8) / 4096 -
(d * (224 * d2 - 1969) * e10) / 16384 -
(d * (33152 * d2 - 112599) * e12) / 1048576) *
Math.cos(4 * d) +
((151 * d * e8) / 4096 +
(4681 * d * e10) / 65536 +
(1479 * d * e12) / 16384 -
(453 * d3 * e12) / 32768) *
Math.cos(6 * d) +
((1097 * d * e10) / 65536 + (42783 * d * e12) / 1048576) * Math.cos(8 * d) +
((8011 * d * e12) / 1048576) * Math.cos(10 * d) +
((3 * e2) / 8 +
(3 * e4) / 16 +
(213 * e6) / 2048 -
(3 * d2 * e6) / 64 +
(255 * e8) / 4096 -
(33 * d2 * e8) / 512 +
(20861 * e10) / 524288 -
(33 * d2 * e10) / 512 +
(d4 * e10) / 1024 +
(28273 * e12) / 1048576 -
(471 * d2 * e12) / 8192 +
(9 * d4 * e12) / 4096) *
Math.sin(2 * d) +
((21 * e4) / 256 +
(21 * e6) / 256 +
(533 * e8) / 8192 -
(21 * d2 * e8) / 512 +
(197 * e10) / 4096 -
(315 * d2 * e10) / 4096 +
(584039 * e12) / 16777216 -
(12517 * d2 * e12) / 131072 +
(7 * d4 * e12) / 2048) *
Math.sin(4 * d) +
((151 * e6) / 6144 +
(151 * e8) / 4096 +
(5019 * e10) / 131072 -
(453 * d2 * e10) / 16384 +
(26965 * e12) / 786432 -
(8607 * d2 * e12) / 131072) *
Math.sin(6 * d) +
((1097 * e8) / 131072 +
(1097 * e10) / 65536 +
(225797 * e12) / 10485760 -
(1097 * d2 * e12) / 65536) *
Math.sin(8 * d) +
((8011 * e10) / 2621440 + (8011 * e12) / 1048576) * Math.sin(10 * d) +
((293393 * e12) / 251658240) * Math.sin(12 * d)
);
}
/** Isometric latitude. */
function sigma(latitude) {
const eSinL = E * Math.sin(latitude);
return (
Math.log(Math.tan(0.5 * (HALF_PI + latitude))) -
(E / 2) * Math.log((1 + eSinL) / (1 - eSinL))
);
}
/** Radius of the parallel at `latitude`. */
function parallelRadius(latitude) {
const sinPhi = Math.sin(latitude);
return (MAJOR * Math.cos(latitude)) / Math.sqrt(1 - E2 * sinPhi * sinPhi);
}
/**
* The rhumb line from `start` to `end` (`{lon, lat}` radians): its heading
* (radians from north), its length, and the point a distance along it.
*/
export function rhumbLine(start, end) {
const heading = Math.atan2(
negativePiToPi(end.lon - start.lon),
sigma(end.lat) - sigma(start.lat),
);
// Near due east or west the series diverge: such a line follows its
// parallel. Its length and its points decide that as the renderer does.
const offEast = Math.abs(Math.abs(heading) - HALF_PI);
const measuredAlongParallel =
offEast <= Math.max(EPSILON8, EPSILON8 * HALF_PI);
const alongParallel = !(offEast > EPSILON8);
const distance = Math.abs(
measuredAlongParallel
? parallelRadius(start.lat) * negativePiToPi(end.lon - start.lon)
: (meridian(end.lat) - meridian(start.lat)) / Math.cos(heading),
);
return {
heading,
distance,
/** The point `metres` along the line from its start. */
at(metres) {
if (metres === 0) return { lon: start.lon, lat: start.lat };
if (alongParallel) {
const delta = metres / parallelRadius(start.lat);
return {
lon: negativePiToPi(start.lon + (heading > 0 ? delta : -delta)),
lat: start.lat,
};
}
const lat = inverseMeridian(
meridian(start.lat) + metres * Math.cos(heading),
);
const lon =
Math.abs(heading) < EPSILON10
? negativePiToPi(start.lon)
: negativePiToPi(
start.lon + Math.tan(heading) * (sigma(lat) - sigma(start.lat)),
);
return { lon, lat };
},
};
}
/**
* The points along a path's rhumb lines no more than `granularity` metres
* apart, as a renderer drawing the path along rhumb lines places them: each
* leg of `distance` split into `ceil(distance / granularity)` equal parts.
* Takes and gives `{lon, lat}` in radians; the path's own points are kept.
*/
export function densifyRhumb(points, granularity = 9999) {
if (points.length < 2) return points.slice();
const out = [points[0]];
for (let i = 1; i < points.length; i++) {
const line = rhumbLine(points[i - 1], points[i]);
if (line.distance >= granularity) {
const parts = Math.ceil(line.distance / granularity);
const step = line.distance / parts;
for (let k = 1; k < parts; k++) out.push(line.at(step * k));
}
out.push(points[i]);
}
return out;
}
+79
View File
@@ -0,0 +1,79 @@
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import test from 'node:test';
import { densifyRhumb, rhumbLine } from './rhumb.js';
const d = Math.PI / 180;
test('a rhumb line is the default renderer’s, length and points', () => {
let seed = 11;
const random = () => (seed = (seed * 16807) % 2147483647) / 2147483647;
const cases = [
[
[-40, 35],
[-30, 40],
],
[
[170, -10],
[-170, 12],
],
[
[10, 20],
[60, 20],
],
[
[5, -60],
[5, 70],
],
];
for (let i = 0; i < 40; i++)
cases.push([
[random() * 360 - 180, random() * 160 - 80],
[random() * 360 - 180, random() * 160 - 80],
]);
for (const [[lonA, latA], [lonB, latB]] of cases) {
const start = { lon: lonA * d, lat: latA * d };
const end = { lon: lonB * d, lat: latB * d };
let cesium;
try {
cesium = new Cesium.EllipsoidRhumbLine(
new Cesium.Cartographic(start.lon, start.lat),
new Cesium.Cartographic(end.lon, end.lat),
);
} catch {
continue; // antipodal: the renderer refuses it too
}
const line = rhumbLine(start, end);
assert.ok(
Math.abs(line.distance - cesium.surfaceDistance) <=
1e-9 * cesium.surfaceDistance + 1e-6,
`${lonA},${latA} → ${lonB},${latB}`,
);
assert.ok(Math.abs(line.heading - cesium.heading) < 1e-12);
for (const f of [0.1, 0.5, 0.9]) {
const ours = line.at(line.distance * f);
const theirs = cesium.interpolateUsingSurfaceDistance(
cesium.surfaceDistance * f,
);
assert.ok(Math.abs(ours.lon - theirs.longitude) < 1e-12);
assert.ok(Math.abs(ours.lat - theirs.latitude) < 1e-12);
}
}
});
test('a densified path keeps its points and spaces the rest under the granularity', () => {
const path = [
{ lon: -40 * d, lat: 35 * d },
{ lon: -39.95 * d, lat: 35 * d },
{ lon: -30 * d, lat: 40 * d },
];
const dense = densifyRhumb(path, 9999);
assert.equal(dense[0], path[0]);
assert.equal(dense[1], path[1], 'a short leg adds nothing');
assert.equal(dense.at(-1), path[2]);
const leg = rhumbLine(path[1], path[2]);
assert.equal(dense.length, 2 + Math.ceil(leg.distance / 9999));
for (let i = 2; i < dense.length; i++)
assert.ok(rhumbLine(dense[i - 1], dense[i]).distance < 9999);
assert.deepEqual(densifyRhumb([path[0]]), [path[0]]);
});