Map stacks off the Cesium allow-list: providers move into the Cesium adapter

The map stacks' imagery, terrain and Google 3D factories move into the
Cesium adapter (src/render/cesium/mapImagery.js, mapTerrain.js,
google3d.js); the ./maps/imagery, ./maps/terrain and ./maps/3d exports
point there. The catalog names its ion stacks by asset number, and the
map source controller and default sources are Cesium-free: they
build providers and switch imagery layers, terrain, tilesets and the
globe's visibility through a map engine (src/maps/engine.js) that the
Cesium adapter provides as it loads (mapEngine.js), through the
application's renderer or the ./render/cesium/unbound export. The
controller and createDefaultMapSources also take it as an `engine`
option.

src/maps/catalog.js, controller.js, imagery.js, terrain.js and google3d.js
leave the allow-list.
This commit is contained in:
Sameh Khamis committed 2026-11-09 12:11:42 -08:00
1 parent aea5c3acc6
commit a8a9cc73a4
31 files changed
+364 -140

No files matched your search

+8
View File
@@ -0,0 +1,8 @@
/**
* @module maps/attribution
* @description The on-map credits of the map stacks' sources.
*/
// Attribution and service rights are documented in DATA_SOURCES.md.
export const ESRI_ATTRIBUTION_HTML =
'<a href="https://www.esri.com" target="_blank" rel="noopener">Powered by Esri</a>';
+7 -3
View File
@@ -1,4 +1,8 @@
import * as Cesium from 'cesium';
/**
* The map stacks the maps panel offers, free of renderer code: an `ion` stack's
* `style` is the Cesium ion world imagery asset it shows (2, aerial; 3,
* aerial with labels), the values of Cesium's `IonWorldImageryStyle`.
*/
export const MAP_STACKS = [
{
id: 'photoreal',
@@ -12,7 +16,7 @@ export const MAP_STACKS = [
label: 'Bing Aerial', // i18n-ignore: imagery product name
shortLabel: 'Aerial',
kind: 'ion',
style: Cesium.IonWorldImageryStyle.AERIAL,
style: 2,
requiresIon: true,
},
{
@@ -20,7 +24,7 @@ export const MAP_STACKS = [
label: 'Bing Labels', // i18n-ignore: imagery product name
shortLabel: 'Labels',
kind: 'ion',
style: Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS,
style: 3,
requiresIon: true,
},
{
+73 -62
View File
@@ -1,10 +1,7 @@
import { indexMapSources } from './registry.js';
import * as Cesium from 'cesium';
import { createMapCredits } from './credits.js';
// A viewer of a caller's own gets its credits port (and camera) from the
// factories this loads.
import '../render/cesium/camera.js';
import { markBaseTileset } from '../render/cesium/globe.js';
import { mapEngine } from './engine.js';
import { markBaseTileset } from '../render/baseTilesets.js';
import { acquireImageryComparison } from './imageryComparison.js';
/**
@@ -25,7 +22,12 @@ const resolved = (provider, effectiveStackId) => ({
fallbackMessage: null,
});
/** Coordinate source lifetimes and scene changes; the registry owns provider choices. */
/**
* Coordinate source lifetimes and scene changes; the registry owns provider
* choices. The scene changes go through the renderer's map engine
* (`engine.js`), which a viewer with no renderer bound gets once its owner
* has loaded the package's `./render/cesium/unbound` export.
*/
export class MapSourceController {
constructor(
viewer,
@@ -34,11 +36,13 @@ export class MapSourceController {
initialStack,
onChange = null,
onError = null,
requestRender = () => viewer?.scene?.requestRender?.(),
createImageryLayer = (provider) => new Cesium.ImageryLayer(provider),
engine = mapEngine(),
requestRender = () => engine.requestRender(viewer),
createImageryLayer = (provider) => engine.createImageryLayer(provider),
},
) {
this.viewer = viewer;
this._engine = engine;
this._registry = registry;
this._sources = indexMapSources(registry.sources);
this._activeId = this.isStackAvailable(initialStack)
@@ -110,10 +114,11 @@ export class MapSourceController {
/** Return the shown supplied or controller-owned tileset, if any. */
getImageryHostTileset() {
if (this._destroyed) return null;
const shown = this._engine.tilesetShown;
for (const source of this._sources.values())
if (source.tileset?.show === true) return source.tileset;
if (shown(source.tileset)) return source.tileset;
for (const tileset of this._ownedTilesets)
if (tileset.show === true) return tileset;
if (shown(tileset)) return tileset;
return null;
}
/**
@@ -124,9 +129,9 @@ export class MapSourceController {
*/
getDrapeSurface() {
if (this._destroyed) return null;
if (this.viewer?.scene?.globe?.show === true) return 'globe';
if (this._engine.globeShown(this.viewer)) return 'globe';
const tileset = this.getImageryHostTileset();
return tileset && !tileset.isDestroyed?.() ? 'tileset' : 'none';
return tileset && !this._engine.isDestroyed(tileset) ? 'tileset' : 'none';
}
getActiveId() {
return this._activeId;
@@ -285,23 +290,24 @@ export class MapSourceController {
}
if (gen !== this._switchGen) return;
if (!source.tileset && !this._ownedTilesets.has(tileset)) {
tileset.show = false;
this._engine.showTileset(tileset, false);
markBaseTileset(tileset);
this.viewer.scene.primitives.add(tileset);
this._engine.addTileset(this.viewer, tileset);
this._ownedTilesets.add(tileset);
}
this._removeImageryLayer();
this._credits.show(source.credit || null);
this._showTileset(tileset);
this.viewer.scene.globe.show = false;
this._engine.setGlobeShown(this.viewer, false);
// Terrain is intentionally untouched while the globe is hidden.
}
_showTileset(active) {
const show = this._engine.showTileset;
for (const source of this._sources.values())
if (source.tileset) source.tileset.show = source.tileset === active;
if (source.tileset) show(source.tileset, source.tileset === active);
for (const tileset of this._ownedTilesets)
tileset.show = tileset === active;
show(tileset, tileset === active);
}
async _activateGlobeStack(stack, gen) {
@@ -317,7 +323,7 @@ export class MapSourceController {
this._removeImageryLayer();
this._imageryLayer = this._createImageryLayer(resolution.provider);
this._activeImageryProvider = resolution.provider;
this.viewer.imageryLayers.add(this._imageryLayer, 0);
this._engine.addImageryLayer(this.viewer, this._imageryLayer, 0);
}
const source = this._sources.get(resolution.effectiveStackId);
this._credits.show(source?.credit || null);
@@ -327,7 +333,7 @@ export class MapSourceController {
this._removeImageryErrorListener = null;
this._watchProvider(resolution, gen);
this._showTileset(null);
this.viewer.scene.globe.show = true;
this._engine.setGlobeShown(this.viewer, true);
this._activeId = resolution.effectiveStackId;
this._activeResolution = resolution;
if (source?.terrain && source.terrain.id !== this._terrainMode) {
@@ -349,8 +355,7 @@ export class MapSourceController {
}
_applyTerrain(result) {
if (result.terrain) this.viewer.scene.setTerrain(result.terrain);
else this.viewer.terrainProvider = result.provider;
this._engine.applyTerrain(this.viewer, result);
this._terrainFallback = result.fallback ? result : null;
if (this._replacedTerrain && this._replacedTerrain !== result) {
this._dispose(this._replacedTerrain.provider);
@@ -379,7 +384,9 @@ export class MapSourceController {
async _retryFallbacks() {
const resolution = this._activeResolution;
const flat = this.viewer.scene.globe.show ? this._terrainFallback : null;
const flat = this._engine.globeShown(this.viewer)
? this._terrainFallback
: null;
const id = resolution?.fallbackFor;
let terrain = flat && this._sources.get(this._activeId)?.terrain;
if (terrain?.id !== this._terrainMode) terrain = null;
@@ -460,7 +467,10 @@ export class MapSourceController {
return Boolean(real && !real.fallback);
}
this._terrainProviders.set(terrain.id, Promise.resolve(real));
if (this._terrainFallback === flat && this.viewer.scene.globe.show) {
if (
this._terrainFallback === flat &&
this._engine.globeShown(this.viewer)
) {
this._applyTerrain(real);
this._dispose(flat.provider);
this._requestRender('map-stack');
@@ -540,50 +550,52 @@ export class MapSourceController {
const fallback = this._sources.get(
resolution.effectiveStackId,
)?.tileFailureFallback;
const errorEvent = resolution.provider?.errorEvent;
if (!fallback || !errorEvent?.addEventListener) return;
if (!fallback) return;
let failures = 0;
let pending = false;
this._removeImageryErrorListener = errorEvent.addEventListener((error) => {
if (
gen !== this._switchGen ||
this._activeImageryProvider !== resolution.provider
)
return;
const retryCount = Number(error?.timesRetried);
failures =
Number.isInteger(retryCount) && retryCount >= 0
? Math.max(failures + 1, retryCount + 1)
: failures + 1;
if (failures < fallback.threshold || pending) return;
pending = true;
this._onError?.(
fallback.message,
this.getStack(resolution.effectiveStackId),
);
const expectedGen = this._switchGen + 1;
void this.setStack(fallback.id, { silent: true, [AUTOMATIC]: true })
.then((state) => {
if (
!this._destroyed &&
this._switchGen === expectedGen &&
state?.activeId === fallback.id
) {
this._lastError = fallback.message;
this._emitChange('error');
}
})
.finally(() => {
pending = false;
});
});
this._removeImageryErrorListener = this._engine.onTileError(
resolution.provider,
(error) => {
if (
gen !== this._switchGen ||
this._activeImageryProvider !== resolution.provider
)
return;
const retryCount = Number(error?.timesRetried);
failures =
Number.isInteger(retryCount) && retryCount >= 0
? Math.max(failures + 1, retryCount + 1)
: failures + 1;
if (failures < fallback.threshold || pending) return;
pending = true;
this._onError?.(
fallback.message,
this.getStack(resolution.effectiveStackId),
);
const expectedGen = this._switchGen + 1;
void this.setStack(fallback.id, { silent: true, [AUTOMATIC]: true })
.then((state) => {
if (
!this._destroyed &&
this._switchGen === expectedGen &&
state?.activeId === fallback.id
) {
this._lastError = fallback.message;
this._emitChange('error');
}
})
.finally(() => {
pending = false;
});
},
);
}
_removeImageryLayer() {
this._removeImageryErrorListener?.();
this._removeImageryErrorListener = null;
if (this._imageryLayer)
this.viewer.imageryLayers.remove(this._imageryLayer, true);
this._engine.removeImageryLayer(this.viewer, this._imageryLayer);
this._imageryLayer = null;
this._activeImageryProvider = null;
this._activeResolution = null;
@@ -591,8 +603,7 @@ export class MapSourceController {
_dispose(value) {
if (!value || this._disposed.has(value)) return;
this._disposed.add(value);
if (typeof value.destroy === 'function' && !value.isDestroyed?.())
value.destroy();
this._engine.release(value);
}
destroy() {
if (this._destroyed) return;
@@ -620,7 +631,7 @@ export class MapSourceController {
() => {},
);
for (const tileset of this._ownedTilesets) {
this.viewer.scene.primitives.remove(tileset);
this._engine.removeTileset(this.viewer, tileset);
this._dispose(tileset);
}
for (const promise of this._tilesets.values())
+2
View File
@@ -1,6 +1,8 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { MapSourceController } from './controller.js';
// The controller switches stacks through the Cesium map engine.
import '../render/cesium/mapEngine.js';
import { createDefaultMapSources } from './defaultSources.js';
import { bindRenderer } from '../render/rendererOf.js';
+16 -13
View File
@@ -2,28 +2,31 @@ import { MAP_STACKS } from './catalog.js';
import { photorealUnavailableReason } from './availability.js';
import { keySetupRequirementEnvVars } from '../keySetupCore.mjs';
import { t } from '../i18n/index.js';
import {
createOsmImagery,
createEsriImagery,
createIonImagery,
ESRI_ATTRIBUTION_HTML,
} from './imagery.js';
import { createWorldTerrain, createKeylessTerrain } from './terrain.js';
import { mapEngine } from './engine.js';
import { ESRI_ATTRIBUTION_HTML } from './attribution.js';
/** Select sources and setup guidance without putting provider branches in the controller. */
/**
* Select sources and setup guidance without putting provider branches in the
* controller. Each source builds its imagery and terrain through the
* renderer's map engine (`engine.js`), or the `engine` given, when it is
* first shown.
*/
export function createDefaultMapSources({
googleTileset = null,
cesiumToken = '',
googleApiKey = '',
engine = null,
} = {}) {
// The engine given, else the one the renderer provided, read when used.
const engineOf = () => engine ?? mapEngine();
const ionToken = String(cesiumToken || '').trim();
const hasIon = Boolean(ionToken);
const hasGoogle = Boolean(String(googleApiKey || '').trim());
const terrain = {
id: hasIon ? 'world' : 'keyless',
create: hasIon
? (request) => createWorldTerrain(ionToken, request)
: createKeylessTerrain,
? (request) => engineOf().terrain.world(ionToken, request)
: () => engineOf().terrain.keyless(),
};
return {
defaultId: googleTileset ? 'photoreal' : 'esri-imagery',
@@ -52,10 +55,10 @@ export function createDefaultMapSources({
};
const imagery =
descriptor.kind === 'ion'
? () => createIonImagery(descriptor.style, ionToken)
? () => engineOf().imagery.ion(descriptor.style, ionToken)
: descriptor.id === 'osm'
? createOsmImagery
: createEsriImagery;
? () => engineOf().imagery.osm()
: () => engineOf().imagery.esri();
return {
...common,
imagery,
+33
View File
@@ -0,0 +1,33 @@
/**
* @module maps/engine
* @description What the map stacks need from the renderer that no contract
* port gives yet: the providers each stack's imagery and terrain come from,
* and the scene operations the map source controller (`controller.js`)
* switches stacks with. Cesium-free: the renderer adapter provides it
* as it loads (the Cesium one in `src/render/cesium/mapEngine.js`, loaded by
* the application's renderer and by the package's `./render/cesium/unbound`
* export), and the map code asks for it when it first needs it.
*/
let provided = null;
/**
* Provide the map engine; a later call replaces it.
* @param {object} engine
*/
export function provideMapEngine(engine) {
provided = engine;
}
/**
* The map engine the renderer adapter provided.
* @returns {object}
* @throws {Error} When no adapter has provided one yet.
*/
export function mapEngine() {
if (!provided)
throw new Error(
'No map engine: load the renderer, or the package export ./render/cesium/unbound, first',
);
return provided;
}
-130
View File
@@ -1,130 +0,0 @@
const clean = (value) => String(value || '').trim();
/**
* Decide which map provider can deliver the best startup experience.
* @param {{googleApiKey?: string, cesiumToken?: string}} credentials
* @returns {'google-direct'|'google-ion'|'osm'}
*/
export function selectMapStartupRoute({
googleApiKey = '',
cesiumToken = '',
} = {}) {
if (clean(googleApiKey)) return 'google-direct';
if (clean(cesiumToken)) return 'google-ion';
return 'osm';
}
/**
* Load Google Photorealistic 3D Tiles through direct Google access when
* configured, otherwise through Cesium ion's hosted Google asset. Direct
* access uses a browser key, or else short-lived tokens from the app's
* server (see googleTokens.js). If direct access fails and an ion token is
* available, ion is the recovery path.
*
* @param {object} Cesium
* @param {{googleApiKey?: string, cesiumToken?: string, googleTokens?: {token: Function}|null}} credentials
* @returns {Promise<{tileset: object|null, route: 'google-direct'|'google-token'|'google-ion'|'osm', errors: Error[]}>}
*/
export async function loadPhotorealisticTileset(
Cesium,
{ googleApiKey = '', cesiumToken = '', googleTokens = null } = {},
) {
const googleKey = clean(googleApiKey);
const ionToken = clean(cesiumToken);
const errors = [];
const attempts = [];
if (googleKey)
attempts.push({
route: 'google-direct',
create: () => createGoogleDirectTileset(Cesium, googleKey),
});
else if (googleTokens)
attempts.push({
route: 'google-token',
create: () => createGoogleTokenTileset(Cesium, googleTokens),
});
if (ionToken)
attempts.push({
route: 'google-ion',
create: () => createGoogleIonTileset(Cesium, ionToken),
});
for (const attempt of attempts) {
try {
const tileset = await attempt.create();
return { tileset, route: attempt.route, errors };
} catch (error) {
errors.push(error instanceof Error ? error : new Error(String(error)));
}
}
return { tileset: null, route: 'osm', errors };
}
/** Pass credentials to the source instead of changing SDK-wide defaults. */
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.
return Cesium.createGooglePhotorealistic3DTileset(
{ key, onlyUsingWithGoogleGeocoder: true },
{ asynchronouslyLoadImagery: true },
);
}
/**
* Google 3D with short-lived tokens instead of a key. Every tile request
* carries the token as a header; a tile refused for an expired token gets
* the renewed one and is tried once more.
*/
export async function createGoogleTokenTileset(Cesium, tokens) {
const token = await tokens.token();
if (!token) throw new Error('Google 3D tokens are not offered');
const credit = Cesium.GoogleMaps.getDefaultCredit?.();
const resource = new Cesium.Resource({
url: `${Cesium.GoogleMaps.mapTilesApiEndpoint}v1/3dtiles/root.json`,
headers: { Authorization: `Bearer ${token}` },
credits: credit ? [credit] : undefined,
retryAttempts: 1,
async retryCallback(failed, error) {
if (![401, 403].includes(error?.statusCode)) return false;
const used = failed.headers.Authorization?.replace(/^Bearer /, '');
const renewed = await tokens.token({ replacing: used });
if (!renewed || renewed === used) return false;
failed.headers.Authorization = `Bearer ${renewed}`;
return true;
},
});
// The settings Cesium's Google helper applies to the key route.
return Cesium.Cesium3DTileset.fromUrl(resource, {
cacheBytes: 1536 * 1024 * 1024,
maximumCacheOverflowBytes: 1024 * 1024 * 1024,
enableCollision: true,
// Tiles keep drawing their own texture while draped weather loads.
asynchronouslyLoadImagery: true,
});
}
export async function createGoogleIonTileset(
Cesium,
accessToken,
{ signal } = {},
) {
accessToken = clean(accessToken);
if (!accessToken)
throw new Error('Google 3D through ion requires an explicit token');
signal?.throwIfAborted();
const resource = await Cesium.IonResource.fromAssetId(2275207, {
accessToken,
});
signal?.throwIfAborted();
// Match the installed SDK's Google helper rendering/cache defaults.
return Cesium.Cesium3DTileset.fromUrl(resource, {
cacheBytes: 1536 * 1024 * 1024,
maximumCacheOverflowBytes: 1024 * 1024 * 1024,
enableCollision: true,
// Tiles keep drawing their own texture while draped weather loads.
asynchronouslyLoadImagery: true,
});
}
-66
View File
@@ -1,66 +0,0 @@
import * as Cesium from 'cesium';
// Attribution and service rights are documented in DATA_SOURCES.md.
export const ESRI_ATTRIBUTION_HTML =
'<a href="https://www.esri.com" target="_blank" rel="noopener">Powered by Esri</a>';
export function createOsmImagery() {
return new Cesium.OpenStreetMapImageryProvider({
url: 'https://tile.openstreetmap.org/',
credit: '© OpenStreetMap contributors',
});
}
export function createEsriImagery() {
return Cesium.ArcGisMapServerImageryProvider.fromUrl(
'https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer',
{
credit:
'Powered by Esri — Source: Esri, Maxar, Earthstar Geographics, and the GIS User Community',
enablePickFeatures: false,
},
);
}
export function createIonImagery(style, accessToken) {
accessToken = String(accessToken || '').trim();
if (!accessToken) throw new Error('Ion imagery requires an explicit token');
if (
style === Cesium.IonWorldImageryStyle.AERIAL ||
style === Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS
) {
return createBingIonImagery(style, accessToken);
}
return Cesium.IonImageryProvider.fromAssetId(style, { accessToken });
}
async function createBingIonImagery(style, accessToken) {
const endpoint = await new Cesium.Resource({
url: `https://api.cesium.com/v1/assets/${style}/endpoint`,
queryParameters: { access_token: accessToken },
}).fetchJson();
if (
endpoint?.type !== 'IMAGERY' ||
endpoint.externalType !== 'BING' ||
typeof endpoint.options?.url !== 'string'
) {
throw new Error('Ion world imagery did not return a Bing imagery endpoint');
}
// Bing otherwise follows the page's HTTP scheme on localhost. Resolve its
// ion-issued credentials through public APIs so tiles use HTTPS without
// weakening CSP, changing SDK defaults or touching provider internals.
const { url, ...options } = endpoint.options;
const provider = await Cesium.BingMapsImageryProvider.fromUrl(url, {
...options,
tileProtocol: 'https',
});
const ionCredits = (endpoint.attributions ?? []).map(
({ html, collapsible }) => new Cesium.Credit(html, collapsible === false),
);
const getTileCredits = provider.getTileCredits.bind(provider);
provider.getTileCredits = (x, y, level) => [
...ionCredits,
...(getTileCredits(x, y, level) ?? []),
];
return provider;
}
@@ -1,6 +1,8 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { MapSourceController } from './controller.js';
// The controller switches stacks through the Cesium map engine.
import '../render/cesium/mapEngine.js';
function fixture() {
return new MapSourceController(
{
-329
View File
@@ -1,329 +0,0 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import { createIonImagery } from './imagery.js';
import { createWorldTerrain, createKeylessTerrain } from './terrain.js';
import { createDefaultMapSources } from './defaultSources.js';
test('Esri uses Re:Earth without keys and preserves ion terrain when configured', async () => {
const originalTerrain = Cesium.CesiumTerrainProvider.fromUrl;
const originalResource = Cesium.IonResource.fromAssetId;
const calls = [];
try {
Cesium.CesiumTerrainProvider.fromUrl = async (resource) => {
calls.push(resource);
return { resource };
};
Cesium.IonResource.fromAssetId = async () =>
assert.fail('keyless mode must not acquire ion terrain');
const keyless = createDefaultMapSources();
const esri = keyless.sources.find(
({ descriptor }) => descriptor.id === 'esri-imagery',
);
assert.equal(esri.available, true);
assert.equal(esri.terrain.id, 'keyless');
assert.equal(esri.terrain.create, createKeylessTerrain);
await esri.terrain.create();
// A Resource, not a bare URL: the retry policy rides on it (terrainRetry.js).
assert.equal(calls.length, 1);
assert.ok(calls[0] instanceof Cesium.Resource);
assert.equal(
calls[0].url,
'https://terrain.reearth.land/cesium-mesh/ellipsoid',
);
assert.equal(calls[0].retryAttempts, 3);
assert.equal(typeof calls[0].retryCallback, 'function');
assert.equal(
keyless.sources.find(({ descriptor }) => descriptor.id === 'photoreal')
.available,
false,
);
for (const credentials of [
{ googleApiKey: 'test-key' },
{ cesiumToken: 'test-token' },
]) {
const keyed = createDefaultMapSources({
...credentials,
googleTileset: { show: true },
});
assert.equal(
keyed.sources.find(({ descriptor }) => descriptor.id === 'photoreal')
.available,
true,
);
assert.equal(
keyed.sources.find(({ descriptor }) => descriptor.id === 'esri-imagery')
.terrain.id,
credentials.cesiumToken ? 'world' : 'keyless',
);
const failedTileset = createDefaultMapSources(credentials);
assert.equal(
failedTileset.sources.find(
({ descriptor }) => descriptor.id === 'photoreal',
).available,
false,
);
}
} finally {
Cesium.CesiumTerrainProvider.fromUrl = originalTerrain;
Cesium.IonResource.fromAssetId = originalResource;
}
});
test('imagery and terrain pass their own ion token without relying on SDK defaults', async () => {
const originalImagery = Cesium.IonImageryProvider.fromAssetId;
const originalResource = Cesium.IonResource.fromAssetId;
const originalTerrain = Cesium.CesiumTerrainProvider.fromUrl;
const calls = [];
const defaultToken = Cesium.Ion.defaultAccessToken;
try {
Cesium.IonImageryProvider.fromAssetId = async (id, options) => {
calls.push({ kind: 'imagery', id, options });
return { id };
};
Cesium.IonResource.fromAssetId = async (id, options) => {
calls.push({ kind: 'resource', id, options });
return { id };
};
Cesium.CesiumTerrainProvider.fromUrl = async (resource, options) => {
calls.push({ kind: 'terrain', resource, options });
return { id: 'terrain' };
};
await createIonImagery(12345, 'imagery-token');
const result = await createWorldTerrain('terrain-token');
assert.equal(calls[0].options.accessToken, 'imagery-token');
assert.equal(calls[1].options.accessToken, 'terrain-token');
assert.equal(calls[1].id, 1);
assert.equal(calls[2].options.requestVertexNormals, true);
assert.equal(result.provider.id, 'terrain');
assert.equal(Cesium.Ion.defaultAccessToken, defaultToken);
} finally {
Cesium.IonImageryProvider.fromAssetId = originalImagery;
Cesium.IonResource.fromAssetId = originalResource;
Cesium.CesiumTerrainProvider.fromUrl = originalTerrain;
}
});
test('both Bing ion stacks use HTTPS and retain ion and per-tile attribution', async (t) => {
const defaultToken = Cesium.Ion.defaultAccessToken;
const metadataCalls = [];
const bingCalls = [];
const perTileCalls = [];
const bingCredit = new Cesium.Credit('Bing tile credit', true);
const endpoint = {
type: 'IMAGERY',
externalType: 'BING',
options: Object.freeze({
url: 'https://dev.virtualearth.net',
key: 'ion-issued-bing-fixture',
mapStyle: 'Aerial',
tileProtocol: 'http',
}),
attributions: [
{ html: 'Ion required credit', collapsible: false },
{ html: 'Ion optional credit', collapsible: true },
],
};
t.mock.method(Cesium.Resource.prototype, 'fetchJson', async function () {
metadataCalls.push({
url: this.url,
token: this.queryParameters.access_token,
});
const mapStyle = this.url.includes(
`/assets/${Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS}/`,
)
? 'AerialWithLabels'
: 'Aerial';
return {
...endpoint,
options: Object.freeze({ ...endpoint.options, mapStyle }),
};
});
t.mock.method(Cesium.IonImageryProvider, 'fromAssetId', () =>
assert.fail('Bing must not inherit the local HTTP page protocol'),
);
t.mock.method(
Cesium.BingMapsImageryProvider,
'fromUrl',
async (url, options) => {
bingCalls.push({ url, options });
const provider = {
errorEvent: new Cesium.Event(),
getTileCredits(x, y, level) {
assert.equal(this, provider);
perTileCalls.push([x, y, level]);
return level === 0 ? undefined : [bingCredit];
},
};
return provider;
},
);
for (const style of [
Cesium.IonWorldImageryStyle.AERIAL,
Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS,
]) {
const provider = await createIonImagery(style, ' own-ion-token ');
const credits = provider.getTileCredits(3, 4, 5);
assert.deepEqual(
credits.map(({ html, showOnScreen }) => ({ html, showOnScreen })),
[
{ html: 'Ion required credit', showOnScreen: true },
{ html: 'Ion optional credit', showOnScreen: false },
{ html: 'Bing tile credit', showOnScreen: true },
],
);
assert.equal(credits[2], bingCredit);
assert.equal(provider.getTileCredits(0, 0, 0).length, 2);
assert.ok(provider.errorEvent instanceof Cesium.Event);
assert.equal(metadataCalls.at(-1).token, 'own-ion-token');
const requested = new URL(metadataCalls.at(-1).url);
assert.equal(requested.origin, 'https://api.cesium.com');
assert.equal(requested.pathname, `/v1/assets/${style}/endpoint`);
}
assert.deepEqual(perTileCalls, [
[3, 4, 5],
[0, 0, 0],
[3, 4, 5],
[0, 0, 0],
]);
assert.equal(bingCalls.length, 2);
for (const [index, { url, options }] of bingCalls.entries()) {
assert.equal(url, 'https://dev.virtualearth.net');
assert.deepEqual(options, {
key: 'ion-issued-bing-fixture',
mapStyle: index === 0 ? 'Aerial' : 'AerialWithLabels',
tileProtocol: 'https',
});
}
assert.equal(endpoint.options.tileProtocol, 'http');
assert.equal(Cesium.Ion.defaultAccessToken, defaultToken);
});
test('Bing ion metadata and construction failures propagate without another source', async (t) => {
const style = Cesium.IonWorldImageryStyle.AERIAL;
const metadataError = new Error('ion metadata fixture failure');
const providerError = new Error('Bing construction fixture failure');
let metadata = () => {
throw metadataError;
};
let bingCalls = 0;
t.mock.method(Cesium.Resource.prototype, 'fetchJson', async () => metadata());
t.mock.method(Cesium.BingMapsImageryProvider, 'fromUrl', async () => {
bingCalls += 1;
throw providerError;
});
t.mock.method(Cesium.IonImageryProvider, 'fromAssetId', () =>
assert.fail('Bing failures must not silently use an alternate provider'),
);
await assert.rejects(createIonImagery(style, 'test-token'), metadataError);
for (const endpoint of [
undefined,
{
type: 'TERRAIN',
externalType: 'BING',
options: { url: 'https://example.test' },
},
{
type: 'IMAGERY',
externalType: 'OTHER',
options: { url: 'https://example.test' },
},
{ type: 'IMAGERY', externalType: 'BING', options: {} },
]) {
metadata = () => endpoint;
await assert.rejects(
createIonImagery(style, 'test-token'),
/Bing imagery endpoint/,
);
}
assert.equal(bingCalls, 0);
metadata = () => ({
type: 'IMAGERY',
externalType: 'BING',
options: { url: 'https://dev.virtualearth.net', key: 'bing-fixture' },
});
await assert.rejects(createIonImagery(style, 'test-token'), providerError);
assert.equal(bingCalls, 1);
});
test('other ion imagery assets keep the standard SDK factory', async (t) => {
const expected = {};
const calls = [];
t.mock.method(Cesium.Resource.prototype, 'fetchJson', () =>
assert.fail('generic assets must use the SDK ion factory'),
);
t.mock.method(Cesium.IonImageryProvider, 'fromAssetId', async (...args) => {
calls.push(args);
return expected;
});
assert.equal(await createIonImagery(12345, ' custom-token '), expected);
assert.deepEqual(calls, [[12345, { accessToken: 'custom-token' }]]);
});
test('cancellation after ion metadata prevents terrain construction', async () => {
const originalResource = Cesium.IonResource.fromAssetId;
const originalTerrain = Cesium.CesiumTerrainProvider.fromUrl;
const controller = new AbortController();
try {
Cesium.IonResource.fromAssetId = async () => {
controller.abort();
return {};
};
Cesium.CesiumTerrainProvider.fromUrl = () =>
assert.fail('cancelled terrain construction');
await assert.rejects(
createWorldTerrain('test-token', { signal: controller.signal }),
{ name: 'AbortError' },
);
} finally {
Cesium.IonResource.fromAssetId = originalResource;
Cesium.CesiumTerrainProvider.fromUrl = originalTerrain;
}
});
test('credentialed source factories reject an omitted token instead of consuming an SDK default', async () => {
assert.throws(
() => createIonImagery(Cesium.IonWorldImageryStyle.AERIAL, ''),
/explicit token/,
);
await assert.rejects(createWorldTerrain(' '), /explicit ion token/);
});
test('both Google 3D routes keep tiles drawing while draped imagery loads', async () => {
const { createGoogleDirectTileset, createGoogleIonTileset } =
await import('./google3d.js');
const calls = [];
const sdk = {
createGooglePhotorealistic3DTileset: async (...args) => {
calls.push(args);
return 'direct';
},
IonResource: { fromAssetId: async (id, options) => ({ id, ...options }) },
Cesium3DTileset: {
fromUrl: async (...args) => {
calls.push(args);
return 'ion';
},
},
};
assert.equal(await createGoogleDirectTileset(sdk, 'key'), 'direct');
assert.equal(await createGoogleIonTileset(sdk, 'token'), 'ion');
assert.deepEqual(calls[0], [
{ key: 'key', onlyUsingWithGoogleGeocoder: true },
{ asynchronouslyLoadImagery: true },
]);
assert.equal(calls[1][0].id, 2275207);
assert.equal(calls[1][0].accessToken, 'token');
assert.equal(calls[1][1].asynchronouslyLoadImagery, true);
assert.equal(calls[1][1].enableCollision, true);
});
test('unreachable keyless terrain falls back to flat terrain marked as a fallback', async (t) => {
t.mock.method(Cesium.CesiumTerrainProvider, 'fromUrl', async () => {
throw new Error('layer.json unreachable');
});
t.mock.method(console, 'warn', () => {});
const result = await createKeylessTerrain();
assert.ok(result.provider instanceof Cesium.EllipsoidTerrainProvider);
assert.equal(result.fallback, true);
});
+20
View File
@@ -0,0 +1,20 @@
/**
* @module maps/startupRoute
* @description Which route the photoreal base starts on, from the
* credentials configured; Cesium-free.
*/
const clean = (value) => String(value || '').trim();
/**
* Decide which map provider can deliver the best startup experience.
* @param {{googleApiKey?: string, cesiumToken?: string}} credentials
* @returns {'google-direct'|'google-ion'|'osm'}
*/
export function selectMapStartupRoute({
googleApiKey = '',
cesiumToken = '',
} = {}) {
if (clean(googleApiKey)) return 'google-direct';
if (clean(cesiumToken)) return 'google-ion';
return 'osm';
}
-64
View File
@@ -1,64 +0,0 @@
import * as Cesium from 'cesium';
import { createTerrainRetryPolicy } from './terrainRetry.js';
/** Re:Earth / Mapterhorn ellipsoidal quantized mesh, CC BY 4.0. */
export const KEYLESS_TERRAIN_URL =
'https://terrain.reearth.land/cesium-mesh/ellipsoid';
/** These factories are lazy: a hidden globe must not trigger terrain loading. */
export async function createWorldTerrain(accessToken, { signal } = {}) {
accessToken = String(accessToken || '').trim();
if (!accessToken)
throw new Error('World terrain requires an explicit ion token');
signal?.throwIfAborted();
const resource = await Cesium.IonResource.fromAssetId(1, { accessToken });
signal?.throwIfAborted();
return {
provider: await Cesium.CesiumTerrainProvider.fromUrl(resource, {
requestVertexNormals: true,
requestWaterMask: false,
ellipsoid: Cesium.Ellipsoid.WGS84,
}),
};
}
function logThrottle({ statusCode, delayMs, inWindow }) {
// One line per cooldown window, not per tile: a burst throttles dozens.
if (inWindow !== 1) return;
console.warn(
`[MapStack] Re:Earth terrain answered ${statusCode}; retrying throttled tiles after ${Math.round(delayMs)} ms`,
);
}
/**
* The Re:Earth resource with the tile retry policy attached. Cesium copies
* `retryCallback`/`retryAttempts` onto every derived resource, so layer.json
* and each `{z}/{x}/{y}.terrain` fetch inherit it (see `terrainRetry.js`).
* @param {ReturnType<typeof createTerrainRetryPolicy>} [policy]
* @returns {Cesium.Resource}
*/
export function createKeylessTerrainResource(
policy = createTerrainRetryPolicy({ onThrottle: logThrottle }),
) {
return new Cesium.Resource({
url: KEYLESS_TERRAIN_URL,
retryCallback: policy.retryCallback,
retryAttempts: policy.retryAttempts,
});
}
export async function createKeylessTerrain() {
try {
return {
provider: await Cesium.CesiumTerrainProvider.fromUrl(
createKeylessTerrainResource(),
),
};
} catch (error) {
console.warn(
'[MapStack] Re:Earth terrain unavailable, falling back to flat ellipsoid terrain:',
error,
);
return { provider: new Cesium.EllipsoidTerrainProvider(), fallback: true };
}
}
+1 -1
View File
@@ -12,7 +12,7 @@ import {
import {
KEYLESS_TERRAIN_URL,
createKeylessTerrainResource,
} from './terrain.js';
} from '../render/cesium/mapTerrain.js';
const START = 1_700_000_000_000;