Files
gods-eye-view/src/render/cesium/globe.js
T
Sameh Khamis 46cdeba7fa Remove renderer contract members nothing in the application uses
Drops from the contract, the stub, the Cesium renderer and the
conformance suite: agent paths, renderer-propagated orbits and celestial
draws (orbits stay drawn as icons and inertial lines), scalar raster
fields, lodGroup, volume classification, icon eye offsets, the dash gap
colour, box shapes, courseBlendMs (courseGlide covers easing), relief
surface shading, globe clouds and water, sky atmosphere tuning, heightmap
and quantized-mesh terrain, WMTS and ArcGIS imagery, the batched cached
height read, the quality benchmark and the animated-style and overlay
pixel-ratio knobs. Capabilities clouds, water, celestial, agents, orbits
and benchmark go with them.

The lodGroup check becomes a displayRange check across two sets, the
height-query check uses an extruded polygon in place of a box, the shape
scenes draw extruded blocks where they drew boxes, and the fields scene
draws a raster shell. The shape references are recorded again.
2026-11-10 03:27:10 -08:00

583 lines
21 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* @module render/cesium/globe
* @description The Cesium renderer's globe port (`src/render/contract/globe.d.ts`):
* the base (photoreal tiles, terrain, imagery), the globe's visibility,
* imagery layers (`imagery.js`), the split, the sky, settling and load
* progress, over a Cesium widget or viewer someone else made.
*
* Imagery drapes on the globe, or on the drawn base tileset: the photoreal
* tileset this port loaded, or one the application's map stack marked as
* its base (`markBaseTileset`, `../baseTilesets.js`) while it still loads
* its own. Where each layer drapes follows what is drawn, looked at every
* frame, so a base switched outside the port moves the layers with it.
*
* The sky reads the scene as it was set up and writes through to it; what
* the scene has no part for (stars without a sky box, say) is kept as set.
*/
import * as Cesium from 'cesium';
import { loadPhotorealisticTileset } from './google3d.js';
import { provideUnboundGlobe } from '../rendererOf.js';
import { isBaseTileset, markBaseTileset } from '../baseTilesets.js';
import { listenerList, uncaught } from './common.js';
import { createCesiumImagery } from './imagery.js';
// The base marks live outside the adapter, so code that is not Cesium's can
// mark a base; they are re-exported here for the code that still is.
export { markBaseTileset };
/** Ion's world terrain asset. */
const WORLD_TERRAIN_ASSET = 1;
const ROUTES = {
'google-direct': 'google',
'google-token': 'google',
'google-ion': 'fallback',
};
/** The terrain provider a spec describes, once ready. */
async function terrainProvider(spec, { worldDataToken }) {
if (!spec || spec.kind === 'ellipsoid')
return new Cesium.EllipsoidTerrainProvider();
if (spec.kind === 'world') {
const accessToken = String(worldDataToken || '').trim();
if (!accessToken)
throw new TypeError(
'World terrain needs the renderer’s world data token',
);
const resource = await Cesium.IonResource.fromAssetId(WORLD_TERRAIN_ASSET, {
accessToken,
});
return Cesium.CesiumTerrainProvider.fromUrl(resource, {
requestVertexNormals: spec.requestVertexNormals ?? false,
requestWaterMask: false,
});
}
throw new TypeError(`Unknown terrain kind: ${spec.kind}`);
}
/**
* `hillshade` surface shading: view-directed display lighting over the
* terrain's own normals, or the ellipsoid's curvature where the terrain
* has none (Cesium leaves normal-dependent materials out without them). It
* darkens only, up to `strength` opacity; it stands for no sun, changes no
* geometry and asks for no data.
* @param {boolean} terrainNormals
*/
function hillshadeSource(terrainNormals) {
const normal = terrainNormals
? 'vec3 normal = normalize(materialInput.normalEC);'
: `vec3 worldPosition = (czm_inverseView * vec4(-materialInput.positionToEyeEC, 1.0)).xyz;
vec3 geodeticNormal = normalize(worldPosition * czm_ellipsoidInverseRadii * czm_ellipsoidInverseRadii);
vec3 normal = normalize(czm_viewRotation * geodeticNormal);`;
return `
czm_material czm_getMaterial(czm_materialInput materialInput)
{
czm_material material = czm_getDefaultMaterial(materialInput);
${normal}
vec3 displayLight = normalize(vec3(-0.45, 0.55, 0.8));
float shade = clamp((1.0 - dot(normal, displayLight)) * strength * (0.32 / 0.28), 0.0, strength);
material.diffuse = vec3(0.0);
material.alpha = shade;
return material;
}
`;
}
/** The last `surfaceVersion` any globe port handed out. */
let surfaceVersions = 0;
/**
* @param {object} widget A Cesium `CesiumWidget` or `Viewer`.
* @param {{capabilities: ReadonlySet<string>,
* requestRender: (reason: string) => void,
* report?: (error: unknown) => void,
* credits?: import('../contract/credits').CreditsPort | null,
* credentials?: {googleApiKey?: string, googleTokens?: () => Promise<string>,
* worldDataToken?: string}}} options
* @returns {{port: import('../contract/globe').GlobePort, dispose: () => void}}
*/
export function createCesiumGlobe(
widget,
{
capabilities,
requestRender,
report = uncaught,
credits = null,
credentials = {},
},
) {
const scene = widget.scene;
const can = (capability) => capabilities.has(capability);
let disposed = false;
// --- Base ------------------------------------------------------------------
/** The photoreal tileset this port loaded, if any. */
let photoreal = null;
let photorealStatus = { route: 'none' };
let photorealGen = 0;
let terrainGen = 0;
let baseCredit = null;
/** Every 3D tileset the scene holds. */
function tilesets() {
const found = [];
const primitives = scene.primitives;
const n = primitives?.length ?? 0;
for (let i = 0; i < n; i++) {
const primitive = primitives.get(i);
if (primitive instanceof Cesium.Cesium3DTileset) found.push(primitive);
}
return found;
}
/** The base tileset drawn now, which `objects` imagery drapes on. */
function drawnBase() {
if (photoreal && !photoreal.isDestroyed() && photoreal.show)
return photoreal;
for (const tileset of tilesets())
if (isBaseTileset(tileset) && tileset.show && !tileset.isDestroyed())
return tileset;
return null;
}
const imagery = createCesiumImagery(scene, {
capabilities,
requestRender,
report,
objects: drawnBase,
worldDataToken: () => credentials.worldDataToken,
});
function removePhotoreal() {
if (!photoreal) return;
const tileset = photoreal;
photoreal = null;
// The layers draped on it move off before it takes them with it.
imagery.sync();
if (!tileset.isDestroyed() && !scene.primitives.remove(tileset))
tileset.destroy();
}
async function setPhotoreal(spec) {
const gen = ++photorealGen;
removePhotoreal();
photorealStatus = { route: 'none' };
if (!spec || !can('photoreal')) {
photorealStatus = { route: 'none' };
requestRender('base');
return photorealStatus;
}
// The spec's own route first: its key, else its tokens, else the
// renderer's credentials.
const googleApiKey =
spec.key ?? (spec.token ? '' : (credentials.googleApiKey ?? ''));
const token = spec.token ?? credentials.googleTokens;
const result = await loadPhotorealisticTileset(Cesium, {
googleApiKey,
// A renewal names the token it replaces.
googleTokens: token ? { token: (options) => token(options) } : null,
cesiumToken: spec.fallback ? (credentials.worldDataToken ?? '') : '',
});
if (gen !== photorealGen || disposed) {
if (result.tileset && !result.tileset.isDestroyed())
result.tileset.destroy();
return photorealStatus;
}
if (!result.tileset) {
const error = result.errors.at(-1);
photorealStatus = {
route: 'none',
error: {
code: error ? 'load-failed' : 'no-credentials',
message: error?.message ?? 'No photoreal credentials were given',
},
};
} else {
photoreal = scene.primitives.add(result.tileset);
photorealStatus = { route: ROUTES[result.route] ?? 'google' };
}
imagery.sync();
requestRender('base');
return photorealStatus;
}
async function setTerrain(spec) {
if (spec && spec.kind !== 'ellipsoid' && !can('terrain'))
throw new TypeError('This renderer draws no terrain');
// The last call wins, even one whose terrain then fails to load.
const gen = ++terrainGen;
const provider = await terrainProvider(spec, credentials);
if (gen !== terrainGen || disposed) {
if (!provider.isDestroyed?.()) provider.destroy?.();
return;
}
scene.terrainProvider = provider;
scene.verticalExaggeration = spec?.exaggeration ?? 1;
requestRender('base');
}
async function setBase(base) {
if (base.vector) throw new TypeError('This renderer draws no vector base');
for (const handle of imagery.list()) handle.remove();
baseCredit?.();
baseCredit = base.credit && credits ? credits.addStatic(base.credit) : null;
const loads = [];
if (base.photoreal !== undefined) loads.push(setPhotoreal(base.photoreal));
if (base.terrain !== undefined) loads.push(setTerrain(base.terrain));
const layers = (base.imagery ?? []).map((spec) =>
imagery.add(spec, undefined, { base: true }),
);
await Promise.all(loads);
await imagery.ready(layers);
await baseSettled();
return {
photoreal: photorealStatus,
imagery: layers,
settled: isSettled('base'),
};
}
/** How long `setBase` waits for the new base to settle. */
const BASE_SETTLE_MS = 20000;
/**
* Resolves once the base has settled, checked after each drawn frame, or
* after `BASE_SETTLE_MS`; `setBase` then says whether it had.
*/
function baseSettled() {
if (isSettled('base') || !scene.postRender?.addEventListener)
return Promise.resolve();
return new Promise((resolve) => {
const done = () => {
off();
clearTimeout(timer);
settleWaits.delete(done);
resolve();
};
const off = scene.postRender.addEventListener(() => {
// Loads draw on their own as they land; no frame is asked for.
if (isSettled('base')) done();
});
const timer = setTimeout(done, BASE_SETTLE_MS);
settleWaits.add(done);
requestRender('base');
});
}
const settleWaits = new Set();
// --- Sky -------------------------------------------------------------------
const sky = {
atmosphere:
scene.skyAtmosphere?.show ?? scene.globe?.showGroundAtmosphere ?? false,
stars: scene.skyBox?.show ?? false,
milkyWay: scene.skyBox?.milkyWayVisibility ?? 0,
sun: scene.sun?.show ?? false,
moon: scene.moon?.show ?? false,
fog: scene.fog?.enabled ?? false,
lighting: scene.globe?.enableLighting ?? false,
};
/** The settings as drawn: the scene's own parts, else what was set. */
function readSky() {
const out = { ...sky };
if (scene.skyAtmosphere) out.atmosphere = scene.skyAtmosphere.show;
else if (scene.globe) out.atmosphere = scene.globe.showGroundAtmosphere;
if (scene.skyBox && 'show' in scene.skyBox) out.stars = scene.skyBox.show;
if (scene.skyBox?.milkyWayVisibility !== undefined)
out.milkyWay = scene.skyBox.milkyWayVisibility;
if (scene.sun) out.sun = scene.sun.show;
if (scene.moon) out.moon = scene.moon.show;
if (scene.fog) out.fog = scene.fog.enabled;
if (scene.globe) out.lighting = scene.globe.enableLighting;
return out;
}
function setSky(settings) {
Object.assign(sky, settings);
if ('atmosphere' in settings) {
if (scene.skyAtmosphere) scene.skyAtmosphere.show = sky.atmosphere;
if (scene.globe) scene.globe.showGroundAtmosphere = sky.atmosphere;
}
if ('stars' in settings && scene.skyBox && 'show' in scene.skyBox)
scene.skyBox.show = sky.stars;
if (
'milkyWay' in settings &&
scene.skyBox?.milkyWayVisibility !== undefined
)
scene.skyBox.milkyWayVisibility = sky.milkyWay;
if ('sun' in settings && scene.sun) scene.sun.show = sky.sun;
if ('moon' in settings && scene.moon) scene.moon.show = sky.moon;
if ('fog' in settings && scene.fog) scene.fog.enabled = sky.fog;
if ('lighting' in settings && scene.globe)
scene.globe.enableLighting = sky.lighting;
requestRender('sky');
}
// --- Settling and progress ---------------------------------------------
const terrainLoaded = () =>
!scene.globe?.show || scene.globe.tilesLoaded !== false;
const tilesLoaded = () => {
const base = drawnBase();
return !base || base.tilesLoaded !== false;
};
const imageryLoaded = () => imagery.pending() === 0 && terrainLoaded();
/**
* `surface`: what surface heights answer from has loaded what is in view:
* the globe's terrain while it is shown, otherwise the shown 3D tiles;
* false with neither drawn.
*/
function surfaceLoaded() {
if (scene.globe?.show) return scene.globe.tilesLoaded !== false;
let found = false;
for (const tileset of tilesets()) {
if (!tileset.show || tileset.isDestroyed?.()) continue;
found = true;
if (tileset.tilesLoaded === false) return false;
}
return found;
}
// `surfaceVersion`: bumped when what heights answer against changes, read
// off the scene (so a base changed around the port counts too): whether
// the globe is shown, its terrain provider, and the shown 3D tilesets.
// Taken from one counter for every port, so no two surfaces share one.
let surfaceVersion = 0;
const surfaceSeen = { globe: null, terrain: null, tiles: new Set() };
function readSurfaceVersion() {
const globe = Boolean(scene.globe?.show);
const terrain = scene.globe?.terrainProvider ?? null;
let changed =
surfaceSeen.globe !== globe || surfaceSeen.terrain !== terrain;
// The shown tilesets as a set: their order among the primitives is no
// change to the surface.
let count = 0;
for (const tileset of tilesets()) {
if (!tileset.show || tileset.isDestroyed?.()) continue;
count += 1;
if (!surfaceSeen.tiles.has(tileset)) changed = true;
}
if (count !== surfaceSeen.tiles.size) changed = true;
if (changed) {
surfaceSeen.globe = globe;
surfaceSeen.terrain = terrain;
surfaceSeen.tiles.clear();
for (const tileset of tilesets())
if (tileset.show && !tileset.isDestroyed?.())
surfaceSeen.tiles.add(tileset);
surfaceVersion = ++surfaceVersions;
}
return surfaceVersion;
}
function isSettled(kind) {
if (kind === 'surface' && can('surfaceIdentity')) return surfaceLoaded();
if (kind === 'terrain') return terrainLoaded();
if (kind === 'tiles') return tilesLoaded();
if (kind === 'imagery') return imageryLoaded();
return terrainLoaded() && tilesLoaded() && imageryLoaded();
}
const progressListeners = listenerList(report);
const progress = { tilesPending: 0, imageryPending: 0, terrainPending: 0 };
let lastProgress = '';
function emitProgress() {
progress.imageryPending = imagery.pending();
const key = `${progress.tilesPending}/${progress.imageryPending}/${progress.terrainPending}`;
if (key === lastProgress || progressListeners.size === 0) return;
lastProgress = key;
progressListeners.fire({ ...progress });
}
const removers = [];
const globeProgress = scene.globe?.tileLoadProgressEvent;
if (globeProgress?.addEventListener)
removers.push(
globeProgress.addEventListener((queued) => {
progress.terrainPending = queued;
emitProgress();
}),
);
// Every tick: where each layer drapes follows what is drawn, and the base
// tileset's load progress is read.
if (scene.preUpdate?.addEventListener)
removers.push(
scene.preUpdate.addEventListener(() => {
// A throw here would stop the widget's render loop.
try {
if (shadingStale()) {
applyShading();
requestRender('base');
}
if (imagery.list().length) imagery.sync();
if (progressListeners.size === 0) return;
const base = drawnBase();
progress.tilesPending = base && !base.tilesLoaded ? 1 : 0;
emitProgress();
} catch (error) {
report(error);
}
}),
);
// --- Surface shading --------------------------------------------------
// `setSurfaceShading`: the globe material this port owns, while it shades.
// It takes the globe's material only when no one else holds it, and gives
// it back on null. On the tick after a change it follows the terrain
// (with normals or without), lets go of a material someone replaced, and
// takes the globe's material once it comes free.
let shading = null;
let shadingMaterial = null;
let shadingNormals = null;
// The terrain's normals when shading was last applied, owned or not, so
// an idle tick never applies it again.
let shadingSeen = null;
// A material that could not be made is not retried until the terrain or
// the shading changes.
let shadingBroken = false;
const shadingNormalsNow = () =>
scene.globe?.terrainProvider?.hasVertexNormals === true;
// Whether a tick should apply the shading again: the terrain's normals
// changed, someone took our material, or the globe's material came free.
function shadingStale() {
const globe = scene.globe;
if (!shading || !globe) return false;
if (shadingSeen !== shadingNormalsNow()) return true;
if (shadingMaterial) return globe.material !== shadingMaterial;
return globe.material == null && !shadingBroken;
}
function dropShadingMaterial() {
if (!shadingMaterial) return;
if (scene.globe && scene.globe.material === shadingMaterial)
scene.globe.material = undefined;
if (!shadingMaterial.isDestroyed?.()) shadingMaterial.destroy?.();
shadingMaterial = null;
shadingNormals = null;
}
function applyShading() {
const globe = scene.globe;
const normals = shadingNormalsNow();
if (normals !== shadingSeen) shadingBroken = false;
shadingSeen = normals;
if (!shading || !globe) return dropShadingMaterial();
if (shadingMaterial && globe.material !== shadingMaterial) {
// Someone else took the globe's material: theirs it stays, and ours,
// no longer drawn, goes.
if (!shadingMaterial.isDestroyed?.()) shadingMaterial.destroy?.();
shadingMaterial = null;
shadingNormals = null;
}
if (shadingMaterial && shadingNormals === normals) {
shadingMaterial.uniforms.strength = shading.strength;
return;
}
if (!shadingMaterial && globe.material != null) return;
dropShadingMaterial();
shadingBroken = true;
shadingMaterial = new Cesium.Material({
fabric: {
type: normals ? 'GEVHillshadeTerrain' : 'GEVHillshadeCurvature',
uniforms: { strength: shading.strength },
source: hillshadeSource(normals),
},
translucent: true,
});
shadingBroken = false;
shadingNormals = normals;
globe.material = shadingMaterial;
}
function setSurfaceShading(next) {
if (next && next.kind !== 'hillshade')
throw new TypeError(`This renderer has no ${next.kind} shading`);
shading = next
? { strength: Math.min(1, Math.max(0, Number(next.strength) || 0)) }
: null;
shadingBroken = false;
applyShading();
requestRender('base');
}
// --- Port ------------------------------------------------------------------
const port = {
setBase,
setPhotoreal,
setTerrain,
setGlobeVisible(visible) {
if (!scene.globe) return;
scene.globe.show = Boolean(visible);
imagery.sync();
requestRender('base');
},
imagery: {
add: (spec, index) => imagery.add(spec, index),
list: imagery.list,
},
sky: { get: readSky, set: setSky },
isSettled,
on(event, cb) {
if (event !== 'progress') return () => {};
return progressListeners.on(cb);
},
};
if (can('globeVisibility'))
port.isGlobeVisible = () => scene.globe?.show === true;
if (can('surfaceIdentity')) port.surfaceVersion = readSurfaceVersion;
if (can('surfaceShading')) port.setSurfaceShading = setSurfaceShading;
if (can('splitSwipe')) {
// Cesium's split starts at the canvas's left edge, as the scene was
// made: a `left` layer shows once the split moves.
port.imagery.getSplit = () => scene.splitPosition ?? 0;
port.imagery.setSplit = (x01) => {
scene.splitPosition = Math.min(1, Math.max(0, Number(x01)));
requestRender('imagery');
};
}
return {
port,
dispose() {
if (disposed) return;
disposed = true;
photorealGen += 1;
terrainGen += 1;
for (const off of removers) off();
shading = null;
dropShadingMaterial();
progressListeners.clear();
for (const done of [...settleWaits]) done();
imagery.dispose();
baseCredit?.();
baseCredit = null;
},
};
}
// A viewer with no renderer bound gets a globe port
// built over it: imagery and the sky as the renderer's would.
provideUnboundGlobe((viewer) => {
if (!viewer?.scene) return null;
// Visibility reads back only from a globe that keeps it: a scene made
// without one gives no reading, so its callers keep their own default.
const capabilities = new Set([
'imageHooks',
'imageryOnTiles',
'splitSwipe',
'surfaceIdentity',
]);
if (typeof viewer.scene.globe?.show === 'boolean')
capabilities.add('globeVisibility');
// The globe's surface shading needs a globe to shade.
if (viewer.scene.globe) capabilities.add('surfaceShading');
const { port, dispose } = createCesiumGlobe(viewer, {
capabilities,
requestRender: () => viewer.scene.requestRender?.(),
});
// A renderer bound later leaves it running: its layers keep following
// the base until their callers remove them.
return { port, dispose, release() {} };
});