diff --git a/src/library/layers.js b/src/library/layers.js index e69963fa9..b87d1cfbd 100644 --- a/src/library/layers.js +++ b/src/library/layers.js @@ -430,9 +430,6 @@ export function minimumTerrainLevelFor(entry) { */ export const LIBRARY_AERIAL_Z = 10; -/** Why a dense entry's tile below its minimum zoom is not drawn. */ -const BELOW_MIN_ZOOM = 'below the entry’s minimum zoom'; - /** * The globe port imagery spec for a tiles entry. * @param {object} entry Validated tiles entry. @@ -442,10 +439,9 @@ const BELOW_MIN_ZOOM = 'below the entry’s minimum zoom'; export function libraryImagerySpec(entry, url) { const bbox = entry.source.bounded ? entry.coverage.bbox : null; const minZoom = entry.source.minZoom ?? 0; - // A dense entry (`minimumTerrainLevelFor`) asks for no tile below its - // minimum zoom: the globe then takes this layer's tiles at its own - // level, a few zoomed out, and those below the minimum fail at once, so - // nothing is drawn or fetched until the view is close enough. + // A dense entry (`minimumTerrainLevelFor`) is hidden where the view is + // coarser than its minimum zoom, so nothing is drawn or fetched until the + // view is close enough; from there on it draws as any entry does. const dense = minimumTerrainLevelFor(entry) !== undefined; const tileTransform = libraryTileTransform(entry); return { @@ -453,7 +449,8 @@ export function libraryImagerySpec(entry, url) { url, tiling: 'webMercator', tileSize: entry.source.tileSize ?? 256, - ...(dense ? {} : { minLevel: minZoom }), + minLevel: minZoom, + ...(dense ? { hiddenBelowMinLevel: true } : {}), maxLevel: entry.source.maxZoom ?? 18, credit: { text: entry.provider }, // A bounded entry requests tiles inside its coverage only. @@ -469,14 +466,6 @@ export function libraryImagerySpec(entry, url) { : {}), ...(entry.display.aerial ? { zOrder: LIBRARY_AERIAL_Z } : {}), ...(tileTransform ? { tileTransform } : {}), - ...(dense - ? { - admit: (tile, issue) => - tile.level < minZoom - ? Promise.reject(new Error(BELOW_MIN_ZOOM)) - : issue(), - } - : {}), }; } @@ -501,7 +490,6 @@ export function createLibraryTileLayer( const id = libraryLayerId(entry.id); const extent = coverageExtent(entry); const outlineMode = entry.display.outline || null; - const minZoom = entry.source.minZoom ?? 0; /** The coverage outline's set, and how many rings it draws. */ let outline = null; let outlineCount = 0; @@ -606,8 +594,8 @@ export function createLibraryTileLayer( libraryImagerySpec(entry, source.tileTemplate(entry)), ); } catch (error) { - // A renderer without tile hooks cannot draw relief, clear the - // no-data fill or hold back a dense entry: no drape, not a wrong one. + // A renderer without tile hooks cannot draw relief or clear the + // no-data fill: no drape, not a wrong one. console.warn(`[Library] ${entry.id} tiles refused:`, error); refused = true; return false; @@ -615,11 +603,9 @@ export function createLibraryTileLayer( imagery.alpha = entry.display.opacity ?? 1; removeErrorListener = imagery.on('tileError', (error) => { // A 4xx is the provider saying "no imagery here" (outside its - // coverage), and a tile below a dense entry's minimum zoom is held - // back on purpose: neither is a failure. + // coverage), not a failure. const status = error?.status; if (status >= 400 && status < 500) return; - if (error?.tile?.level < minZoom) return; tileErrors += 1; }); lastUpdate = Date.now(); diff --git a/src/library/tileLayer.test.mjs b/src/library/tileLayer.test.mjs index 79de97451..7330d2a65 100644 --- a/src/library/tileLayer.test.mjs +++ b/src/library/tileLayer.test.mjs @@ -10,6 +10,7 @@ import { import { LIBRARY_ENTRIES, libraryEntry } from './catalog.js'; import { libraryTileUrl } from './manifest.js'; import { createLibrarySource } from './source.js'; +import { layerOptions } from '../render/cesium/imagery.js'; import { fakeGlobePort } from '../testSupport/fakeGlobePort.mjs'; import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs'; @@ -225,31 +226,23 @@ test('an entry too dense to draw zoomed out is hidden below its scale', async (t undefined, ); - // It names no minimum level, so zoomed out the globe takes its tiles at - // its own coarse levels, and every tile below z14 is held back unfetched. + // It keeps its minimum level and is hidden where the view is coarser, as + // Cesium's own layer was (minimumTerrainLevel z13 on the geographic globe). const { viewer, globe } = globeViewer(t); const layer = createLibraryTileLayer(cadastre, { source }); await layer.init(viewer); await layer.enable(viewer); const [imagery] = globe.layers; - assert.equal(imagery.spec.minLevel, undefined); - let fetched = 0; - const fetch = () => { - fetched += 1; - return Promise.resolve('tile'); - }; - for (const level of [0, 4, 12, 13]) - await assert.rejects(imagery.request({ x: 0, y: 0, level }, fetch)); - assert.equal(fetched, 0, 'no tile below z14 is requested'); - assert.equal(await imagery.request({ x: 0, y: 0, level: 14 }, fetch), 'tile'); - // The held-back tiles are not failures. - for (let i = 0; i < 30; i++) imagery.fail({ tile: { x: i, y: 0, level: 4 } }); - assert.equal(layer.getStats().error, null); + assert.equal(imagery.spec.minLevel, 14); + assert.equal(imagery.spec.hiddenBelowMinLevel, true); + assert.equal(imagery.spec.admit, undefined); + assert.deepEqual(layerOptions(imagery.spec), { minimumTerrainLevel: 13 }); // An entry that is not dense keeps its minimum level. const lee = libraryEntry('lee-county-fl'); const spec = libraryImagerySpec(lee, lee.source.url); assert.equal(spec.minLevel, lee.source.minZoom ?? 0); - assert.equal(spec.admit, undefined); + assert.equal(spec.hiddenBelowMinLevel, undefined); + assert.equal(layerOptions(spec), undefined); await layer.disable(); assert.equal(globe.layers.length, 0); }); diff --git a/src/render/cesium/globe.test.mjs b/src/render/cesium/globe.test.mjs index 0a7c51104..8d30364dd 100644 --- a/src/render/cesium/globe.test.mjs +++ b/src/render/cesium/globe.test.mjs @@ -132,6 +132,20 @@ test('the look writes through to the Cesium layer', () => { assert.equal(layer.lit, false); }); +test('a layer hidden below its minimum level shows from the globe level as fine as it', () => { + const { scene, port } = setup(); + port.imagery.add({ + kind: 'xyz', + url: url('dense'), + minLevel: 14, + hiddenBelowMinLevel: true, + }); + port.imagery.add({ kind: 'xyz', url: url('plain'), minLevel: 14 }); + // Web Mercator z14 is as fine as the geographic globe's level 13. + assert.equal(scene.imageryLayers.get(0)._minimumTerrainLevel, 13); + assert.equal(scene.imageryLayers.get(1)._minimumTerrainLevel, undefined); +}); + test('imagery drapes on the drawn base tileset while the globe is hidden', () => { const { scene, port, tick } = setup(); const tileset = fakeTileset(); diff --git a/src/render/cesium/imagery.js b/src/render/cesium/imagery.js index b355ba3a7..c89fe87ea 100644 --- a/src/render/cesium/imagery.js +++ b/src/render/cesium/imagery.js @@ -108,6 +108,21 @@ function canvasProvider(spec) { }; } +/** + * The Cesium layer options a spec asks for: one hidden below its minimum + * level is shown only from the globe level as fine as it (Cesium's globe + * tiles are geographic, two Web Mercator tiles across a level's one). + * @param {import('../contract/globe').ImagerySpec} spec + * @returns {object|undefined} + */ +export function layerOptions(spec) { + if (!spec.hiddenBelowMinLevel || !(spec.minLevel > 0)) return undefined; + const tiling = + spec.tiling ?? (spec.kind === 'canvas' ? 'geographic' : 'webMercator'); + const shift = tiling === 'geographic' ? 0 : 1; + return { minimumTerrainLevel: Math.max(0, spec.minLevel - shift) }; +} + /** * The Cesium provider a spec describes; a promise for the kinds Cesium * builds from metadata it fetches first. @@ -437,10 +452,14 @@ export function createCesiumImagery( /** A Cesium layer for the record, with its look. */ function build(record) { + const options = layerOptions(record.spec); const layer = record.provider !== undefined - ? new Cesium.ImageryLayer(record.provider) - : Cesium.ImageryLayer.fromProviderAsync(record.providerPromise); + ? new Cesium.ImageryLayer(record.provider, options) + : Cesium.ImageryLayer.fromProviderAsync( + record.providerPromise, + options, + ); layer.alpha = record.alpha; // A layer showing timed frames hides its own imagery. layer.show = record.show && !record.timed; @@ -710,11 +729,15 @@ export function createCesiumImagery( return hookProvider(provider, spec, record.ctx); }); provider.catch(() => {}); - entry.layer = Cesium.ImageryLayer.fromProviderAsync(provider); + entry.layer = Cesium.ImageryLayer.fromProviderAsync( + provider, + layerOptions(spec), + ); } else { entry.offError = record.watchErrors(made); entry.layer = new Cesium.ImageryLayer( timed.video ? made : hookProvider(made, spec, record.ctx), + layerOptions(spec), ); } entry.layer.alpha = 0; diff --git a/src/render/contract/globe.d.ts b/src/render/contract/globe.d.ts index e8e5635ea..da7eff9f8 100644 --- a/src/render/contract/globe.d.ts +++ b/src/render/contract/globe.d.ts @@ -82,6 +82,12 @@ export interface ImagerySpec { rectangle?: GeoRect; minLevel?: number; maxLevel?: number; + /** + * Drawn nowhere the surface is coarser than `minLevel`, rather than made + * from `minLevel` tiles there: for a layer whose `minLevel` tiles are too + * many to fetch far out. + */ + hiddenBelowMinLevel?: boolean; tileSize?: number; credit?: Credit; /** Requests in flight at once for this layer. */