Keyless terrain reaches the renderer as quantized-mesh terrain

The contract's TerrainSpec gains quantizedMesh terrain: Cesium's tile
format in the folder at its url, heights above the ellipsoid. Without an
ion key the globe-port map engine asks for Re:Earth's keyless terrain as
it, where it asked for the ellipsoid, so the renderer
draws the same ground; without the terrain capability keeps the
ellipsoid. Cesium's globe port draws it through CesiumTerrainProvider with
the keyless terrain's retry policy.
This commit is contained in:
Sameh Khamis committed 2026-11-11 09:20:33 -08:00
1 parent c57e535275
commit 1f307e0735
9 files changed
+101 -17

No files matched your search

+4 -3
View File
@@ -7850,9 +7850,10 @@ and the application scene loads the photoreal base through it too. A renderer
whose plugin hands none switches through its globe port
(`src/maps/globeEngine.js`): Esri and OSM as `xyz` imagery, ion's world
imagery as `world` imagery, photoreal as the port's photoreal base (turned off
while hidden, on again when shown), and world terrain, or the ellipsoid where
Cesium uses Re:Earth's keyless terrain (the contract's `TerrainSpec` has no
such kind). A viewer with no renderer bound gets the Cesium engine, with the
while hidden, on again when shown), and world terrain, or without a key
Re:Earth's keyless terrain as `quantizedMesh` terrain at its URL
(`src/maps/keylessTerrain.js`), as the Cesium engine draws it; a renderer
without the `terrain` capability keeps the ellipsoid. A viewer with no renderer bound gets the Cesium engine, with the
other unbound ports, from the package's `./render/cesium/unbound` export.
The controller accepts other source registries without adding provider branches.
+12 -6
View File
@@ -1492,7 +1492,8 @@
"src/render/cesium/zoomOutGuard.js",
"src/render/cesium/sceneOcclusionProbe.js",
"src/render/occlusion/depthProbe.js",
"src/data/detectionOcclusion.js"
"src/data/detectionOcclusion.js",
"src/maps/keylessTerrain.js"
],
"external": ["cesium", "vue", "pinia", "vue-i18n"]
},
@@ -2172,7 +2173,8 @@
"src/render/cesium/zoomOutGuard.js",
"src/render/cesium/sceneOcclusionProbe.js",
"src/render/occlusion/depthProbe.js",
"src/data/detectionOcclusion.js"
"src/data/detectionOcclusion.js",
"src/maps/keylessTerrain.js"
],
"external": ["cesium"]
},
@@ -2222,7 +2224,8 @@
"src/layers/recentImagery/display.js",
"src/render/applicationHooks.js",
"src/maps/globeEngine.js",
"src/maps/engine.js"
"src/maps/engine.js",
"src/maps/keylessTerrain.js"
],
"external": ["cesium"]
},
@@ -3511,7 +3514,8 @@
"src/render/cesium/zoomOutGuard.js",
"src/render/cesium/sceneOcclusionProbe.js",
"src/render/occlusion/depthProbe.js",
"src/data/detectionOcclusion.js"
"src/data/detectionOcclusion.js",
"src/maps/keylessTerrain.js"
],
"external": ["cesium"]
},
@@ -4810,7 +4814,8 @@
"src/maps/globeEngine.js",
"src/render/cesium/viewers.js",
"src/ui/creditsView.js",
"src/data/planespottersPhoto.js"
"src/data/planespottersPhoto.js",
"src/maps/keylessTerrain.js"
],
"external": [
"hls.js",
@@ -5585,7 +5590,8 @@
"src/maps/globeEngine.js",
"src/maps/engine.js",
"src/data/planespottersPhoto.js",
"src/render/cesium/zoomOutGuard.js"
"src/render/cesium/zoomOutGuard.js",
"src/maps/keylessTerrain.js"
],
"external": [
"hls.js",
+13 -3
View File
@@ -12,7 +12,8 @@
* provider, a handle per imagery layer and photoreal base. A hidden
* photoreal base is turned off through the port and on again when shown.
*/
import { findFrame, findGlobe } from '../render/rendererOf.js';
import { findFrame, findGlobe, rendererOf } from '../render/rendererOf.js';
import { KEYLESS_TERRAIN_URL } from './keylessTerrain.js';
const ESRI_TILES =
'https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}';
@@ -154,7 +155,11 @@ export const globeMapEngine = Object.freeze({
spec: { kind: 'world', requestVertexNormals: true },
};
},
keyless: async () => ({ provider: null, spec: { kind: 'ellipsoid' } }),
// Re:Earth's keyless terrain, as the Cesium map engine draws it.
keyless: async () => ({
provider: null,
spec: { kind: 'quantizedMesh', url: KEYLESS_TERRAIN_URL },
}),
}),
createImageryLayer: (spec) => ({ spec, layer: null }),
requestRender(host) {
@@ -197,8 +202,13 @@ export const globeMapEngine = Object.freeze({
handle.layer = null;
},
applyTerrain(host, result) {
// Where the renderer draws no terrain, the ellipsoid stays.
const spec = result.spec ?? null;
const flat =
spec?.kind !== 'ellipsoid' &&
rendererOf(host)?.capabilities?.has('terrain') === false;
findGlobe(host)
?.setTerrain(result.spec ?? null)
?.setTerrain(flat ? null : spec)
.catch((error) => console.warn('[MapStack] terrain failed', error));
},
/**
+10 -3
View File
@@ -1,6 +1,7 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { globeMapEngine as engine } from './globeEngine.js';
import { KEYLESS_TERRAIN_URL } from './keylessTerrain.js';
import { mapEngineFor, provideMapEngine } from './engine.js';
import { bindRenderer } from '../render/rendererOf.js';
import { provideApplicationHooks } from '../render/applicationHooks.js';
@@ -69,8 +70,8 @@ test('the globe is shown and hidden through the port, read back without globe vi
assert.equal(engine.globeShown(visible.host), false);
});
test('terrain is the port’s world terrain, or the ellipsoid without a token', async () => {
const { host, renderer } = scene();
test('terrain is the port’s world terrain, or the keyless quantized mesh without a token', async () => {
const { host, renderer } = scene(['terrain']);
await assert.rejects(engine.terrain.world(''), /ion token/);
const world = await engine.terrain.world('token');
engine.applyTerrain(host, world);
@@ -79,7 +80,7 @@ test('terrain is the port’s world terrain, or the ellipsoid without a token',
]);
engine.applyTerrain(host, await engine.terrain.keyless());
assert.deepEqual(calls(renderer, 'setTerrain').at(-1).args, [
{ kind: 'ellipsoid' },
{ kind: 'quantizedMesh', url: KEYLESS_TERRAIN_URL },
]);
assert.throws(() => engine.imagery.ion(2, ''), /token/);
assert.deepEqual(engine.imagery.ion(3, 'token'), {
@@ -88,6 +89,12 @@ test('terrain is the port’s world terrain, or the ellipsoid without a token',
});
});
test('where the renderer draws no terrain the ellipsoid stays', async () => {
const { host, renderer } = scene([]);
engine.applyTerrain(host, await engine.terrain.keyless());
assert.deepEqual(calls(renderer, 'setTerrain').at(-1).args, [null]);
});
test('photoreal loads through the port, hides and shows, and is released', async () => {
const { host, renderer } = scene(['photoreal']);
const none = await engine.loadPhotoreal(host, {});
+9
View File
@@ -0,0 +1,9 @@
/**
* @module maps/keylessTerrain
* @description The terrain the map stacks draw without an ion key:
* Re:Earth's keyless quantized-mesh terrain, heights above the ellipsoid.
*/
/** Its folder: `layer.json` and `{z}/{x}/{y}.terrain` under it. */
export const KEYLESS_TERRAIN_URL =
'https://terrain.reearth.land/cesium-mesh/ellipsoid';
+17
View File
@@ -20,6 +20,7 @@ import { provideUnboundGlobe } from '../rendererOf.js';
import { isBaseTileset, markBaseTileset } from '../baseTilesets.js';
import { listenerList, uncaught } from './common.js';
import { createCesiumImagery } from './imagery.js';
import { createTerrainRetryPolicy } from '../../maps/terrainRetry.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.
@@ -51,6 +52,22 @@ async function terrainProvider(spec, { worldDataToken }) {
requestWaterMask: false,
});
}
if (spec.kind === 'quantizedMesh') {
if (typeof spec.url !== 'string' || !spec.url)
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 resource = new Cesium.Resource({
url: spec.url,
retryCallback: policy.retryCallback,
retryAttempts: policy.retryAttempts,
});
return Cesium.CesiumTerrainProvider.fromUrl(resource, {
requestVertexNormals: spec.requestVertexNormals ?? false,
requestWaterMask: false,
});
}
throw new TypeError(`Unknown terrain kind: ${spec.kind}`);
}
+29
View File
@@ -421,6 +421,35 @@ test('terrain: the ellipsoid with exaggeration; the last call wins', async () =>
await assert.rejects(flat.port.setTerrain({ kind: 'world' }), /no terrain/);
});
test('terrain: quantized mesh at its url, asked again when its host is busy', async (t) => {
const { scene, port } = setup();
const made = new Cesium.EllipsoidTerrainProvider();
const asked = [];
t.mock.method(Cesium.CesiumTerrainProvider, 'fromUrl', async (...args) => {
asked.push(args);
return made;
});
await port.setTerrain({
kind: 'quantizedMesh',
url: 'https://terrain.example/mesh',
exaggeration: 1.5,
});
assert.equal(scene.terrainProvider, made);
assert.equal(scene.verticalExaggeration, 1.5);
const [[resource, options]] = asked;
assert.equal(resource.url, 'https://terrain.example/mesh');
assert.ok(resource.retryAttempts > 0);
assert.equal(typeof resource.retryCallback, 'function');
assert.deepEqual(options, {
requestVertexNormals: false,
requestWaterMask: false,
});
await assert.rejects(
port.setTerrain({ kind: 'quantizedMesh' }),
/needs its url/,
);
});
test('setBase replaces the imagery and says what it drew', async () => {
const { scene, port } = setup();
const overlay = port.imagery.add({ kind: 'xyz', url: url('overlay') });
+2 -2
View File
@@ -6,10 +6,10 @@
*/
import * as Cesium from 'cesium';
import { createTerrainRetryPolicy } from '../../maps/terrainRetry.js';
import { KEYLESS_TERRAIN_URL } from '../../maps/keylessTerrain.js';
/** Re:Earth / Mapterhorn ellipsoidal quantized mesh, CC BY 4.0. */
export const KEYLESS_TERRAIN_URL =
'https://terrain.reearth.land/cesium-mesh/ellipsoid';
export { KEYLESS_TERRAIN_URL };
/** These factories are lazy: a hidden globe must not trigger terrain loading. */
export async function createWorldTerrain(accessToken, { signal } = {}) {
+5
View File
@@ -36,6 +36,11 @@ export type TerrainSpec = (
* (for the default renderer, Cesium World Terrain).
*/
| { kind: 'world'; requestVertexNormals?: boolean }
/**
* Quantized-mesh terrain (Cesium's tile format) in the folder `url`,
* holding `layer.json` and its tiles; heights above the ellipsoid.
*/
| { kind: 'quantizedMesh'; url: string; requestVertexNormals?: boolean }
) & {
/** Vertical exaggeration of the drawn terrain; default 1. */
exaggeration?: number;