Base map through the globe port

Cesium switches the map stacks through its globe port, as any renderer
does, rather than through a map engine of its own. Every route keeps its
behaviour:

- Google 3D turned off is kept hidden, and shown again without loading it
  anew; the key route's tiles take clamped marks, as the token routes' do.
- Esri goes to its deepest level (23); its "Map data not yet available"
  picture is a missing tile, so the parent's imagery stays.
- Cesium ion's world imagery is Bing over HTTPS on any page, with ion's
  credits; a token ion refuses refuses the switch, as before.
- Keyless terrain that does not answer is the flat ellipsoid, tried again
  behind it; world terrain asks ion first, as before.
- window.__godsEyeView.tileset is the Cesium photoreal tileset.
This commit is contained in:
Sameh Khamis committed 2026-11-16 17:06:35 -08:00
1 parent 65480f2604
commit 8ff9a1fa29
12 files changed
+496 -81

No files matched your search

+11 -8
View File
@@ -7,17 +7,15 @@
* The renderer it makes is transitional. Its ports are the shared Cesium
* ports (`ports.js`), the ones the conformance renderer is checked with,
* and it has every member of the contract. The application's base (the
* photoreal tiles, the map stack's imagery and terrain) is still loaded
* through the Cesium map engine (`mapEngine.js`), which the plugin hands
* the application with the renderer (its `applicationHooks`); the globe
* port drapes its imagery on that base as drawn (see `globe.js`).
* photoreal tiles, the map stack's imagery and terrain) is loaded through
* the globe port, as on any renderer (`src/maps/globeEngine.js`).
* `whenSettled` waits for the globe, the scene's 3D tiles and what the draw
* sets hold.
*
* What only this renderer needs at startup is set up here: the free-look
* height limit, keyboard access to the credits' expand link (in the page's
* language). The plugin's `applicationHooks` are what the application
* uses where a renderer has them: the map engine, stale command trimming,
* uses where a renderer has them: stale command trimming,
* whether an entity is the viewer's own, and the viewer QA scripts read.
* Adapter code reaches the viewer behind a renderer through
* `cesiumViewerOf` (`viewers.js`), never through a renderer member, so no
@@ -30,7 +28,6 @@ import { bindRenderer } from '../rendererOf.js';
import { FREE_LOOK_MAX_HEIGHT_METERS } from '../../globeInView.js';
import { createCesiumInput } from './input.js';
import { cesiumCapabilities, createCesiumPorts } from './ports.js';
import { cesiumMapEngine } from './mapEngine.js';
import { installFreeLookHeightLimit } from './freeLookLimit.js';
import { trimStaleSceneCommands } from './sceneCommandRelease.js';
import { configureCreditKeyboardAccess } from './creditKeyboard.js';
@@ -38,6 +35,7 @@ import { onLocaleChange } from '../../i18n/index.js';
import { cesiumViewerOf, recordViewer } from './viewers.js';
import { installRenderFailureNotice } from './renderFailure.js';
import { cesiumCardPreviews } from './cardPreviews.js';
import { cesiumPhotorealOf } from './globe.js';
export { cesiumViewerOf };
@@ -212,7 +210,6 @@ export function createCesiumRendererPlugin({
applicationHooks(renderer) {
const viewer = cesiumViewerOf(renderer);
return {
mapEngine: cesiumMapEngine,
// Cesium's credit display (#cesium-credits) shows the credits.
ownCreditDisplay: true,
// Drops the draw commands the scene keeps after it stops drawing
@@ -222,7 +219,13 @@ export function createCesiumRendererPlugin({
// the aircraft it flies still draws).
viewerDrawsEntity: (entity) => viewer.entities.contains(entity),
// QA scripts drive and read the viewer itself.
qaHandles: { viewer },
qaHandles: {
viewer,
/** The photoreal tileset the globe holds now, shown or hidden. */
get tileset() {
return cesiumPhotorealOf(viewer.scene);
},
},
// A recoverable notice when the globe stops drawing
// (renderFailure.js).
renderFailureNotice: (options) =>
+5 -2
View File
@@ -11,7 +11,6 @@ import {
releaseContinuousRender,
uninstallRenderGovernor,
} from '../../renderGovernor.js';
import { cesiumMapEngine } from './mapEngine.js';
import {
ReadonlySet,
cesiumRenderer,
@@ -150,7 +149,11 @@ test('the plugin wraps the viewer it is given, behind the accessor only', async
'free look is limited to low heights from the start',
);
const hooks = plugin.applicationHooks(renderer);
assert.equal(hooks.mapEngine, cesiumMapEngine, 'the map stacks use Cesium');
assert.equal(
hooks.mapEngine,
undefined,
'the map stacks switch through the globe port',
);
assert.equal(hooks.ownCreditDisplay, true, 'Cesium shows its own credits');
assert.equal(hooks.qaHandles.viewer, viewer, 'QA scripts read the viewer');
assert.equal(hooks.viewerDrawsEntity({ own: true }), true);
+92 -12
View File
@@ -59,7 +59,15 @@ async function terrainProvider(spec, { worldDataToken }) {
throw new TypeError('Quantized-mesh terrain needs its url');
// Busy hosts are asked again as the keyless terrain is
// (`terrainRetry.js`); every tile's resource inherits the policy.
const policy = createTerrainRetryPolicy();
const policy = createTerrainRetryPolicy({
// One line per cooldown window, not per tile: a burst throttles dozens.
onThrottle: ({ statusCode, delayMs, inWindow }) => {
if (inWindow === 1)
console.warn(
`[MapStack] terrain answered ${statusCode}; retrying throttled tiles after ${Math.round(delayMs)} ms`,
);
},
});
const resource = new Cesium.Resource({
url: spec.url,
retryCallback: policy.retryCallback,
@@ -104,6 +112,19 @@ czm_material czm_getMaterial(czm_materialInput materialInput)
/** The last `surfaceVersion` any globe port handed out. */
let surfaceVersions = 0;
/** Each scene's photoreal tileset as a globe port holds it, shown or hidden. */
const photorealTilesets = new WeakMap();
/**
* The Cesium photoreal tileset a globe port over `scene` holds: shown, or
* hidden and kept to show again; null when it holds none. For QA scripts.
* @param {object} scene
* @returns {object | null}
*/
export function cesiumPhotorealOf(scene) {
return photorealTilesets.get(scene)?.() ?? null;
}
/**
* @param {object} widget A Cesium `CesiumWidget` or `Viewer`.
* @param {{capabilities: ReadonlySet<string>,
@@ -111,7 +132,8 @@ let surfaceVersions = 0;
* report?: (error: unknown) => void,
* credits?: import('../contract/credits').CreditsPort | null,
* credentials?: {googleApiKey?: string, googleTokens?: () => Promise<string>,
* worldDataToken?: string}}} options
* worldDataToken?: string},
* loadPhotoreal?: typeof loadPhotorealisticTileset}} options
* @returns {{port: import('../contract/globe').GlobePort, dispose: () => void}}
*/
export function createCesiumGlobe(
@@ -122,6 +144,8 @@ export function createCesiumGlobe(
report = uncaught,
credits = null,
credentials = {},
// Tests load their own.
loadPhotoreal = loadPhotorealisticTileset,
},
) {
const scene = widget.scene;
@@ -130,9 +154,17 @@ export function createCesiumGlobe(
// --- Base ------------------------------------------------------------------
/** The photoreal tileset this port loaded, if any. */
/** The photoreal tileset this port loaded, if any, and its spec. */
let photoreal = null;
let photorealSpec = null;
let photorealStatus = { route: 'none' };
/**
* The photoreal tileset last turned off, kept hidden with the spec and
* status it loaded with: that same spec shows it again at once, without
* loading it anew (Google counts each load).
*/
let parked = null;
photorealTilesets.set(scene, () => photoreal ?? parked?.tileset ?? null);
let photorealGen = 0;
let terrainGen = 0;
let baseGen = 0;
@@ -178,31 +210,74 @@ export function createCesiumGlobe(
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();
function destroyTileset(tileset) {
if (!tileset.isDestroyed() && !scene.primitives.remove(tileset))
tileset.destroy();
}
function removePhotoreal() {
if (!photoreal) return;
const tileset = photoreal;
photoreal = null;
photorealSpec = null;
// The layers draped on it move off before it takes them with it.
imagery.sync();
destroyTileset(tileset);
}
/** Hide the photoreal tileset, kept for its spec to show again. */
function parkPhotoreal() {
if (!photoreal) return;
if (parked) destroyTileset(parked.tileset);
parked = {
spec: photorealSpec,
status: photorealStatus,
tileset: photoreal,
};
photoreal.show = false;
photoreal = null;
photorealSpec = null;
imagery.sync();
}
/** Show the parked tileset again when `spec` is the one it loaded with. */
function unparkPhotoreal(spec) {
const kept = parked;
if (!kept || kept.spec !== spec || kept.tileset.isDestroyed()) return null;
parked = null;
removePhotoreal();
photoreal = kept.tileset;
photorealSpec = spec;
photoreal.show = true;
photorealStatus = kept.status;
imagery.sync();
requestRender('base');
return photorealStatus;
}
async function setPhotoreal(spec) {
const gen = ++photorealGen;
removePhotoreal();
photorealStatus = { route: 'none' };
if (!spec || !can('photoreal')) {
if (spec) removePhotoreal();
else parkPhotoreal();
photorealStatus = { route: 'none' };
requestRender('base');
return photorealStatus;
}
const shown = unparkPhotoreal(spec);
if (shown) return shown;
removePhotoreal();
if (parked) {
destroyTileset(parked.tileset);
parked = null;
}
photorealStatus = { route: 'none' };
// 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, {
const result = await loadPhotoreal(Cesium, {
googleApiKey,
// A renewal names the token it replaces.
googleTokens: token ? { token: (options) => token(options) } : null,
@@ -224,6 +299,7 @@ export function createCesiumGlobe(
};
} else {
photoreal = scene.primitives.add(result.tileset);
photorealSpec = spec;
photorealStatus = { route: ROUTES[result.route] ?? 'google' };
}
imagery.sync();
@@ -616,6 +692,10 @@ export function createCesiumGlobe(
if (disposed) return;
disposed = true;
photorealGen += 1;
if (parked) {
destroyTileset(parked.tileset);
parked = null;
}
terrainGen += 1;
baseGen += 1;
baseLoad?.abort();
+45 -1
View File
@@ -1,7 +1,11 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import { createCesiumGlobe, markBaseTileset } from './globe.js';
import {
cesiumPhotorealOf,
createCesiumGlobe,
markBaseTileset,
} from './globe.js';
import { hookProvider, TILE_RETRY_DELAY_MS, xyzTileUrl } from './imagery.js';
const ALL = new Set([
@@ -805,3 +809,43 @@ test('hillshade shading owns a free globe material, follows the terrain, gives i
assert.equal(scene.globe.material, theirs);
dispose();
});
test('photoreal turned off is kept hidden, and the same spec shows it without loading it again', async () => {
const scene = fakeScene();
const loads = [];
const { port } = createCesiumGlobe(
{ scene },
{
capabilities: new Set(['photoreal']),
requestRender: () => {},
credentials: { worldDataToken: 'ion' },
loadPhotoreal: async (_sdk, credentials) => {
loads.push(credentials);
return { tileset: fakeTileset(), route: 'direct', errors: [] };
},
},
);
const spec = { provider: 'google', key: 'key', fallback: true };
assert.deepEqual(await port.setPhotoreal(spec), { route: 'google' });
assert.equal(loads.length, 1);
assert.equal(loads[0].googleApiKey, 'key');
assert.equal(loads[0].cesiumToken, 'ion');
const first = cesiumPhotorealOf(scene);
assert.equal(first.show, true);
assert.deepEqual(await port.setPhotoreal(null), { route: 'none' });
assert.equal(first.isDestroyed(), false, 'kept');
assert.equal(first.show, false, 'hidden');
assert.equal(cesiumPhotorealOf(scene), first, 'QA scripts still read it');
assert.deepEqual(await port.setPhotoreal(spec), { route: 'google' });
assert.equal(loads.length, 1, 'not loaded again');
assert.equal(cesiumPhotorealOf(scene), first);
assert.equal(first.show, true);
await port.setPhotoreal(null);
await port.setPhotoreal({ provider: 'google', key: 'other' });
assert.equal(loads.length, 2, 'another spec loads its own');
assert.equal(first.isDestroyed(), true, 'the kept one goes');
assert.notEqual(cesiumPhotorealOf(scene), first);
});
+3 -2
View File
@@ -59,10 +59,11 @@ export async function loadPhotorealisticTileset(
export function createGoogleDirectTileset(Cesium, key) {
key = clean(key);
if (!key) throw new Error('Google 3D requires an explicit browser key');
// Tiles keep drawing their own texture while draped weather loads.
// Tiles keep drawing their own texture while draped weather loads, and
// clamped marks land on them, as on the token routes' tiles.
return Cesium.createGooglePhotorealistic3DTileset(
{ key, onlyUsingWithGoogleGeocoder: true },
{ asynchronouslyLoadImagery: true },
{ asynchronouslyLoadImagery: true, enableCollision: true },
);
}
+5 -2
View File
@@ -32,6 +32,7 @@ import {
videoProvider,
} from './imageryFrames.js';
import { withTileRequestHook } from './tileRequests.js';
import { createIonImagery } from './mapImagery.js';
const SPLITS = { none: 'NONE', left: 'LEFT', right: 'RIGHT' };
const DRAPES = new Set(['surface', 'objects', 'all']);
@@ -157,9 +158,11 @@ export function providerFor(spec, { worldDataToken } = {}) {
throw new TypeError(
'World imagery needs the renderer’s world data token',
);
return Cesium.IonImageryProvider.fromAssetId(
// Bing through ion, its tiles over HTTPS on any page, with ion's
// credits, as the map stacks have always drawn it.
return createIonImagery(
WORLD_ASSETS[spec.worldStyle ?? 'aerial'] ?? WORLD_ASSETS.aerial,
{ accessToken },
accessToken,
);
}
// The app's own: the vector base's tiles, painted from its style.
+1 -1
View File
@@ -329,7 +329,7 @@ test('both Google 3D routes keep tiles drawing while draped imagery loads', asyn
assert.equal(await createGoogleIonTileset(sdk, 'token'), 'ion');
assert.deepEqual(calls[0], [
{ key: 'key', onlyUsingWithGoogleGeocoder: true },
{ asynchronouslyLoadImagery: true },
{ asynchronouslyLoadImagery: true, enableCollision: true },
]);
assert.equal(calls[1][0].id, 2275207);
assert.equal(calls[1][0].accessToken, 'token');