Give a viewer of its own a query port, as it has draw and camera ports

The Cesium query port moves out of createCesiumPorts into its own module,
unchanged, so it can also be built over a caller's viewer with no
renderer bound. findQuery and queryOf find the bound renderer's query port
or, for such a viewer, one the Cesium adapter's factory builds, as findDraw
and findCamera do. It picks the sets drawn through findDraw on that viewer
and its height samples see through them, so a layer can exclude its own
sets; it projects, casts rays and picks the ellipsoid as the renderer's
does. A renderer bound later answers new callers.

The camera factory and the caller's unbound export load it, and the
factory walk checks that every public entry reaching a findQuery or queryOf
caller loads it, or is a Cesium-free entry whose caller does.
This commit is contained in:
Sameh Khamis committed 2026-11-06 22:25:07 -08:00
1 parent ee6b9e49aa
commit 784561a6ae
10 files changed
+654 -308

No files matched your search

+1
View File
@@ -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',
+3 -1
View File
@@ -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:
+13
View File
@@ -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()),
+15 -296
View File
@@ -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);
+372
View File
@@ -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<string, object>,
* version: () => number}, capabilities: ReadonlySet<string>}} 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() {} };
});
+132
View File
@@ -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');
});
+3 -2
View File
@@ -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';
+49 -7
View File
@@ -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');
}
/**
+25 -2
View File
@@ -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);