diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 7c8057a5a..ffdd7016d 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -9,6 +9,7 @@ "src/data/infrastructure.js", "src/data/localGeojsonCore.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -874,6 +875,8 @@ "src/ui/cockpitRollingValue.js", "src/ui/cockpitCamera.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -1007,6 +1010,8 @@ "src/styles/thermal.js", "src/ui/applicationShell.js", "src/render/cesium/effects.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/data/followed.js", "src/render/cesium/camera.js", @@ -1280,6 +1285,8 @@ "src/scenes/director.js", "src/data/followed.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -1427,6 +1434,8 @@ "src/layers/flights/policy.js", "src/layers/flights/queries.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -1523,6 +1532,8 @@ "src/layers/military/policy.js", "src/layers/military/queries.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -1685,6 +1696,9 @@ "exports": ["./render/cesium/unbound"], "modules": [ "src/render/cesium/unbound.js", + "src/render/cesium/query.js", + "src/render/cesium/drawHit.js", + "src/queries/heights.js", "src/render/cesium/effects.js", "src/render/cesium/draw.js", "src/render/cesium/camera.js", @@ -1759,6 +1773,8 @@ "src/layers/firms/cards.js", "src/geo/index.js", "src/render/rendererOf.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/camera.js", "src/render/camera/events.js", "src/geo/celestial.js", @@ -1843,6 +1859,8 @@ "src/layers/satellites/testing.js", "src/layers/satellites/tracking.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -1894,6 +1912,8 @@ "src/layers/launches/controls.js", "src/layers/launches/index.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -1964,6 +1984,8 @@ "src/layers/installations/controls.js", "src/geo/geodesic.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -2246,6 +2268,8 @@ "src/layers/cctv/modelSpecs.js", "src/layers/cctv/navigation.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -2317,6 +2341,7 @@ "modules": [ "src/layers/streetLevel/index.js", "src/render/cesium/credits.js", + "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/geo/index.js", "src/layers/streetLevel/credits.js", @@ -2416,6 +2441,7 @@ "src/layers/alpr/policy.js", "src/layers/alpr/presentation.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -2494,6 +2520,8 @@ "src/layers/radio/navigation.js", "src/data/followed.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -2557,6 +2585,8 @@ "src/geo/index.js", "src/layers/submarineCables/interaction.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", @@ -2648,6 +2678,9 @@ "src/maps/catalog.js", "src/maps/controller.js", "src/render/cesium/globe.js", + "src/render/cesium/query.js", + "src/queries/heights.js", + "src/render/cesium/drawHit.js", "src/render/cesium/credits.js", "src/render/cesium/tileRequests.js", "src/render/cesium/draw.js", @@ -2866,6 +2899,7 @@ "src/render/creditMarkup.js", "src/render/rendererOf.js", "src/render/cesium/ports.js", + "src/render/cesium/query.js", "src/render/cesium/globe.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", @@ -3857,6 +3891,7 @@ "src/data/bhoteKoshiEmbeddedMedia.js", "src/data/bhoteKoshiLocator.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/imagery.js", "src/maps/google3d.js", @@ -4517,6 +4552,8 @@ "src/layers/firms/anchors.js", "src/locations.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/cameraInput.js", @@ -4628,6 +4665,9 @@ "src/geo/index.js", "src/ui/navigationController.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", + "src/queries/heights.js", + "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/cameraInput.js", @@ -5161,6 +5201,7 @@ "src/cyberSonar.js", "src/celestialRing.js", "src/render/cesium/camera.js", + "src/render/cesium/query.js", "src/render/cesium/draw.js", "src/render/cesium/cameraControls.js", "src/render/cesium/credits.js", diff --git a/src/data/infrastructure.test.mjs b/src/data/infrastructure.test.mjs index cde4cfaba..8babcd589 100644 --- a/src/data/infrastructure.test.mjs +++ b/src/data/infrastructure.test.mjs @@ -209,6 +209,7 @@ test('consumer build includes only infrastructure code and resolves assets under 'localGeojsonCore.js', 'localGeojsonLod.js', 'pickRegistry.js', + 'query.js', 'rendererOf.js', 'router.js', 'scenePick.js', diff --git a/src/render/cesium/camera.js b/src/render/cesium/camera.js index 47e979312..b2a6a365c 100644 --- a/src/render/cesium/camera.js +++ b/src/render/cesium/camera.js @@ -12,9 +12,11 @@ import { cameraFlightActive } from './internals.js'; import { createCesiumFollow } from './follow.js'; import { createCesiumControls } from './cameraControls.js'; import { cameraOf, findCamera, provideUnboundCamera } from '../rendererOf.js'; -// Loads the factories an unbound viewer gets its credits and draw ports from. +// Loads the factories an unbound viewer gets its credits, draw and query +// ports from. import './credits.js'; import './draw.js'; +import './query.js'; /** * `cameraOf` and `findCamera`, for code that already reaches Cesium: diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index ef283e053..a827adda5 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -1394,6 +1394,18 @@ export function createCesiumDraw({ scene, report }) { }; } +/** The parts of the draw ports built for viewers with no renderer, by port. */ +const unboundParts = new WeakMap(); + +/** + * The draw port part (its sets) behind a port built for a viewer with no + * renderer, for that viewer's query port to pick and see through; null for + * any other port. + * @param {object|null|undefined} port + */ +export const unboundDrawPart = (port) => + (port && unboundParts.get(port)) ?? null; + // A Cesium viewer with no renderer bound to it gets a // draw port over its scene when code first asks `findDraw` for one. A // renderer bound later supersedes it: released, its sets keep drawing until @@ -1409,6 +1421,7 @@ provideUnboundDraw((viewer) => { ) return null; const part = createCesiumDraw({ scene, report: uncaught }); + unboundParts.set(part.port, part); const offs = [ scene.preRender?.addEventListener?.(() => part.beforeRender()), scene.postRender.addEventListener(() => part.afterRender()), diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index cff83b317..696176544 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -13,14 +13,13 @@ * absent, never stubbed. */ import * as Cesium from 'cesium'; -import { heightsFor } from '../../queries/heights.js'; import { createCesiumCamera } from './camera.js'; import { listenerList, toCartesian, uncaught } from './common.js'; import { createCesiumCredits } from './credits.js'; import { createCesiumDraw } from './draw.js'; -import { drawHitOf } from './drawHit.js'; import { createCesiumEffects } from './effects.js'; import { createCesiumGlobe } from './globe.js'; +import { createCesiumQuery, queryCapabilities } from './query.js'; import { createCesiumQuality } from './quality.js'; import { atEndOfTick, @@ -104,10 +103,14 @@ const GLOBE_CAPABILITIES = [ * @returns {string[]} */ export function cesiumCapabilities(scene, only) { - const all = ['models', 'styles', 'bloom', 'sharpen', ...GLOBE_CAPABILITIES]; - if (scene.pickPositionSupported) all.push('pickPosition'); - if (scene.sampleHeightSupported) - all.push('sampleHeight', 'finestHeights', 'rayCast'); + const all = [ + 'models', + 'styles', + 'bloom', + 'sharpen', + ...GLOBE_CAPABILITIES, + ...queryCapabilities(scene), + ]; const allowed = only && new Set(only); return all.filter((c) => !allowed || allowed.has(c)); } @@ -391,296 +394,12 @@ export function createCesiumPorts(widget, { capabilities, credentials = {} }) { // --- Query ----------------------------------------------------------------- - const screen = (x, y) => new Cesium.Cartesian2(x, y); - const ecef = (c) => (c ? { x: c.x, y: c.y, z: c.z } : null); - const finite = (p) => - Number.isFinite(p?.x) && Number.isFinite(p?.y) && Number.isFinite(p?.z); - const cesiumRay = (ray) => - new Cesium.Ray(toCartesian(ray.origin), toCartesian(ray.direction)); - - /** The live set and item a picked object belongs to, or null. */ - function ownerOf(picked) { - const id = picked?.id; - if (!id || typeof id.set !== 'string') return null; - const record = sets.get(id.set); - const item = record?.items.get(id.id); - return record && item ? { record, item, id } : null; - } - - const pickable = ({ record, item }) => - record.host?.show !== false && - record.spec.pickable !== false && - item.show !== false && - item.pickable !== false; - - const hitOf = ({ id }) => drawHitOf({ id }); - - /** The globe (or ellipsoid) under a pixel, as a surface hit. */ - function surfaceHit(x, y) { - const position = query.pickPosition(x, y) ?? query.pickEllipsoid(x, y); - return position ? { set: '', id: '', surface: true, position } : null; - } - - /** - * The pickable draw-set items under a pixel, nearest first, once each (a - * shape's fill and outline share one id). `untilForeign` stops at the first - * thing that is not a draw-set item (a tile, the app's own primitives): - * what is behind it is hidden. - */ - function drill(x, y, { width = 3, height = 3, limit, untilForeign } = {}) { - const hits = []; - if (limit === 0) return hits; - const seen = new Set(); - for (const picked of scene.drillPick( - screen(x, y), - undefined, - width, - height, - )) { - const owner = ownerOf(picked); - if (!owner) { - if (untilForeign) break; - continue; - } - const key = `${owner.id.set}\u0000${owner.id.id}`; - if (!pickable(owner) || seen.has(key)) continue; - seen.add(key); - hits.push(hitOf(owner)); - if (limit !== undefined && hits.length >= limit) break; - } - return hits; - } - - // What height queries see through, by their items' pick ids: the sets not - // drawn as ground, and the sets a caller excludes. Built once per change - // to the sets, not per query. - const seeThroughCache = new Map(); - let seeThroughVersion = -1; - function seeThrough(exclude, { allSets = false } = {}) { - if (seeThroughVersion !== drawPart.version()) { - seeThroughCache.clear(); - seeThroughVersion = drawPart.version(); - } - const key = `${allSets}\u0000${exclude?.join('\u0000') ?? ''}`; - let out = seeThroughCache.get(key); - if (!out) { - out = []; - for (const record of sets.values()) - if ( - allSets || - !record.spec.includeInHeightQueries || - exclude?.includes(record.spec.id) - ) - for (const id of record.pickIds) out.push(id); - seeThroughCache.set(key, out); - } - return out; - } - - /** Whether a set drawn as ground is in the scene, other than `exclude`. */ - const groundSets = (exclude) => - [...sets.values()].some( - (record) => - record.spec.includeInHeightQueries && - record.host?.show !== false && - !exclude?.includes(record.spec.id), - ); - - const heights = () => heightsFor(scene); - const can = (capability) => capabilities.has(capability); - const globeShown = () => Boolean(scene.globe?.show); - - /** - * `fn` with the globe hidden, so a pick or sample sees tiles and sets - * alone. Synchronous: the globe is shown again before anything draws. - */ - function withoutGlobe(fn) { - if (!globeShown()) return fn(); - scene.globe.show = false; - try { - return fn(); - } finally { - scene.globe.show = true; - } - } - - /** A height now from what is loaded, against the surface asked for. */ - function heightNow(point, against, excluded) { - if (against === 'terrain') - return heights().now(point, { against: 'terrain' }); - const sample = () => heights().now(point, { exclude: excluded }); - return against === 'tiles' ? withoutGlobe(sample) : sample(); - } - - const close = (a, b) => a !== null && b !== null && Math.abs(a - b) <= 0.01; - const ellipsoidTerrain = () => - scene.terrainProvider instanceof Cesium.EllipsoidTerrainProvider; - - /** - * Where a height came from, told apart by sampling again without the - * ground sets and against the terrain alone. - */ - function sourceOf(point, height, against, exclude) { - const terrain = () => (ellipsoidTerrain() ? 'ellipsoid' : 'terrain'); - if (against === 'terrain') return terrain(); - if (groundSets(exclude)) { - const bare = heightNow( - point, - against, - seeThrough(exclude, { allSets: true }), - ); - if (!close(bare, height)) return 'set'; - } - if (against === 'tiles' || !globeShown()) return 'tiles'; - return close(heights().now(point, { against: 'terrain' }), height) - ? terrain() - : 'tiles'; - } - - const query = { - pick(x, y, window = {}) { - const owner = ownerOf( - scene.pick(screen(x, y), window.width ?? 3, window.height ?? 3), - ); - if (owner && pickable(owner)) return hitOf(owner); - // Something unpickable is on top: the first pickable item under it, - // unless something else hides it. - if (owner) { - const [under] = drill(x, y, { - ...window, - limit: 1, - untilForeign: true, - }); - if (under) return under; - } - return surfaceHit(x, y); - }, - drillPick: (x, y, options = {}) => - drill(x, y, { ...options, untilForeign: false }), - pickPosition(x, y) { - if (!can('pickPosition') || !scene.pickPositionSupported) return null; - return ecef(scene.pickPosition(screen(x, y))); - }, - pickEllipsoid(x, y) { - return ecef(camera.pickEllipsoid(screen(x, y))); - }, - pickGlobe(ray) { - return ecef(scene.globe?.pick(cesiumRay(ray), scene)); - }, - pickRay(x, y) { - const ray = camera.getPickRay(screen(x, y)); - return { origin: ecef(ray.origin), direction: ecef(ray.direction) }; - }, - project(position) { - const s = Cesium.SceneTransforms.worldToWindowCoordinates( - scene, - toCartesian(position), - ); - return s ? { x: s.x, y: s.y } : null; - }, - projectMany(source, out) { - const p = new Cesium.Cartesian3(); - const s = new Cesium.Cartesian2(); - for (let i = 0, j = 0; i + 2 < source.length; i += 3, j += 2) { - p.x = source[i]; - p.y = source[i + 1]; - p.z = source[i + 2]; - const w = Cesium.SceneTransforms.worldToWindowCoordinates(scene, p, s); - out[j] = w ? w.x : NaN; - out[j + 1] = w ? w.y : NaN; - } - }, - isOccluded(position) { - const occluder = new Cesium.EllipsoidalOccluder( - scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84, - camera.positionWC, - ); - return !occluder.isPointVisible(toCartesian(position)); - }, - sampleHeightNow(point, { against = 'surface', exclude } = {}) { - if (!can('sampleHeight')) return null; - return heightNow(point, against, seeThrough(exclude)); - }, - sampleHeightNowMany(points, out, { against = 'surface', exclude } = {}) { - const excluded = can('sampleHeight') && seeThrough(exclude); - const point = { lon: 0, lat: 0 }; - for (let i = 0; i < out.length; i++) { - point.lon = points[i * 2]; - point.lat = points[i * 2 + 1]; - out[i] = excluded ? (heightNow(point, against, excluded) ?? NaN) : NaN; - } - }, - /** - * Cesium streams the finest tiles for every sample, `mostDetailed` or - * not. Against `tiles` it streams them, then samples them with the - * globe hidden, which only a synchronous sample can do. - */ - async sampleHeight(points, { against = 'surface', exclude } = {}) { - if (!can('sampleHeight')) return points.map(() => null); - const excluded = seeThrough(exclude); - let found = await heights().batch( - points, - against === 'terrain' ? { against: 'terrain' } : { exclude: excluded }, - ); - if (against === 'tiles') - found = points.map((point) => heightNow(point, 'tiles', excluded)); - const lod = can('finestHeights') ? 'finest' : 'visible'; - return found.map((height, i) => - height === null - ? null - : { - height, - confidence: 1, - source: sourceOf(points[i], height, against, exclude), - lod, - }, - ); - }, - async clampToSurface(positions, options = {}) { - const points = positions.map((p) => { - const c = - finite(p) && Cesium.Cartographic.fromCartesian(toCartesian(p)); - return c - ? { - lon: Cesium.Math.toDegrees(c.longitude), - lat: Cesium.Math.toDegrees(c.latitude), - } - : null; - }); - const samples = await query.sampleHeight( - points.map((p) => p ?? { lon: NaN, lat: NaN }), - options, - ); - return samples.map((sample, i) => - sample && points[i] - ? ecef( - Cesium.Cartesian3.fromDegrees( - points[i].lon, - points[i].lat, - sample.height, - ), - ) - : null, - ); - }, - async rayCast( - ray, - { against = 'surface', exclude, maxDistance = Infinity } = {}, - ) { - if (!can('rayCast')) return null; - const r = cesiumRay(ray); - let position; - if (against === 'terrain') position = scene.globe?.pick(r, scene); - else { - const cast = () => scene.pickFromRay(r, seeThrough(exclude))?.position; - position = against === 'tiles' ? withoutGlobe(cast) : cast(); - } - if (!position) return null; - return Cesium.Cartesian3.distance(r.origin, position) <= maxDistance - ? ecef(position) - : null; - }, - }; + const query = createCesiumQuery({ + scene, + camera, + draw: drawPart, + capabilities, + }); async function capture({ type = 'png' } = {}) { scene.render(widget.clock.currentTime); diff --git a/src/render/cesium/query.js b/src/render/cesium/query.js new file mode 100644 index 000000000..616e9063c --- /dev/null +++ b/src/render/cesium/query.js @@ -0,0 +1,372 @@ +/** + * @module render/cesium/query + * @description The Cesium renderer's query port + * (`src/render/contract/query.d.ts`) over a scene and the draw sets drawn + * in it: picks of draw-set items (by their pick ids), projection, rays and + * height samples that see through the sets not drawn as ground. + * + * Built over a scene by `createCesiumPorts`, and on its own over a Cesium + * viewer with no renderer bound, when code first asks + * `findQuery` for one (`rendererOf.js`): then it answers over that viewer's + * draw sets (`findDraw`), so a layer's height samples can see through its + * own sets. + */ +import * as Cesium from 'cesium'; +import { heightsFor } from '../../queries/heights.js'; +import { findDraw, provideUnboundQuery } from '../rendererOf.js'; +import { toCartesian } from './common.js'; +import { unboundDrawPart } from './draw.js'; +import { drawHitOf } from './drawHit.js'; + +/** + * The query capabilities a Cesium scene has: depth picks, height samples + * and ray casts all need depth textures, which `pickPositionSupported` and + * `sampleHeightSupported` report. + * @param {object} scene + * @returns {string[]} + */ +export function queryCapabilities(scene) { + const found = []; + if (scene.pickPositionSupported) found.push('pickPosition'); + if (scene.sampleHeightSupported) + found.push('sampleHeight', 'finestHeights', 'rayCast'); + return found; +} + +/** + * @param {{scene: object, camera?: object, draw: {sets: Map, + * version: () => number}, capabilities: ReadonlySet}} options + * `draw`: the draw port's part (`createCesiumDraw`) whose sets it picks + * and sees through, read on each query; `capabilities` gate the members that need them. + * @returns {import('../contract/query').QueryPort} + */ +export function createCesiumQuery({ + scene, + camera = scene.camera, + draw: drawPart, + capabilities, +}) { + const screen = (x, y) => new Cesium.Cartesian2(x, y); + const ecef = (c) => (c ? { x: c.x, y: c.y, z: c.z } : null); + const finite = (p) => + Number.isFinite(p?.x) && Number.isFinite(p?.y) && Number.isFinite(p?.z); + const cesiumRay = (ray) => + new Cesium.Ray(toCartesian(ray.origin), toCartesian(ray.direction)); + + /** The live set and item a picked object belongs to, or null. */ + function ownerOf(picked) { + const id = picked?.id; + if (!id || typeof id.set !== 'string') return null; + const record = drawPart.sets.get(id.set); + const item = record?.items.get(id.id); + return record && item ? { record, item, id } : null; + } + + const pickable = ({ record, item }) => + record.host?.show !== false && + record.spec.pickable !== false && + item.show !== false && + item.pickable !== false; + + const hitOf = ({ id }) => drawHitOf({ id }); + + /** The globe (or ellipsoid) under a pixel, as a surface hit. */ + function surfaceHit(x, y) { + const position = query.pickPosition(x, y) ?? query.pickEllipsoid(x, y); + return position ? { set: '', id: '', surface: true, position } : null; + } + + /** + * The pickable draw-set items under a pixel, nearest first, once each (a + * shape's fill and outline share one id). `untilForeign` stops at the first + * thing that is not a draw-set item (a tile, the app's own primitives): + * what is behind it is hidden. + */ + function drill(x, y, { width = 3, height = 3, limit, untilForeign } = {}) { + const hits = []; + if (limit === 0) return hits; + const seen = new Set(); + for (const picked of scene.drillPick( + screen(x, y), + undefined, + width, + height, + )) { + const owner = ownerOf(picked); + if (!owner) { + if (untilForeign) break; + continue; + } + const key = `${owner.id.set}\u0000${owner.id.id}`; + if (!pickable(owner) || seen.has(key)) continue; + seen.add(key); + hits.push(hitOf(owner)); + if (limit !== undefined && hits.length >= limit) break; + } + return hits; + } + + // What height queries see through, by their items' pick ids: the sets not + // drawn as ground, and the sets a caller excludes. Built once per change + // to the sets, not per query. + const seeThroughCache = new Map(); + let seeThroughVersion = -1; + function seeThrough(exclude, { allSets = false } = {}) { + if (seeThroughVersion !== drawPart.version()) { + seeThroughCache.clear(); + seeThroughVersion = drawPart.version(); + } + const key = `${allSets}\u0000${exclude?.join('\u0000') ?? ''}`; + let out = seeThroughCache.get(key); + if (!out) { + out = []; + for (const record of drawPart.sets.values()) + if ( + allSets || + !record.spec.includeInHeightQueries || + exclude?.includes(record.spec.id) + ) + for (const id of record.pickIds) out.push(id); + seeThroughCache.set(key, out); + } + return out; + } + + /** Whether a set drawn as ground is in the scene, other than `exclude`. */ + const groundSets = (exclude) => + [...drawPart.sets.values()].some( + (record) => + record.spec.includeInHeightQueries && + record.host?.show !== false && + !exclude?.includes(record.spec.id), + ); + + const heights = () => heightsFor(scene); + const can = (capability) => capabilities.has(capability); + const globeShown = () => Boolean(scene.globe?.show); + + /** + * `fn` with the globe hidden, so a pick or sample sees tiles and sets + * alone. Synchronous: the globe is shown again before anything draws. + */ + function withoutGlobe(fn) { + if (!globeShown()) return fn(); + scene.globe.show = false; + try { + return fn(); + } finally { + scene.globe.show = true; + } + } + + /** A height now from what is loaded, against the surface asked for. */ + function heightNow(point, against, excluded) { + if (against === 'terrain') + return heights().now(point, { against: 'terrain' }); + const sample = () => heights().now(point, { exclude: excluded }); + return against === 'tiles' ? withoutGlobe(sample) : sample(); + } + + const close = (a, b) => a !== null && b !== null && Math.abs(a - b) <= 0.01; + const ellipsoidTerrain = () => + scene.terrainProvider instanceof Cesium.EllipsoidTerrainProvider; + + /** + * Where a height came from, told apart by sampling again without the + * ground sets and against the terrain alone. + */ + function sourceOf(point, height, against, exclude) { + const terrain = () => (ellipsoidTerrain() ? 'ellipsoid' : 'terrain'); + if (against === 'terrain') return terrain(); + if (groundSets(exclude)) { + const bare = heightNow( + point, + against, + seeThrough(exclude, { allSets: true }), + ); + if (!close(bare, height)) return 'set'; + } + if (against === 'tiles' || !globeShown()) return 'tiles'; + return close(heights().now(point, { against: 'terrain' }), height) + ? terrain() + : 'tiles'; + } + + const query = { + pick(x, y, window = {}) { + const owner = ownerOf( + scene.pick(screen(x, y), window.width ?? 3, window.height ?? 3), + ); + if (owner && pickable(owner)) return hitOf(owner); + // Something unpickable is on top: the first pickable item under it, + // unless something else hides it. + if (owner) { + const [under] = drill(x, y, { + ...window, + limit: 1, + untilForeign: true, + }); + if (under) return under; + } + return surfaceHit(x, y); + }, + drillPick: (x, y, options = {}) => + drill(x, y, { ...options, untilForeign: false }), + pickPosition(x, y) { + if (!can('pickPosition') || !scene.pickPositionSupported) return null; + return ecef(scene.pickPosition(screen(x, y))); + }, + pickEllipsoid(x, y) { + return ecef(camera.pickEllipsoid(screen(x, y))); + }, + pickGlobe(ray) { + return ecef(scene.globe?.pick(cesiumRay(ray), scene)); + }, + pickRay(x, y) { + const ray = camera.getPickRay(screen(x, y)); + return { origin: ecef(ray.origin), direction: ecef(ray.direction) }; + }, + project(position) { + const s = Cesium.SceneTransforms.worldToWindowCoordinates( + scene, + toCartesian(position), + ); + return s ? { x: s.x, y: s.y } : null; + }, + projectMany(source, out) { + const p = new Cesium.Cartesian3(); + const s = new Cesium.Cartesian2(); + for (let i = 0, j = 0; i + 2 < source.length; i += 3, j += 2) { + p.x = source[i]; + p.y = source[i + 1]; + p.z = source[i + 2]; + const w = Cesium.SceneTransforms.worldToWindowCoordinates(scene, p, s); + out[j] = w ? w.x : NaN; + out[j + 1] = w ? w.y : NaN; + } + }, + isOccluded(position) { + const occluder = new Cesium.EllipsoidalOccluder( + scene.globe?.ellipsoid ?? Cesium.Ellipsoid.WGS84, + camera.positionWC, + ); + return !occluder.isPointVisible(toCartesian(position)); + }, + sampleHeightNow(point, { against = 'surface', exclude } = {}) { + if (!can('sampleHeight')) return null; + return heightNow(point, against, seeThrough(exclude)); + }, + sampleHeightNowMany(points, out, { against = 'surface', exclude } = {}) { + const excluded = can('sampleHeight') && seeThrough(exclude); + const point = { lon: 0, lat: 0 }; + for (let i = 0; i < out.length; i++) { + point.lon = points[i * 2]; + point.lat = points[i * 2 + 1]; + out[i] = excluded ? (heightNow(point, against, excluded) ?? NaN) : NaN; + } + }, + /** + * Cesium streams the finest tiles for every sample, `mostDetailed` or + * not. Against `tiles` it streams them, then samples them with the + * globe hidden, which only a synchronous sample can do. + */ + async sampleHeight(points, { against = 'surface', exclude } = {}) { + if (!can('sampleHeight')) return points.map(() => null); + const excluded = seeThrough(exclude); + let found = await heights().batch( + points, + against === 'terrain' ? { against: 'terrain' } : { exclude: excluded }, + ); + if (against === 'tiles') + found = points.map((point) => heightNow(point, 'tiles', excluded)); + const lod = can('finestHeights') ? 'finest' : 'visible'; + return found.map((height, i) => + height === null + ? null + : { + height, + confidence: 1, + source: sourceOf(points[i], height, against, exclude), + lod, + }, + ); + }, + async clampToSurface(positions, options = {}) { + const points = positions.map((p) => { + const c = + finite(p) && Cesium.Cartographic.fromCartesian(toCartesian(p)); + return c + ? { + lon: Cesium.Math.toDegrees(c.longitude), + lat: Cesium.Math.toDegrees(c.latitude), + } + : null; + }); + const samples = await query.sampleHeight( + points.map((p) => p ?? { lon: NaN, lat: NaN }), + options, + ); + return samples.map((sample, i) => + sample && points[i] + ? ecef( + Cesium.Cartesian3.fromDegrees( + points[i].lon, + points[i].lat, + sample.height, + ), + ) + : null, + ); + }, + async rayCast( + ray, + { against = 'surface', exclude, maxDistance = Infinity } = {}, + ) { + if (!can('rayCast')) return null; + const r = cesiumRay(ray); + let position; + if (against === 'terrain') position = scene.globe?.pick(r, scene); + else { + const cast = () => scene.pickFromRay(r, seeThrough(exclude))?.position; + position = against === 'tiles' ? withoutGlobe(cast) : cast(); + } + if (!position) return null; + return Cesium.Cartesian3.distance(r.origin, position) <= maxDistance + ? ecef(position) + : null; + }, + }; + return query; +} + +/** No draw sets, while a viewer has no draw port. */ +const NO_SETS = new Map(); + +// A Cesium viewer with no renderer bound to it gets a +// query port over its scene when code first asks `findQuery` for one, +// answering over the draw sets drawn through `findDraw` on the same viewer +// (looked up on each query, which makes the viewer's draw port if it has +// none yet: a layer may draw after it asks for the query port). +provideUnboundQuery((viewer) => { + const scene = viewer.scene; + // By shape, not `instanceof`: the viewer may come from another + // copy of Cesium. + if ( + typeof scene?.pick !== 'function' || + typeof scene.drillPick !== 'function' || + typeof scene.camera?.pickEllipsoid !== 'function' + ) + return null; + const part = () => unboundDrawPart(findDraw(viewer)); + const port = createCesiumQuery({ + scene, + draw: { + get sets() { + return part()?.sets ?? NO_SETS; + }, + version: () => part()?.version() ?? 0, + }, + capabilities: new Set(queryCapabilities(scene)), + }); + return { port, dispose() {} }; +}); diff --git a/src/render/cesium/query.test.mjs b/src/render/cesium/query.test.mjs new file mode 100644 index 000000000..70e53fd1b --- /dev/null +++ b/src/render/cesium/query.test.mjs @@ -0,0 +1,132 @@ +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +import test from 'node:test'; +import { bindRenderer, drawOf, findQuery, queryOf } from '../rendererOf.js'; +import './query.js'; + +/** + * A viewer's scene with what the draw and query ports touch: primitives, + * frame events, picks, and height samples that record what they see + * through. + */ +function fakeViewer() { + const added = []; + const sampled = []; + const scene = { + added, + sampled, + preRender: new Cesium.Event(), + postRender: new Cesium.Event(), + frameState: { mode: Cesium.SceneMode.SCENE3D }, + camera: { + positionWC: new Cesium.Cartesian3(2e7, 0, 0), + pickEllipsoid: (s) => + s.x === 50 && s.y === 50 ? new Cesium.Cartesian3(6378137, 0, 0) : null, + }, + primitives: { + add: (primitive) => (added.push(primitive), primitive), + remove: (primitive) => { + const at = added.indexOf(primitive); + if (at >= 0) added.splice(at, 1); + return at >= 0; + }, + length: 0, + }, + picked: undefined, + pick() { + return this.picked; + }, + drillPick() { + return this.picked ? [this.picked] : []; + }, + sampleHeightSupported: true, + sampleHeight(carto, exclude) { + sampled.push(exclude); + return 12; + }, + updateHeight: () => () => {}, + getHeight: () => undefined, + requestRender() {}, + isDestroyed: () => false, + }; + return { scene }; +} + +test('a viewer of its own, with no renderer bound, is queried through a built port over its draw sets', () => { + const viewer = fakeViewer(); + const { scene } = viewer; + const query = queryOf(viewer); + assert.equal(findQuery(viewer), query, 'one per viewer'); + + const ground = drawOf(viewer).points({ + id: 'mine', + includeInHeightQueries: true, + }); + ground.set([ + { id: 'a', pos: { lon: 0, lat: 0 }, pixelSize: 4, meta: { n: 1 } }, + ]); + const other = drawOf(viewer).points({ id: 'theirs' }); + other.set([{ id: 'b', pos: { lon: 1, lat: 0 }, pixelSize: 4 }]); + const idsOf = (exclude) => exclude.map((id) => `${id.set}:${id.id}`).sort(); + + // Heights see through the sets not drawn as ground, and those excluded. + assert.equal(query.sampleHeightNow({ lon: 0, lat: 0 }), 12); + assert.deepEqual(idsOf(scene.sampled.at(-1)), ['theirs:b']); + query.sampleHeightNow({ lon: 0, lat: 0 }, { exclude: ['mine'] }); + assert.deepEqual(idsOf(scene.sampled.at(-1)), ['mine:a', 'theirs:b']); + + // Picks name the set's item. + scene.picked = { id: scene.added[0].get(0).id }; + assert.deepEqual(query.pick(5, 5), { + set: 'mine', + id: 'a', + meta: { n: 1 }, + surface: false, + }); + + // The screen centre's ellipsoid point, and the horizon from the eye. + assert.deepEqual(query.pickEllipsoid(50, 50), { x: 6378137, y: 0, z: 0 }); + assert.equal(query.pickEllipsoid(0, 0), null); + assert.equal(query.isOccluded({ x: 6378137, y: 0, z: 0 }), false); + assert.equal(query.isOccluded({ x: -6378137, y: 0, z: 0 }), true); + + // A renderer bound later answers new callers. + const unbind = bindRenderer(viewer, { query: { id: 'renderer' } }); + assert.equal(findQuery(viewer).id, 'renderer'); + unbind(); + assert.notEqual(findQuery(viewer), query, 'built again once unbound'); + ground.dispose(); + other.dispose(); +}); + +test('nothing to query, no port', () => { + assert.equal(findQuery({ scene: {} }), null); + assert.throws(() => queryOf({ scene: {} }), /no renderer to query/); + assert.throws( + () => queryOf({ scene: {}, isDestroyed: () => true }), + /destroyed/, + ); +}); + +test('a query port built before its viewer can draw sees the sets drawn later, and goes with the viewer', () => { + const viewer = fakeViewer(); + const { scene } = viewer; + const primitives = scene.primitives; + scene.primitives = undefined; + const query = queryOf(viewer); + assert.equal(query.pick(5, 5)?.set, undefined, 'nothing drawn yet'); + scene.primitives = primitives; + const set = drawOf(viewer).points({ id: 'later' }); + set.set([{ id: 'a', pos: { lon: 0, lat: 0 }, pixelSize: 4 }]); + scene.picked = { id: scene.added[0].get(0).id }; + assert.equal(query.pick(5, 5)?.set, 'later', 'its sets are picked'); + query.sampleHeightNow({ lon: 0, lat: 0 }, { exclude: ['later'] }); + assert.deepEqual( + scene.sampled.at(-1).map((id) => id.set), + ['later'], + 'and seen through', + ); + set.dispose(); + viewer.isDestroyed = () => true; + assert.equal(findQuery(viewer), null, 'gone with its viewer'); +}); diff --git a/src/render/cesium/unbound.js b/src/render/cesium/unbound.js index 9b0100ce7..696e0daa4 100644 --- a/src/render/cesium/unbound.js +++ b/src/render/cesium/unbound.js @@ -2,8 +2,9 @@ * @module render/cesium/unbound * @description What to load, once, before handing the Cesium-free * layers a Cesium viewer with no renderer bound: the factories - * that build a camera, credits, effects and draw port over such a viewer - * when code first asks for one (`rendererOf.js`). + * that build a camera, credits, effects, draw and query port over such a + * viewer when code first asks for one (`rendererOf.js`). */ import './camera.js'; import './effects.js'; +import './query.js'; diff --git a/src/render/rendererOf.js b/src/render/rendererOf.js index 587eb85da..7ab608cdb 100644 --- a/src/render/rendererOf.js +++ b/src/render/rendererOf.js @@ -65,6 +65,7 @@ const unboundGlobes = unboundPorts('globe'); const unboundCredits = unboundPorts('credits'); /** Draw ports are `{port, dispose, release}`, as credits ports are. */ const unboundDraws = unboundPorts('draw'); +const unboundQueries = unboundPorts('query'); /** * Provide the factory `cameraOf` builds a camera port with for a scene @@ -99,6 +100,16 @@ export function provideUnboundDraw(build) { unboundDraws.provide(build); } +/** + * Provide the factory `findQuery` builds a query port with for a scene + * object no renderer is bound to, as `provideUnboundCamera` does. It answers + * over the sets drawn through `findDraw` on the same scene object. + * @param {(host: object) => ({port: object, dispose: () => void} | null)} build + */ +export function provideUnboundQuery(build) { + unboundQueries.provide(build); +} + /** * Provide the factory `findEffects` builds an effects port with for a * scene object no renderer is bound to, as `provideUnboundCamera` does. @@ -151,6 +162,7 @@ export function bindRenderer(host, renderer) { unboundGlobes.supersede(host); unboundCredits.supersede(host); unboundDraws.supersede(host); + unboundQueries.drop(host); renderers.set(host, renderer); return () => { if (renderers.get(host) === renderer) renderers.delete(host); @@ -235,6 +247,16 @@ export function findDraw(host) { return unboundDraws.find(host); } +/** Why `host` has no port to `what` (draw with, query). */ +const noPort = (host, what) => + new Error( + host?.isDestroyed?.() + ? 'This scene has been destroyed' + : `This scene has no renderer to ${what}: bind one, or load the ` + + "Cesium adapter's factories (the ./render/cesium/unbound export) for a viewer " + + 'with no renderer bound', + ); + /** * `findDraw`, for code that cannot start without one. * @param {object} host @@ -244,13 +266,33 @@ export function findDraw(host) { export function drawOf(host) { const draw = findDraw(host); if (draw) return draw; - throw new Error( - host?.isDestroyed?.() - ? 'This scene has been destroyed' - : 'This scene has no renderer to draw with: bind one, or load the ' + - "Cesium adapter's factories (the ./render/cesium/unbound export) for a viewer " + - 'with no renderer bound', - ); + throw noPort(host, 'draw with'); +} + +/** + * The query port of the renderer bound to `host`; with no renderer bound, + * one built over `host` by the provided factory and kept with it while + * `host` lives, as `findCamera` does. A built one picks, and its height + * queries see through, the sets drawn through `findDraw` on `host`; one + * kept from before a renderer was bound answers as it did, while new + * callers get the renderer's. + * @param {object|null|undefined} host + * @returns {import('./contract/query').QueryPort | null} + */ +export function findQuery(host) { + return unboundQueries.find(host); +} + +/** + * `findQuery`, for code that cannot start without one. + * @param {object} host + * @returns {import('./contract/query').QueryPort} + * @throws When there is no query port for `host`. + */ +export function queryOf(host) { + const query = findQuery(host); + if (query) return query; + throw noPort(host, 'query'); } /** diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index 7c70d5f07..f3c2535ac 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -12,7 +12,9 @@ * `render/cesium/draw.js` the same way (the camera factory loads it), * unless it is Cesium-free: then it is listed in `DRAW_FROM_CALLER`, and * a caller handing it a viewer with no renderer bound loads the package's - * `./render/cesium/unbound` export once. + * `./render/cesium/unbound` export once. An entry that reaches a caller of + * `findQuery` or `queryOf` loads `render/cesium/query.js` (the camera + * factory loads it too), or is such a Cesium-free entry. * * The graph is every static import, re-export and literal dynamic import of * the entry's module and those it reaches, read by the parsers the Cesium @@ -35,6 +37,7 @@ const FACTORY = 'src/render/cesium/camera.js'; const EFFECTS_FACTORY = 'src/render/cesium/effects.js'; const GLOBE_FACTORY = 'src/render/cesium/globe.js'; const DRAW_FACTORY = 'src/render/cesium/draw.js'; +const QUERY_FACTORY = 'src/render/cesium/query.js'; const UNBOUND = 'src/render/cesium/unbound.js'; /** @@ -196,8 +199,14 @@ test('every public entry that reaches the renderer bridge loads the unbound came /** * Every public entry reaching a caller of `lookup` loads `factory`. With * `reached`, at least one entry must reach one, or the walk is broken. + * With `fromCaller`, the Cesium-free entries listed in + * `DRAW_FROM_CALLER` may leave the factory to their caller. */ -function checkLookupFactory(lookup, factory, { reached = true } = {}) { +function checkLookupFactory( + lookup, + factory, + { reached = true, fromCaller = false } = {}, +) { const missing = []; let reaching = 0; const calls = (file) => @@ -212,6 +221,7 @@ function checkLookupFactory(lookup, factory, { reached = true } = {}) { const entry = path.normalize(target.slice(2)); if (![...reachable(entry)].some(calls)) continue; reaching += 1; + if (fromCaller && DRAW_FROM_CALLER.has(key)) continue; const carrier = INJECTED[key]; const loads = (file) => reachable(file, { eager: true }).has(factory); if (!loads(entry) && !(carrier && loads(carrier))) missing.push(key); @@ -235,12 +245,25 @@ test('every public entry that reaches a findGlobe caller loads the unbound globe checkLookupFactory('findGlobe', GLOBE_FACTORY); }); +test('every public entry that reaches a findQuery or queryOf caller loads the unbound query factory, or its caller can', () => { + for (const lookup of ['findQuery', 'queryOf']) + checkLookupFactory(lookup, QUERY_FACTORY, { + reached: false, + fromCaller: true, + }); +}); + +test('the unbound camera factory loads the unbound query factory', () => { + assert.ok(reachable(FACTORY, { eager: true }).has(QUERY_FACTORY)); +}); + test('the unbound export brings every unbound factory', () => { const loaded = reachable(UNBOUND, { eager: true }); for (const factory of [ FACTORY, EFFECTS_FACTORY, DRAW_FACTORY, + QUERY_FACTORY, 'src/render/cesium/credits.js', ]) assert.ok(loaded.has(factory), factory);