Files
gods-eye-view/src/layers/cctv/ground.js
T
Sameh Khamis 2e91579f8f Add a globe visibility getter to the renderer contract
The globe port could show or hide the globe surface but not say whether it
is shown. It now has an optional isGlobeVisible(), gated by a new
globeVisibility capability, in the Cesium adapter, the stub and a
conformance check. A Cesium scene without a globe does not offer it, so
callers keep their own default for an unknown surface.

The OSM overlays, the CCTV ground regime and the submarine cable drape now
read the getter instead of the scene's globe. cableClassificationTypeForScene
takes the viewer rather than its scene.
2026-11-07 19:44:15 -08:00

405 lines
17 KiB
JavaScript

import { fromDegrees } from '../../geo/ellipsoid.js';
import { findGlobe } from '../../render/rendererOf.js';
import {
SUPPORT_KEYS,
planeSupportPoints,
poseHash,
} from '../../data/cctvFootprint.js';
/** Cooldown before a provisional (geoid-fallback / partial) footprint is retried. */
const FOOTPRINT_RETRY_MS = 60_000;
export function createGround({ state: layerState, services, parts, source }) {
const { resolveGroundFloorCells } = services.ground;
const { resolveEllipsoidalGround } = services.terrain;
/**
* Task 5 (height-datum fix): maps whether the renderer shows the globe to the surface
* regime key the per-camera ground cache is keyed by (spec §2 "cache by
* surface regime", collapsed to two keys — ion World Terrain and Re:Earth
* globe terrain get the same handling):
*
* - `google-3d` — photoreal stack: globe hidden, the visible Google 3D
* tileset IS the surface → one-shot scene sampling refines.
* - `terrain-globe` — any globe stack: the Re:Earth point-height prior IS the
* resolution (zero scene queries).
*
* Only an explicit `false` (the photoreal stack hides the globe) selects
* `google-3d`; undefined/null (no viewer / torn down) must fall to the regime
* that never touches the scene. Pure — exported for the unit suite.
* @param {boolean|undefined|null} globeShow - Whether the renderer shows the
* globe (`globe.isGlobeVisible()`).
* @returns {'google-3d'|'terrain-globe'}
*/
function surfaceRegimeKey(globeShow) {
return globeShow === false ? 'google-3d' : 'terrain-globe';
}
/**
* Task 5: the surface regime the scene is CURRENTLY rendering, derived live
* from whether the renderer shows the globe (mapStackController's
* `_activatePhotoreal` / `_activateGlobeStack` flip exactly this). Reading it live
* — rather than caching the map-stack id — means the regime is correct even
* for stack changes this module never got an event for.
* @returns {'google-3d'|'terrain-globe'}
*/
function currentSurfaceRegime() {
return surfaceRegimeKey(findGlobe(layerState._viewer)?.isGlobeVisible?.());
}
/**
* Task 5: the record's ellipsoidal ground PRIOR (Re:Earth point-height batch,
* `record.groundPrior.ellipsoid`), falling back to the catalog's fabricated
* orthometric `groundElevationM` only when the prior batch hasn't landed yet.
* This is the value that replaces every previous
* `Number(camera.groundElevationM) || 0` ground fallback — it alone lifts
* London's cameras from the fabricated 15 m to ~52.7 m ellipsoidal in every
* regime, on first paint.
* @param {Object} record - Camera record.
* @returns {number} Ellipsoidal ground altitude in metres.
*/
function groundPriorAltFor(record) {
const prior = record?.groundPrior?.ellipsoid;
return Number.isFinite(prior)
? prior
: Number(record?.camera?.groundElevationM) || 0;
}
/**
* Task 5: whether the record's one-shot ground resolution has completed for
* the given regime (per-regime latch — replaces the old boolean
* `groundResolved`).
* @param {Object} record - Camera record.
* @param {string} [regime] - Defaults to the current surface regime.
* @returns {boolean}
*/
function isGroundResolved(record, regime = currentSurfaceRegime()) {
return record?.groundResolved?.[regime] === true;
}
/**
* True until the record has geometry grounded for the regime. Cameras are
* refined only once they enter the view, so many never have geometry.
*/
function needsGeometry(record, regime = currentSurfaceRegime()) {
return !record?.frustumGeometry || !isGroundResolved(record, regime);
}
/**
* Ground altitude used for pure geometry recomputes: the given regime's
* cached resolution (`record.groundSamples[regime]` — a shared mesh/DEM floor
* in google-3d, the DEM/prior in terrain-globe) when it exists, else the prior
* itself. Never queries the scene.
* @param {Object} record - Camera record.
* @param {string} [regime] - Defaults to the current surface regime.
* @returns {number} Ground altitude in metres.
*/
function groundAltFor(record, regime = currentSurfaceRegime()) {
const cached = record?.groundSamples?.[regime];
return Number.isFinite(cached) ? cached : groundPriorAltFor(record);
}
/**
* Re-arms a record for a fresh one-shot ground resolution after a GENUINE
* pose change (an explicit user select/move or manual calibration edit).
* Clears the CURRENT regime's resolved latch so the next real pass in
* updateRecordGeometry always applies, then the record re-freezes. Never
* called on a timer.
*
* The cached `groundSamples` entries are deliberately KEPT (only the latch is
* cleared). They are the record's "has ever resolved" memory: the B9c
* fallback guard in updateRecordGeometry reads the google-3d entry so a
* rearmed camera whose tiles are mid-stream (e.g. select → flyTo →
* tilesLoaded false) is not yanked back to prior/catalog heights before its
* fresh shared floor lands. In the terrain-globe regime the re-arm is
* effectively free: the next pass re-latches from the DEM/prior with zero
* scene queries.
* @param {Object} record - Camera record.
*/
function rearmGroundResolution(record) {
if (!record) return;
record.groundResolved[currentSurfaceRegime()] = false;
}
/**
* Resolves a user-moved ground anchor exactly once at commit. The synchronous
* pass uses a warm shared floor immediately, or preserves the pre-drag floor
* while the new cell is cold. A revision and coordinate check prevent an
* older asynchronous release from rewriting a newer edit.
* @param {Object} record - Camera record whose lat/lon just committed.
*/
function resolveCommittedGroundAnchor(record) {
if (!record?.camera) return;
record.calibrationGroundResolveCount =
(record.calibrationGroundResolveCount || 0) + 1;
const revision = (record.calibrationGroundRevision || 0) + 1;
record.calibrationGroundRevision = revision;
const point = { lat: record.camera.lat, lon: record.camera.lon };
rearmGroundResolution(record);
parts.geometry.updateRecordGeometry(record);
if (isGroundResolved(record)) return;
resolveGroundFloorCells([point]).then(() => {
if (layerState._recordById.get(record.camera.id) !== record) return;
if (record.calibrationGroundRevision !== revision) return;
if (record.camera.lat !== point.lat || record.camera.lon !== point.lon)
return;
rearmGroundResolution(record);
parts.geometry.updateRecordGeometry(record);
parts.rendering.refreshCoverageStyles();
parts.presentation.notifyListeners();
});
}
/**
* Task 5: batches every catalog camera's coords through the Re:Earth
* ellipsoidal ground resolver (`/api/terrain/heights` proxy — network-cached,
* chunked, geoid fallback; NOT a scene query). The catalog's orthometric
* `groundElevationM` rides along as `sourceOrthometricM` so the geoid
* fallback chain is meaningful where the catalog value is real (Caltrans).
* Never rejects — a total failure resolves null and geometry stays on
* catalog fallbacks (no worse than pre-Task-5).
* @param {Object[]} catalog - Camera objects (post-ensureCameraPose).
* @returns {Promise<Array<{ellipsoid:number, source:string}>|null>}
*/
async function resolveGroundPriors(catalog) {
try {
const coords = catalog.map((camera) => {
const ortho = Number(camera.groundElevationM);
return {
lat: camera.lat,
lon: camera.lon,
...(Number.isFinite(ortho) ? { sourceOrthometricM: ortho } : {}),
};
});
return await resolveEllipsoidalGround(coords);
} catch (error) {
console.warn(
'[Data:CCTV] ground-prior batch failed (keeping catalog fallbacks):',
error?.message || error,
);
return null;
}
}
/**
* Task 5: applies a LATE-arriving ground-prior batch (init's bounded race
* lost — cold proxy cache / slow upstream). Pure recomputes only, no scene
* queries:
* - records without geometry yet: only the icon moves onto the prior;
* the frustum is built when the camera enters the view.
* - terrain-globe regime: the prior IS the resolution → re-run the
* resolution (updateRecordGeometry latches it) for every record with
* geometry.
* - google-3d regime: records still awaiting a shared floor move from the
* catalog fallback onto the exact prior; records already holding a shared
* mesh/DEM floor keep it untouched.
* Guarded per record against a torn-down/re-inited layer (records are only
* touched while they are still the live catalog entries).
* @param {Object[]} records - The record array captured at init time.
* @param {Array<{ellipsoid:number, source:string}>} priors - Aligned by index.
*/
function applyLateGroundPriors(records, priors) {
if (!Array.isArray(records) || !Array.isArray(priors)) return;
let applied = 0;
let moved = 0;
for (let i = 0; i < records.length && i < priors.length; i++) {
const record = records[i];
const prior = priors[i];
if (!record || !prior || !Number.isFinite(prior.ellipsoid)) continue;
// Stale-record guard: init() may have re-run (destroy/init cycle) while
// the batch was in flight — only touch records still live in the map.
if (layerState._recordById.get(record.camera.id) !== record) continue;
record.groundPrior = prior;
// Keep the cheap pre-enable altitude consistent for records whose
// geometry hasn't been applied yet (applyFrustumGeometry overwrites it).
if (!record.frustumPositions) {
record.camera.absoluteHeightM =
prior.ellipsoid + record.camera.mountHeightM;
}
// Cameras without geometry only move their icon onto the prior, so the
// view pass projects the right point; their frustums are built when
// they enter the view, as recomputing the whole catalog here would
// stall a large one.
if (!record.frustumGeometry) {
if (record.position) {
// In place: the record keeps its position object.
const { x, y, z } = fromDegrees(
record.camera.lon,
record.camera.lat,
record.camera.absoluteHeightM,
);
record.position.x = x;
record.position.y = y;
record.position.z = z;
parts.rendering.moveCameraIcon(record);
moved += 1;
}
continue;
}
const regime = currentSurfaceRegime();
if (regime === 'terrain-globe') {
// Prior IS the resolution — re-latch onto the fresh value.
parts.geometry.updateRecordGeometry(record, { sampleGround: false });
applied += 1;
} else if (!Number.isFinite(record.groundSamples['google-3d'])) {
// Still awaiting the shared floor: snap interim geometry onto the exact
// prior (pure recompute; the shared cell may refine later).
parts.geometry.applyFrustumGeometry(record, prior.ellipsoid);
applied += 1;
}
}
if (moved && parts.rendering.refreshHorizonCulling())
parts.geometryQueue.enqueueViewGeometry();
if (applied || moved) parts.presentation.notifyListeners();
}
/**
* Task 5: surface-regime change handler ('gev:map-stack-changed'
* CustomEvent, dispatched by main.js from MapStackController.onChange). The
* surface HEIGHT at a camera differs between regimes (a photogrammetric
* deck/building-top in google-3d vs bare Re:Earth DEM on globe stacks), so
* on a REGIME change (photoreal ↔ globe; bing→osm stays 'terrain-globe' and
* no-ops):
* 1. every record that has geometry recomputes IMMEDIATELY from the new regime's
* resolution — cached sample if that regime has one, else the Re:Earth
* prior (never blank, zero scene queries);
* 2. entering google-3d re-arms the one-shot tiles-ready completion latch so
* update()'s existing event-driven machinery refines records that never
* took their sample, through the same staggered queue.
* Event-driven only — never called on a timer.
*/
function handleMapStackChanged() {
if (!layerState._viewer || !layerState._records.length) return;
const regime = currentSurfaceRegime();
if (regime === layerState._lastAppliedRegime) return;
layerState._lastAppliedRegime = regime;
for (const record of layerState._records) {
// Only cameras that already have geometry are rewritten; the rest are
// grounded for the new regime when they enter the view.
if (!record.frustumGeometry) continue;
if (regime === 'terrain-globe') {
// Prior IS the resolution — latch it (zero scene queries).
record.groundSamples['terrain-globe'] = groundPriorAltFor(record);
record.groundResolved['terrain-globe'] = true;
}
const ground = groundAltFor(record, regime);
// Skip the entity rewrite when the applied ground already matches (e.g.
// entering google-3d before any sample: prior → prior is a no-op) —
// unless the record has a footprint source, whose eligibility depends
// on the regime (shipped mesh samples apply in google-3d only).
const hasFootprintSource =
!!record.camera?.groundHeights || !!record.footprintGround;
if (
!hasFootprintSource &&
record.frustumGeometry &&
Math.abs(record.frustumGeometry.groundAltM - ground) < 0.001
) {
continue;
}
parts.geometry.applyFrustumGeometry(record, ground);
}
if (regime === 'google-3d') {
// Fresh google-3d session: let update()'s ONE-SHOT completion pass
// re-enqueue records without an accepted sample once the (re-shown)
// tileset reports tilesLoaded. Records already sampled in a previous
// google-3d session keep their cached resolution — 0 new samples, well
// under the ≤1-per-(camera, session) ceiling.
layerState._tilesReadyReenqueued = false;
}
// The active camera may have just lost its shipped footprint (globe
// regime) — resolve its DEM footprint for the new surface.
const active = layerState._recordById.get(layerState._activeCameraId);
if (active) void resolveFootprintGround(active);
parts.presentation.notifyListeners();
}
/**
* Resolves the ground under the monitor plane's nine support points for the
* record's CURRENT pose from the Re:Earth DEM (network-cached proxy, never a
* scene query), then re-applies the geometry so the rigid lift accounts for
* terrain rising under the plane's far edge. This is the fallback for
* cameras without a shipped precompute for this pose (a new pack, or a
* camera the user has edited), and it runs only on demand: activation and
* calibration commit. A late result for a stale pose or a torn-down record
* is dropped. Never rejects.
* @param {Object} record - Camera record.
* @returns {Promise<void>}
*/
async function resolveFootprintGround(record) {
if (!record?.camera) return;
const pose = parts.geometry.footprintPose(record);
const hash = poseHash(pose);
const existing = record.footprintGround;
if (existing?.poseHash === hash) {
// Complete real-DEM results are final; a geoid-fallback (proxy outage)
// or partial result is retried after a cooldown.
if (!existing.provisional || Date.now() < existing.retryAt) return;
}
if (parts.geometry.hasShippedFootprint(record)) return;
const revision = (record.footprintRevision || 0) + 1;
record.footprintRevision = revision;
const { supports } = planeSupportPoints(pose);
const coords = SUPPORT_KEYS.map((key) => ({
lat: supports[key].lat,
lon: supports[key].lon,
}));
let results = null;
try {
results = await resolveEllipsoidalGround(coords);
} catch {
results = null;
}
if (!Array.isArray(results)) return;
if (record.footprintRevision !== revision) return;
if (layerState._recordById.get(record.camera.id) !== record) return;
if (poseHash(parts.geometry.footprintPose(record)) !== hash) return;
const under = {};
let real = 0;
results.forEach((result, index) => {
if (Number.isFinite(result?.ellipsoid)) {
under[SUPPORT_KEYS[index]] = result.ellipsoid;
if (result.source === 'reearth') real += 1;
}
});
const provisional = real < SUPPORT_KEYS.length;
record.footprintGround = {
poseHash: hash,
supports: under,
source: provisional ? 'dem-provisional' : 'dem',
provisional,
retryAt: provisional ? Date.now() + FOOTPRINT_RETRY_MS : 0,
};
parts.geometry.applyFrustumGeometry(record, groundAltFor(record));
parts.rendering.refreshCoverageStyles();
parts.presentation.notifyListeners();
}
return {
surfaceRegimeKey,
currentSurfaceRegime,
resolveFootprintGround,
groundPriorAltFor,
isGroundResolved,
needsGeometry,
groundAltFor,
rearmGroundResolution,
resolveCommittedGroundAnchor,
resolveGroundPriors,
applyLateGroundPriors,
handleMapStackChanged,
};
}