Files
gods-eye-view/src/globe/navara/maps.js
T
German Khokhlov 00153acbeb Keep Navara's 3D Tiles where the tileset puts them
Navara's 3D Tiles source defaults to model.height 1, which moves a
transformed tileset by a metre along Earth-fixed X: on the synthetic set
flat roofs read 0.12 m high and a sloping roof 0.68 m off, and the drawn
meshes move with them. The adapter sets the height to 0 and records the
package behaviour in WORKAROUNDS.md, with a test that loads the real
package. The downward surface ray now takes its direction from the
place's own normal, so it no longer drifts sideways.

qa-tiles-fixture gains --report (heights and drape pixels per engine,
without asserting), starts on Cesium, and checks each drape hidden, shown
and hidden again; qa-surface-heights uses the plan's 0.5 m tolerance under
tiles and names the point that misses.
2026-11-10 17:16:23 +04:00

390 lines
13 KiB
JavaScript

// Map sources on a Navara view. Sources are maps/registry.js entries
// ({ descriptor, credit } for imagery, { id } for terrain) or plain
// descriptions ({ kind, accessToken?, googleApiKey? }); this module builds
// Navara sources and layers from them. The URLs and credits repeat those of
// src/globe/cesium/mapImagery.js and terrain.js, which import Cesium.
//
// - imagery: OSM and Esri as `raster-tile` layers; Cesium ion imagery (Bing)
// has no Navara path yet and rejects.
// - terrain: the keyless Re:Earth quantized mesh, Cesium World Terrain through
// the ion endpoint with an explicit token (Navara sends it as a Bearer
// token), or none (the ellipsoid). Navara 0.2.1 panics on a quantized-mesh
// URL without the {z}/{x}/{y}.terrain template, so URLs always carry it.
// - photoreal: Google 3D tiles with a browser key only (no server proxy),
// with Google's logo and the tiles' own
// copyright lines (creditLayerId) on screen. Showing them hides the base
// imagery; clearing them restores the last base imagery and its credit.
// Hidden, not deleted: deleting the last raster layer stops Navara 0.2.1
// loading terrain at the current view.
import {
SENTINEL2_CREDIT,
SENTINEL2_MAX_ZOOM,
SENTINEL2_URL,
} from '../../maps/sentinel2.js';
import { localTilesetPath } from '../../maps/qaTileset.js';
const OSM_URL = 'https://tile.openstreetmap.org/{z}/{x}/{y}.png';
const OSM_CREDIT = {
attribution: '© OpenStreetMap contributors',
attributionUrl: 'https://www.openstreetmap.org/copyright',
};
const ESRI_URL =
'https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}';
const ESRI_CREDIT = {
attributionHtml:
'<a href="https://www.esri.com" target="_blank" rel="noopener">Powered by Esri</a>',
};
const KEYLESS_TERRAIN_URL =
'https://terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain';
const KEYLESS_TERRAIN_MAX_ZOOM = 14;
const ION_WORLD_TERRAIN_ENDPOINT =
'https://api.cesium.com/v1/assets/1/endpoint?access_token=';
const GOOGLE_TILES_ROOT = 'https://tile.googleapis.com/v1/3dtiles/root.json';
// The mark Cesium shows for Google tiles (GoogleMaps.getDefaultCredit).
const GOOGLE_LOGO = 'https://assets.ion.cesium.com/google-credit.png';
// Cesium3DTileset's default maximumScreenSpaceError.
const PHOTOREAL_MAX_SSE = 16;
const kindOf = (source) => (source?.descriptor ?? source)?.kind;
function imageryFor(source) {
const kind = kindOf(source);
const credit =
source?.credit != null ? { attributionHtml: String(source.credit) } : null;
switch (kind) {
case 'sentinel2':
return {
url: SENTINEL2_URL,
maxZoom: SENTINEL2_MAX_ZOOM,
credit: { attributionHtml: SENTINEL2_CREDIT },
};
case 'osm':
return { url: OSM_URL, credit: credit ?? OSM_CREDIT };
case 'esri-imagery':
return { url: ESRI_URL, credit: credit ?? ESRI_CREDIT };
case 'ion':
throw new Error('Cesium ion imagery is not available on Navara yet');
default:
throw new TypeError(`Unknown imagery source: ${kind}`);
}
}
// After a map change Navara 0.2.1 can report idle and stop drawing before a
// raster tile it fetched arrives (measured at the whole-globe view: the
// stack switch drew a stale picture until something else asked for a
// frame). For a while after each change the engine asks for frames itself.
const SETTLE_MS = 6000;
const SETTLE_EVERY_MS = 250;
/**
* @param {object} view A Navara ThreeView (addSource, addLayer, attribution, forceUpdate).
* @param {{ fetch?: typeof fetch, setInterval?: Function,
* clearInterval?: Function, now?: () => number }} [options] timers: test seams.
* @returns {{ maps: object, destroy: () => void }}
*/
export function createNavaraMaps(
view,
{
fetch: fetchJson = globalThis.fetch,
setInterval: every = globalThis.setInterval,
clearInterval: stopEvery = globalThis.clearInterval,
now = () => performance.now(),
} = {},
) {
let settleTimer = null;
let settleUntil = 0;
const stopSettling = () => {
if (settleTimer !== null) stopEvery(settleTimer);
settleTimer = null;
};
// A frame now, and frames for SETTLE_MS while tiles arrive.
const changed = () => {
view.forceUpdate();
settleUntil = now() + SETTLE_MS;
if (settleTimer !== null || destroyed) return;
settleTimer = every(() => {
if (destroyed || now() >= settleUntil) {
stopSettling();
return;
}
view.forceUpdate();
}, SETTLE_EVERY_MS);
};
const slots = { imagery: null, terrain: null, photoreal: null };
// Transparent tile overlays (sea marks, ski pistes) above the base
// imagery: Navara draws raster layers in the order they were added.
const overlays = new Set();
function restackOverlays() {
for (const overlay of overlays) {
overlay.layer.delete();
overlay.layer = view.addLayer({ type: 'raster', source: overlay.source });
}
}
// Base imagery and photoreal tiles share one switch order (display): the
// call made last decides what shows.
const generations = { display: 0, terrain: 0 };
let destroyed = false;
// maps.terrainRevision: one more for every terrain shown or cleared.
let terrainRevision = 0;
function retire(slot) {
if (!slot) return;
slot.layer.delete();
slot.source.delete();
if (slot.credits.length && !slot.hidden)
view.attribution?.remove(slot.credits);
}
function clear(name) {
const slot = slots[name];
slots[name] = null;
retire(slot);
if (name === 'terrain' && slot) terrainRevision++;
}
// The new layer goes in before the old one goes: deleting the last raster
// layer stops Navara 0.2.1 loading terrain at the current view.
function show(name, key, sourceDesc, layerDesc, credits = []) {
const previous = slots[name];
const source = view.addSource(sourceDesc);
const layer = view.addLayer({ ...layerDesc, source });
if (name === 'imagery') restackOverlays();
const shown = credits.map((credit) =>
typeof credit === 'function' ? credit(layer) : credit,
);
retire(previous);
if (name === 'terrain') terrainRevision++;
if (shown.length) view.attribution?.add(shown);
slots[name] = {
key,
source,
layer,
layerDesc,
credits: shown,
hidden: false,
};
changed();
}
// Base imagery under photoreal is hidden rather than deleted (see show).
function setImageryShown(shown) {
const slot = slots.imagery;
if (!slot || slot.hidden === !shown) return;
slot.hidden = !shown;
slot.layer.update({
...slot.layerDesc,
source: slot.source,
raster: { show: shown },
});
if (slot.credits.length)
view.attribution?.[shown ? 'add' : 'remove'](slot.credits);
changed();
}
async function terrainFor(source) {
const kind = source?.kind ?? source?.id;
switch (kind) {
case 'ellipsoid':
return null;
case 'keyless':
return {
type: 'quantized-mesh',
url: KEYLESS_TERRAIN_URL,
maxZoom: KEYLESS_TERRAIN_MAX_ZOOM,
requestVertexNormals: true,
requestWaterMask: true,
};
case 'world': {
const token = String(source.accessToken || '').trim();
if (!token)
throw new Error('World terrain requires an explicit ion token');
const response = await fetchJson(
`${ION_WORLD_TERRAIN_ENDPOINT}${encodeURIComponent(token)}`,
);
if (!response.ok)
throw new Error(`Cesium ion answered ${response.status}`);
const endpoint = await response.json();
return {
type: 'quantized-mesh',
url: `${endpoint.url}{z}/{x}/{y}.terrain?v=1.2.0`,
token: endpoint.accessToken,
attributions: endpoint.attributions ?? [],
};
}
default:
throw new TypeError(`Unknown terrain source: ${kind}`);
}
}
// What current() reports: the base imagery on the globe (none while tiles
// replace it) and the tiles shown, as the objects passed in.
let baseSource = null;
let currentBase = null;
let tilesSource = null;
const knownTiles = new Set();
// The package exposes no provider error event, so tileErrors is absent.
const maps = {
get baseKind() {
return kindOf(currentBase);
},
async setBaseImagery(source) {
const generation = ++generations.display;
const { url, credit, maxZoom } = imageryFor(source);
if (destroyed || generation !== generations.display) return;
baseSource = source;
currentBase = source;
if (slots.imagery?.key !== url)
show(
'imagery',
url,
{ type: 'raster-tile', url, ...(maxZoom && { maxZoom }) },
{ type: 'raster' },
[credit],
);
// Under tiles the base imagery waits hidden, credit included.
setImageryShown(slots.photoreal == null);
},
async setTerrain(source) {
const generation = ++generations.terrain;
const description = await terrainFor(source);
if (destroyed || generation !== generations.terrain) return;
if (!description) {
clear('terrain');
changed();
return;
}
if (slots.terrain?.key === description.url) return;
const { attributions = [], ...sourceDesc } = description;
show(
'terrain',
description.url,
sourceDesc,
{ type: 'terrain' },
attributions.map(({ html }) => ({ attributionHtml: html })),
);
if (attributions.some(({ collapsible }) => collapsible === false))
view.attribution?.show();
},
async setPhotorealTiles(source) {
const generation = ++generations.display;
if (source == null) {
clear('photoreal');
tilesSource = null;
// The globe comes back with the last base imagery and its credit.
if (slots.imagery) {
setImageryShown(true);
currentBase = baseSource;
}
changed();
return;
}
const key = String(source.googleApiKey || '').trim();
const tilesetUrl = localTilesetPath(source.tilesetUrl);
if (!tilesetUrl && !key)
throw new Error(
'Google 3D tiles on Navara need a browser key (googleApiKey)',
);
if (destroyed || generation !== generations.display) return;
const url = tilesetUrl
? new URL(tilesetUrl, globalThis.location.origin).href
: `${GOOGLE_TILES_ROOT}?key=${encodeURIComponent(key)}`;
setImageryShown(false);
currentBase = null;
tilesSource = source;
knownTiles.add(source);
if (slots.photoreal?.key === url) return;
show(
'photoreal',
url,
{ type: '3d-tiles', url },
// Navara's default height shifts transformed tiles along ECEF X.
{ type: '3d-tiles', model: { maxSse: PHOTOREAL_MAX_SSE, height: 0 } },
tilesetUrl
? []
: [
(layer) => ({
attribution: 'Google',
logo: GOOGLE_LOGO,
creditLayerId: layer.id,
}),
],
);
// Google's terms want its copyright lines on screen, as Cesium shows
// them; Navara lists them in its attribution card, collapsed by default.
if (!tilesetUrl) view.attribution?.show();
},
releasePhotorealTiles(source) {
if (!knownTiles.delete(source)) return;
if (tilesSource !== source) return;
tilesSource = null;
clear('photoreal');
changed();
},
photorealActive: () => slots.photoreal != null,
/**
* Navara-only extension: a transparent XYZ tile overlay ({z}/{x}/{y}
* `url`) above the base imagery, with its credit. Returns its removal.
*/
addOverlay({ url, maxZoom, credit }) {
if (destroyed) return () => {};
const source = view.addSource({
type: 'raster-tile',
url,
...(maxZoom && { maxZoom }),
});
const overlay = {
source,
layer: view.addLayer({ type: 'raster', source }),
credits: credit ? [{ attributionHtml: String(credit) }] : [],
};
overlays.add(overlay);
if (overlay.credits.length) view.attribution?.add(overlay.credits);
changed();
return () => {
if (!overlays.delete(overlay)) return;
overlay.layer.delete();
overlay.source.delete();
if (overlay.credits.length) view.attribution?.remove(overlay.credits);
changed();
};
},
current: () => ({ baseImagery: currentBase, photoreal: tilesSource }),
terrainRevision: () => terrainRevision,
};
return {
maps,
/**
* surface.sampleTerrainMostDetailed: the terrain shown sampled at its
* finest level (Navara fetches the tiles); 0 on the ellipsoid.
*/
async sampleTerrain(positions) {
const source = slots.terrain?.source;
if (!source) return positions.map(() => 0);
const sampled = await view.sampleTerrainMostDetailed(
source,
positions.map((place) => ({
lat: (place.latitude * 180) / Math.PI,
lng: (place.longitude * 180) / Math.PI,
})),
);
return sampled.map(({ height }) =>
Number.isFinite(height) ? height : undefined,
);
},
destroy() {
if (destroyed) return;
destroyed = true;
stopSettling();
for (const overlay of overlays) {
overlay.layer.delete();
overlay.source.delete();
}
overlays.clear();
for (const name of Object.keys(slots)) clear(name);
},
};
}