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

+19 -111
View File
@@ -1,126 +1,34 @@
import * as Cesium from 'cesium';
import {
CABLE_GLOBE_STACK_IDS,
MARKER_COLLECTION_EXPECTATIONS,
} from './policy.js';
import { CABLE_GLOBE_STACK_IDS } from './policy.js';
/**
* Ground-line classification for one map stack. The photoreal stack renders
* Google 3D tiles with the Cesium globe HIDDEN, so cable ground lines only
* need the 3D-tile classification pass there; every other known stack (the
* bing stacks and osm) renders imagery on the shown globe, so only the
* terrain pass applies.
* Classifying against just the active surface halves the batched
* GroundPolylinePrimitive's emitted command sets. BOTH is the safe fallback
* for an unknown stack — it renders on every surface, exactly the shipped
* pre-optimization behavior.
* What cable ground lines drape on for one map stack. The photoreal stack
* renders Google 3D tiles with the globe HIDDEN, so cable ground lines only
* need to drape on the tiles there; every other known stack (the bing
* stacks and osm) renders imagery on the shown globe, so only the terrain
* applies.
* Draping on just the active surface halves the ground lines' draw
* commands. `both` is the safe fallback for an unknown stack — it renders
* on every surface, exactly the shipped pre-optimization behavior.
* @param {string|null|undefined} activeId MapStackController stack id.
* @returns {Cesium.ClassificationType}
* @returns {'tiles'|'terrain'|'both'} The draw sets' `clampTo`.
*/
export function cableClassificationTypeForStack(activeId) {
if (activeId === 'photoreal') return Cesium.ClassificationType.CESIUM_3D_TILE;
if (CABLE_GLOBE_STACK_IDS.has(activeId))
return Cesium.ClassificationType.TERRAIN;
return Cesium.ClassificationType.BOTH;
if (activeId === 'photoreal') return 'tiles';
if (CABLE_GLOBE_STACK_IDS.has(activeId)) return 'terrain';
return 'both';
}
/**
* Derive the active surface from live scene state. The boot-time
* `setStack(..., { silent: true })` fires no 'gev:map-stack-changed' event,
* so the initial classification reads the scene the way the height-datum
* listeners do: the photoreal regime is exactly "globe hidden".
* @param {Cesium.Scene|null|undefined} scene
* @returns {Cesium.ClassificationType}
* so the initial surface is read the way the height-datum listeners do: the
* photoreal regime is exactly "globe hidden".
* @param {{globe?: {show?: boolean}}|null|undefined} scene
* @returns {'tiles'|'terrain'|'both'}
*/
export function cableClassificationTypeForScene(scene) {
if (!scene?.globe) return Cesium.ClassificationType.BOTH;
return scene.globe.show === false
? Cesium.ClassificationType.CESIUM_3D_TILE
: Cesium.ClassificationType.TERRAIN;
}
/**
* Validate one data source's marker collections WITHOUT mutating anything.
* Splitting validation from mutation is what makes the fallback honest: a
* shape failure on the SECOND collection (or the second data source) must
* not leave the first one already forced to TRANSLUCENT.
* @param {Cesium.DataSource|null|undefined} dataSource
* @returns {{ready:object[],pending:number,invariantFailed:boolean}}
*/
export function probeTranslucentMarkerBlend(dataSource) {
const cluster = dataSource?.clustering;
if (!cluster) return { ready: [], pending: 0, invariantFailed: true };
const ready = [];
let pending = 0;
let invariantFailed = false;
for (const { key, type } of MARKER_COLLECTION_EXPECTATIONS) {
if (!(key in cluster)) {
invariantFailed = true;
continue;
}
const collection = cluster[key];
if (collection === undefined || collection === null) {
pending++;
continue;
}
if (!(collection instanceof type) || !('blendOption' in collection)) {
invariantFailed = true;
continue;
}
ready.push(collection);
}
// Any failure discards every collected target: nothing is mutated at all.
if (invariantFailed) return { ready: [], pending: 0, invariantFailed: true };
return { ready, pending, invariantFailed: false };
}
/**
* Commit a clean probe. Only ever called once every probe in the batch has
* passed, so this cannot land a partial application.
* @param {{ready:object[],pending:number}} probe
* @returns {{applied:number,pending:number,invariantFailed:boolean}}
*/
export function commitTranslucentMarkerBlend(probe) {
for (const collection of probe.ready) {
if (collection.blendOption !== Cesium.BlendOption.TRANSLUCENT) {
collection.blendOption = Cesium.BlendOption.TRANSLUCENT;
}
}
return {
applied: probe.ready.length,
pending: probe.pending,
invariantFailed: false,
};
}
/**
* Force one translucent draw pass for a data source's marker collections.
* The default `OPAQUE_AND_TRANSLUCENT` blend emits two draw commands per
* collection, and every cable marker is translucent (alpha < 1), so the
* opaque pass is pure overhead across 1,917 landing billboards + 2,629
* reference points. Cesium has no public accessor for the entity-backed
* collections, so this reaches through EntityCluster's private fields under
* a SHAPE INVARIANT the caller must honor loudly: the constructor
* pre-assigns `_billboardCollection`/`_pointCollection` (= undefined until a
* visualizer lazily creates them), so a missing PROPERTY means Cesium's
* shape changed — report `invariantFailed` and never touch anything —
* while a present-but-undefined value only means "not created yet"
* (`pending`). Wrong instance types also fail the invariant. The cables
* sources never enable clustering, so created collections persist.
* VALIDATE-ALL-THEN-MUTATE-ALL: every field/type check runs before the first
* assignment, so a failure anywhere leaves BOTH collections on Cesium's
* default blend — the fallback this helper promises.
* @param {Cesium.DataSource|null|undefined} dataSource
* @returns {{applied:number,pending:number,invariantFailed:boolean}}
*/
export function applyTranslucentMarkerBlend(dataSource) {
const probe = probeTranslucentMarkerBlend(dataSource);
if (probe.invariantFailed)
return { applied: 0, pending: 0, invariantFailed: true };
return commitTranslucentMarkerBlend(probe);
if (!scene?.globe) return 'both';
return scene.globe.show === false ? 'tiles' : 'terrain';
}