Files
gods-eye-view/src/globe/cesium/maps.js
T
German Khokhlov ab0acb0e09 feat(globe): engine-agnostic maps checks and maps.current
The contract suite gains maps checks (opt-in with mapSources: two imagery
sources and a photoreal one the engine can show): setPhotorealTiles(null)
brings back the last base imagery, the last imagery or photoreal call
decides what shows, and a released photoreal source no longer shows or
counts. They observe the new maps.current(), the source objects on screen
as passed. The fake engine follows the same semantics; qa-globe-contract
runs the checks on the app engine with the startup tileset and reapplies
the app's map stack afterwards. The contract documents map sources as
engine-neutral descriptions whose prebuilt members only the engine kind
that built them uses.
2026-10-15 19:01:00 +04:00

240 lines
8.3 KiB
JavaScript

// Map sources on a Cesium viewer. Sources are maps/registry.js entries
// ({ descriptor, imagery(), credit } and terrain { id, create() }) or plain
// descriptions ({ kind, style?, accessToken? }); providers come from the
// shared factories in src/maps, as MapSourceController builds them.
import * as Cesium from 'cesium';
import { loadPhotorealisticTileset } from '../../maps/google3d.js';
import { createMapScene } from '../../maps/sceneApply.js';
import {
ESRI_ATTRIBUTION_HTML,
imageryFactoryFor,
} from '../../maps/imagery.js';
import { applyTerrain, terrainSourceFor } from '../../maps/terrain.js';
const IMAGERY_KINDS = new Set(['osm', 'esri-imagery', 'ion']);
function imageryCreator(source) {
if (typeof source?.imagery === 'function') return source.imagery;
const descriptor = source?.descriptor ?? source;
if (!IMAGERY_KINDS.has(descriptor?.kind))
throw new TypeError(`Unknown imagery source: ${descriptor?.kind}`);
return imageryFactoryFor(descriptor, source.accessToken);
}
// Registry sources are stable by id; plain descriptions by kind and style.
const imageryKey = (source) =>
source?.descriptor?.id ?? `${source?.kind}:${source?.style ?? ''}`;
function imageryCredit(source) {
if (source?.credit !== undefined) return source.credit;
const kind = (source?.descriptor ?? source)?.kind;
return kind === 'esri-imagery' ? ESRI_ATTRIBUTION_HTML : null;
}
function terrainCreator(source) {
if (typeof source?.create === 'function') return source.create;
switch (source?.kind) {
case 'ellipsoid':
return () => ({ provider: new Cesium.EllipsoidTerrainProvider() });
case 'keyless':
return terrainSourceFor('').create;
case 'world': {
const token = String(source.accessToken || '').trim();
if (!token)
return () => {
throw new Error('World terrain requires an explicit ion token');
};
return terrainSourceFor(token).create;
}
default:
throw new TypeError(`Unknown terrain source: ${source?.kind}`);
}
}
const dispose = (value) => {
if (typeof value?.destroy === 'function' && !value.isDestroyed?.())
value.destroy();
};
/**
* @param {Cesium.Viewer} viewer
* @param {{
* tilesetRef?: { current: object | null } | (() => object | null),
* requestRender?: (reason: string) => void,
* createImageryLayer?: (provider: object) => object,
* credits?: object,
* loadPhotorealTileset?: (credentials: object) => Promise<{ tileset: object | null, errors: Error[] }>,
* }} [options] `tilesetRef` names the startup Google tileset the app added.
* @returns {{ maps: object, destroy: () => void }}
*/
export function createCesiumMaps(
viewer,
{
tilesetRef = null,
requestRender = () => viewer.scene.requestRender?.(),
createImageryLayer = (provider) => new Cesium.ImageryLayer(provider),
credits,
loadPhotorealTileset = (credentials) =>
loadPhotorealisticTileset(Cesium, credentials),
} = {},
) {
const abort = new AbortController();
const mapScene = createMapScene(viewer, {
createImageryLayer,
...(credits && { credits }),
});
const providers = new Map();
let ownedTileset = null;
let shownTileset = null;
// Every tileset shown through the engine, so a switch hides all of them;
// `added` are those the engine put into scene.primitives itself.
const known = new Set();
const added = new Set();
// Imagery and photoreal share one generation: whichever was asked for last
// decides what the globe shows. Terrain has its own.
const generations = { display: 0, terrain: 0 };
let baseSource = null;
// The source objects on screen, as passed (maps.current()).
let currentBase = null;
let currentTiles = null;
let creditOwner = null;
let destroyed = false;
const startupTileset = () =>
(typeof tilesetRef === 'function' ? tilesetRef() : tilesetRef?.current) ??
null;
const tilesets = () =>
[startupTileset(), shownTileset, ownedTileset, ...known].filter(
(tileset, index, all) => tileset && all.indexOf(tileset) === index,
);
// One provider per source, as MapSourceController caches them, so applying
// the same source again keeps the live layer. Failures are not cached. A
// source carrying a ready `provider` belongs to its caller: it is neither
// cached nor disposed here.
function providerFor(source) {
if (source?.provider) return Promise.resolve(source.provider);
const key = imageryKey(source);
if (providers.has(key)) return providers.get(key);
const promise = Promise.resolve()
.then(() => imageryCreator(source)({ signal: abort.signal }))
.catch((error) => {
if (providers.get(key) === promise) providers.delete(key);
throw error;
});
providers.set(key, promise);
return promise;
}
function showCredit(owner, html) {
creditOwner = owner;
mapScene.showCredit(html);
}
function showBase(source, provider) {
currentBase = source;
mapScene.showBaseImagery(provider);
showCredit('imagery', imageryCredit(source));
}
const maps = {
async setBaseImagery(source) {
const generation = ++generations.display;
const provider = await providerFor(source);
if (destroyed || generation !== generations.display) return;
baseSource = { source, provider };
showBase(source, provider);
requestRender('map-imagery');
},
async setTerrain(source) {
const generation = ++generations.terrain;
const result = await terrainCreator(source)({ signal: abort.signal });
if (destroyed || generation !== generations.terrain) return;
applyTerrain(viewer, result);
requestRender('map-terrain');
},
async setPhotorealTiles(source) {
const generation = ++generations.display;
const { scene } = viewer;
if (source == null) {
mapScene.showTileset(null, tilesets());
shownTileset = null;
currentTiles = null;
// The globe comes back with the last base imagery and its credit;
// the photoreal credit goes.
if (baseSource) {
if (!mapScene.baseProvider)
showBase(baseSource.source, baseSource.provider);
} else if (creditOwner === 'photoreal') showCredit(null, null);
mapScene.showGlobe(true);
requestRender('map-photoreal');
return;
}
let tileset = source.tileset ?? null;
let owned = false;
if (!tileset) {
const { tileset: loaded, errors = [] } =
await loadPhotorealTileset(source);
if (!loaded)
throw errors.at(-1) ?? new Error('Google 3D Tiles are unavailable');
tileset = loaded;
owned = true;
}
if (destroyed || generation !== generations.display) {
if (owned) dispose(tileset);
return;
}
if (owned && ownedTileset !== tileset) {
if (ownedTileset) {
scene.primitives.remove(ownedTileset);
dispose(ownedTileset);
}
ownedTileset = tileset;
}
if (!scene.primitives.contains(tileset)) {
scene.primitives.add(tileset);
if (!owned) added.add(tileset);
}
known.add(tileset);
// As MapSourceController activates a 3D stack: no base layer, the
// source's credit, one tileset shown and the globe hidden.
mapScene.removeBaseImagery();
currentBase = null;
currentTiles = source;
showCredit('photoreal', source.credit);
shownTileset = tileset;
mapScene.showTileset(tileset, tilesets());
mapScene.showGlobe(false);
requestRender('map-photoreal');
},
releasePhotorealTiles(source) {
const tileset = source?.tileset;
if (!tileset || !known.delete(tileset)) return;
if (shownTileset === tileset) shownTileset = null;
if (currentTiles?.tileset === tileset) currentTiles = null;
if (added.delete(tileset)) viewer.scene.primitives.remove(tileset);
},
photorealActive: () => tilesets().some((tileset) => tileset.show === true),
current: () => ({ baseImagery: currentBase, photoreal: currentTiles }),
};
return {
maps,
destroy() {
if (destroyed) return;
destroyed = true;
abort.abort();
mapScene.destroy();
for (const promise of providers.values())
void promise.then(dispose, () => {});
providers.clear();
if (ownedTileset) {
viewer.scene.primitives.remove(ownedTileset);
dispose(ownedTileset);
ownedTileset = null;
}
},
};
}