diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 9c6552bd7..f3bd967b7 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -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. diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index c76f8f22c..1e2577436 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -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", diff --git a/src/maps/globeEngine.js b/src/maps/globeEngine.js index b0555f1e9..3e55e9c71 100644 --- a/src/maps/globeEngine.js +++ b/src/maps/globeEngine.js @@ -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)); }, /** diff --git a/src/maps/globeEngine.test.mjs b/src/maps/globeEngine.test.mjs index a20e0324b..246326deb 100644 --- a/src/maps/globeEngine.test.mjs +++ b/src/maps/globeEngine.test.mjs @@ -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, {}); diff --git a/src/maps/keylessTerrain.js b/src/maps/keylessTerrain.js new file mode 100644 index 000000000..b6b54849f --- /dev/null +++ b/src/maps/keylessTerrain.js @@ -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'; diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js index 9d1f71924..276030686 100644 --- a/src/render/cesium/globe.js +++ b/src/render/cesium/globe.js @@ -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}`); } diff --git a/src/render/cesium/globe.test.mjs b/src/render/cesium/globe.test.mjs index 561a0472e..36a524e47 100644 --- a/src/render/cesium/globe.test.mjs +++ b/src/render/cesium/globe.test.mjs @@ -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') }); diff --git a/src/render/cesium/mapTerrain.js b/src/render/cesium/mapTerrain.js index d062655cd..80a0ccaa6 100644 --- a/src/render/cesium/mapTerrain.js +++ b/src/render/cesium/mapTerrain.js @@ -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 } = {}) { diff --git a/src/render/contract/globe.d.ts b/src/render/contract/globe.d.ts index 26c1df39a..d890f6182 100644 --- a/src/render/contract/globe.d.ts +++ b/src/render/contract/globe.d.ts @@ -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;