mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
Merge remote-tracking branch 'upstream/main' into HEAD
This commit is contained in:
commit
0dbbd9047e
402 files changed
+63739
-1868
No files matched your search
Vendored
+1
@@ -23,6 +23,7 @@ export function createControls({ state: layerState, services, parts, source }) {
|
||||
|
||||
attachDataManager(dataManager) {
|
||||
layerState.dataManager = dataManager;
|
||||
parts.dependencies.watchAdoptions(dataManager);
|
||||
},
|
||||
|
||||
setParams(params = {}) {
|
||||
|
||||
@@ -79,6 +79,25 @@ export function createDependencies({
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Give up a dependency the user adopts. A direct selection, or the Cockpit
|
||||
* riding one of its aircraft, promotes a layer Contacts turned on into the
|
||||
* user's own (`DataLayerManager.adoptLayerVisibility`). Releasing it when
|
||||
* Contacts goes off would tear down that track or Cockpit before the
|
||||
* Context restore could put the layer back.
|
||||
*/
|
||||
function relinquishAdoptedDependency(change) {
|
||||
if (change?.type === 'visibility' && change.adopted && change.enabled)
|
||||
layerState.ownedDependencies.delete(change.layerId);
|
||||
}
|
||||
|
||||
/** Follow one manager's adoptions; null stops following. */
|
||||
function watchAdoptions(dataManager) {
|
||||
layerState.unwatchAdoptions?.();
|
||||
layerState.unwatchAdoptions =
|
||||
dataManager?.subscribe?.(relinquishAdoptedDependency) || null;
|
||||
}
|
||||
|
||||
function activateOperationalContext() {
|
||||
const activationId = ++layerState.activationId;
|
||||
layerState.autoFocusRetryPending = false;
|
||||
@@ -113,6 +132,7 @@ export function createDependencies({
|
||||
refreshAfterDeferredDependency,
|
||||
enableDependencies,
|
||||
releaseOwnedDependencies,
|
||||
watchAdoptions,
|
||||
activateOperationalContext,
|
||||
};
|
||||
}
|
||||
@@ -1,4 +1,5 @@
|
||||
import { cameraPoseSignature } from '../../data/iconOrientation.js';
|
||||
import { AWARENESS_RANGE_PULSE } from './policy.js';
|
||||
|
||||
export function createLifecycle({
|
||||
state: layerState,
|
||||
@@ -8,6 +9,86 @@ export function createLifecycle({
|
||||
}) {
|
||||
const { holdContinuousRender, releaseContinuousRender } = services.render;
|
||||
|
||||
/**
|
||||
* Note the user handling the map's camera (pointer, wheel or touch on the
|
||||
* Cesium canvas, where its camera controller listens), so a camera move the
|
||||
* user made can wake the range pulses and one the app made (tracking,
|
||||
* cockpit, orbit, a fly-to) does not. Keys are left out: Cesium's camera
|
||||
* controller reads none, and typing elsewhere must not count. Nor does
|
||||
* input while the camera controller's inputs are off: the cockpit (or a
|
||||
* gizmo drag, or a drawing tool) owns the camera then, and the user's
|
||||
* gesture moves nothing.
|
||||
*/
|
||||
function noteCameraInput(event) {
|
||||
if (event?.type === 'pointermove' && !event.buttons) return;
|
||||
if (!cameraInputsEnabled()) return;
|
||||
layerState.lastCameraInputMs = Date.now();
|
||||
if (event?.type === 'pointerdown') activePointers.add(event.pointerId);
|
||||
if (event?.type === 'pointerdown' || event?.type === 'touchstart')
|
||||
followGesture(true);
|
||||
}
|
||||
|
||||
// A drag can leave the canvas, and Cesium follows it at document level
|
||||
// (in Firefox, and wherever there are no pointer events). So does this,
|
||||
// from a gesture's start on the canvas to its end, so a long gesture keeps
|
||||
// the input window open the whole way.
|
||||
const GESTURE_MOVE_EVENTS = ['pointermove', 'touchmove'];
|
||||
const GESTURE_END_EVENTS = [
|
||||
'pointerup',
|
||||
'pointercancel',
|
||||
'touchend',
|
||||
'touchcancel',
|
||||
];
|
||||
let followingGesture = false;
|
||||
const activePointers = new Set();
|
||||
|
||||
function followGesture(on) {
|
||||
if (followingGesture === on) return;
|
||||
followingGesture = on;
|
||||
if (!on) activePointers.clear();
|
||||
const listen = on ? 'addEventListener' : 'removeEventListener';
|
||||
for (const type of GESTURE_MOVE_EVENTS)
|
||||
globalThis.document?.[listen]?.(type, noteCameraInput, { passive: true });
|
||||
for (const type of GESTURE_END_EVENTS)
|
||||
globalThis.document?.[listen]?.(type, endGesture, { passive: true });
|
||||
globalThis[listen]?.('blur', dropGesture);
|
||||
globalThis.document?.[listen]?.('visibilitychange', dropGesture);
|
||||
}
|
||||
|
||||
// A gesture ends with its last contact: lifting one finger of a pinch
|
||||
// leaves Cesium a one-finger drag.
|
||||
function endGesture(event) {
|
||||
noteCameraInput(event);
|
||||
activePointers.delete(event?.pointerId);
|
||||
if (activePointers.size || event?.touches?.length) return;
|
||||
followGesture(false);
|
||||
}
|
||||
|
||||
// Losing the window or the page mid-gesture means its end may never
|
||||
// arrive here, so stop following it and drop its pending input.
|
||||
function dropGesture(event) {
|
||||
if (
|
||||
event?.type === 'visibilitychange' &&
|
||||
document.visibilityState !== 'hidden'
|
||||
)
|
||||
return;
|
||||
followGesture(false);
|
||||
layerState.lastCameraInputMs = Number.NEGATIVE_INFINITY;
|
||||
}
|
||||
|
||||
function cameraInputsEnabled() {
|
||||
const controller = layerState.viewer?.scene?.screenSpaceCameraController;
|
||||
return controller?.enableInputs !== false;
|
||||
}
|
||||
|
||||
const CAMERA_INPUT_EVENTS = [
|
||||
'pointerdown',
|
||||
'pointermove',
|
||||
'pointerup',
|
||||
'wheel',
|
||||
'touchstart',
|
||||
];
|
||||
|
||||
/**
|
||||
* Quantized camera-pose signature, or '' when the camera cannot report a full
|
||||
* pose yet. An unknown pose reads as PARKED, so a camera that is still coming
|
||||
@@ -50,10 +131,18 @@ export function createLifecycle({
|
||||
'gev:awareness-subject-cleared',
|
||||
layerState.subjectClearListener,
|
||||
);
|
||||
const input = layerState.viewer.canvas ?? layerState.viewer.scene?.canvas;
|
||||
for (const type of CAMERA_INPUT_EVENTS)
|
||||
input?.addEventListener?.(type, noteCameraInput, { passive: true });
|
||||
layerState.cameraInputTarget = input ?? null;
|
||||
layerState.preRenderRemover =
|
||||
layerState.viewer.scene.preRender.addEventListener(() => {
|
||||
if (!layerState.enabled) return;
|
||||
const now = Date.now();
|
||||
// Another owner took the camera: a gesture begun before it did must
|
||||
// not wake the pulses on that owner's first move.
|
||||
if (!cameraInputsEnabled())
|
||||
layerState.lastCameraInputMs = Number.NEGATIVE_INFINITY;
|
||||
// "Did the camera move" uses the SAME quantized pose signature the fleet
|
||||
// rotation pass gates on (iconOrientation.cameraPoseSignature) rather than
|
||||
// camera.changed, whose granularity is globally degraded by other layers
|
||||
@@ -62,6 +151,14 @@ export function createLifecycle({
|
||||
if (poseSig !== layerState.lastCameraPoseSig) {
|
||||
layerState.lastCameraPoseSig = poseSig;
|
||||
layerState.lastCameraPoseChangeMs = now;
|
||||
// A camera move the user made runs the range pulses again; parked,
|
||||
// or moved by the app (tracking, cockpit, orbit, a fly-to), they
|
||||
// rest.
|
||||
if (
|
||||
now - layerState.lastCameraInputMs <
|
||||
AWARENESS_RANGE_PULSE.inputWakeMs
|
||||
)
|
||||
parts.rendering.wakePulses();
|
||||
}
|
||||
const decision = parts.model.awarenessRefreshDecision({
|
||||
nowMs: now,
|
||||
@@ -108,6 +205,13 @@ export function createLifecycle({
|
||||
'gev:awareness-subject-cleared',
|
||||
layerState.subjectClearListener,
|
||||
);
|
||||
for (const type of CAMERA_INPUT_EVENTS)
|
||||
layerState.cameraInputTarget?.removeEventListener?.(
|
||||
type,
|
||||
noteCameraInput,
|
||||
);
|
||||
layerState.cameraInputTarget = null;
|
||||
followGesture(false);
|
||||
}
|
||||
layerState.preRenderRemover?.();
|
||||
layerState.preRenderRemover = null;
|
||||
@@ -236,6 +340,7 @@ export function createLifecycle({
|
||||
layerState.clearListener = null;
|
||||
layerState.subjectClearListener = null;
|
||||
layerState.viewer = null;
|
||||
parts.dependencies.watchAdoptions(null);
|
||||
layerState.dataManager = null;
|
||||
},
|
||||
};
|
||||
|
||||
@@ -196,6 +196,7 @@ export function createModel({ state: layerState, services, parts, source }) {
|
||||
id: cohort.id,
|
||||
label: cohort.label,
|
||||
source: cohort.source,
|
||||
sourceStatus: cohort.sourceStatus || null,
|
||||
coverage: cohort.coverage || null,
|
||||
relationship: cohort.summary.relationship,
|
||||
count: cohort.summary.count,
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
t,
|
||||
translateKnown,
|
||||
} from '../../i18n/index.js';
|
||||
import { sourceStatusLabel } from '../../ui/layerNames.js';
|
||||
import { formatQuantity } from '../../ui/unitLabels.js';
|
||||
import { AWARENESS_PAGE_SIZE, AWARENESS_PAGE_ROTATE_MS } from './policy.js';
|
||||
import { distanceParts } from '../../data/distanceFormat.js';
|
||||
@@ -150,7 +151,7 @@ export function createPanel({ state: layerState, parts }) {
|
||||
relationship: summary.relationship.toLowerCase(),
|
||||
label: cohort.label,
|
||||
count: `${presentAwarenessCount(summary)}${pageLabel}`,
|
||||
detail: `${cohort.source}${coverage} · ${presentAwarenessReason(summary)}`,
|
||||
detail: `${sourceStatusLabel(cohort.source, cohort.sourceStatus)}${coverage} · ${presentAwarenessReason(summary)}`,
|
||||
nearest,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { createPanel } from './panel.js';
|
||||
|
||||
test('a Contacts row names its provider as the Layers panel does, with its feed state', () => {
|
||||
const cohort = (id, source, sourceStatus) => ({
|
||||
id,
|
||||
label: id,
|
||||
source,
|
||||
sourceStatus,
|
||||
summary: { relationship: 'OBSERVED', count: 1, nearest: [], reason: 'observed' },
|
||||
});
|
||||
const state = {
|
||||
enabled: true,
|
||||
results: {
|
||||
subject: { label: 'AFR38JF' },
|
||||
cohorts: [
|
||||
cohort('flights', 'adsb.lol', 'fallback'),
|
||||
cohort('military', 'adsb.lol', null),
|
||||
cohort('ais-live-vessels', 'Datalastic', 'stale'),
|
||||
],
|
||||
},
|
||||
cohortPages: new Map(),
|
||||
panelListeners: new Set(),
|
||||
panelSignature: '',
|
||||
navigationIndex: 0,
|
||||
};
|
||||
const parts = {
|
||||
navigation: { canNavigateNext: () => false },
|
||||
rendering: { hideDirectionOverlay() {} },
|
||||
};
|
||||
createPanel({ state, parts }).renderResults();
|
||||
assert.deepEqual(
|
||||
state.panelView.rows.map((row) => row.detail),
|
||||
['adsb.lol · FALLBACK · observed', 'adsb.lol · observed', 'Datalastic · STALE · observed'],
|
||||
);
|
||||
state.offPanelLocale?.();
|
||||
});
|
||||
@@ -44,6 +44,93 @@ export const AWARENESS_MAX_NAVIGATION_EXAMPLES = 10000;
|
||||
|
||||
export const CONTEXT_RIM_HEIGHT_M = 2500;
|
||||
|
||||
/** @constant The 250 km range ring around the Global Context subject.
|
||||
* The old 1 px ellipse outline vanished over desert, snow and under
|
||||
* the FLIR, NVG and CRT styles. A bright core inside a dark halo keeps
|
||||
* luminance contrast on light and dark ground alike, and luminance is what
|
||||
* the monochrome styles keep. The core is the Context panel's blue; the halo
|
||||
* is the map-card ink. Widths are screen pixels; `outlineWidth` is per side.
|
||||
* It is drawn as an unpickable primitive, so clicks on its edge reach the
|
||||
* contacts underneath.
|
||||
* While the sonar pulses run, the ring dims to `restOpacity` and flashes
|
||||
* to full as each pulse reaches it, fading over `flashMs`. `restOpacity`
|
||||
* keeps the 250 km edge readable between flashes, in screenshots and for
|
||||
* low-vision viewers. Once the pulses rest, and without pulses (reduced
|
||||
* motion, or a scene that cannot animate), it stays on screen at full. */
|
||||
export const AWARENESS_RANGE_RING_STYLE = Object.freeze({
|
||||
color: 'rgba(98, 181, 255, 0.95)',
|
||||
outlineColor: 'rgba(4, 12, 16, 0.8)',
|
||||
width: 4,
|
||||
outlineWidth: 1,
|
||||
segments: 128,
|
||||
flashMs: 1800,
|
||||
restOpacity: 0.4,
|
||||
});
|
||||
|
||||
/** @constant Sonar-style pulses that grow slowly from the subject to the
|
||||
* range ring and are almost gone when they reach it. `count` pulses share
|
||||
* one `periodMs`, evenly staggered, so a new one starts every
|
||||
* `periodMs / count`. Each starts at `startFraction` of the radius, fades in
|
||||
* over `fadeInFraction` of its travel, then fades as (1 - travel) to the
|
||||
* `fadeOutPower` down to `endOpacityFraction` of `peakOpacity`, so a pulse
|
||||
* is dim but still visible when it reaches the ring and the ring flashes.
|
||||
* Each line is `width` CSS pixels wide, its outer `outlineWidth` a dark
|
||||
* halo, in the ring's colours, as Cesium's polyline outline material draws.
|
||||
* Behind each line a radial gradient in the same blue fades inward over
|
||||
* `gradientDepthFraction` of the radius, at most
|
||||
* `gradientOpacity` strong. One unpickable disc draws the lines and the
|
||||
* gradient, so pulses never catch a click meant for a contact; its shader
|
||||
* takes at most four pulses. The disc follows the subject by a model-matrix
|
||||
* rotation, so it stays concentric with the ring, and is rebuilt only after
|
||||
* the subject moves `gradientRebuildM` from where it was built; while the
|
||||
* pulses rest the hidden disc is left alone and catches up when they wake. The
|
||||
* disc is hidden while the camera is below its height, where it would sweep
|
||||
* the sky.
|
||||
* The pulses run for `activeMs` (three ring flashes) after a selection or
|
||||
* a camera move, fading in and out over `settleMs`, then rest: the ring
|
||||
* stays on screen, static, and nothing asks for frames, so a parked view
|
||||
* goes quiet again. Only a camera move within `inputWakeMs` of the user
|
||||
* handling the map (pointer, wheel or touch on the canvas, which covers a
|
||||
* drag's inertia, while the camera controls take input) wakes them; a moving subject and the app's own camera moves
|
||||
* (tracking, cockpit, orbit, a fly-to) do not. Below the disc's height they
|
||||
* rest too. While they run they never hold
|
||||
* continuous rendering; each drawn frame arms one more request after the
|
||||
* Cyber sonar's 80 ms cadence, so the two never beat. When something else
|
||||
* already renders continuously they update every frame. Skipped under
|
||||
* prefers-reduced-motion. */
|
||||
export const AWARENESS_RANGE_PULSE = Object.freeze({
|
||||
count: 3,
|
||||
periodMs: 9000,
|
||||
startFraction: 0.02,
|
||||
fadeInFraction: 0.08,
|
||||
fadeOutPower: 1.5,
|
||||
endOpacityFraction: 0.35,
|
||||
peakOpacity: 0.6,
|
||||
width: 3,
|
||||
outlineWidth: 1,
|
||||
gradientDepthFraction: 0.35,
|
||||
gradientOpacity: 0.22,
|
||||
gradientGranularityDeg: 0.25,
|
||||
gradientRebuildM: 20000,
|
||||
activeMs: 9000,
|
||||
settleMs: 1200,
|
||||
inputWakeMs: 1500,
|
||||
});
|
||||
|
||||
/** @constant Sonar echoes on contact brackets. When a pulse front reaches a
|
||||
* flight, military aircraft or AIS vessel in the window, the detection
|
||||
* overlay draws a second bracket in `color` around that contact's own
|
||||
* bracket. It starts on the bracket and spreads outward by up to `spreadPx`
|
||||
* as it fades over `fadeMs`, so the frame pulses. Only `layerIds` echo;
|
||||
* mapped installations have no detection bracket. */
|
||||
export const AWARENESS_RANGE_ECHO = Object.freeze({
|
||||
layerIds: ['flights', 'military', 'ais-live-vessels'],
|
||||
fadeMs: 1400,
|
||||
color: 'rgb(98, 181, 255)',
|
||||
spreadPx: 8,
|
||||
lineWidth: 1.75,
|
||||
});
|
||||
|
||||
export const VESSEL_FOCUS_RADIUS_M = 3000;
|
||||
|
||||
export const SOURCE_LABEL = {
|
||||
|
||||
@@ -91,6 +91,7 @@ export function createQueries({ state: layerState, services, parts, source }) {
|
||||
stats.count ?? null,
|
||||
stats.status || null,
|
||||
stats.error || null,
|
||||
stats.source || null,
|
||||
];
|
||||
})
|
||||
.map((parts) => parts.join(':'))
|
||||
|
||||
@@ -81,3 +81,29 @@ test('Contacts excludes square corners and measures from the current moving subj
|
||||
assert.equal(moved.reason, 'mapped matches within 100 km of the subject');
|
||||
assert.deepEqual(installationState.contextAnchor, { latitude: 0, longitude: 0 });
|
||||
});
|
||||
|
||||
test('Contacts cohorts carry the provider and whether it answered as a fallback or stale', () => {
|
||||
const services = { installations: { getNearby: () => [], getStats: () => ({}) },
|
||||
flights: { getNearby: () => [] }, military: { getNearby: () => [] }, vessels: { getNearby: () => [] } };
|
||||
const parts = { navigation: { summarizeAwarenessCohortForNavigation: (items, source) =>
|
||||
summarizeAwarenessCohort(items, source) } };
|
||||
parts.queries = createQueries({ state: {}, services, parts });
|
||||
const subjectOwner = createSubject({ state: {}, services, parts });
|
||||
const states = {
|
||||
// The OpenSky proxy answers from adsb.lol when OpenSky fails.
|
||||
flights: { available: true, stats: { source: 'adsb.lol', coverage: '250nm regional fallback', count: 4, lastUpdate: 1 } },
|
||||
military: { available: true, stats: { source: 'adsb.lol', fallback: false, count: 2, lastUpdate: 1 } },
|
||||
'ais-live-vessels': { available: true, stats: { source: 'Datalastic', stale: true, count: 3, lastUpdate: 1 } },
|
||||
'military-installations': { available: true, stats: { coverage: { kind: 'subject', radiusM: 100000 } } },
|
||||
};
|
||||
const { cohorts } = subjectOwner.evaluateSubject({
|
||||
id: 'subject', layerId: 'flights', position: Cesium.Cartesian3.fromDegrees(0, 0, 10000),
|
||||
}, states);
|
||||
const byId = Object.fromEntries(cohorts.map((cohort) => [cohort.id, cohort]));
|
||||
assert.equal(byId.flights.source, 'adsb.lol');
|
||||
assert.equal(byId.flights.sourceStatus, 'fallback');
|
||||
assert.equal(byId.military.sourceStatus, null);
|
||||
assert.equal(byId['ais-live-vessels'].source, 'Datalastic');
|
||||
assert.equal(byId['ais-live-vessels'].sourceStatus, 'stale');
|
||||
assert.equal(byId['military-installations'].sourceStatus, null);
|
||||
});
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,6 +1,7 @@
|
||||
import * as Cesium from 'cesium';
|
||||
import { t } from '../../i18n/index.js';
|
||||
import {
|
||||
CYBER_SONAR_RENDER_INTERVAL_MS,
|
||||
createCyberSonarSampler,
|
||||
isCyberContactSonarActive as isCyberSonarActive,
|
||||
} from '../../cyberSonar.js';
|
||||
@@ -10,8 +11,339 @@ import {
|
||||
AWARENESS_RADIUS_M,
|
||||
} from '../../data/militaryAwarenessEngine.js';
|
||||
import { bearingBetweenCoordinates } from '../../cockpitMath.js';
|
||||
import { AWARENESS_PAGE_SIZE, CONTEXT_RIM_HEIGHT_M } from './policy.js';
|
||||
import {
|
||||
AWARENESS_PAGE_SIZE,
|
||||
AWARENESS_RANGE_ECHO,
|
||||
AWARENESS_RANGE_PULSE,
|
||||
AWARENESS_RANGE_RING_STYLE,
|
||||
CONTEXT_RIM_HEIGHT_M,
|
||||
} from './policy.js';
|
||||
import { formatAwarenessDirection } from './presentation.js';
|
||||
import {
|
||||
awarenessEchoStrength,
|
||||
clearAwarenessEchoField,
|
||||
setAwarenessEchoField,
|
||||
} from '../../awarenessEcho.js';
|
||||
|
||||
/**
|
||||
* A closed ring of positions `radiusM` along the surface from `groundCenter`,
|
||||
* raised to `heightM`. Each bearing steps over a sphere with the ellipsoid's
|
||||
* radius of curvature in that direction (Euler's formula), which keeps the
|
||||
* ring within ~50 m of the true geodesic radius at 250 km.
|
||||
* @param {Cesium.Cartesian3} groundCenter Ring centre on the ellipsoid.
|
||||
* @param {number} radiusM Surface radius in metres.
|
||||
* @param {number} heightM Height of the ring above the ellipsoid.
|
||||
* @param {number} [segments] Chords around the ring.
|
||||
* @returns {Cesium.Cartesian3[]} `segments + 1` positions; the last repeats the first.
|
||||
*/
|
||||
export function awarenessRangeRingPositions(
|
||||
groundCenter,
|
||||
radiusM,
|
||||
heightM,
|
||||
segments = AWARENESS_RANGE_RING_STYLE.segments,
|
||||
) {
|
||||
const { latitude, longitude } =
|
||||
Cesium.Cartographic.fromCartesian(groundCenter);
|
||||
const { x: a, z: b } = Cesium.Ellipsoid.WGS84.radii;
|
||||
const e2 = 1 - (b * b) / (a * a);
|
||||
const sinLat = Math.sin(latitude);
|
||||
const cosLat = Math.cos(latitude);
|
||||
const sinLon = Math.sin(longitude);
|
||||
const cosLon = Math.cos(longitude);
|
||||
const w = 1 - e2 * sinLat * sinLat;
|
||||
const meridional = (a * (1 - e2)) / (w * Math.sqrt(w));
|
||||
const primeVertical = a / Math.sqrt(w);
|
||||
// Step along the great circle in 3D from the centre's up, north and east
|
||||
// unit vectors. Unlike the latitude/longitude destination formula, this
|
||||
// stays well conditioned at and next to the poles.
|
||||
const up = [cosLat * cosLon, cosLat * sinLon, sinLat];
|
||||
const north = [-sinLat * cosLon, -sinLat * sinLon, cosLat];
|
||||
const east = [-sinLon, cosLon, 0];
|
||||
const positions = [];
|
||||
for (let i = 0; i <= segments; i++) {
|
||||
const bearing = ((i % segments) / segments) * Cesium.Math.TWO_PI;
|
||||
const cosB = Math.cos(bearing);
|
||||
const sinB = Math.sin(bearing);
|
||||
const angular =
|
||||
radiusM * ((cosB * cosB) / meridional + (sinB * sinB) / primeVertical);
|
||||
const cosA = Math.cos(angular);
|
||||
const sinA = Math.sin(angular);
|
||||
const [x, y, z] = up.map(
|
||||
(u, k) => u * cosA + (north[k] * cosB + east[k] * sinB) * sinA,
|
||||
);
|
||||
const lat = Math.atan2(z, Math.hypot(x, y));
|
||||
const lon = Math.atan2(y, x);
|
||||
positions.push(Cesium.Cartesian3.fromRadians(lon, lat, heightM));
|
||||
}
|
||||
return positions;
|
||||
}
|
||||
|
||||
/**
|
||||
* Where pulse `index` is at `nowMs`: its radius and opacity. Pulses travel at
|
||||
* constant speed from `startFraction` of the range to the full range, fade in
|
||||
* over `fadeInFraction` of the way, then fade as (1 - travel) to the
|
||||
* `fadeOutPower` down to `endOpacityFraction` of the peak, so each is dim
|
||||
* but still visible when it reaches the range ring. The opacity already
|
||||
* includes `peakOpacity`.
|
||||
* @param {number} nowMs Monotonic clock in milliseconds.
|
||||
* @param {number} index Pulse number, 0 to `count - 1`.
|
||||
* @param {number} [radiusM] Range the pulses grow to.
|
||||
* @param {object} [pulse] Timing and shape, see `AWARENESS_RANGE_PULSE`.
|
||||
* @returns {{radiusM: number, alpha: number}}
|
||||
*/
|
||||
export function awarenessPulseState(
|
||||
nowMs,
|
||||
index,
|
||||
radiusM = AWARENESS_RADIUS_M,
|
||||
pulse = AWARENESS_RANGE_PULSE,
|
||||
) {
|
||||
const cycle = nowMs / pulse.periodMs + index / pulse.count;
|
||||
const phase = cycle - Math.floor(cycle);
|
||||
return {
|
||||
radiusM:
|
||||
radiusM * (pulse.startFraction + (1 - pulse.startFraction) * phase),
|
||||
alpha:
|
||||
pulse.peakOpacity *
|
||||
Math.min(1, phase / pulse.fadeInFraction) *
|
||||
(pulse.endOpacityFraction +
|
||||
(1 - pulse.endOpacityFraction) * (1 - phase) ** pulse.fadeOutPower),
|
||||
};
|
||||
}
|
||||
|
||||
const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
|
||||
|
||||
/** Whether the viewer asked the system for less motion. */
|
||||
function prefersReducedMotion() {
|
||||
return globalThis.matchMedia?.(REDUCED_MOTION_QUERY)?.matches ?? false;
|
||||
}
|
||||
|
||||
/**
|
||||
* How far the pulses are switched on at `nowMs`: 0 at rest, rising to 1 over
|
||||
* `settleMs` from `wake.startMs` and falling back to 0 over `settleMs` up to
|
||||
* `wake.untilMs`.
|
||||
* @param {number} nowMs Monotonic clock in milliseconds.
|
||||
* @param {{startMs: number, untilMs: number}} wake Window from `wakeAwarenessPulses`.
|
||||
* @param {object} [pulse] Timing, see `AWARENESS_RANGE_PULSE`.
|
||||
* @returns {number} 0 to 1.
|
||||
*/
|
||||
export function awarenessPulseLevel(
|
||||
nowMs,
|
||||
wake,
|
||||
pulse = AWARENESS_RANGE_PULSE,
|
||||
) {
|
||||
const level = Math.min(
|
||||
(nowMs - wake.startMs) / pulse.settleMs,
|
||||
(wake.untilMs - nowMs) / pulse.settleMs,
|
||||
);
|
||||
return Math.max(0, Math.min(1, level));
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the pulses for `activeMs` from `nowMs`. A wake while they already run
|
||||
* keeps their current level, so they never jump back to full mid-fade.
|
||||
* @param {{startMs: number, untilMs: number}} wake Updated in place.
|
||||
* @param {number} nowMs Monotonic clock in milliseconds.
|
||||
* @param {object} [pulse] Timing, see `AWARENESS_RANGE_PULSE`.
|
||||
* @returns {{startMs: number, untilMs: number}} `wake`.
|
||||
*/
|
||||
export function wakeAwarenessPulses(
|
||||
wake,
|
||||
nowMs,
|
||||
pulse = AWARENESS_RANGE_PULSE,
|
||||
) {
|
||||
wake.startMs =
|
||||
nowMs - awarenessPulseLevel(nowMs, wake, pulse) * pulse.settleMs;
|
||||
wake.untilMs = nowMs + pulse.activeMs;
|
||||
return wake;
|
||||
}
|
||||
|
||||
/**
|
||||
* How strongly the 250 km ring shows at `nowMs` while pulses run: 1 as a
|
||||
* pulse front reaches it, fading over `flashMs`, so the ring appears once
|
||||
* per arriving pulse instead of standing on screen.
|
||||
* @param {number} nowMs Monotonic clock in milliseconds.
|
||||
* @returns {number} 0 to 1.
|
||||
*/
|
||||
export function awarenessRingFlash(nowMs) {
|
||||
return awarenessEchoStrength(
|
||||
nowMs,
|
||||
AWARENESS_RADIUS_M,
|
||||
AWARENESS_RADIUS_M,
|
||||
AWARENESS_RANGE_PULSE,
|
||||
{ fadeMs: AWARENESS_RANGE_RING_STYLE.flashMs },
|
||||
);
|
||||
}
|
||||
|
||||
/** Most pulses the pulse shader draws; its uniforms are vec4s. */
|
||||
export const AWARENESS_PULSE_GRADIENT_MAX = 4;
|
||||
|
||||
/** The pulse disc's Cesium material type, one cached template per page. */
|
||||
const AWARENESS_PULSE_MATERIAL_TYPE = 'GevAwarenessPulseGradient';
|
||||
|
||||
// Ellipse texture coordinates put the centre at (0.5, 0.5) and the rim at
|
||||
// distance 0.5, so `r` is the fraction of the range. Each pulse is a line
|
||||
// `lineWidth` CSS pixels wide whose outer `haloWidth` is a dark halo, half
|
||||
// on each side, as Cesium's polyline outline material draws it, with a band
|
||||
// behind it that is strongest at the line and fades to nothing `depth`
|
||||
// inward. Widths come from the screen-space gradient of `r`, as Cesium's
|
||||
// contour material measures its lines; without derivatives the lines are
|
||||
// left out and only the band shows.
|
||||
const PULSE_GRADIENT_SOURCE = `
|
||||
uniform vec4 color;
|
||||
uniform vec4 lineColor;
|
||||
uniform vec4 haloColor;
|
||||
uniform vec4 radii;
|
||||
uniform vec4 alphas;
|
||||
uniform float depth;
|
||||
uniform float lineWidth;
|
||||
uniform float haloWidth;
|
||||
vec4 over(vec4 top, vec4 under) {
|
||||
float a = top.a + under.a * (1.0 - top.a);
|
||||
if (a <= 0.0) return vec4(0.0);
|
||||
return vec4((top.rgb * top.a + under.rgb * under.a * (1.0 - top.a)) / a, a);
|
||||
}
|
||||
czm_material czm_getMaterial(czm_materialInput materialInput) {
|
||||
czm_material material = czm_getDefaultMaterial(materialInput);
|
||||
float r = length(materialInput.st - vec2(0.5)) * 2.0;
|
||||
float band = 0.0;
|
||||
for (int i = 0; i < 4; i++) {
|
||||
float inside = radii[i] - r;
|
||||
if (inside >= 0.0 && inside <= depth) {
|
||||
float t = 1.0 - inside / depth;
|
||||
band += alphas[i] * t * t;
|
||||
}
|
||||
}
|
||||
vec4 result = vec4(color.rgb, clamp(band * color.a, 0.0, 1.0));
|
||||
#if (__VERSION__ == 300 || defined(GL_OES_standard_derivatives))
|
||||
// Change in r per CSS pixel: the gradient's length per device pixel,
|
||||
// times the device pixels in one CSS pixel.
|
||||
float cssPx = max(length(vec2(dFdx(r), dFdy(r))), 1e-7) * czm_pixelRatio;
|
||||
float outerHalf = lineWidth * 0.5;
|
||||
float coreHalf = max(lineWidth - haloWidth, 0.0) * 0.5;
|
||||
for (int i = 0; i < 4; i++) {
|
||||
float d = abs(radii[i] - r) / cssPx;
|
||||
float cover = clamp(outerHalf + 0.5 - d, 0.0, 1.0);
|
||||
if (cover <= 0.0) continue;
|
||||
float core = clamp(coreHalf + 0.5 - d, 0.0, 1.0);
|
||||
vec4 pulse = mix(haloColor, lineColor, core);
|
||||
result = over(vec4(pulse.rgb, pulse.a * cover * alphas[i]), result);
|
||||
}
|
||||
#endif
|
||||
material.diffuse = result.rgb;
|
||||
material.alpha = result.a;
|
||||
return material;
|
||||
}
|
||||
`;
|
||||
|
||||
/**
|
||||
* The pulses: one flat, translucent, unpickable disc the size of the range
|
||||
* ring whose shader draws each pulse line and the band behind it. Drawing
|
||||
* them here rather than as entities keeps them out of picking, so clicks and
|
||||
* taps near a pulse still reach the contact underneath. Moving pulses only
|
||||
* change its uniforms; the disc is rebuilt only when the subject moves.
|
||||
* @param {Cesium.Cartesian3} groundCenter Disc centre on the ellipsoid.
|
||||
* @param {Cesium.Material} material Shared pulse-gradient material.
|
||||
* @returns {Cesium.Primitive}
|
||||
*/
|
||||
function createPulseGradient(groundCenter, material) {
|
||||
return new Cesium.Primitive({
|
||||
geometryInstances: new Cesium.GeometryInstance({
|
||||
geometry: new Cesium.EllipseGeometry({
|
||||
center: groundCenter,
|
||||
semiMajorAxis: AWARENESS_RADIUS_M,
|
||||
semiMinorAxis: AWARENESS_RADIUS_M,
|
||||
height: CONTEXT_RIM_HEIGHT_M,
|
||||
granularity: Cesium.Math.toRadians(
|
||||
AWARENESS_RANGE_PULSE.gradientGranularityDeg,
|
||||
),
|
||||
vertexFormat:
|
||||
Cesium.MaterialAppearance.MaterialSupport.TEXTURED.vertexFormat,
|
||||
}),
|
||||
}),
|
||||
appearance: new Cesium.MaterialAppearance({
|
||||
material,
|
||||
flat: true,
|
||||
translucent: true,
|
||||
faceForward: true,
|
||||
}),
|
||||
asynchronous: false,
|
||||
allowPicking: false,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* The ring's polyline geometry: `AWARENESS_RANGE_RING_STYLE.width` screen
|
||||
* pixels, straight chords between the given positions (they already follow
|
||||
* the surface), in the material appearance's vertex format.
|
||||
* @param {Cesium.Cartesian3[]} positions Ring positions.
|
||||
* @returns {object} PolylineGeometry options.
|
||||
*/
|
||||
export function awarenessRingGeometryOptions(positions) {
|
||||
return {
|
||||
positions,
|
||||
width: AWARENESS_RANGE_RING_STYLE.width,
|
||||
arcType: Cesium.ArcType.NONE,
|
||||
vertexFormat: Cesium.PolylineMaterialAppearance.VERTEX_FORMAT,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The 250 km ring as an unpickable polyline primitive in the ring's outline
|
||||
* material, so a click or tap on its edge reaches the contact underneath.
|
||||
* Its positions are geometry, so a moved subject rebuilds it; the material
|
||||
* is shared between builds so a flash keeps going.
|
||||
* @param {Cesium.Cartesian3[]} positions Ring positions.
|
||||
* @param {Cesium.Material} material Shared PolylineOutline material.
|
||||
* @returns {Cesium.Primitive}
|
||||
*/
|
||||
function createRingPrimitive(positions, material) {
|
||||
return new Cesium.Primitive({
|
||||
geometryInstances: new Cesium.GeometryInstance({
|
||||
geometry: new Cesium.PolylineGeometry(
|
||||
awarenessRingGeometryOptions(positions),
|
||||
),
|
||||
}),
|
||||
appearance: new Cesium.PolylineMaterialAppearance({
|
||||
material,
|
||||
translucent: true,
|
||||
}),
|
||||
asynchronous: false,
|
||||
allowPicking: false,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* The rotation about the Earth's centre that carries `from` onto `to`, as a
|
||||
* model matrix, so a disc built around `from` sits around `to`.
|
||||
* @param {Cesium.Cartesian3} from Where the disc was built.
|
||||
* @param {Cesium.Cartesian3} to Where it should be.
|
||||
* @param {Cesium.Matrix4} [result]
|
||||
* @returns {Cesium.Matrix4}
|
||||
*/
|
||||
export function discFollowMatrix(from, to, result = new Cesium.Matrix4()) {
|
||||
const a = Cesium.Cartesian3.normalize(from, new Cesium.Cartesian3());
|
||||
const b = Cesium.Cartesian3.normalize(to, new Cesium.Cartesian3());
|
||||
const axis = Cesium.Cartesian3.cross(a, b, new Cesium.Cartesian3());
|
||||
const sin = Cesium.Cartesian3.magnitude(axis);
|
||||
if (sin < 1e-12) return Cesium.Matrix4.clone(Cesium.Matrix4.IDENTITY, result);
|
||||
const angle = Math.atan2(sin, Cesium.Cartesian3.dot(a, b));
|
||||
const rotation = Cesium.Matrix3.fromQuaternion(
|
||||
Cesium.Quaternion.fromAxisAngle(
|
||||
Cesium.Cartesian3.divideByScalar(axis, sin, axis),
|
||||
angle,
|
||||
),
|
||||
);
|
||||
return Cesium.Matrix4.fromRotationTranslation(
|
||||
rotation,
|
||||
Cesium.Cartesian3.ZERO,
|
||||
result,
|
||||
);
|
||||
}
|
||||
|
||||
/** Camera height above the ellipsoid, or NaN when the scene cannot say. */
|
||||
function cameraHeightM(scene) {
|
||||
return scene.camera?.positionCartographic?.height ?? Number.NaN;
|
||||
}
|
||||
|
||||
export function createRendering({
|
||||
state: layerState,
|
||||
@@ -271,7 +603,62 @@ export function createRendering({
|
||||
presentDirection({ hidden: false, ring, heading, labels, markers });
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the range pulses again for `activeMs`, after a camera move. Call it
|
||||
* during a frame (lifecycle's preRender): that frame's postRender arms the
|
||||
* next request, so waking asks for no extra frame of its own.
|
||||
*/
|
||||
function wakePulses() {
|
||||
const wake = layerState.visual?.wake;
|
||||
if (!wake) return;
|
||||
wakeAwarenessPulses(wake, performance.now());
|
||||
followPulseDisc();
|
||||
}
|
||||
|
||||
/**
|
||||
* Keep the pulse disc centred on the subject. Within `gradientRebuildM` of
|
||||
* where it was built, the disc is rotated about the Earth's centre onto
|
||||
* the subject by its model matrix, which keeps it concentric with the ring
|
||||
* at no build cost; the ellipsoid curves a little differently from that
|
||||
* sphere, a few tens of metres in height at 20 km. Further away it is
|
||||
* rebuilt, which costs a few milliseconds.
|
||||
*/
|
||||
function followPulseDisc() {
|
||||
const { gradient, gradientCenter, center } = layerState.visual;
|
||||
if (!gradient) return;
|
||||
if (
|
||||
Cesium.Cartesian3.distance(gradientCenter, center) <
|
||||
AWARENESS_RANGE_PULSE.gradientRebuildM
|
||||
) {
|
||||
gradient.modelMatrix = discFollowMatrix(
|
||||
gradientCenter,
|
||||
center,
|
||||
gradient.modelMatrix,
|
||||
);
|
||||
return;
|
||||
}
|
||||
const primitives = layerState.viewer.scene.primitives;
|
||||
layerState.visual.gradient = primitives.add(
|
||||
createPulseGradient(center, gradient.appearance.material),
|
||||
);
|
||||
// Primitive.destroy leaves the material alone, so the new disc keeps
|
||||
// sharing it.
|
||||
primitives.remove(gradient);
|
||||
Cesium.Cartesian3.clone(center, gradientCenter);
|
||||
}
|
||||
|
||||
function clearVisual() {
|
||||
layerState.visual?.stopPulses?.();
|
||||
layerState.visual?.removeMotionListener?.();
|
||||
if (layerState.visual?.gradient && layerState.viewer)
|
||||
layerState.viewer.scene.primitives.remove(layerState.visual.gradient);
|
||||
if (layerState.visual?.ringPrimitive && layerState.viewer) {
|
||||
layerState.viewer.scene.primitives.remove?.(
|
||||
layerState.visual.ringPrimitive,
|
||||
);
|
||||
governorRequestRender('awareness-visual');
|
||||
}
|
||||
clearAwarenessEchoField();
|
||||
if (layerState.visual?.entities && layerState.viewer) {
|
||||
for (const entity of layerState.visual.entities)
|
||||
layerState.viewer.entities.remove(entity);
|
||||
@@ -291,17 +678,39 @@ export function createRendering({
|
||||
0,
|
||||
);
|
||||
const key = `${subject.layerId}:${subject.id}`;
|
||||
if (layerState.visual?.key === key) {
|
||||
// Large ellipse geometry is more reliable as a ConstantPositionProperty.
|
||||
// Move it only after a meaningful displacement so live tracking does not
|
||||
// churn ten large geometries for sub-pixel motion every 750 ms.
|
||||
const reducedMotion = prefersReducedMotion();
|
||||
// A reduced-motion change rebuilds the visual, with or without pulses.
|
||||
if (
|
||||
layerState.visual?.key === key &&
|
||||
layerState.visual.reducedMotion === reducedMotion
|
||||
) {
|
||||
// Move the ring only after a meaningful displacement so live tracking
|
||||
// does not rebuild its geometry for sub-pixel motion every 750 ms.
|
||||
if (
|
||||
Cesium.Cartesian3.distance(layerState.visual.center, groundCenter) >=
|
||||
250
|
||||
) {
|
||||
for (const entity of layerState.visual.entities)
|
||||
entity.position.setValue(groundCenter);
|
||||
const positions = awarenessRangeRingPositions(
|
||||
groundCenter,
|
||||
AWARENESS_RADIUS_M,
|
||||
CONTEXT_RIM_HEIGHT_M,
|
||||
);
|
||||
// The echo field reads `visual.center` in place and follows on its
|
||||
// own. The pulse disc follows by its model matrix and is rebuilt only
|
||||
// every `gradientRebuildM`: a build costs a few milliseconds.
|
||||
layerState.visual.ringPositions = positions;
|
||||
const { ringPrimitive } = layerState.visual;
|
||||
if (ringPrimitive) {
|
||||
const primitives = layerState.viewer.scene.primitives;
|
||||
layerState.visual.ringPrimitive = primitives.add(
|
||||
createRingPrimitive(positions, ringPrimitive.appearance.material),
|
||||
);
|
||||
primitives.remove(ringPrimitive);
|
||||
} else layerState.visual.ring.polyline.positions.setValue(positions);
|
||||
Cesium.Cartesian3.clone(groundCenter, layerState.visual.center);
|
||||
// A resting disc is hidden, so it catches up when the pulses wake.
|
||||
if (performance.now() < layerState.visual.wake?.untilMs)
|
||||
followPulseDisc();
|
||||
// Content actually changed — buy exactly one frame instead of holding.
|
||||
governorRequestRender('awareness-visual');
|
||||
}
|
||||
@@ -310,26 +719,188 @@ export function createRendering({
|
||||
clearVisual();
|
||||
|
||||
const entities = [];
|
||||
|
||||
entities.push(
|
||||
layerState.viewer.entities.add({
|
||||
position: groundCenter,
|
||||
ellipse: {
|
||||
semiMajorAxis: AWARENESS_RADIUS_M,
|
||||
semiMinorAxis: AWARENESS_RADIUS_M,
|
||||
fill: false,
|
||||
outline: true,
|
||||
outlineColor:
|
||||
Cesium.Color.fromCssColorString('#62b5ff').withAlpha(0.72),
|
||||
height: CONTEXT_RIM_HEIGHT_M,
|
||||
},
|
||||
}),
|
||||
const scene = layerState.viewer.scene;
|
||||
// A viewer without a primitive collection or a preRender hook (headless
|
||||
// tools, partial stubs) gets the static ring only, as the Cyber sonar
|
||||
// scene does. So does a viewer who prefers reduced motion.
|
||||
const animate = Boolean(
|
||||
!reducedMotion &&
|
||||
scene?.primitives?.add &&
|
||||
scene?.preRender?.addEventListener &&
|
||||
scene?.postRender?.addEventListener,
|
||||
);
|
||||
// Pulses run from now until `wake.untilMs`, then rest.
|
||||
const wake = animate
|
||||
? wakeAwarenessPulses(
|
||||
{ startMs: -Infinity, untilMs: -Infinity },
|
||||
performance.now(),
|
||||
)
|
||||
: null;
|
||||
// From a camera below the rim height the disc would sweep across the sky,
|
||||
// so it is hidden there, and the pulses rest with it: no flash, no
|
||||
// echoes, no frames.
|
||||
const belowRim = () => cameraHeightM(scene) < CONTEXT_RIM_HEIGHT_M;
|
||||
const levelAt = (nowMs) =>
|
||||
wake && !belowRim() ? awarenessPulseLevel(nowMs, wake) : 0;
|
||||
|
||||
// A polyline, not an ellipse outline: WebGL draws ellipse outlines at
|
||||
// 1 px whatever `outlineWidth` says, and the ring needs a halo.
|
||||
const ring = AWARENESS_RANGE_RING_STYLE;
|
||||
const core = Cesium.Color.fromCssColorString(ring.color);
|
||||
const halo = Cesium.Color.fromCssColorString(ring.outlineColor);
|
||||
const ringPositions = awarenessRangeRingPositions(
|
||||
groundCenter,
|
||||
AWARENESS_RADIUS_M,
|
||||
CONTEXT_RIM_HEIGHT_M,
|
||||
);
|
||||
// While pulses run, the ring flashes as each one arrives and otherwise
|
||||
// dims to `restOpacity`; as they settle it returns to full and stays.
|
||||
const ringAlpha = (nowMs) => {
|
||||
const pulsed = Math.max(ring.restOpacity, awarenessRingFlash(nowMs));
|
||||
return 1 - levelAt(nowMs) * (1 - pulsed);
|
||||
};
|
||||
let ringEntity = null;
|
||||
let ringMaterial = null;
|
||||
let ringPrimitive = null;
|
||||
if (scene?.primitives?.add) {
|
||||
ringMaterial = Cesium.Material.fromType('PolylineOutline', {
|
||||
color: core.clone(),
|
||||
outlineColor: halo.clone(),
|
||||
outlineWidth: ring.outlineWidth,
|
||||
});
|
||||
ringPrimitive =
|
||||
scene.primitives.add(
|
||||
createRingPrimitive(ringPositions, ringMaterial),
|
||||
) ?? null;
|
||||
}
|
||||
if (!ringPrimitive) {
|
||||
// Headless tools and partial stubs have no primitive collection; they
|
||||
// get the static ring as an entity.
|
||||
ringEntity = layerState.viewer.entities.add({
|
||||
polyline: {
|
||||
positions: new Cesium.ConstantProperty(ringPositions),
|
||||
width: ring.width,
|
||||
arcType: Cesium.ArcType.NONE,
|
||||
material: new Cesium.PolylineOutlineMaterialProperty({
|
||||
color: core,
|
||||
outlineColor: halo,
|
||||
outlineWidth: ring.outlineWidth,
|
||||
}),
|
||||
},
|
||||
});
|
||||
entities.push(ringEntity);
|
||||
}
|
||||
|
||||
const center = Cesium.Cartesian3.clone(groundCenter);
|
||||
let gradient = null;
|
||||
let stopPulses = null;
|
||||
if (animate) {
|
||||
const pulse = AWARENESS_RANGE_PULSE;
|
||||
const count = Math.min(pulse.count, AWARENESS_PULSE_GRADIENT_MAX);
|
||||
const uniforms = {
|
||||
color: core.clone(),
|
||||
lineColor: core.clone(),
|
||||
haloColor: halo.clone(),
|
||||
radii: new Cesium.Cartesian4(),
|
||||
alphas: new Cesium.Cartesian4(),
|
||||
depth: pulse.gradientDepthFraction,
|
||||
lineWidth: pulse.width,
|
||||
haloWidth: pulse.outlineWidth,
|
||||
};
|
||||
uniforms.color.alpha = pulse.gradientOpacity;
|
||||
// A named type: Cesium caches every material type for the page's
|
||||
// lifetime, so an unnamed fabric (a fresh GUID each time) would leave
|
||||
// one entry per new visual. Built from the cached template, the
|
||||
// uniforms come back as plain copies; restore this visual's own.
|
||||
const material = new Cesium.Material({
|
||||
fabric: {
|
||||
type: AWARENESS_PULSE_MATERIAL_TYPE,
|
||||
uniforms,
|
||||
source: PULSE_GRADIENT_SOURCE,
|
||||
},
|
||||
translucent: true,
|
||||
});
|
||||
Object.assign(material.uniforms, uniforms);
|
||||
gradient = scene.primitives.add(
|
||||
createPulseGradient(groundCenter, material),
|
||||
);
|
||||
const radii = [0, 0, 0, 0];
|
||||
const alphas = [0, 0, 0, 0];
|
||||
const removePreRender = scene.preRender.addEventListener(() => {
|
||||
const nowMs = performance.now();
|
||||
const level = levelAt(nowMs);
|
||||
const alpha = ringAlpha(nowMs);
|
||||
ringMaterial.uniforms.color.alpha = core.alpha * alpha;
|
||||
ringMaterial.uniforms.outlineColor.alpha = halo.alpha * alpha;
|
||||
// The disc is looked up each frame: a subject move swaps it.
|
||||
const disc = layerState.visual?.gradient;
|
||||
if (disc) disc.show = level > 0;
|
||||
for (let index = 0; index < count; index++) {
|
||||
const state = awarenessPulseState(nowMs, index);
|
||||
radii[index] = state.radiusM / AWARENESS_RADIUS_M;
|
||||
alphas[index] = state.alpha * level;
|
||||
}
|
||||
Cesium.Cartesian4.fromArray(radii, 0, material.uniforms.radii);
|
||||
Cesium.Cartesian4.fromArray(alphas, 0, material.uniforms.alphas);
|
||||
});
|
||||
// Each drawn frame, whoever asked for it, arms one request a Cyber
|
||||
// sonar interval later, as the Cyber sonar scene does. Requests never
|
||||
// land within 80 ms of a frame, so they cannot beat the detection
|
||||
// lane's 80 ms gate, and they stop once the pulses rest.
|
||||
let timer = null;
|
||||
const removePostRender = scene.postRender.addEventListener(() => {
|
||||
globalThis.clearTimeout(timer);
|
||||
timer = null;
|
||||
if (performance.now() < wake.untilMs && !belowRim())
|
||||
timer = globalThis.setTimeout(() => {
|
||||
timer = null;
|
||||
governorRequestRender('awareness-pulse');
|
||||
}, CYBER_SONAR_RENDER_INTERVAL_MS);
|
||||
});
|
||||
stopPulses = () => {
|
||||
removePreRender();
|
||||
removePostRender();
|
||||
globalThis.clearTimeout(timer);
|
||||
timer = null;
|
||||
};
|
||||
// The detection overlay pulses the brackets of flights and vessels a
|
||||
// front crosses; it reads the centre in place, so it follows too.
|
||||
setAwarenessEchoField({
|
||||
center,
|
||||
radiusM: AWARENESS_RADIUS_M,
|
||||
pulse,
|
||||
echo: AWARENESS_RANGE_ECHO,
|
||||
level: levelAt,
|
||||
});
|
||||
}
|
||||
|
||||
// Turning reduced motion on or off mid-session rebuilds the visual.
|
||||
const motionQuery = globalThis.matchMedia?.(REDUCED_MOTION_QUERY);
|
||||
const onMotionChange = () => {
|
||||
if (layerState.subject) renderVisual(layerState.subject);
|
||||
};
|
||||
// Safari before 14 has only the older addListener / removeListener.
|
||||
if (motionQuery?.addEventListener)
|
||||
motionQuery.addEventListener('change', onMotionChange);
|
||||
else motionQuery?.addListener?.(onMotionChange);
|
||||
|
||||
layerState.visual = {
|
||||
key,
|
||||
entities,
|
||||
center: Cesium.Cartesian3.clone(groundCenter),
|
||||
ring: ringEntity,
|
||||
ringPrimitive,
|
||||
ringPositions,
|
||||
center,
|
||||
gradient,
|
||||
gradientCenter: Cesium.Cartesian3.clone(groundCenter),
|
||||
reducedMotion,
|
||||
wake,
|
||||
stopPulses,
|
||||
removeMotionListener: () => {
|
||||
if (motionQuery?.removeEventListener)
|
||||
motionQuery.removeEventListener('change', onMotionChange);
|
||||
else motionQuery?.removeListener?.(onMotionChange);
|
||||
},
|
||||
};
|
||||
governorRequestRender('awareness-visual');
|
||||
}
|
||||
@@ -343,5 +914,6 @@ export function createRendering({
|
||||
updateDirectionOverlay,
|
||||
clearVisual,
|
||||
renderVisual,
|
||||
wakePulses,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,159 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import * as Cesium from 'cesium';
|
||||
import { createQueries } from './queries.js';
|
||||
import { createSubject } from './subject.js';
|
||||
import { createModel } from './model.js';
|
||||
import { summarizeAwarenessCohort } from '../../data/militaryAwarenessEngine.js';
|
||||
import { layerFeedState } from '../../data/feedState.js';
|
||||
import aisLiveVesselsLayer, {
|
||||
_setVesselStateForTest,
|
||||
_beginAisSessionForTest,
|
||||
_applyAisFeedSnapshotForTest,
|
||||
_setAisRuntimeForTest,
|
||||
} from '../../data/aisLiveVessels.js';
|
||||
|
||||
test('a poll that returns the same stale AIS snapshot restores STALE on Contacts cohorts', () => {
|
||||
globalThis.document ??= { body: null };
|
||||
const services = {
|
||||
installations: { getNearby: () => [], getStats: () => ({}) },
|
||||
flights: { getNearby: () => [] },
|
||||
military: { getNearby: () => [] },
|
||||
vessels: { getNearby: () => [] },
|
||||
};
|
||||
const layerState = {
|
||||
enabled: true,
|
||||
passive: true,
|
||||
sourceRevision: '',
|
||||
cohortPages: new Map(),
|
||||
subject: {
|
||||
id: 'site-1',
|
||||
layerId: 'military-installations',
|
||||
label: 'Site',
|
||||
position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
|
||||
},
|
||||
};
|
||||
let states;
|
||||
const parts = {
|
||||
navigation: {
|
||||
summarizeAwarenessCohortForNavigation: (items, source) =>
|
||||
summarizeAwarenessCohort(items, source),
|
||||
isFlightLayer: (id) => id === 'flights' || id === 'military',
|
||||
},
|
||||
rendering: { renderVisual() {}, scheduleDirectionOverlayUpdate() {} },
|
||||
panel: { renderResults() {} },
|
||||
};
|
||||
const realQueries = createQueries({ state: layerState, services, parts });
|
||||
parts.queries = { ...realQueries, collectSourceStates: () => states };
|
||||
parts.model = createModel({ state: layerState, services, parts });
|
||||
const subject = createSubject({ state: layerState, services, parts });
|
||||
const flights = (lastUpdate) => ({
|
||||
available: true, enabled: true, stale: false,
|
||||
stats: { source: 'OpenSky Network', count: 4, lastUpdate },
|
||||
});
|
||||
const vessels = (loading) => ({
|
||||
available: true, enabled: true, stale: true,
|
||||
stats: { source: 'Datalastic', stale: true, count: 3, lastUpdate: 1000, loading },
|
||||
});
|
||||
const rest = {
|
||||
military: { available: true, enabled: true, stale: false, stats: { source: 'adsb.lol', fallback: false, count: 1, lastUpdate: 1 } },
|
||||
'military-installations': { available: true, enabled: true, stale: false, stats: { coverage: { kind: 'subject', radiusM: 100000 } } },
|
||||
};
|
||||
const ais = () => layerState.results.cohorts.find((c) => c.id === 'ais-live-vessels');
|
||||
|
||||
// 1. Stale AIS cache, nothing loading.
|
||||
states = { flights: flights(1), 'ais-live-vessels': vessels(false), ...rest };
|
||||
subject.refreshSelectedSubject(true);
|
||||
assert.equal(ais().sourceStatus, 'stale');
|
||||
|
||||
// 2. AIS re-poll in flight while the flights poll lands (revision changes).
|
||||
states = { flights: flights(2), 'ais-live-vessels': vessels(true), ...rest };
|
||||
subject.refreshSelectedSubject();
|
||||
assert.equal(ais().sourceStatus, 'stale', 'a poll in flight keeps the snapshot stale');
|
||||
|
||||
// 3. AIS poll returns the same stale snapshot; only loading flips back.
|
||||
states = { flights: flights(2), 'ais-live-vessels': vessels(false), ...rest };
|
||||
subject.refreshSelectedSubject();
|
||||
subject.refreshSelectedSubject();
|
||||
assert.equal(ais().sourceStatus, 'stale', 'Layers reads STALE again; Contacts/Cockpit must too');
|
||||
});
|
||||
|
||||
function fakeRuntime() {
|
||||
return {
|
||||
now: () => 1000,
|
||||
setTimeout: () => ({}),
|
||||
clearTimeout() {},
|
||||
};
|
||||
}
|
||||
|
||||
test('first AIS connect (no snapshot yet) carries no STALE on the Contacts cohort', () => {
|
||||
globalThis.document ??= { body: null };
|
||||
_setAisRuntimeForTest(fakeRuntime());
|
||||
_setVesselStateForTest({ viewer: {}, records: [] });
|
||||
try {
|
||||
_beginAisSessionForTest();
|
||||
// What server/providers/vessels/ais-live.js answers while its socket connects.
|
||||
_applyAisFeedSnapshotForTest({}, {
|
||||
rows: [], source: 'AISStream', status: 'connecting', refreshing: true,
|
||||
});
|
||||
const vesselStats = aisLiveVesselsLayer.getStats();
|
||||
assert.equal(vesselStats.loading, true);
|
||||
assert.equal(vesselStats.stale, true);
|
||||
assert.equal(vesselStats.lastUpdate, null);
|
||||
assert.equal(layerFeedState(vesselStats), 'loading', 'Layers chip reads LOADING');
|
||||
|
||||
const flightsStats = { source: 'OpenSky Network', count: 2, lastUpdate: 5 };
|
||||
const militaryStats = { source: 'adsb.lol', fallback: false, count: 1, lastUpdate: 5 };
|
||||
const installStats = { coverage: { kind: 'subject', radiusM: 100000 } };
|
||||
const statsById = {
|
||||
flights: flightsStats,
|
||||
military: militaryStats,
|
||||
'ais-live-vessels': vesselStats,
|
||||
'military-installations': installStats,
|
||||
};
|
||||
const services = {
|
||||
installations: { getNearby: () => [], getStats: () => installStats },
|
||||
flights: { getNearby: () => [] },
|
||||
military: { getNearby: () => [] },
|
||||
vessels: aisLiveVesselsLayer,
|
||||
};
|
||||
const layerState = {
|
||||
enabled: true,
|
||||
passive: true,
|
||||
sourceRevision: '',
|
||||
cohortPages: new Map(),
|
||||
dataManager: {
|
||||
isEnabled: () => true,
|
||||
getLayerLifecycleState: () => ({ enabled: true, lifecycleState: 'enabled' }),
|
||||
layers: new Map(Object.entries(statsById).map(([id, s]) => [id, { module: { getStats: () => s } }])),
|
||||
},
|
||||
subject: {
|
||||
id: 'site-1',
|
||||
layerId: 'military-installations',
|
||||
label: 'Site',
|
||||
position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
|
||||
},
|
||||
};
|
||||
const parts = {
|
||||
navigation: {
|
||||
summarizeAwarenessCohortForNavigation: (items, source) => summarizeAwarenessCohort(items, source),
|
||||
isFlightLayer: (id) => id === 'flights' || id === 'military',
|
||||
},
|
||||
rendering: { renderVisual() {}, scheduleDirectionOverlayUpdate() {} },
|
||||
panel: { renderResults() {} },
|
||||
};
|
||||
parts.queries = createQueries({ state: layerState, services, parts });
|
||||
parts.model = createModel({ state: layerState, services, parts });
|
||||
const subject = createSubject({ state: layerState, services, parts });
|
||||
|
||||
const vesselsSource = parts.queries.collectSourceStates()['ais-live-vessels'];
|
||||
assert.equal(vesselsSource.available, false, 'never-answered source is unavailable');
|
||||
|
||||
subject.refreshSelectedSubject(true);
|
||||
const ais = layerState.results.cohorts.find((c) => c.id === 'ais-live-vessels');
|
||||
assert.equal(ais.sourceStatus, null, 'no snapshot yet: no STALE label, Layers says LOADING');
|
||||
} finally {
|
||||
_setVesselStateForTest({ enabled: false });
|
||||
_setAisRuntimeForTest();
|
||||
}
|
||||
});
|
||||
@@ -26,6 +26,8 @@ export function createState({ services }) {
|
||||
// layers activate only after Contacts is explicitly selected.
|
||||
passive: true,
|
||||
ownedDependencies: new Set(),
|
||||
/** Stops following the manager's adoptions (see watchAdoptions). */
|
||||
unwatchAdoptions: null,
|
||||
subject: null,
|
||||
results: null,
|
||||
visual: null,
|
||||
@@ -59,6 +61,10 @@ export function createState({ services }) {
|
||||
lastCameraPoseSig: '',
|
||||
/** When the pose signature last changed bins (hysteresis anchor). */
|
||||
lastCameraPoseChangeMs: 0,
|
||||
/** When the viewer last handled the camera (pointer, wheel, touch, key). */
|
||||
lastCameraInputMs: Number.NEGATIVE_INFINITY,
|
||||
/** Element the camera-input listeners are attached to. */
|
||||
cameraInputTarget: null,
|
||||
/** Whether the view currently counts as moving (hysteretic, not per-frame). */
|
||||
cameraMoving: false,
|
||||
lastEvaluatedPosition: null,
|
||||
|
||||
@@ -3,6 +3,7 @@ import {
|
||||
AWARENESS_RELATIONSHIP,
|
||||
} from '../../data/militaryAwarenessEngine.js';
|
||||
import * as Cesium from 'cesium';
|
||||
import { layerFeedState } from '../../data/feedState.js';
|
||||
import { t } from '../../i18n/index.js';
|
||||
import {
|
||||
AWARENESS_QUERY_LIMIT,
|
||||
@@ -52,6 +53,18 @@ export function createSubject({ state: layerState, services, parts, source }) {
|
||||
const vesselsState = sourceStates['ais-live-vessels'];
|
||||
const installationsState = sourceStates['military-installations'];
|
||||
const evaluatedAt = Date.now();
|
||||
// A poll in flight keeps FALLBACK or STALE: the revision key ignores loading.
|
||||
// Before the first answer there is no snapshot, so loading stays.
|
||||
const sourceStatus = (sourceState) => {
|
||||
const feedState = layerFeedState(
|
||||
sourceState.available
|
||||
? { ...sourceState.stats, loading: false }
|
||||
: sourceState.stats,
|
||||
);
|
||||
return feedState === 'fallback' || feedState === 'stale'
|
||||
? feedState
|
||||
: null;
|
||||
};
|
||||
const retainedProvenance = (id, label, sourceState, fallbackSource) => {
|
||||
const retainedSource = sourceState.stats.source || fallbackSource;
|
||||
return {
|
||||
@@ -94,6 +107,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
|
||||
id: 'flights',
|
||||
label: t('Flights'),
|
||||
source: flightsState.stats.source || SOURCE_LABEL.flights,
|
||||
sourceStatus: sourceStatus(flightsState),
|
||||
provenance: retainedProvenance(
|
||||
'flights',
|
||||
'Flights',
|
||||
@@ -113,6 +127,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
|
||||
id: 'military',
|
||||
label: t('Military flights'),
|
||||
source: militaryState.stats.source || SOURCE_LABEL.military,
|
||||
sourceStatus: sourceStatus(militaryState),
|
||||
provenance: retainedProvenance(
|
||||
'military',
|
||||
'Military flights',
|
||||
@@ -132,6 +147,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
|
||||
id: 'ais-live-vessels',
|
||||
label: t('AIS vessels'),
|
||||
source: vesselsState.stats.source || SOURCE_LABEL['ais-live-vessels'],
|
||||
sourceStatus: sourceStatus(vesselsState),
|
||||
provenance: retainedProvenance(
|
||||
'ais-live-vessels',
|
||||
'AIS vessels',
|
||||
@@ -149,6 +165,7 @@ export function createSubject({ state: layerState, services, parts, source }) {
|
||||
source:
|
||||
installationsState.stats.source ||
|
||||
SOURCE_LABEL['military-installations'],
|
||||
sourceStatus: sourceStatus(installationsState),
|
||||
provenance: retainedProvenance(
|
||||
'military-installations',
|
||||
'Mapped installations',
|
||||
|
||||
@@ -12,20 +12,28 @@
|
||||
* Cameras without an identified model are untouched — unknown never implies
|
||||
* anything.
|
||||
*
|
||||
* Spec records are vendored verbatim from the CCTV Camera Database
|
||||
* Specification fields are vendored from the CCTV Camera Database
|
||||
* (https://github.com/ch-bas/cctv-camera-database, CC0-1.0) — an open dataset
|
||||
* of 28,000+ camera models transcribed from manufacturer datasheets (84% with
|
||||
* FOV, as of v2.26.0). This module vendors the records that the currently integrated public
|
||||
* of 29,000+ camera models transcribed from manufacturer datasheets (76% with
|
||||
* FOV, as of v2.29.0). This module vendors records that the integrated public
|
||||
* catalogs publish hardware for — King County WA (Cohu, Bosch AUTODOME, Axis
|
||||
* Q6135-LE), plus the Bosch AUTODOME and Axis PTZ/multisensor models that
|
||||
* appear in Sarasota County FL and Sioux Falls SD open data; packs that
|
||||
* appear in Sarasota County FL and Sioux Falls SD open data, plus the Bosch MIC
|
||||
* PTZs for the City of Amsterdam camera register proposed in #251; packs that
|
||||
* publish other hardware models can grow it, or vendor the full extract.
|
||||
*
|
||||
* Scope guardrail: records describe camera PRODUCTS (optics, resolution,
|
||||
* night vision) — never endpoints, stream paths, or access/config data.
|
||||
*/
|
||||
|
||||
/** Verbatim records from the dataset's model-enrichment extract (v2.26.0). */
|
||||
/**
|
||||
* Records from the dataset's model-enrichment extract: v2.26.0, plus the Bosch
|
||||
* MIC records from v2.29.0 with titles shortened to model codes.
|
||||
* A Bosch MIC order code ends in a colour letter (B, G, W; registries write
|
||||
* `x`) on one shared datasheet. The colours are aliases of one record whose
|
||||
* `model` leaves the letter out, so the HUD never names a variant the source
|
||||
* did not.
|
||||
*/
|
||||
const RECORDS = [
|
||||
{
|
||||
id: 'axis-q6135-le',
|
||||
@@ -264,6 +272,67 @@ const RECORDS = [
|
||||
autotracking: true,
|
||||
environment: ['outdoor'],
|
||||
},
|
||||
{
|
||||
id: 'bosch-mic-7130-pb4',
|
||||
brand: 'Bosch',
|
||||
model: 'MIC-7130-P_4',
|
||||
type: 'ptz',
|
||||
url: 'https://www.cctv-database.com/camera/bosch-mic-7130-pb4/',
|
||||
aliases: [
|
||||
'MIC IP starlight 7000 HD',
|
||||
'MIC-7130-PB4',
|
||||
'MIC-7130-PG4',
|
||||
'MIC-7130-PW4',
|
||||
'MIC-7130-Px4',
|
||||
],
|
||||
fov_deg: '2.1-59',
|
||||
resolution: { mp: 1, w: 1280, h: 720, label: '720p' },
|
||||
ptz: true,
|
||||
autotracking: true,
|
||||
varifocal: true,
|
||||
environment: ['outdoor'],
|
||||
},
|
||||
{
|
||||
id: 'bosch-mic-7502-z30b',
|
||||
brand: 'Bosch',
|
||||
model: 'MIC-7502-Z30',
|
||||
type: 'ptz',
|
||||
url: 'https://www.cctv-database.com/camera/bosch-mic-7502-z30b/',
|
||||
aliases: [
|
||||
'MIC-7502-Z30B',
|
||||
'MIC-7502-Z30G',
|
||||
'MIC-7502-Z30W',
|
||||
'MIC-7502-Z30x',
|
||||
],
|
||||
fov_deg: '2.3-63.7',
|
||||
resolution: { mp: 2.13, w: 1920, h: 1080, label: '1080p' },
|
||||
ptz: true,
|
||||
autotracking: true,
|
||||
varifocal: true,
|
||||
night_vision: { type: 'color' },
|
||||
environment: ['outdoor'],
|
||||
},
|
||||
{
|
||||
id: 'bosch-mic-7522-z30b',
|
||||
brand: 'Bosch',
|
||||
model: 'MIC-7522-Z30',
|
||||
type: 'ptz',
|
||||
url: 'https://www.cctv-database.com/camera/bosch-mic-7522-z30b/',
|
||||
aliases: [
|
||||
'MIC-7522-Z30B',
|
||||
'MIC-7522-Z30G',
|
||||
'MIC-7522-Z30W',
|
||||
'MIC-7522-Z30x',
|
||||
],
|
||||
fov_deg: '2.1-58.3',
|
||||
// i18n-ignore: datasheet label
|
||||
resolution: { mp: 2, w: 1920, h: 1080, label: '1080p HD' },
|
||||
ptz: true,
|
||||
varifocal: true,
|
||||
night_vision: { type: 'color' },
|
||||
environment: ['outdoor'],
|
||||
ndaa_compliant: true,
|
||||
},
|
||||
{
|
||||
id: 'cohu-3920-idome',
|
||||
brand: 'Cohu',
|
||||
@@ -431,7 +500,7 @@ const NAME_INDEX = RECORDS.flatMap((record) => {
|
||||
* guesses).
|
||||
* @param {string} model - Hardware model as named by a source pack or seed.
|
||||
* @param {string} [manufacturer] - The source's manufacturer, when published.
|
||||
* @returns {Object|null} The verbatim spec record, or null when unknown.
|
||||
* @returns {Object|null} The matched spec record, or null when unknown.
|
||||
*/
|
||||
export function lookupModelSpec(model, manufacturer) {
|
||||
const query = words(model).map(stripVariantSuffix);
|
||||
|
||||
@@ -245,6 +245,95 @@ test('King County snapshot model strings still resolve', () => {
|
||||
);
|
||||
});
|
||||
|
||||
test('Amsterdam camera register model strings resolve', () => {
|
||||
// The register writes the Bosch MIC colour letter as `x`.
|
||||
assert.equal(
|
||||
lookupModelSpec('Bosch MIC-7522-Z30x')?.id,
|
||||
'bosch-mic-7522-z30b',
|
||||
);
|
||||
assert.equal(
|
||||
lookupModelSpec('Bosch MIC-7502-Z30x')?.id,
|
||||
'bosch-mic-7502-z30b',
|
||||
);
|
||||
assert.equal(lookupModelSpec('Bosch MIC-7130-Px4')?.id, 'bosch-mic-7130-pb4');
|
||||
assert.equal(lookupModelSpec('MIC-7522-Z30W')?.id, 'bosch-mic-7522-z30b');
|
||||
// Its ANPR units are not in the table: unknown, never a guess.
|
||||
assert.equal(lookupModelSpec('CSG-8800'), null);
|
||||
// The MIC and AUTODOME starlight 7000 HD (code-less names, so the brand
|
||||
// is needed) stay apart.
|
||||
assert.equal(
|
||||
lookupModelSpec('MIC IP starlight 7000 HD', 'Bosch')?.id,
|
||||
'bosch-mic-7130-pb4',
|
||||
);
|
||||
assert.equal(
|
||||
lookupModelSpec('AUTODOME IP starlight 7000 HD', 'Bosch')?.id,
|
||||
'bosch-autodome-ip-starlight-7000-hd',
|
||||
);
|
||||
// The MIC datasheets state FOV without an axis, so no horizontal range.
|
||||
assert.equal(horizontalFovRangeDeg(lookupModelSpec('MIC-7522-Z30B')), null);
|
||||
});
|
||||
|
||||
test('Bosch MIC colour aliases resolve without accepting unknown variants', () => {
|
||||
for (const [pattern, id] of [
|
||||
['MIC-7130-P?4', 'bosch-mic-7130-pb4'],
|
||||
['MIC-7502-Z30?', 'bosch-mic-7502-z30b'],
|
||||
['MIC-7522-Z30?', 'bosch-mic-7522-z30b'],
|
||||
]) {
|
||||
for (const colour of ['B', 'G', 'W', 'x']) {
|
||||
const model = pattern.replace('?', colour);
|
||||
assert.equal(lookupModelSpec(model)?.id, id, model);
|
||||
assert.equal(lookupModelSpec(`bosch ${model.toLowerCase()}`)?.id, id);
|
||||
assert.equal(lookupModelSpec(model, 'Bosch')?.id, id);
|
||||
assert.equal(lookupModelSpec(model, 'Axis'), null);
|
||||
assert.equal(lookupModelSpec(`${model}-UNKNOWN`), null);
|
||||
}
|
||||
assert.equal(lookupModelSpec(pattern.replace('?', 'R')), null);
|
||||
}
|
||||
});
|
||||
|
||||
test('Bosch MIC HUD summary never names a colour the source did not', () => {
|
||||
assert.equal(
|
||||
specSummary(lookupModelSpec('MIC-7522-Z30W')),
|
||||
'Bosch MIC-7522-Z30 · 1080p HD · COLOR · PTZ',
|
||||
);
|
||||
assert.equal(
|
||||
specSummary(lookupModelSpec('Bosch MIC-7522-Z30x')),
|
||||
'Bosch MIC-7522-Z30 · 1080p HD · COLOR · PTZ',
|
||||
);
|
||||
for (const pattern of ['MIC-7130-P?4', 'MIC-7502-Z30?', 'MIC-7522-Z30?']) {
|
||||
for (const colour of ['B', 'G', 'W', 'x']) {
|
||||
const spec = lookupModelSpec(pattern.replace('?', colour));
|
||||
const summary = specSummary(spec);
|
||||
for (const other of ['B', 'G', 'W', 'x']) {
|
||||
assert.ok(!summary.includes(pattern.replace('?', other)), summary);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test('Bosch MIC catalog enrichment preserves estimated and explicit optics', () => {
|
||||
for (const model of [
|
||||
'Bosch MIC-7130-Px4',
|
||||
'Bosch MIC-7502-Z30x',
|
||||
'Bosch MIC-7522-Z30x',
|
||||
]) {
|
||||
for (const pose of [{}, { fovDeg: 44 }, { poseSource: 'curated' }]) {
|
||||
const [camera] = browserCatalog().buildCatalogFromSources([
|
||||
{ id: 'amsterdam-mic', lat: 52.37, lon: 4.9, model, ...pose },
|
||||
]);
|
||||
assert.ok(camera.spec, model);
|
||||
assert.equal(camera.fovDeg, pose.fovDeg ?? 74, model);
|
||||
assert.equal(camera.fovSource, undefined);
|
||||
assert.equal(camera.specFovMinDeg, undefined);
|
||||
assert.equal(camera.specFovMaxDeg, undefined);
|
||||
assert.equal(horizontalFovRangeDeg(camera.spec), null);
|
||||
assert.equal(fixedHorizontalFovDeg(camera.spec), null);
|
||||
assert.equal(specFovCapabilityToken(camera), null);
|
||||
assert.match(specSummary(camera.spec), /^Bosch MIC-.* · PTZ$/);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test('catalog never overwrites an explicit FOV or a curated pose', () => {
|
||||
const [explicit, curated, cohu, pelco] =
|
||||
browserCatalog().buildCatalogFromSources([
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
/** Card model for one selected special-use airspace zone. Pure — no Cesium types. */
|
||||
|
||||
import { t } from '../../i18n/index.js';
|
||||
|
||||
export const DRONE_AIRSPACE_OVERLAY_SOURCE_ID = 'drone-airspace';
|
||||
|
||||
/** Fill/line CSS color for a zone by TYPE_CODE. */
|
||||
export function droneAirspaceAccent(typeCode) {
|
||||
return typeCode === 'P' ? '#ff3b30' : '#ff7a00';
|
||||
}
|
||||
|
||||
/** Shoelace area (degree², sign dropped) — relative sizes only. */
|
||||
function ringArea(ring) {
|
||||
let sum = 0;
|
||||
for (let i = 0; i < ring.length - 1; i++) {
|
||||
const [x1, y1] = ring[i];
|
||||
const [x2, y2] = ring[i + 1];
|
||||
sum += x1 * y2 - x2 * y1;
|
||||
}
|
||||
return Math.abs(sum / 2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Anchor point for the zone card: the centroid of the largest polygon's
|
||||
* outer ring. Degrees, so callers own the Cartesian conversion.
|
||||
* @param {Array<Array<Array<[number, number]>>>} polygons
|
||||
* @returns {{lon: number, lat: number}}
|
||||
*/
|
||||
export function droneAirspaceAnchorDegrees(polygons) {
|
||||
let best = null;
|
||||
let bestArea = -1;
|
||||
for (const rings of polygons) {
|
||||
const outer = rings[0];
|
||||
const area = ringArea(outer);
|
||||
if (area > bestArea) {
|
||||
bestArea = area;
|
||||
best = outer;
|
||||
}
|
||||
}
|
||||
let lon = 0;
|
||||
let lat = 0;
|
||||
const count = best.length - 1;
|
||||
for (let i = 0; i < count; i++) {
|
||||
lon += best[i][0];
|
||||
lat += best[i][1];
|
||||
}
|
||||
return { lon: lon / count, lat: lat / count };
|
||||
}
|
||||
|
||||
function altitudeLine(row) {
|
||||
const lower = row.lowerAltitude;
|
||||
const upper = row.upperAltitude;
|
||||
if (lower && upper) return t('{lower} to {upper}', { lower, upper });
|
||||
if (upper) return t('Up to {upper}', { upper });
|
||||
if (lower) return t('From {lower}', { lower });
|
||||
return null;
|
||||
}
|
||||
|
||||
function placeLine(row) {
|
||||
if (row.city && row.state) return `${row.city}, ${row.state}`;
|
||||
return row.city || row.state || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the overlay-host entry for one selected zone. The caller supplies
|
||||
* `position` (Cartesian) separately — this model stays JSON-safe for tests.
|
||||
* @param {Object} row - Normalized zone row (see records.js).
|
||||
* @returns {Object} World-overlay entry without `position`.
|
||||
*/
|
||||
export function buildDroneAirspaceCard(row) {
|
||||
const facts = [row.type ? t(row.type) : row.typeCode].filter(Boolean);
|
||||
const altitude = altitudeLine(row);
|
||||
if (altitude) facts.push(altitude);
|
||||
if (row.timesOfUse) facts.push(row.timesOfUse);
|
||||
|
||||
const details = [facts.join(' · ')];
|
||||
const place = placeLine(row);
|
||||
if (place) details.push(place);
|
||||
if (row.agency) details.push(row.agency);
|
||||
details.push(t('Informational only · not for flight planning'));
|
||||
|
||||
const type = row.type ? t(row.type) : 'SUA';
|
||||
const title = `${type.toUpperCase()} · ${row.name || t('Unnamed zone')}`;
|
||||
return {
|
||||
id: `drone-airspace-card:${row.stableId}`,
|
||||
selected: true,
|
||||
interactive: false,
|
||||
title,
|
||||
details,
|
||||
accent: droneAirspaceAccent(row.typeCode),
|
||||
priority: Number.MAX_SAFE_INTEGER,
|
||||
gapPx: 15,
|
||||
verticalOnly: true,
|
||||
placement: 'above',
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
droneAirspaceAnchorDegrees,
|
||||
droneAirspaceAccent,
|
||||
buildDroneAirspaceCard,
|
||||
} from './cards.js';
|
||||
|
||||
const square = [
|
||||
[-77.2, 38.8],
|
||||
[-77.0, 38.8],
|
||||
[-77.0, 39.0],
|
||||
[-77.2, 39.0],
|
||||
[-77.2, 38.8],
|
||||
];
|
||||
const tiny = [
|
||||
[-76.01, 38.0],
|
||||
[-76.0, 38.0],
|
||||
[-76.0, 38.01],
|
||||
[-76.01, 38.0],
|
||||
];
|
||||
|
||||
test('the card anchors at the centroid of the largest polygon', () => {
|
||||
const anchor = droneAirspaceAnchorDegrees([[tiny], [square]]);
|
||||
assert.ok(Math.abs(anchor.lon - -77.1) < 1e-9);
|
||||
assert.ok(Math.abs(anchor.lat - 38.9) < 1e-9);
|
||||
});
|
||||
|
||||
test('a prohibited zone card names the type, altitudes and the disclaimer', () => {
|
||||
const card = buildDroneAirspaceCard({
|
||||
stableId: '310',
|
||||
name: 'P-56',
|
||||
typeCode: 'P',
|
||||
type: 'Prohibited',
|
||||
lowerAltitude: 'SFC',
|
||||
upperAltitude: '18,000 ft MSL',
|
||||
timesOfUse: 'CONTINUOUS',
|
||||
agency: 'WASHINGTON CENTER',
|
||||
city: 'WASHINGTON',
|
||||
state: 'DC',
|
||||
});
|
||||
assert.equal(card.id, 'drone-airspace-card:310');
|
||||
assert.equal(card.title, 'PROHIBITED · P-56');
|
||||
assert.deepEqual(card.details, [
|
||||
'Prohibited · SFC to 18,000 ft MSL · CONTINUOUS',
|
||||
'WASHINGTON, DC',
|
||||
'WASHINGTON CENTER',
|
||||
'Informational only · not for flight planning',
|
||||
]);
|
||||
assert.equal(card.accent, droneAirspaceAccent('P'));
|
||||
assert.equal(card.interactive, false);
|
||||
assert.equal(card.selected, true);
|
||||
});
|
||||
|
||||
test('missing attributes degrade to available facts instead of placeholders', () => {
|
||||
const card = buildDroneAirspaceCard({
|
||||
stableId: 'x',
|
||||
name: null,
|
||||
typeCode: 'R',
|
||||
type: 'Restricted',
|
||||
lowerAltitude: null,
|
||||
upperAltitude: null,
|
||||
timesOfUse: null,
|
||||
agency: null,
|
||||
city: null,
|
||||
state: null,
|
||||
});
|
||||
assert.equal(card.title, 'RESTRICTED · Unnamed zone');
|
||||
assert.deepEqual(card.details, [
|
||||
'Restricted',
|
||||
'Informational only · not for flight planning',
|
||||
]);
|
||||
assert.equal(card.accent, droneAirspaceAccent('R'));
|
||||
});
|
||||
@@ -0,0 +1,37 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { VOICE_OFF_LAYERS } from '../../voice/layerManifest.js';
|
||||
import { ANALYST_LAYERS } from '../../data/analystEngine.js';
|
||||
|
||||
const read = (path) =>
|
||||
readFileSync(new URL(`../../../${path}`, import.meta.url), 'utf8');
|
||||
const currentState = read('docs/CURRENT-STATE.md');
|
||||
const section = currentState.slice(
|
||||
currentState.indexOf('## Prohibited & Restricted Airspace'),
|
||||
currentState.indexOf('\n## ', currentState.indexOf('## Prohibited')) + 1,
|
||||
);
|
||||
const tokens = JSON.parse(read('src/data/layerStateTokenReservations.json'));
|
||||
|
||||
test('CURRENT-STATE names the reserved share-link token', () => {
|
||||
const token = JSON.stringify(tokens).match(
|
||||
/\["drone-airspace","([^"]+)"\]/,
|
||||
)?.[1];
|
||||
assert.ok(token, 'drone-airspace has a reserved token');
|
||||
assert.match(section, new RegExp(`share-link token \`${token}\``));
|
||||
});
|
||||
|
||||
test('CURRENT-STATE matches the layer being outside voice and the analyst', () => {
|
||||
assert.ok(Object.hasOwn(VOICE_OFF_LAYERS, 'drone-airspace'));
|
||||
assert.ok(!Object.hasOwn(ANALYST_LAYERS, 'drone-airspace'));
|
||||
assert.doesNotMatch(section, /Voice can toggle/);
|
||||
assert.match(section, /Voice is off for this layer for now/);
|
||||
const analyst = currentState.match(/Analyst records come on demand[^\n]*/)[0];
|
||||
assert.doesNotMatch(analyst, /drone/i);
|
||||
});
|
||||
|
||||
test('CURRENT-STATE states what the layer does not cover', () => {
|
||||
assert.match(section, /UAS Facility Map/);
|
||||
assert.match(section, /LAANC/);
|
||||
assert.match(section, /TFRs/);
|
||||
});
|
||||
@@ -0,0 +1,366 @@
|
||||
import * as Cesium from 'cesium';
|
||||
import { msg, t } from '../../i18n/index.js';
|
||||
import {
|
||||
DRONE_AIRSPACE_OVERLAY_SOURCE_ID,
|
||||
droneAirspaceAnchorDegrees,
|
||||
buildDroneAirspaceCard,
|
||||
droneAirspaceAccent,
|
||||
} from './cards.js';
|
||||
export { normalizeDroneAirspaceSnapshot } from './records.js';
|
||||
export { createDroneAirspaceSource } from './source.js';
|
||||
export * from './cards.js';
|
||||
|
||||
/** Fill/line color for a zone by TYPE_CODE. */
|
||||
export function droneAirspaceColor(typeCode) {
|
||||
return Cesium.Color.fromCssColorString(droneAirspaceAccent(typeCode));
|
||||
}
|
||||
|
||||
const ringPositions = (ring) =>
|
||||
ring.map(([lon, lat]) => Cesium.Cartesian3.fromDegrees(lon, lat));
|
||||
|
||||
/**
|
||||
* FNV-1a over a zone's rings: a short, deterministic fingerprint so a
|
||||
* boundary change with unchanged attributes still alters the refresh signature.
|
||||
*/
|
||||
function geometryHash(polygons) {
|
||||
const text = JSON.stringify(polygons);
|
||||
let hash = 0x811c9dc5;
|
||||
for (let i = 0; i < text.length; i++) {
|
||||
hash ^= text.charCodeAt(i);
|
||||
hash = Math.imul(hash, 0x01000193);
|
||||
}
|
||||
return (hash >>> 0).toString(36);
|
||||
}
|
||||
|
||||
const PICK_PREFIX = 'drone-airspace:';
|
||||
const CARD_HOST_OPTIONS = Object.freeze({
|
||||
cohortLimit: 1,
|
||||
collisionCapacity: 1,
|
||||
moving: false,
|
||||
});
|
||||
|
||||
/** Own one drone-restriction display, its refresh lifecycle, and click selection. */
|
||||
export function createDroneAirspaceLayer({
|
||||
source,
|
||||
overlayHost = null,
|
||||
screenSpaceEventHandlerFactory = null,
|
||||
picking = null,
|
||||
pointer = null,
|
||||
} = {}) {
|
||||
if (typeof source?.getSnapshot !== 'function')
|
||||
throw new TypeError('Drone airspace requires a snapshot source');
|
||||
let _viewer = null;
|
||||
let _request = null;
|
||||
let _snapshotSignature = null;
|
||||
let _dataSource = null;
|
||||
let _count = 0;
|
||||
let _lastUpdate = null;
|
||||
let _lastError = null;
|
||||
let _stale = false;
|
||||
let _enabled = false;
|
||||
let _clickHandler = null;
|
||||
let _selectedId = null;
|
||||
let _selectedCardId = null;
|
||||
/** @type {Map<string, {stableId: string, anchor: {lon: number, lat: number}}>} */
|
||||
const _rowById = new Map();
|
||||
|
||||
const canSelect = () =>
|
||||
overlayHost && screenSpaceEventHandlerFactory && picking;
|
||||
|
||||
function publishSelectedCard() {
|
||||
if (!canSelect()) return;
|
||||
const row = _selectedId ? _rowById.get(_selectedId) : null;
|
||||
if (!row) {
|
||||
_selectedId = null;
|
||||
_selectedCardId = null;
|
||||
overlayHost.setEntries(
|
||||
DRONE_AIRSPACE_OVERLAY_SOURCE_ID,
|
||||
[],
|
||||
CARD_HOST_OPTIONS,
|
||||
);
|
||||
return;
|
||||
}
|
||||
const card = {
|
||||
...buildDroneAirspaceCard(row),
|
||||
position: Cesium.Cartesian3.fromDegrees(row.anchor.lon, row.anchor.lat),
|
||||
};
|
||||
_selectedCardId = card.id;
|
||||
overlayHost.setEntries(
|
||||
DRONE_AIRSPACE_OVERLAY_SOURCE_ID,
|
||||
[card],
|
||||
CARD_HOST_OPTIONS,
|
||||
);
|
||||
}
|
||||
|
||||
/** Resolve a scene pick to one of this layer's zone ids, or null. */
|
||||
function pickedZoneId(picked) {
|
||||
const pickId = picking.resolvePickId(picked);
|
||||
if (typeof pickId !== 'string' || !pickId.startsWith(PICK_PREFIX))
|
||||
return null;
|
||||
const zoneId = pickId.slice(PICK_PREFIX.length).split(':')[0];
|
||||
return _rowById.has(zoneId) ? zoneId : null;
|
||||
}
|
||||
|
||||
function installClickHandler() {
|
||||
if (!canSelect() || _clickHandler || !_viewer) return;
|
||||
// Deliberately NOT registered in the pick-ownership registry: sibling
|
||||
// layers yield to owned picks before their own overlay-card hit-tests,
|
||||
// so claiming these large ground polygons would make FIRMS/vessel/CCTV
|
||||
// cards inert anywhere over a zone. Unowned, our picks read as
|
||||
// "empty space" to siblings — the same contract as fire perimeters.
|
||||
_clickHandler = screenSpaceEventHandlerFactory(_viewer);
|
||||
_clickHandler.setInputAction((click) => {
|
||||
if (pointer && !pointer.isPointerFree()) return;
|
||||
const cardHit = overlayHost.hitTest?.(
|
||||
click.position?.x,
|
||||
click.position?.y,
|
||||
{ sourceId: DRONE_AIRSPACE_OVERLAY_SOURCE_ID },
|
||||
);
|
||||
if (cardHit && cardHit.entryId === _selectedCardId) return;
|
||||
const picked = _viewer.scene.pick(click.position);
|
||||
const zoneId = picked ? pickedZoneId(picked) : null;
|
||||
if (zoneId) {
|
||||
_selectedId = zoneId;
|
||||
publishSelectedCard();
|
||||
return;
|
||||
}
|
||||
if (picked) {
|
||||
const pickId = picking.resolvePickId(picked);
|
||||
if (pickId && picking.isOwnedByOtherLayer(layer.id, pickId)) return;
|
||||
}
|
||||
if (_selectedId) {
|
||||
_selectedId = null;
|
||||
publishSelectedCard();
|
||||
}
|
||||
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
|
||||
}
|
||||
|
||||
function removeClickHandler() {
|
||||
if (_clickHandler) {
|
||||
_clickHandler.destroy();
|
||||
_clickHandler = null;
|
||||
}
|
||||
}
|
||||
|
||||
function clearSelection() {
|
||||
_selectedId = null;
|
||||
_selectedCardId = null;
|
||||
if (overlayHost) {
|
||||
overlayHost.clearSource(DRONE_AIRSPACE_OVERLAY_SOURCE_ID);
|
||||
overlayHost.setVisible?.(DRONE_AIRSPACE_OVERLAY_SOURCE_ID, false);
|
||||
}
|
||||
}
|
||||
|
||||
const layer = {
|
||||
id: 'drone-airspace',
|
||||
name: 'Prohibited & Restricted Airspace',
|
||||
icon: '🚫',
|
||||
source: 'FAA SUA',
|
||||
updateInterval: 3600000,
|
||||
|
||||
init(viewer) {
|
||||
if (_viewer)
|
||||
throw new Error('Drone airspace layer is already initialized');
|
||||
_viewer = viewer;
|
||||
_dataSource = new Cesium.CustomDataSource('drone-airspace');
|
||||
_dataSource.show = false;
|
||||
viewer.dataSources.add(_dataSource);
|
||||
_count = 0;
|
||||
_lastUpdate = null;
|
||||
_lastError = null;
|
||||
_stale = false;
|
||||
_enabled = false;
|
||||
console.log('[Data:DroneAirspace] Initialized');
|
||||
},
|
||||
|
||||
enable() {
|
||||
_enabled = true;
|
||||
if (_dataSource) _dataSource.show = true;
|
||||
overlayHost?.setVisible?.(DRONE_AIRSPACE_OVERLAY_SOURCE_ID, true);
|
||||
installClickHandler();
|
||||
},
|
||||
|
||||
disable() {
|
||||
_request?.abort();
|
||||
_request = null;
|
||||
_enabled = false;
|
||||
if (_dataSource) _dataSource.show = false;
|
||||
removeClickHandler();
|
||||
clearSelection();
|
||||
},
|
||||
|
||||
async update() {
|
||||
if (!_enabled || !_dataSource) return false;
|
||||
_request?.abort();
|
||||
const request = new AbortController();
|
||||
_request = request;
|
||||
try {
|
||||
// The source contract is getSnapshot; a source that can also say how
|
||||
// fresh its rows are (the FAA proxy) offers getSnapshotDetail.
|
||||
const snapshot =
|
||||
typeof source.getSnapshotDetail === 'function'
|
||||
? await source.getSnapshotDetail({ signal: request.signal })
|
||||
: { rows: await source.getSnapshot({ signal: request.signal }) };
|
||||
if (request.signal.aborted || _request !== request || !_enabled)
|
||||
return false;
|
||||
const { rows } = snapshot;
|
||||
_stale = snapshot.stale === true;
|
||||
// A stale snapshot is as old as its fetch, not this poll.
|
||||
const updatedAt =
|
||||
_stale && Number.isFinite(snapshot.fetchedAt)
|
||||
? snapshot.fetchedAt
|
||||
: Date.now();
|
||||
|
||||
// FAA amends boundaries in its 8-week cycle without any attribute
|
||||
// changing, so the geometry is part of the signature.
|
||||
const signature = JSON.stringify(
|
||||
rows
|
||||
.map(({ polygons, ...facts }) => ({
|
||||
...facts,
|
||||
geometry: geometryHash(polygons),
|
||||
}))
|
||||
.sort((a, b) => a.stableId.localeCompare(b.stableId)),
|
||||
);
|
||||
if (signature === _snapshotSignature) {
|
||||
if (_selectedId) publishSelectedCard();
|
||||
_lastUpdate = updatedAt;
|
||||
_lastError = null;
|
||||
return true;
|
||||
}
|
||||
const nextEntities = [];
|
||||
_rowById.clear();
|
||||
for (const row of rows) {
|
||||
const color = droneAirspaceColor(row.typeCode);
|
||||
for (const [index, rings] of row.polygons.entries()) {
|
||||
const [outer, ...holes] = rings;
|
||||
const outerPositions = ringPositions(outer);
|
||||
nextEntities.push(
|
||||
new Cesium.Entity({
|
||||
id: `drone-airspace:${row.stableId}:${index}`,
|
||||
polygon: {
|
||||
hierarchy: new Cesium.PolygonHierarchy(
|
||||
outerPositions,
|
||||
holes.map(
|
||||
(hole) =>
|
||||
new Cesium.PolygonHierarchy(ringPositions(hole)),
|
||||
),
|
||||
),
|
||||
material: new Cesium.ColorMaterialProperty(
|
||||
color.withAlpha(0.25),
|
||||
),
|
||||
},
|
||||
polyline: {
|
||||
positions: outerPositions,
|
||||
clampToGround: true,
|
||||
width: 2,
|
||||
material: new Cesium.ColorMaterialProperty(
|
||||
color.withAlpha(0.9),
|
||||
),
|
||||
},
|
||||
}),
|
||||
);
|
||||
}
|
||||
const { polygons, ...facts } = row;
|
||||
_rowById.set(row.stableId, {
|
||||
...facts,
|
||||
anchor: droneAirspaceAnchorDegrees(polygons),
|
||||
});
|
||||
}
|
||||
|
||||
_dataSource.entities.removeAll();
|
||||
for (const entity of nextEntities) _dataSource.entities.add(entity);
|
||||
_snapshotSignature = signature;
|
||||
if (_selectedId) publishSelectedCard();
|
||||
_count = rows.length;
|
||||
_lastUpdate = updatedAt;
|
||||
_lastError = null;
|
||||
console.log(
|
||||
`[Data:DroneAirspace] Updated: ${_count} zones, ${nextEntities.length} polygons`,
|
||||
);
|
||||
return true;
|
||||
} catch (e) {
|
||||
if (request.signal.aborted || _request !== request || !_enabled)
|
||||
return false;
|
||||
console.warn('[Data:DroneAirspace] Fetch error:', e);
|
||||
_lastError =
|
||||
e?.message || msg('Restricted airspace source unavailable');
|
||||
// A failure now outranks the stale snapshot still drawn.
|
||||
_stale = false;
|
||||
return false;
|
||||
} finally {
|
||||
if (_request === request) _request = null;
|
||||
}
|
||||
},
|
||||
|
||||
destroy(viewer = _viewer) {
|
||||
_request?.abort();
|
||||
_request = null;
|
||||
removeClickHandler();
|
||||
clearSelection();
|
||||
_rowById.clear();
|
||||
_snapshotSignature = null;
|
||||
_viewer = null;
|
||||
_enabled = false;
|
||||
if (_dataSource) {
|
||||
viewer.dataSources.remove(_dataSource, true);
|
||||
_dataSource = null;
|
||||
}
|
||||
_count = 0;
|
||||
_lastUpdate = null;
|
||||
_lastError = null;
|
||||
_stale = false;
|
||||
},
|
||||
|
||||
getAnalystRecords(maxCount = 2000) {
|
||||
if (!_dataSource || !_dataSource.show) return [];
|
||||
const limit = Number.isFinite(maxCount)
|
||||
? Math.max(1, Math.floor(maxCount))
|
||||
: 2000;
|
||||
const result = [];
|
||||
for (const row of _rowById.values()) {
|
||||
if (result.length >= limit) break;
|
||||
const { anchor, stableId, ...facts } = row;
|
||||
result.push({
|
||||
id: stableId,
|
||||
...facts,
|
||||
lat: anchor.lat,
|
||||
lon: anchor.lon,
|
||||
});
|
||||
}
|
||||
return result;
|
||||
},
|
||||
|
||||
getRowControls() {
|
||||
const bands = [
|
||||
{ label: t('Prohibited (P)'), color: droneAirspaceAccent('P') },
|
||||
{ label: t('Restricted (R)'), color: droneAirspaceAccent('R') },
|
||||
];
|
||||
return {
|
||||
chips: [],
|
||||
legend: bands.map((band, index) => ({
|
||||
...band,
|
||||
count: [..._rowById.values()].filter(
|
||||
(row) => droneAirspaceAccent(row.typeCode) === band.color,
|
||||
).length,
|
||||
...(index === 0
|
||||
? {
|
||||
blurb: t(
|
||||
'FAA prohibited and restricted special-use airspace only, not the UAS Facility Map or UAS flight restrictions. Informational only — not a substitute for official UAS flight-planning tools (B4UFLY / LAANC).',
|
||||
),
|
||||
}
|
||||
: {}),
|
||||
})),
|
||||
};
|
||||
},
|
||||
|
||||
getStats() {
|
||||
return {
|
||||
count: _count,
|
||||
lastUpdate: _lastUpdate,
|
||||
error: _lastError,
|
||||
stale: _stale,
|
||||
};
|
||||
},
|
||||
};
|
||||
return layer;
|
||||
}
|
||||
@@ -0,0 +1,218 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { createDroneAirspaceLayer } from './index.js';
|
||||
import { layerFeedState } from '../../data/feedState.js';
|
||||
|
||||
function harness(source, { pick = () => null, cardHit = () => null } = {}) {
|
||||
const sources = [];
|
||||
const overlay = { entries: new Map(), visible: null };
|
||||
const clicks = { handler: null, destroyed: 0 };
|
||||
const owners = new Map();
|
||||
const viewer = {
|
||||
scene: { pick },
|
||||
dataSources: {
|
||||
add(value) {
|
||||
sources.push(value);
|
||||
},
|
||||
remove(value) {
|
||||
sources.splice(sources.indexOf(value), 1);
|
||||
},
|
||||
},
|
||||
};
|
||||
const layer = createDroneAirspaceLayer({
|
||||
source,
|
||||
overlayHost: {
|
||||
setEntries(sourceId, entries) {
|
||||
overlay.entries.set(sourceId, entries);
|
||||
},
|
||||
setVisible(sourceId, visible) {
|
||||
overlay.visible = visible;
|
||||
},
|
||||
clearSource(sourceId) {
|
||||
overlay.entries.delete(sourceId);
|
||||
},
|
||||
hitTest: (x, y, options) => cardHit(x, y, options),
|
||||
},
|
||||
screenSpaceEventHandlerFactory: () => ({
|
||||
setInputAction(callback) {
|
||||
clicks.handler = callback;
|
||||
},
|
||||
destroy() {
|
||||
clicks.destroyed += 1;
|
||||
clicks.handler = null;
|
||||
},
|
||||
}),
|
||||
picking: {
|
||||
resolvePickId: (picked) => picked?.id ?? null,
|
||||
isOwnedByOtherLayer: (layerId, pickedId) =>
|
||||
String(pickedId).startsWith('other-layer:'),
|
||||
registerPickOwner: (layerId, predicate) => owners.set(layerId, predicate),
|
||||
unregisterPickOwner: (layerId) => owners.delete(layerId),
|
||||
},
|
||||
pointer: { isPointerFree: () => true },
|
||||
});
|
||||
layer.init(viewer);
|
||||
layer.enable(viewer);
|
||||
return { layer, viewer, sources, overlay, clicks, owners };
|
||||
}
|
||||
|
||||
const ring = [
|
||||
[-77.04, 38.89],
|
||||
[-77.03, 38.89],
|
||||
[-77.03, 38.9],
|
||||
[-77.04, 38.89],
|
||||
];
|
||||
const row = {
|
||||
stableId: '310',
|
||||
name: 'P-56',
|
||||
typeCode: 'P',
|
||||
type: 'Prohibited',
|
||||
lowerAltitude: 'SFC',
|
||||
upperAltitude: '18,000 ft MSL',
|
||||
timesOfUse: 'CONTINUOUS',
|
||||
agency: null,
|
||||
city: 'WASHINGTON',
|
||||
state: 'DC',
|
||||
polygons: [[ring]],
|
||||
};
|
||||
|
||||
test('each zone polygon renders as one filled entity with its outline', async () => {
|
||||
const h = harness({
|
||||
getSnapshot: async () => [
|
||||
row,
|
||||
{ ...row, stableId: '400', typeCode: 'R', polygons: [[ring], [ring]] },
|
||||
],
|
||||
});
|
||||
assert.equal(await h.layer.update(h.viewer), true);
|
||||
const entities = h.sources[0].entities.values;
|
||||
assert.equal(entities.length, 3);
|
||||
assert.equal(entities[0].id, 'drone-airspace:310:0');
|
||||
assert.ok(entities[0].polygon, 'zone fill missing');
|
||||
assert.ok(entities[0].polyline, 'zone outline missing');
|
||||
assert.equal(h.layer.getStats().count, 2);
|
||||
});
|
||||
|
||||
test('clicking a zone publishes its card; empty space clears it', async () => {
|
||||
let pickResult = null;
|
||||
const h = harness(
|
||||
{ getSnapshot: async () => [row] },
|
||||
{ pick: () => pickResult },
|
||||
);
|
||||
await h.layer.update(h.viewer);
|
||||
assert.equal(typeof h.clicks.handler, 'function', 'click handler missing');
|
||||
assert.equal(h.owners.size, 0);
|
||||
|
||||
pickResult = { id: 'drone-airspace:310:0' };
|
||||
h.clicks.handler({ position: { x: 10, y: 10 } });
|
||||
const entries = h.overlay.entries.get('drone-airspace');
|
||||
assert.equal(entries.length, 1);
|
||||
assert.equal(entries[0].id, 'drone-airspace-card:310');
|
||||
assert.equal(entries[0].title, 'PROHIBITED · P-56');
|
||||
assert.ok(entries[0].position, 'card must carry a world anchor');
|
||||
|
||||
pickResult = { id: 'other-layer:aircraft-1' };
|
||||
h.clicks.handler({ position: { x: 10, y: 10 } });
|
||||
assert.equal(
|
||||
h.overlay.entries.get('drone-airspace')?.length,
|
||||
1,
|
||||
'sibling-layer picks must not clear the selection',
|
||||
);
|
||||
|
||||
pickResult = null;
|
||||
h.clicks.handler({ position: { x: 10, y: 10 } });
|
||||
assert.equal(h.overlay.entries.get('drone-airspace')?.length ?? 0, 0);
|
||||
});
|
||||
|
||||
test('late refresh cannot publish after disable or destroy', async () => {
|
||||
for (const action of ['disable', 'destroy']) {
|
||||
let resolve, signal;
|
||||
const h = harness({
|
||||
getSnapshot(options) {
|
||||
signal = options.signal;
|
||||
return new Promise((done) => {
|
||||
resolve = done;
|
||||
});
|
||||
},
|
||||
});
|
||||
const pending = h.layer.update(h.viewer);
|
||||
h.layer[action](h.viewer);
|
||||
assert.equal(signal.aborted, true);
|
||||
if (action === 'disable') h.layer.enable(h.viewer);
|
||||
resolve([row]);
|
||||
assert.equal(await pending, false);
|
||||
assert.equal(h.layer.getStats().count, 0);
|
||||
h.layer.destroy(h.viewer);
|
||||
}
|
||||
});
|
||||
|
||||
test('the row legend names prohibited and restricted with the disclaimer', async () => {
|
||||
const h = harness({
|
||||
getSnapshot: async () => [
|
||||
row,
|
||||
{ ...row, stableId: '400', typeCode: 'R', type: 'Restricted' },
|
||||
],
|
||||
});
|
||||
await h.layer.update(h.viewer);
|
||||
const legend = h.layer.getRowControls().legend;
|
||||
assert.equal(legend[0].label, 'Prohibited (P)');
|
||||
assert.equal(legend[1].label, 'Restricted (R)');
|
||||
assert.equal(legend[0].count, 1);
|
||||
assert.equal(legend[1].count, 1);
|
||||
assert.match(legend[0].blurb, /not a substitute/);
|
||||
});
|
||||
|
||||
test('a stale snapshot reads STALE, dated by its own fetch, and a fresh one clears it', async () => {
|
||||
const fetchedAt = Date.now() - 3 * 60 * 60 * 1000;
|
||||
let snapshot = { rows: [row], stale: true, fetchedAt };
|
||||
const h = harness({
|
||||
getSnapshot: async () => snapshot.rows,
|
||||
getSnapshotDetail: async () => snapshot,
|
||||
});
|
||||
await h.layer.update(h.viewer);
|
||||
assert.equal(h.layer.getStats().stale, true);
|
||||
assert.equal(h.layer.getStats().lastUpdate, fetchedAt);
|
||||
assert.equal(layerFeedState(h.layer.getStats()), 'stale');
|
||||
snapshot = { rows: [row], stale: false, fetchedAt: Date.now() };
|
||||
await h.layer.update(h.viewer);
|
||||
assert.equal(h.layer.getStats().stale, false);
|
||||
assert.ok(h.layer.getStats().lastUpdate > fetchedAt);
|
||||
assert.equal(layerFeedState(h.layer.getStats()), 'nominal');
|
||||
});
|
||||
|
||||
test('a failed refresh after a stale snapshot reads as the failure, not stale', async () => {
|
||||
let fail = false;
|
||||
const h = harness({
|
||||
getSnapshot: async () => [row],
|
||||
getSnapshotDetail: async () => {
|
||||
if (fail) throw new Error('FAA SUA HTTP 502');
|
||||
return { rows: [row], stale: true, fetchedAt: Date.now() - 60_000 };
|
||||
},
|
||||
});
|
||||
await h.layer.update(h.viewer);
|
||||
assert.equal(layerFeedState(h.layer.getStats()), 'stale');
|
||||
fail = true;
|
||||
await h.layer.update(h.viewer);
|
||||
assert.equal(h.layer.getStats().stale, false);
|
||||
assert.equal(h.layer.getStats().error, 'FAA SUA HTTP 502');
|
||||
assert.equal(layerFeedState(h.layer.getStats()), 'degraded');
|
||||
});
|
||||
|
||||
test('a boundary change alone redraws the zone; identical geometry does not', async () => {
|
||||
const moved = ring.map(([lon, lat]) => [lon + 0.5, lat]);
|
||||
let rows = [row];
|
||||
const h = harness({ getSnapshot: async () => rows });
|
||||
await h.layer.update(h.viewer);
|
||||
const [first] = h.sources[0].entities.values;
|
||||
rows = [{ ...row, polygons: [[ring.map((point) => [...point])]] }];
|
||||
await h.layer.update(h.viewer);
|
||||
assert.equal(h.sources[0].entities.values[0], first, 'same geometry kept');
|
||||
rows = [{ ...row, polygons: [[moved]] }];
|
||||
await h.layer.update(h.viewer);
|
||||
const [redrawn] = h.sources[0].entities.values;
|
||||
assert.notEqual(redrawn, first, 'moved boundary must redraw');
|
||||
assert.notDeepEqual(
|
||||
redrawn.polyline.positions.getValue(),
|
||||
first.polyline.positions.getValue(),
|
||||
);
|
||||
assert.ok(h.layer.getAnalystRecords()[0].lon > -76.6);
|
||||
});
|
||||
@@ -0,0 +1,135 @@
|
||||
/**
|
||||
* Normalize an FAA Special Use Airspace feed, skipping individually invalid
|
||||
* features. Only a payload that is not a feature collection at all rejects
|
||||
* the whole snapshot: a single degenerate polygon must never blank the layer.
|
||||
*/
|
||||
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
|
||||
const TYPE_LABELS = Object.freeze({
|
||||
P: msg('Prohibited'),
|
||||
R: msg('Restricted'),
|
||||
});
|
||||
|
||||
const finiteOrNull = (value) => (Number.isFinite(value) ? value : null);
|
||||
const textOrNull = (value) => {
|
||||
if (typeof value !== 'string') return null;
|
||||
const text = value.trim();
|
||||
return text ? text : null;
|
||||
};
|
||||
|
||||
/** FAA marks line breaks in TIMESOFUSE with `%`; read them as `; ` separators. */
|
||||
const timesOfUseOrNull = (value) =>
|
||||
textOrNull(
|
||||
typeof value === 'string'
|
||||
? value.replace(/\s*;?\s*%\s*/g, '; ').replace(/^[;\s]+|[;\s]+$/g, '')
|
||||
: value,
|
||||
);
|
||||
|
||||
function validRing(ring) {
|
||||
if (!Array.isArray(ring) || ring.length < 4) return false;
|
||||
for (const position of ring) {
|
||||
if (!Array.isArray(position) || position.length < 2) return false;
|
||||
const [lon, lat] = position;
|
||||
if (!Number.isFinite(lon) || Math.abs(lon) > 180) return false;
|
||||
if (!Number.isFinite(lat) || Math.abs(lat) > 90) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Normalize Polygon/MultiPolygon geometry to an array of polygons (each an
|
||||
* array of rings). Returns null on malformed geometry, [] when empty. */
|
||||
function normalizePolygons(geometry) {
|
||||
if (!geometry || typeof geometry !== 'object') return null;
|
||||
let polygons;
|
||||
if (geometry.type === 'Polygon') polygons = [geometry.coordinates];
|
||||
else if (geometry.type === 'MultiPolygon') polygons = geometry.coordinates;
|
||||
else return null;
|
||||
if (!Array.isArray(polygons)) return null;
|
||||
const result = [];
|
||||
for (const rings of polygons) {
|
||||
if (!Array.isArray(rings)) return null;
|
||||
if (!rings.length) continue;
|
||||
if (!rings.every(validRing)) return null;
|
||||
result.push(rings);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* One SUA altitude limit from its VAL/UOM/CODE triple, in aviation notation:
|
||||
* `SFC`, `500 ft AGL`, `5,000 ft MSL`, `FL180` or `Unlimited`. The *_DESC
|
||||
* fields are inclusion qualifiers (TI/TNI/ANI), not altitudes. Returns null
|
||||
* when the triple does not describe a limit.
|
||||
*/
|
||||
export function droneAirspaceAltitude(value, uom, code) {
|
||||
const unit = textOrNull(uom)?.toUpperCase() ?? null;
|
||||
const reference = textOrNull(code)?.toUpperCase() ?? null;
|
||||
if (reference === 'UNLTD') return 'Unlimited';
|
||||
const number = Number(value);
|
||||
if (value == null || value === '' || !Number.isFinite(number) || number < 0)
|
||||
return null;
|
||||
if (unit === 'FL' || reference === 'STD') return `FL${Math.round(number)}`;
|
||||
const feet = `${Math.round(number).toLocaleString('en-US')} ft`;
|
||||
if (reference === 'SFC') return number === 0 ? 'SFC' : `${feet} AGL`;
|
||||
if (reference === 'MSL') return `${feet} MSL`;
|
||||
return unit === 'FT' || unit == null ? feet : null;
|
||||
}
|
||||
|
||||
/** Human label for a TYPE_CODE, or null when the code is not in the pack. */
|
||||
export function droneAirspaceTypeLabel(typeCode) {
|
||||
return TYPE_LABELS[typeCode] || null;
|
||||
}
|
||||
|
||||
export function normalizeDroneAirspaceSnapshot(geojson) {
|
||||
if (!Array.isArray(geojson?.features)) return null;
|
||||
const rows = [];
|
||||
const ids = new Set();
|
||||
for (const feature of geojson.features) {
|
||||
const properties = feature?.properties;
|
||||
if (
|
||||
!properties ||
|
||||
typeof properties !== 'object' ||
|
||||
Array.isArray(properties)
|
||||
)
|
||||
continue;
|
||||
const typeCode = textOrNull(properties.TYPE_CODE);
|
||||
const type = droneAirspaceTypeLabel(typeCode);
|
||||
if (!type) continue;
|
||||
const polygons = normalizePolygons(feature.geometry);
|
||||
if (polygons === null || !polygons.length) continue;
|
||||
const objectId = finiteOrNull(Number(properties.OBJECTID));
|
||||
const featureId =
|
||||
feature.id == null || feature.id === '' ? null : String(feature.id);
|
||||
const stableId =
|
||||
objectId != null
|
||||
? String(objectId)
|
||||
: featureId && !ids.has(featureId)
|
||||
? featureId
|
||||
: null;
|
||||
if (stableId == null || ids.has(stableId)) continue;
|
||||
ids.add(stableId);
|
||||
rows.push({
|
||||
stableId,
|
||||
name: textOrNull(properties.NAME),
|
||||
typeCode,
|
||||
type,
|
||||
lowerAltitude: droneAirspaceAltitude(
|
||||
properties.LOWER_VAL,
|
||||
properties.LOWER_UOM,
|
||||
properties.LOWER_CODE,
|
||||
),
|
||||
upperAltitude: droneAirspaceAltitude(
|
||||
properties.UPPER_VAL,
|
||||
properties.UPPER_UOM,
|
||||
properties.UPPER_CODE,
|
||||
),
|
||||
timesOfUse: timesOfUseOrNull(properties.TIMESOFUSE),
|
||||
agency: textOrNull(properties.CONT_AGENT),
|
||||
city: textOrNull(properties.CITY),
|
||||
state: textOrNull(properties.STATE),
|
||||
polygons,
|
||||
});
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
@@ -0,0 +1,164 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
droneAirspaceAltitude,
|
||||
droneAirspaceTypeLabel,
|
||||
normalizeDroneAirspaceSnapshot,
|
||||
} from './records.js';
|
||||
|
||||
const ring = [
|
||||
[-77.04, 38.89],
|
||||
[-77.03, 38.89],
|
||||
[-77.03, 38.9],
|
||||
[-77.04, 38.89],
|
||||
];
|
||||
|
||||
function feature(overrides = {}) {
|
||||
return {
|
||||
id: 310,
|
||||
geometry: { type: 'Polygon', coordinates: [ring] },
|
||||
properties: {
|
||||
NAME: 'P-56',
|
||||
TYPE_CODE: 'P',
|
||||
UPPER_DESC: 'TNI',
|
||||
UPPER_VAL: '18000',
|
||||
UPPER_UOM: 'FT',
|
||||
UPPER_CODE: 'MSL',
|
||||
LOWER_DESC: null,
|
||||
LOWER_VAL: '0',
|
||||
LOWER_UOM: 'FT',
|
||||
LOWER_CODE: 'SFC',
|
||||
TIMESOFUSE: 'CONTINUOUS',
|
||||
CONT_AGENT: 'WASHINGTON CENTER',
|
||||
CITY: 'WASHINGTON',
|
||||
STATE: 'DC',
|
||||
OBJECTID: 310,
|
||||
...overrides.properties,
|
||||
},
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
test('a valid snapshot yields one row per prohibited or restricted zone', () => {
|
||||
const rows = normalizeDroneAirspaceSnapshot({
|
||||
features: [
|
||||
feature(),
|
||||
feature({
|
||||
id: 400,
|
||||
properties: {
|
||||
NAME: 'R-2508',
|
||||
TYPE_CODE: 'R',
|
||||
OBJECTID: 400,
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
assert.equal(rows.length, 2);
|
||||
assert.deepEqual(rows[0], {
|
||||
stableId: '310',
|
||||
name: 'P-56',
|
||||
typeCode: 'P',
|
||||
type: 'Prohibited',
|
||||
lowerAltitude: 'SFC',
|
||||
upperAltitude: '18,000 ft MSL',
|
||||
timesOfUse: 'CONTINUOUS',
|
||||
agency: 'WASHINGTON CENTER',
|
||||
city: 'WASHINGTON',
|
||||
state: 'DC',
|
||||
polygons: [[ring]],
|
||||
});
|
||||
assert.equal(rows[1].type, 'Restricted');
|
||||
assert.equal(rows[1].typeCode, 'R');
|
||||
});
|
||||
|
||||
test('altitudes come from VAL/UOM/CODE, not the TI/TNI/ANI qualifiers', () => {
|
||||
// P-40 and R-2508 as the FAA service publishes them.
|
||||
assert.equal(droneAirspaceAltitude('0', 'FT', 'SFC'), 'SFC');
|
||||
assert.equal(droneAirspaceAltitude('5000', 'FT', 'MSL'), '5,000 ft MSL');
|
||||
assert.equal(droneAirspaceAltitude('20000', 'FT', 'MSL'), '20,000 ft MSL');
|
||||
assert.equal(droneAirspaceAltitude('-9998', null, 'UNLTD'), 'Unlimited');
|
||||
assert.equal(droneAirspaceAltitude('1500', 'FT', 'SFC'), '1,500 ft AGL');
|
||||
assert.equal(droneAirspaceAltitude('180', 'FL', 'STD'), 'FL180');
|
||||
assert.equal(droneAirspaceAltitude('10000', 'FT', null), '10,000 ft');
|
||||
assert.equal(droneAirspaceAltitude(null, null, null), null);
|
||||
assert.equal(droneAirspaceAltitude('-9998', 'FT', 'MSL'), null);
|
||||
const [row] = normalizeDroneAirspaceSnapshot({
|
||||
features: [
|
||||
feature({
|
||||
properties: {
|
||||
NAME: 'R-2508',
|
||||
TYPE_CODE: 'R',
|
||||
OBJECTID: 400,
|
||||
UPPER_DESC: null,
|
||||
UPPER_VAL: '-9998',
|
||||
UPPER_UOM: null,
|
||||
UPPER_CODE: 'UNLTD',
|
||||
LOWER_VAL: '20000',
|
||||
LOWER_UOM: 'FT',
|
||||
LOWER_CODE: 'MSL',
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
assert.equal(row.lowerAltitude, '20,000 ft MSL');
|
||||
assert.equal(row.upperAltitude, 'Unlimited');
|
||||
});
|
||||
|
||||
test('MOA, warning and advisory codes are dropped, as are bad geometries', () => {
|
||||
const rows = normalizeDroneAirspaceSnapshot({
|
||||
features: [
|
||||
feature({ properties: { TYPE_CODE: 'MOA', OBJECTID: 1 } }),
|
||||
feature({ properties: { TYPE_CODE: 'W', OBJECTID: 2 } }),
|
||||
feature({ properties: { TYPE_CODE: 'A', OBJECTID: 3 } }),
|
||||
feature({ geometry: null, properties: { OBJECTID: 4 } }),
|
||||
feature({
|
||||
geometry: { type: 'Point', coordinates: [-77, 38] },
|
||||
properties: { OBJECTID: 5 },
|
||||
}),
|
||||
feature(),
|
||||
],
|
||||
});
|
||||
assert.equal(rows.length, 1);
|
||||
assert.equal(rows[0].name, 'P-56');
|
||||
});
|
||||
|
||||
test('duplicate ids and a missing collection reject or skip as documented', () => {
|
||||
const dup = normalizeDroneAirspaceSnapshot({
|
||||
features: [feature(), feature({ id: 311 })],
|
||||
});
|
||||
assert.equal(dup.length, 1);
|
||||
assert.equal(normalizeDroneAirspaceSnapshot({}), null);
|
||||
assert.equal(normalizeDroneAirspaceSnapshot(null), null);
|
||||
assert.equal(droneAirspaceTypeLabel('P'), 'Prohibited');
|
||||
assert.equal(droneAirspaceTypeLabel('R'), 'Restricted');
|
||||
assert.equal(droneAirspaceTypeLabel('MOA'), null);
|
||||
});
|
||||
|
||||
test("FAA's % line-break markers in times of use read as separators", () => {
|
||||
const timesOfUse = (TIMESOFUSE) =>
|
||||
normalizeDroneAirspaceSnapshot({
|
||||
features: [
|
||||
feature({
|
||||
properties: {
|
||||
NAME: 'R-2508',
|
||||
TYPE_CODE: 'R',
|
||||
OBJECTID: 400,
|
||||
TIMESOFUSE,
|
||||
},
|
||||
}),
|
||||
],
|
||||
})[0].timesOfUse;
|
||||
// The shape 56 live records carry: a marker after the semicolon.
|
||||
assert.equal(
|
||||
timesOfUse(
|
||||
'0700 - 2200 MON - FRI; 0800 - 1600 SAT - SUN; %OTHER TIMES BY NOTAM',
|
||||
),
|
||||
'0700 - 2200 MON - FRI; 0800 - 1600 SAT - SUN; OTHER TIMES BY NOTAM',
|
||||
);
|
||||
assert.equal(
|
||||
timesOfUse('SR - SS DAILY %OTHER TIMES BY NOTAM'),
|
||||
'SR - SS DAILY; OTHER TIMES BY NOTAM',
|
||||
);
|
||||
assert.equal(timesOfUse('%CONTINUOUS%'), 'CONTINUOUS');
|
||||
assert.equal(timesOfUse(' % '), null);
|
||||
});
|
||||
@@ -0,0 +1,38 @@
|
||||
import { readResponseJsonCapped } from '../../sources/httpBody.js';
|
||||
|
||||
/** Request a normalized snapshot through the bounded, same-origin FAA proxy. */
|
||||
export function createDroneAirspaceSource({
|
||||
fetchImpl = (...args) => globalThis.fetch(...args),
|
||||
} = {}) {
|
||||
/**
|
||||
* The rows with how fresh they are: the proxy answers from its last
|
||||
* snapshot, marked stale, while the FAA service is unreachable.
|
||||
* @returns {Promise<{rows: object[], stale: boolean, fetchedAt: number|null}>}
|
||||
*/
|
||||
async function getSnapshotDetail({ signal } = {}) {
|
||||
signal?.throwIfAborted();
|
||||
const response = await fetchImpl('/api/drone-airspace', { signal });
|
||||
if (!response.ok) throw new Error(`FAA SUA HTTP ${response.status}`);
|
||||
const payload = await readResponseJsonCapped(
|
||||
response,
|
||||
80 * 1024 * 1024,
|
||||
signal,
|
||||
);
|
||||
signal?.throwIfAborted();
|
||||
if (!Array.isArray(payload?.rows))
|
||||
throw new Error('Malformed drone airspace snapshot');
|
||||
return {
|
||||
rows: payload.rows,
|
||||
stale: payload.stale === true,
|
||||
fetchedAt: Number.isFinite(payload.fetchedAt) ? payload.fetchedAt : null,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
/** The zone rows (see getSnapshotDetail for staleness). */
|
||||
async getSnapshot(options = {}) {
|
||||
return (await getSnapshotDetail(options)).rows;
|
||||
},
|
||||
getSnapshotDetail,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { createDroneAirspaceSource } from './source.js';
|
||||
import { normalizeDroneAirspaceSnapshot } from './records.js';
|
||||
import { droneAirspaceProxy } from '../../../server/providers/droneAirspace.js';
|
||||
|
||||
const ring = [
|
||||
[-77.04, 38.89],
|
||||
[-77.03, 38.89],
|
||||
[-77.03, 38.9],
|
||||
[-77.04, 38.89],
|
||||
];
|
||||
const validPayload = {
|
||||
features: [
|
||||
{
|
||||
id: 310,
|
||||
geometry: { type: 'Polygon', coordinates: [ring] },
|
||||
properties: {
|
||||
NAME: 'P-56',
|
||||
TYPE_CODE: 'P',
|
||||
OBJECTID: 310,
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
test('a successful response yields normalized zone rows', async () => {
|
||||
let requested;
|
||||
const source = createDroneAirspaceSource({
|
||||
fetchImpl: async (url) => {
|
||||
requested = String(url);
|
||||
return Response.json({
|
||||
rows: normalizeDroneAirspaceSnapshot(validPayload),
|
||||
});
|
||||
},
|
||||
});
|
||||
const rows = await source.getSnapshot();
|
||||
assert.equal(rows.length, 1);
|
||||
assert.equal(rows[0].stableId, '310');
|
||||
assert.equal(requested, '/api/drone-airspace');
|
||||
});
|
||||
|
||||
test('a truncated response pages until the feed is complete', async () => {
|
||||
const pageRing = (id) => ({
|
||||
id,
|
||||
geometry: { type: 'Polygon', coordinates: [ring] },
|
||||
properties: { NAME: `P-${id}`, TYPE_CODE: 'P', OBJECTID: id },
|
||||
});
|
||||
const requests = [];
|
||||
let handler;
|
||||
const plugin = droneAirspaceProxy({
|
||||
fetchImpl: async (url) => {
|
||||
requests.push(new URL(String(url)).searchParams.get('resultOffset'));
|
||||
const page = requests.length;
|
||||
return Response.json({
|
||||
features: [pageRing(page)],
|
||||
properties: { exceededTransferLimit: page < 3 },
|
||||
});
|
||||
},
|
||||
});
|
||||
plugin.configureServer({
|
||||
middlewares: {
|
||||
use: (_path, callback) => {
|
||||
handler = callback;
|
||||
},
|
||||
},
|
||||
});
|
||||
let payload;
|
||||
await handler(
|
||||
{ url: '/', method: 'GET' },
|
||||
{
|
||||
writeHead(status) {
|
||||
assert.equal(status, 200);
|
||||
},
|
||||
end(body) {
|
||||
payload = JSON.parse(body);
|
||||
},
|
||||
},
|
||||
);
|
||||
const rows = payload.rows;
|
||||
assert.deepEqual(
|
||||
rows.map((row) => row.stableId),
|
||||
['1', '2', '3'],
|
||||
);
|
||||
assert.deepEqual(requests, [null, '1', '2']);
|
||||
});
|
||||
|
||||
test('an upstream failure surfaces its HTTP status', async () => {
|
||||
const source = createDroneAirspaceSource({
|
||||
fetchImpl: async () => ({ ok: false, status: 503 }),
|
||||
});
|
||||
await assert.rejects(source.getSnapshot(), /FAA SUA HTTP 503/);
|
||||
});
|
||||
|
||||
test('a malformed successful response is never accepted as an empty snapshot', async () => {
|
||||
for (const payload of [{}, { rows: null }, { rows: {} }]) {
|
||||
const source = createDroneAirspaceSource({
|
||||
fetchImpl: async () => Response.json(payload),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getSnapshot(),
|
||||
/Malformed drone airspace snapshot/,
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('the snapshot detail carries the proxy staleness and fetch time', async () => {
|
||||
const fetchedAt = Date.UTC(2026, 10, 3, 12);
|
||||
const rows = normalizeDroneAirspaceSnapshot(validPayload);
|
||||
const source = createDroneAirspaceSource({
|
||||
fetchImpl: async () => Response.json({ rows, stale: true, fetchedAt }),
|
||||
});
|
||||
assert.deepEqual(await source.getSnapshotDetail(), {
|
||||
rows,
|
||||
stale: true,
|
||||
fetchedAt,
|
||||
});
|
||||
assert.deepEqual(await source.getSnapshot(), rows);
|
||||
});
|
||||
@@ -0,0 +1,88 @@
|
||||
/**
|
||||
* Drapes the Active Fires heat raster over the globe as one full-extent
|
||||
* imagery tile on the active imagery host (globe or 3D-tiles), like the wind
|
||||
* layer's scalar field. Owns the canvas and the imagery layer; nothing else
|
||||
* in the fires layer touches imagery.
|
||||
*
|
||||
* `show` is only for the layer being on or off. The zoom hand-off fades
|
||||
* `alpha` instead: Cesium unmaps a hidden imagery layer from the globe
|
||||
* tiles and re-maps it when shown, so a show toggle at the band edge left
|
||||
* a beat with neither markers nor heat. At alpha 0 the layer stays mapped
|
||||
* and costs no draw.
|
||||
*/
|
||||
|
||||
const defaultCanvas = (width, height) => {
|
||||
const canvas = document.createElement('canvas');
|
||||
canvas.width = width;
|
||||
canvas.height = height;
|
||||
return canvas;
|
||||
};
|
||||
|
||||
export function createHeatImagery({
|
||||
cesium,
|
||||
getHost,
|
||||
createCanvas = defaultCanvas,
|
||||
}) {
|
||||
let raster = null;
|
||||
let layer = null;
|
||||
let collection = null;
|
||||
let show = true;
|
||||
let opacity = 1;
|
||||
|
||||
function detach() {
|
||||
if (layer && collection) collection.remove(layer, true);
|
||||
layer = null;
|
||||
collection = null;
|
||||
}
|
||||
|
||||
function attach() {
|
||||
detach();
|
||||
if (!raster) return;
|
||||
const host = getHost?.() ?? { collection: null, kind: 'none' };
|
||||
if (!host.collection) return;
|
||||
const canvas = createCanvas(raster.width, raster.height);
|
||||
const ctx = canvas.getContext('2d');
|
||||
const image = ctx.createImageData(raster.width, raster.height);
|
||||
image.data.set(raster.rgba);
|
||||
ctx.putImageData(image, 0, 0);
|
||||
const provider = new cesium.SingleTileImageryProvider({
|
||||
url: canvas.toDataURL('image/png'),
|
||||
tileWidth: raster.width,
|
||||
tileHeight: raster.height,
|
||||
rectangle: cesium.Rectangle.MAX_VALUE,
|
||||
});
|
||||
collection = host.collection;
|
||||
layer = collection.addImageryProvider(provider);
|
||||
layer.show = show;
|
||||
layer.alpha = opacity;
|
||||
collection.raiseToTop?.(layer);
|
||||
}
|
||||
|
||||
return {
|
||||
setRaster(next) {
|
||||
raster = next;
|
||||
attach();
|
||||
},
|
||||
/** True once a raster was handed over (painted or waiting for a host). */
|
||||
hasRaster() {
|
||||
return raster !== null;
|
||||
},
|
||||
setShow(value) {
|
||||
show = Boolean(value);
|
||||
if (layer) layer.show = show;
|
||||
},
|
||||
/** Hand-off fade, 0..1; the layer stays mapped at 0. */
|
||||
setOpacity(value) {
|
||||
opacity = Math.min(1, Math.max(0, Number(value) || 0));
|
||||
if (layer) layer.alpha = opacity;
|
||||
},
|
||||
rehome() {
|
||||
const host = getHost?.();
|
||||
if ((host?.collection ?? null) !== collection) attach();
|
||||
},
|
||||
destroy() {
|
||||
detach();
|
||||
raster = null;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { createHeatImagery } from './heatImagery.js';
|
||||
import { buildHeatRaster } from '../../data/firmsHeatRaster.js';
|
||||
import { HEAT_RASTER } from './policy.js';
|
||||
|
||||
function harness() {
|
||||
const layers = [];
|
||||
const removed = [];
|
||||
const collection = {
|
||||
addImageryProvider(provider) {
|
||||
const layer = { provider, show: true, alpha: 1 };
|
||||
layers.push(layer);
|
||||
return layer;
|
||||
},
|
||||
remove(layer, destroy) {
|
||||
layers.splice(layers.indexOf(layer), 1);
|
||||
removed.push({ layer, destroy });
|
||||
},
|
||||
raiseToTop() {},
|
||||
};
|
||||
let host = { collection, kind: 'globe' };
|
||||
const cesium = {
|
||||
Rectangle: { MAX_VALUE: { max: true } },
|
||||
SingleTileImageryProvider: class {
|
||||
constructor(options) {
|
||||
this.options = options;
|
||||
}
|
||||
},
|
||||
};
|
||||
const createCanvas = (w, h) => ({
|
||||
width: w,
|
||||
height: h,
|
||||
getContext: () => ({
|
||||
createImageData: (cw, ch) => ({
|
||||
data: new Uint8ClampedArray(cw * ch * 4),
|
||||
}),
|
||||
putImageData() {},
|
||||
}),
|
||||
toDataURL: () => 'data:image/png;base64,AAAA',
|
||||
});
|
||||
const imagery = createHeatImagery({
|
||||
cesium,
|
||||
getHost: () => host,
|
||||
createCanvas,
|
||||
});
|
||||
return { imagery, layers, removed, collection, setHost: (h) => (host = h) };
|
||||
}
|
||||
|
||||
const raster = { width: 4, height: 2, rgba: new Uint8ClampedArray(32) };
|
||||
|
||||
test('setRaster drapes one full-globe tile and replaces it on the next build', () => {
|
||||
const h = harness();
|
||||
h.imagery.setRaster(raster);
|
||||
assert.equal(h.layers.length, 1);
|
||||
assert.deepEqual(h.layers[0].provider.options.rectangle, { max: true });
|
||||
assert.equal(h.layers[0].provider.options.tileWidth, 4);
|
||||
h.imagery.setRaster(raster);
|
||||
assert.equal(h.layers.length, 1, 'never two heat layers');
|
||||
assert.equal(h.removed[0].destroy, true);
|
||||
});
|
||||
|
||||
test('setShow toggles without rebuilding', () => {
|
||||
const h = harness();
|
||||
h.imagery.setRaster(raster);
|
||||
const layer = h.layers[0];
|
||||
h.imagery.setShow(false);
|
||||
assert.equal(layer.show, false);
|
||||
h.imagery.setShow(true);
|
||||
assert.equal(h.layers[0], layer);
|
||||
assert.equal(layer.show, true);
|
||||
});
|
||||
|
||||
test('setOpacity fades the same layer and survives a rebuild', () => {
|
||||
const h = harness();
|
||||
h.imagery.setRaster(raster);
|
||||
const layer = h.layers[0];
|
||||
h.imagery.setOpacity(0);
|
||||
assert.equal(layer.alpha, 0);
|
||||
assert.equal(layer.show, true, 'a faded layer stays mapped');
|
||||
h.imagery.setOpacity(0.25);
|
||||
assert.equal(h.layers[0], layer);
|
||||
assert.equal(layer.alpha, 0.25);
|
||||
h.imagery.setRaster(raster);
|
||||
assert.equal(h.layers[0].alpha, 0.25, 'a rebuilt layer keeps the fade');
|
||||
h.imagery.setOpacity(7);
|
||||
assert.equal(h.layers[0].alpha, 1);
|
||||
});
|
||||
|
||||
test('no imagery host keeps nothing draped; rehome brings it back', () => {
|
||||
const h = harness();
|
||||
h.setHost({ collection: null, kind: 'none' });
|
||||
h.imagery.setRaster(raster);
|
||||
assert.equal(h.layers.length, 0);
|
||||
h.setHost({ collection: h.collection, kind: 'globe' });
|
||||
h.imagery.rehome();
|
||||
assert.equal(h.layers.length, 1);
|
||||
});
|
||||
|
||||
test('destroy removes the layer', () => {
|
||||
const h = harness();
|
||||
h.imagery.setRaster(raster);
|
||||
h.imagery.destroy();
|
||||
assert.equal(h.layers.length, 0);
|
||||
});
|
||||
|
||||
test('the shipped raster paints a lone weak fire as a distinct spot', () => {
|
||||
// A hot cluster elsewhere sets the scale, as Africa does on real data.
|
||||
const fires = [{ lat: 0, lon: 0, frp: 5 }];
|
||||
for (let i = 0; i < 40; i++) {
|
||||
fires.push({ lat: -10 + (i % 5) * 0.1, lon: 25 + i * 0.05, frp: 300 });
|
||||
}
|
||||
const r = buildHeatRaster(fires, HEAT_RASTER);
|
||||
const y = Math.floor((90 / 180) * r.height);
|
||||
const painted = [];
|
||||
for (let x = 0; x < r.width; x++) {
|
||||
const lon = ((x + 0.5) / r.width) * 360 - 180;
|
||||
if (Math.abs(lon) < 5 && r.rgba[(y * r.width + x) * 4 + 3] > 0) {
|
||||
painted.push(x);
|
||||
}
|
||||
}
|
||||
const kmPerPx = 40075 / r.width;
|
||||
assert.ok(painted.length > 0, 'the weak fire still shows');
|
||||
assert.ok(
|
||||
painted.length * kmPerPx <= 100,
|
||||
`spot ${Math.round(painted.length * kmPerPx)} km wide`,
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,44 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { createLifecycle } from './lifecycle.js';
|
||||
|
||||
test('reenabling an empty filtered layer never reveals the retained pre-filter heat raster', async () => {
|
||||
let shown = false;
|
||||
const noop = () => {};
|
||||
const layerState = {
|
||||
_enabled: false,
|
||||
_viewer: {},
|
||||
_dataSource: {},
|
||||
_fires: [],
|
||||
_loading: true,
|
||||
_pickIndexById: new Map(),
|
||||
_heatImagery: {
|
||||
setShow(v) {
|
||||
shown = v;
|
||||
},
|
||||
},
|
||||
};
|
||||
const lifecycle = createLifecycle({
|
||||
layerState,
|
||||
services: {
|
||||
picking: { registerPickOwner: noop, unregisterPickOwner: noop },
|
||||
sprites: { restoreSpriteOrderOnEnable: noop },
|
||||
context: { clearSelectedEntityContextForLayer: noop },
|
||||
},
|
||||
config: { id: 'local-firms', overlayHost: { setVisible: noop } },
|
||||
components: {
|
||||
rendering: { applyHandoffFade: noop },
|
||||
viewport: { installLodWatcher: noop, installMoveEndWatcher: noop },
|
||||
selection: { installClickHandler: noop },
|
||||
},
|
||||
});
|
||||
await lifecycle.methods.enable(layerState._viewer);
|
||||
assert.equal(
|
||||
shown,
|
||||
false,
|
||||
'empty current set must keep the old raster hidden while refresh is pending',
|
||||
);
|
||||
layerState._fires = [{ frp: null, confidence: null }];
|
||||
await lifecycle.methods.enable(layerState._viewer);
|
||||
assert.equal(shown, true, 'nonempty sets still resume their raster');
|
||||
});
|
||||
@@ -1,5 +1,6 @@
|
||||
import { adaptFirmsRecords } from '../../data/firmsAdapt.js';
|
||||
import { fireDetectionKey } from '../../data/firmsLabels.js';
|
||||
import { filterFires } from '../../data/firmsIntensity.js';
|
||||
import { msg } from '../../i18n/index.js';
|
||||
|
||||
export function createIngestion({
|
||||
@@ -40,12 +41,13 @@ export function createIngestion({
|
||||
layerState._stale = Boolean(payload?.stale);
|
||||
const previousSelection = layerState._selectedFire;
|
||||
layerState._selectedFire = null;
|
||||
layerState._fires = adaptFirmsRecords(payload?.fires);
|
||||
layerState._cellCacheByGrid.clear(); // aggregation is per-dataset — new fires, new cells
|
||||
layerState._firesByFrp = [...layerState._fires].sort(
|
||||
layerState._allFires = adaptFirmsRecords(payload?.fires);
|
||||
// Sorted once per payload; applyFilter only filters, so a slider drag
|
||||
// over 200k detections never re-sorts.
|
||||
layerState._allFiresByFrp = [...layerState._allFires].sort(
|
||||
(a, b) => b.frp - a.frp,
|
||||
);
|
||||
layerState._count = layerState._fires.length;
|
||||
applyFilter();
|
||||
// Data age, not response age: a stale proxy payload truthfully reads old.
|
||||
layerState._lastUpdate = Number.isFinite(payload?.fetchedAt)
|
||||
? payload.fetchedAt
|
||||
@@ -65,6 +67,7 @@ export function createIngestion({
|
||||
}
|
||||
components.rendering.renderCurrentLod(true);
|
||||
if (reselected) components.selection.selectFire(reselected, false);
|
||||
layerState._rowControlsListener?.();
|
||||
} catch (error) {
|
||||
if (
|
||||
request.signal.aborted ||
|
||||
@@ -83,6 +86,26 @@ export function createIngestion({
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the intensity filter over the loaded payload. This is the ONE place
|
||||
* the shown set is derived: `_fires` / `_firesByFrp` feed markers, cards,
|
||||
* the heatmap, the context store, the top-fires query and the analyst
|
||||
* records, so none of them can disagree about which fires exist. Cells and
|
||||
* the heat raster are built per shown set, so their caches go with it.
|
||||
*/
|
||||
|
||||
function applyFilter() {
|
||||
layerState._fires = filterFires(layerState._allFires, layerState._filter);
|
||||
layerState._cellCacheByGrid.clear();
|
||||
layerState._heatRaster = null;
|
||||
layerState._firesByFrp = filterFires(
|
||||
layerState._allFiresByFrp,
|
||||
layerState._filter,
|
||||
);
|
||||
layerState._count = layerState._fires.length;
|
||||
layerState._totalCount = layerState._allFires.length;
|
||||
}
|
||||
|
||||
/**
|
||||
* Find the record in the freshly-loaded set matching a previous selection.
|
||||
* Identity is the detection itself (lat/lon/acquisition time) — indices
|
||||
@@ -109,5 +132,5 @@ export function createIngestion({
|
||||
},
|
||||
};
|
||||
|
||||
return { loadHeatmap, findMatchingFire, methods };
|
||||
return { loadHeatmap, applyFilter, findMatchingFire, methods };
|
||||
}
|
||||
@@ -14,6 +14,20 @@ export function createLifecycle({
|
||||
const { id, overlayHost } = config;
|
||||
|
||||
const methods = {
|
||||
/**
|
||||
* Shell services: `imageryHost()` resolves where draped imagery goes on
|
||||
* the active map stack (globe or 3D tiles, src/maps/imageryHost.js). The
|
||||
* heatmap moves with it; without a host it drapes on viewer.imageryLayers.
|
||||
* @param {{imageryHost?: () => {collection: ?Object, kind: string}}|null} services
|
||||
*/
|
||||
attachShellServices(services) {
|
||||
layerState._imageryHost =
|
||||
typeof services?.imageryHost === 'function'
|
||||
? services.imageryHost
|
||||
: null;
|
||||
layerState._heatImagery?.rehome();
|
||||
},
|
||||
|
||||
init(viewer) {
|
||||
if (layerState._destroyed) return;
|
||||
layerState._viewer = viewer;
|
||||
@@ -40,6 +54,10 @@ export function createLifecycle({
|
||||
layerState._billboards.show = true;
|
||||
}
|
||||
overlayHost.setVisible(FIRMS_OVERLAY_SOURCE_ID, true);
|
||||
// A filter can leave an old raster cached while the current set is empty.
|
||||
layerState._heatImagery?.setShow(layerState._fires.length > 0);
|
||||
// The camera can have crossed the hand-off while the layer was off.
|
||||
components.rendering.applyHandoffFade(true);
|
||||
components.viewport.installLodWatcher();
|
||||
components.viewport.installMoveEndWatcher();
|
||||
components.selection.installClickHandler();
|
||||
@@ -64,6 +82,7 @@ export function createLifecycle({
|
||||
components.selection.clearFireSelection();
|
||||
if (layerState._dataSource) layerState._dataSource.show = false;
|
||||
if (layerState._billboards) layerState._billboards.show = false;
|
||||
layerState._heatImagery?.setShow(false);
|
||||
overlayHost.clearSource(FIRMS_OVERLAY_SOURCE_ID);
|
||||
overlayHost.setVisible(FIRMS_OVERLAY_SOURCE_ID, false);
|
||||
clearSelectedEntityContextForLayer(id);
|
||||
@@ -91,10 +110,21 @@ export function createLifecycle({
|
||||
components.rendering.removeDetectionCollections(viewer);
|
||||
components.selection.clearContextRegistrations();
|
||||
clearSelectedEntityContextForLayer(id);
|
||||
layerState._allFires = [];
|
||||
layerState._allFiresByFrp = [];
|
||||
layerState._fires = [];
|
||||
layerState._firesByFrp = [];
|
||||
layerState._cellCacheByGrid.clear();
|
||||
clearTimeout(layerState._heatRebuildTimer);
|
||||
layerState._heatRebuildTimer = null;
|
||||
layerState._heatImagery?.destroy();
|
||||
layerState._heatImagery = null;
|
||||
layerState._heatRaster = null;
|
||||
layerState._handoffHeat = -1;
|
||||
layerState._imageryHost = null;
|
||||
layerState._count = 0;
|
||||
layerState._totalCount = 0;
|
||||
layerState._rowControlsListener = null;
|
||||
layerState._cellCount = 0;
|
||||
layerState._lastUpdate = null;
|
||||
layerState._keyRequired = false;
|
||||
|
||||
+43
-27
@@ -6,6 +6,7 @@ import {
|
||||
accentForSeverity,
|
||||
formatFrpMw,
|
||||
} from '../../data/firmsLabels.js';
|
||||
import { FRP_RAMP, frpRampStop } from '../../data/firmsIntensity.js';
|
||||
import {
|
||||
VIEW_PADDING,
|
||||
DETECTION_COLOR_STOPS,
|
||||
@@ -119,27 +120,30 @@ export function createModel({
|
||||
);
|
||||
}
|
||||
|
||||
function heatColor(value, alpha) {
|
||||
if (value > 0.72) return Cesium.Color.RED.withAlpha(alpha);
|
||||
if (value > 0.42) return Cesium.Color.ORANGE.withAlpha(alpha);
|
||||
return Cesium.Color.YELLOW.withAlpha(alpha);
|
||||
/**
|
||||
* The ramp stop for a fire radiative power (stepped, weakest first).
|
||||
* Intensity alone drives the color: confidence feeds the card text and the
|
||||
* switch, brightness is unreliable (saturates at 367 K) — see HAL-675.
|
||||
* @param {number} frp - Megawatts.
|
||||
* @returns {{name: string, minFrp: number, color: Cesium.Color}}
|
||||
*/
|
||||
|
||||
function frpColorStop(frp) {
|
||||
const name = frpRampStop(frp).name;
|
||||
return (
|
||||
DETECTION_COLOR_STOPS.find((stop) => stop.name === name) ||
|
||||
DETECTION_COLOR_STOPS[0]
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pick a sprite color stop from FRP + confidence, reusing the same
|
||||
* yellow → orange → red thresholds as the aggregated heat cells.
|
||||
* Pick a sprite color stop for one detection from its FRP on the shared ramp.
|
||||
* @param {Object} fire - Detection record.
|
||||
* @returns {{name: string, color: Cesium.Color}}
|
||||
*/
|
||||
|
||||
function detectionColorStop(fire) {
|
||||
const heat = Math.min(
|
||||
1,
|
||||
Math.sqrt(Math.max(0, fire.frp) / 150) * 0.85 + fire.confidence * 0.15,
|
||||
);
|
||||
if (heat > 0.72) return DETECTION_COLOR_STOPS[0];
|
||||
if (heat > 0.42) return DETECTION_COLOR_STOPS[1];
|
||||
return DETECTION_COLOR_STOPS[2];
|
||||
return frpColorStop(fire?.frp);
|
||||
}
|
||||
|
||||
/** FRP → core marker pixel size, clamped to 8..28px. */
|
||||
@@ -227,6 +231,19 @@ export function createModel({
|
||||
return fire.position;
|
||||
}
|
||||
|
||||
/**
|
||||
* The anchor already built for a detection, without the floor lookup;
|
||||
* for the far marker band, where floors are never warmed and the height
|
||||
* difference is invisible, so tens of thousands of markers skip a cache
|
||||
* read each per rebuild. Builds one through {@link firePosition} once.
|
||||
* @param {Object} fire - Detection record.
|
||||
* @returns {Cesium.Cartesian3}
|
||||
*/
|
||||
|
||||
function fireBuiltPosition(fire) {
|
||||
return fire.position ?? firePosition(fire);
|
||||
}
|
||||
|
||||
/**
|
||||
* Occlusion-test anchor for one detection. Returns the render position
|
||||
* outright for anchors comfortably above the ellipsoid (the common case) and
|
||||
@@ -234,11 +251,11 @@ export function createModel({
|
||||
* NEVER feeds rendering: the datum-correct anchor from {@link firePosition}
|
||||
* is what the sprite and the card are drawn at.
|
||||
* @param {Object} fire - Detection record.
|
||||
* @param {Cesium.Cartesian3} [position] Its render anchor, if at hand.
|
||||
* @returns {Cesium.Cartesian3}
|
||||
*/
|
||||
|
||||
function fireCullPosition(fire) {
|
||||
const position = firePosition(fire);
|
||||
function fireCullPosition(fire, position = firePosition(fire)) {
|
||||
if (fire.positionHeight >= CULL_LIFT_THRESHOLD_M) return position;
|
||||
if (!fire.cullPosition) {
|
||||
fire.cullPosition = Cesium.Cartesian3.fromDegrees(
|
||||
@@ -398,8 +415,8 @@ export function createModel({
|
||||
|
||||
/**
|
||||
* Card model for an aggregated heat cell, e.g. title "14 FIRES", detail
|
||||
* "max 210 MW · new 3h". Accent comes from the candidate (heat-normalized
|
||||
* score is only known at renderCells time). Exported for unit tests.
|
||||
* "max 210 MW · new 3h". Accent comes from the candidate (renderHeat sets
|
||||
* it with {@link cellCardAccent}). Exported for unit tests.
|
||||
* @param {{cell: Object, position: Cesium.Cartesian3, accent: string}} candidate
|
||||
* @param {number} nowMs - Current epoch milliseconds.
|
||||
* @returns {Object} firmsLabels entry.
|
||||
@@ -417,7 +434,7 @@ export function createModel({
|
||||
position: candidate.position,
|
||||
cullPosition: candidate.cullPosition || candidate.position,
|
||||
gapPx: 10,
|
||||
accent: candidate.accent || accentForSeverity('yellow'),
|
||||
accent: candidate.accent || accentForSeverity(FRP_RAMP[0].name),
|
||||
// The count picks the plural form of the language ("حريقان (2)",
|
||||
// "14 حريقًا", "14 ПОЖАРОВ"); the card shows it in capitals like the
|
||||
// other card titles.
|
||||
@@ -464,16 +481,14 @@ export function createModel({
|
||||
}
|
||||
|
||||
/**
|
||||
* Heat-normalized cell score → severity accent, mirroring heatColor's
|
||||
* red/orange/yellow thresholds.
|
||||
* @param {number} normalized - 0..1 normalized heat score.
|
||||
* Cell card accent: the cell's strongest fire on the FRP ramp, the same
|
||||
* color its markers take once the camera is close enough to show them.
|
||||
* @param {{maxFrp?: number}} cell - Aggregated cell.
|
||||
* @returns {string} "r, g, b" accent string.
|
||||
*/
|
||||
|
||||
function cellAccent(normalized) {
|
||||
if (normalized > 0.72) return accentForSeverity('red');
|
||||
if (normalized > 0.42) return accentForSeverity('orange');
|
||||
return accentForSeverity('yellow');
|
||||
function cellCardAccent(cell) {
|
||||
return accentForSeverity(frpColorStop(cell?.maxFrp ?? 0).name);
|
||||
}
|
||||
|
||||
/** Coordinate line like "30.512°N 75.831°E". */
|
||||
@@ -579,12 +594,13 @@ export function createModel({
|
||||
boundsContainPoint,
|
||||
cellIntersectsBounds,
|
||||
heatScore,
|
||||
heatColor,
|
||||
frpColorStop,
|
||||
detectionColorStop,
|
||||
frpPixelSize,
|
||||
sizeBucket,
|
||||
glowSprite,
|
||||
firePosition,
|
||||
fireBuiltPosition,
|
||||
fireCullPosition,
|
||||
cellCullPosition,
|
||||
applyHorizonCull,
|
||||
@@ -593,7 +609,7 @@ export function createModel({
|
||||
buildFireCard,
|
||||
buildCellCard,
|
||||
applyFirmsOverlayPolicy,
|
||||
cellAccent,
|
||||
cellCardAccent,
|
||||
formatLatLon,
|
||||
formatFrp,
|
||||
formatAge,
|
||||
|
||||
+57
-13
@@ -1,4 +1,5 @@
|
||||
import { FIRMS_AMBIENT_COHORT_LIMIT } from '../../data/firmsLabels.js';
|
||||
import { FRP_RAMP } from '../../data/firmsIntensity.js';
|
||||
import * as Cesium from 'cesium';
|
||||
|
||||
/** Client poll interval; the proxy's 30 min TTL is what guards upstream quota. */
|
||||
@@ -6,9 +7,10 @@ import * as Cesium from 'cesium';
|
||||
export const REFRESH_INTERVAL_MS = 600_000;
|
||||
|
||||
/**
|
||||
* LOD bands keyed by camera height. `cells` bands render aggregated
|
||||
* ground-clamped heat rectangles; `detections` bands (< ~750km plus the
|
||||
* local band) render individual fire detections as glow-sprite billboards.
|
||||
* LOD bands keyed by camera height. `heat` bands (above ~4,500 km) drape a
|
||||
* Snap Map–style heatmap over the globe (firmsHeatRaster.js); their
|
||||
* `gridDegrees` aggregation only feeds the "N FIRES" cards. `detections`
|
||||
* bands render individual fire detections as glow-sprite billboards.
|
||||
* Labels in every band go through the shared screen-space greedy declutter
|
||||
* (hard cap MAX_AMBIENT_LABELS) — there are no per-band label knobs.
|
||||
*/
|
||||
@@ -17,24 +19,28 @@ export const LOD_LEVELS = [
|
||||
{
|
||||
id: 'global',
|
||||
minHeight: 9000000,
|
||||
mode: 'cells',
|
||||
mode: 'heat',
|
||||
gridDegrees: 2.0,
|
||||
maxCells: 1800,
|
||||
labelDistance: 12000000,
|
||||
},
|
||||
{
|
||||
id: 'regional',
|
||||
minHeight: 3000000,
|
||||
mode: 'cells',
|
||||
minHeight: 4500000,
|
||||
mode: 'heat',
|
||||
gridDegrees: 1.0,
|
||||
maxCells: 3600,
|
||||
labelDistance: 8500000,
|
||||
},
|
||||
{
|
||||
// Up to 40,000 markers: at the 3,600 km end of the hand-off the padded
|
||||
// view over Africa, the densest region, holds ~40,000 detections, and a
|
||||
// tighter cap left the heatmap's weak spots dissolving into nothing.
|
||||
// A rebuild of that many costs ~60 ms, only there.
|
||||
id: 'local',
|
||||
minHeight: 750000,
|
||||
mode: 'detections',
|
||||
maxDetections: 2500,
|
||||
maxDetections: 40000,
|
||||
labelDistance: 4500000,
|
||||
},
|
||||
{
|
||||
@@ -46,6 +52,38 @@ export const LOD_LEVELS = [
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* Global heat raster for the `heat` bands: ≈0.09° (≈10 km) per pixel and a
|
||||
* one-pixel Gaussian σ, so a lone fire is a spot about the size of its
|
||||
* marker near the hand-off and the two cross-fade without a jump;
|
||||
* neighbours merge only when they nearly touch (σ 3 on a 2048 grid smeared
|
||||
* each fire over ~200 km). Built once per data refresh or filter change,
|
||||
* never per camera move.
|
||||
*/
|
||||
|
||||
export const HEAT_RASTER = Object.freeze({
|
||||
width: 4096,
|
||||
height: 2048,
|
||||
sigmaPx: 1,
|
||||
});
|
||||
|
||||
/**
|
||||
* Camera heights, in metres, over which the heatmap and the markers
|
||||
* cross-fade around the 4,500 km band edge: markers alone below `from`,
|
||||
* heatmap alone above `to`. Wider than the ±10 % band hysteresis, so
|
||||
* whichever band is active inside it, both layers are already built.
|
||||
*/
|
||||
|
||||
export const HANDOFF_FADE = Object.freeze({ from: 3_600_000, to: 5_400_000 });
|
||||
|
||||
/**
|
||||
* Trailing delay before a stale heatmap is rebuilt while one is already on
|
||||
* screen: a slider drag fires many filter changes, and a build plus PNG
|
||||
* encode costs a few hundred milliseconds. The first paint is immediate.
|
||||
*/
|
||||
|
||||
export const HEAT_REBUILD_MS = 150;
|
||||
|
||||
export const LOD_CHECK_MS = 650;
|
||||
|
||||
/** +/-10% hysteresis on LOD band edges so slow zooms don't thrash rebuilds. */
|
||||
@@ -88,10 +126,16 @@ export const CULL_LIFT_THRESHOLD_M = 10;
|
||||
|
||||
export const CULL_LIFT_M = 12;
|
||||
|
||||
/** Color stops shared by cell heat fills and detection glow sprites. */
|
||||
/**
|
||||
* Color stops for detection glow sprites and card accents: the
|
||||
* six-stop ember → white-hot FRP ramp (firmsIntensity.js), weakest first, as Cesium
|
||||
* colors. Stop names key the glow-sprite cache and the card accents.
|
||||
*/
|
||||
|
||||
export const DETECTION_COLOR_STOPS = [
|
||||
{ name: 'red', color: Cesium.Color.RED },
|
||||
{ name: 'orange', color: Cesium.Color.ORANGE },
|
||||
{ name: 'yellow', color: Cesium.Color.YELLOW },
|
||||
];
|
||||
export const DETECTION_COLOR_STOPS = FRP_RAMP.map((stop) =>
|
||||
Object.freeze({
|
||||
name: stop.name,
|
||||
minFrp: stop.minFrp,
|
||||
color: Cesium.Color.fromCssColorString(stop.hex),
|
||||
}),
|
||||
);
|
||||
+161
-2
@@ -1,6 +1,18 @@
|
||||
import { fireDetectionKey } from '../../data/firmsLabels.js';
|
||||
import { t } from '../../i18n/index.js';
|
||||
import { REFRESH_INTERVAL_MS } from './policy.js';
|
||||
import {
|
||||
FIRMS_CONFIDENCE_MODES,
|
||||
FRP_SLIDER_TICKS,
|
||||
firePassesFilter,
|
||||
frpForSliderPosition,
|
||||
normalizeFireFilter,
|
||||
rampTrackGradient,
|
||||
sliderPositionForFrp,
|
||||
} from '../../data/firmsIntensity.js';
|
||||
import { formatNumber, t } from '../../i18n/index.js';
|
||||
import { LOD_LEVELS, REFRESH_INTERVAL_MS } from './policy.js';
|
||||
|
||||
/** Slider resolution: whole-percent positions along the log axis. */
|
||||
const SLIDER_STEPS = 1000;
|
||||
|
||||
export function createQueries({
|
||||
layerState,
|
||||
@@ -11,6 +23,25 @@ export function createQueries({
|
||||
}) {
|
||||
const { id, name, icon, source } = config;
|
||||
|
||||
/** Whole-megawatt label for a slider value or tick ("0", "20", "1 000"). */
|
||||
function frpLabel(frp) {
|
||||
return formatNumber(frp, { maximumFractionDigits: 0 });
|
||||
}
|
||||
|
||||
const confidenceLabels = () => ({
|
||||
all: t('All', { context: 'fire confidence filter' }),
|
||||
nominal: t('Nominal+', { context: 'fire confidence filter' }),
|
||||
high: t('High', { context: 'fire confidence filter' }),
|
||||
});
|
||||
|
||||
const confidenceTitles = () => ({
|
||||
all: t(
|
||||
'Every detection — many of the strongest fires are rated low confidence',
|
||||
),
|
||||
nominal: t('Nominal and high confidence detections'),
|
||||
high: t('High confidence detections only'),
|
||||
});
|
||||
|
||||
const methods = {
|
||||
/** Return the selected detection as a plain record for application consumers. */
|
||||
getSelectedInfo() {
|
||||
@@ -51,6 +82,110 @@ export function createQueries({
|
||||
// not this interval — is what protects the upstream FIRMS quota).
|
||||
updateInterval: REFRESH_INTERVAL_MS,
|
||||
|
||||
/**
|
||||
* The intensity filter as layer options (share token `w`, owner
|
||||
* `local-firms` in layerState.js).
|
||||
* @returns {{minFrp: number, confidence: string}}
|
||||
*/
|
||||
getParams() {
|
||||
return { ...layerState._filter };
|
||||
},
|
||||
|
||||
/**
|
||||
* Apply a (partial) intensity filter. Invalid fields keep their current
|
||||
* value. The filter runs in one place (ingestion.applyFilter) and the LOD
|
||||
* rebuild re-derives markers, cells, cards and context registrations from
|
||||
* the shown set; a selected fire that no longer passes is deselected.
|
||||
* @param {{minFrp?: number, confidence?: string}} params
|
||||
* @returns {boolean} True — the request is always accepted.
|
||||
*/
|
||||
setParams(params = {}) {
|
||||
const next = normalizeFireFilter(params, layerState._filter);
|
||||
if (
|
||||
next.minFrp === layerState._filter.minFrp &&
|
||||
next.confidence === layerState._filter.confidence
|
||||
)
|
||||
return true;
|
||||
layerState._filter = next;
|
||||
if (!layerState._allFires.length) return true;
|
||||
components.ingestion.applyFilter();
|
||||
if (
|
||||
layerState._selectedFire &&
|
||||
!firePassesFilter(layerState._selectedFire, next)
|
||||
) {
|
||||
components.selection.clearFireSelection();
|
||||
}
|
||||
if (layerState._enabled) components.rendering.renderCurrentLod(true);
|
||||
layerState._rowControlsListener?.();
|
||||
return true;
|
||||
},
|
||||
|
||||
/**
|
||||
* Row controls under the Active Fires row: the log-scale minimum-FRP
|
||||
* slider whose track is painted with the intensity ramp (so it doubles as
|
||||
* the legend), the All / Nominal+ / High confidence switch, and the
|
||||
* "N of M shown" counter.
|
||||
*/
|
||||
getRowControls() {
|
||||
const { minFrp, confidence } = layerState._filter;
|
||||
const labels = confidenceLabels();
|
||||
const titles = confidenceTitles();
|
||||
const shown = layerState._count;
|
||||
const total = layerState._totalCount;
|
||||
return {
|
||||
slider: {
|
||||
id: 'min-frp',
|
||||
label: t('Fire intensity (FRP)'),
|
||||
ariaLabel: t('Minimum fire radiative power, megawatts'),
|
||||
valueText:
|
||||
minFrp > 0
|
||||
? t('≥ {value} MW', { value: frpLabel(minFrp) })
|
||||
: t('All', { context: 'fire intensity filter' }),
|
||||
min: 0,
|
||||
max: SLIDER_STEPS,
|
||||
step: 1,
|
||||
value: Math.round(sliderPositionForFrp(minFrp) * SLIDER_STEPS),
|
||||
track: rampTrackGradient(),
|
||||
ticks: FRP_SLIDER_TICKS.map((frp) => ({
|
||||
at: sliderPositionForFrp(frp),
|
||||
label: frpLabel(frp),
|
||||
})),
|
||||
params: (value) => ({
|
||||
minFrp: frpForSliderPosition(Number(value) / SLIDER_STEPS),
|
||||
}),
|
||||
},
|
||||
segmented: {
|
||||
id: 'confidence',
|
||||
label: t('Confidence'),
|
||||
ariaLabel: t('Detection confidence'),
|
||||
options: FIRMS_CONFIDENCE_MODES.map((mode) => ({
|
||||
id: `confidence-${mode}`,
|
||||
label: labels[mode],
|
||||
title: titles[mode],
|
||||
active: mode === confidence,
|
||||
params: { confidence: mode },
|
||||
})),
|
||||
},
|
||||
info: total
|
||||
? t('{shown} of {total} shown', {
|
||||
shown: formatNumber(shown),
|
||||
total: formatNumber(total),
|
||||
})
|
||||
: '',
|
||||
};
|
||||
},
|
||||
|
||||
/**
|
||||
* Install the panel's "row controls changed" callback: a load or a filter
|
||||
* change moves the counter, and nothing else repaints the row before the
|
||||
* next scheduled refresh.
|
||||
* @param {(() => void)|null} listener
|
||||
*/
|
||||
setRowControlsListener(listener) {
|
||||
layerState._rowControlsListener =
|
||||
typeof listener === 'function' ? listener : null;
|
||||
},
|
||||
|
||||
/**
|
||||
* Layer stats for the data panel. Degraded feed states surface through
|
||||
* `error` (established qa-failstate pattern: a dead feed must never look
|
||||
@@ -84,7 +219,9 @@ export function createQueries({
|
||||
});
|
||||
}
|
||||
return {
|
||||
// Shown (filtered) detections; `total` is the loaded payload.
|
||||
count: layerState._count,
|
||||
total: layerState._totalCount,
|
||||
cells: layerState._cellCount,
|
||||
lastUpdate: layerState._lastUpdate,
|
||||
loading: layerState._loading,
|
||||
@@ -172,12 +309,34 @@ export function createQueries({
|
||||
return result;
|
||||
},
|
||||
|
||||
/** Test seam: render one named LOD band against a near-global view. */
|
||||
_renderLodForTest(lodId) {
|
||||
components.rendering.renderBand(
|
||||
LOD_LEVELS.find((level) => level.id === lodId),
|
||||
null,
|
||||
);
|
||||
},
|
||||
|
||||
/** Test seam: one frame of the hand-off fade at the current camera. */
|
||||
_applyHandoffFadeForTest() {
|
||||
components.rendering.applyHandoffFade();
|
||||
},
|
||||
|
||||
/** Test seam: entities drawn by the layer's data source. */
|
||||
_entityCountForTest() {
|
||||
return layerState._dataSource?.entities?.values?.length ?? 0;
|
||||
},
|
||||
|
||||
/** Test seam that binds the production click path and indexes. */
|
||||
_bindInteractionForTest(viewer, fires = []) {
|
||||
layerState._viewer = viewer;
|
||||
layerState._enabled = true;
|
||||
layerState._allFires = fires;
|
||||
layerState._allFiresByFrp = [...fires];
|
||||
layerState._fires = fires;
|
||||
layerState._firesByFrp = [...fires];
|
||||
layerState._count = fires.length;
|
||||
layerState._totalCount = fires.length;
|
||||
layerState._pickIndexById.clear();
|
||||
layerState._labelLodDistance = 1e7;
|
||||
layerState._labelCandidates = fires.map((fire) => {
|
||||
|
||||
+191
-83
@@ -1,7 +1,21 @@
|
||||
import * as Cesium from 'cesium';
|
||||
import { FIRMS_OVERLAY_SOURCE_ID } from '../../data/firmsLabels.js';
|
||||
import { horizonOccluder } from '../../data/iconOrientation.js';
|
||||
import { LOD_LEVELS, CONTEXT_TOP_N } from './policy.js';
|
||||
import { buildHeatRaster } from '../../data/firmsHeatRaster.js';
|
||||
import {
|
||||
LOD_LEVELS,
|
||||
CONTEXT_TOP_N,
|
||||
HANDOFF_FADE,
|
||||
HEAT_RASTER,
|
||||
HEAT_REBUILD_MS,
|
||||
} from './policy.js';
|
||||
import { createHeatImagery } from './heatImagery.js';
|
||||
|
||||
/** The markers drawn under the far bands' heatmap for the hand-off fade. */
|
||||
const HANDOFF_MARKER_LOD = LOD_LEVELS.find((lod) => lod.mode === 'detections');
|
||||
|
||||
/** Fade steps: a moving camera rewrites marker colors at most this often. */
|
||||
const FADE_STEPS = 32;
|
||||
|
||||
export function createRendering({
|
||||
layerState,
|
||||
@@ -29,8 +43,11 @@ export function createRendering({
|
||||
!layerState._dataSource ||
|
||||
!layerState._fires.length ||
|
||||
!layerState._viewer
|
||||
)
|
||||
) {
|
||||
// A filter that leaves nothing shown must not leave the old heat behind.
|
||||
if (!layerState._fires.length) layerState._heatImagery?.setShow(false);
|
||||
return false;
|
||||
}
|
||||
const lodIndex = components.viewport.selectLodIndex(
|
||||
components.viewport.cameraHeight(),
|
||||
);
|
||||
@@ -51,14 +68,54 @@ export function createRendering({
|
||||
? components.model.paddedDegreeBounds(viewRect)
|
||||
: null;
|
||||
|
||||
if (lod.mode === 'detections') {
|
||||
renderDetections(lod, bounds);
|
||||
} else {
|
||||
renderCells(aggregateFires(lod, bounds), lod, bounds);
|
||||
}
|
||||
renderBand(lod, bounds);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Draw one band. Markers and heatmap stay built in every band; the
|
||||
* hand-off only fades between them.
|
||||
* @param {Object} lod - Band descriptor.
|
||||
* @param {?Object} bounds - Padded view bounds in degrees, or null.
|
||||
*/
|
||||
|
||||
function renderBand(lod, bounds) {
|
||||
prepareHeat(lod.mode === 'heat');
|
||||
if (lod.mode === 'detections') renderDetections(lod, bounds);
|
||||
else renderHeat(lod, bounds);
|
||||
applyHandoffFade(true);
|
||||
}
|
||||
|
||||
const fadeColor = new Cesium.Color();
|
||||
|
||||
/**
|
||||
* Cross-fade between markers and heatmap by camera height (HANDOFF_FADE),
|
||||
* on every rendered frame, so a fast zoom never outruns the throttled band
|
||||
* check. Cheap when nothing changed: one height read and a compare.
|
||||
* @param {boolean} [force] Reapply, e.g. to freshly added markers.
|
||||
*/
|
||||
|
||||
function applyHandoffFade(force = false) {
|
||||
const height = components.viewport.cameraHeight();
|
||||
const t = Math.min(
|
||||
1,
|
||||
Math.max(
|
||||
0,
|
||||
(height - HANDOFF_FADE.from) / (HANDOFF_FADE.to - HANDOFF_FADE.from),
|
||||
),
|
||||
);
|
||||
const heat = Math.round(t * t * (3 - 2 * t) * FADE_STEPS) / FADE_STEPS;
|
||||
if (!force && heat === layerState._handoffHeat) return;
|
||||
layerState._handoffHeat = heat;
|
||||
layerState._heatImagery?.setOpacity(heat);
|
||||
const billboards = layerState._billboards;
|
||||
if (!billboards) return;
|
||||
billboards.show = layerState._enabled && heat < 1;
|
||||
const color = Cesium.Color.WHITE.withAlpha(1 - heat, fadeColor);
|
||||
for (let i = 0; i < billboards.length; i += 1)
|
||||
billboards.get(i).color = color;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bin all detections into grid cells, then viewport-clip BEFORE the
|
||||
* top-N cap so fires in view never lose their slot to higher-scoring
|
||||
@@ -118,65 +175,96 @@ export function createRendering({
|
||||
return clipped;
|
||||
}
|
||||
|
||||
/** The heat imagery adapter, created on first use. */
|
||||
|
||||
function heatImagery() {
|
||||
if (!layerState._heatImagery) {
|
||||
layerState._heatImagery = createHeatImagery({
|
||||
cesium: Cesium,
|
||||
getHost: () =>
|
||||
layerState._imageryHost?.() ?? {
|
||||
collection: layerState._viewer?.imageryLayers ?? null,
|
||||
kind: 'globe',
|
||||
},
|
||||
});
|
||||
}
|
||||
return layerState._heatImagery;
|
||||
}
|
||||
|
||||
/** Build the heat raster from the shown set and drape it. */
|
||||
|
||||
function rebuildHeatRaster() {
|
||||
clearTimeout(layerState._heatRebuildTimer);
|
||||
layerState._heatRebuildTimer = null;
|
||||
if (layerState._destroyed) return;
|
||||
layerState._heatRaster = buildHeatRaster(layerState._fires, HEAT_RASTER);
|
||||
heatImagery().setRaster(layerState._heatRaster);
|
||||
}
|
||||
|
||||
/**
|
||||
* Render aggregated heat cells (global/regional bands) as ground-clamped
|
||||
* rectangles. Cell labels do NOT live on the entities anymore — they go
|
||||
* through the same unclamped, screen-space-decluttered label pipeline as
|
||||
* detections (see {@link rebuildAmbientLabels}).
|
||||
* @param {Array<Object>} cells - Aggregated cells, heat-sorted descending.
|
||||
* Make sure the draped heatmap matches the shown set. The first paint in a
|
||||
* far band is immediate; other builds (filter drags, refreshes, the
|
||||
* preload under the markers) trail by HEAT_REBUILD_MS and keep the
|
||||
* previous heatmap on screen meanwhile.
|
||||
* @param {boolean} now Build at once when nothing is draped yet.
|
||||
*/
|
||||
|
||||
function ensureHeatRaster(now) {
|
||||
if (layerState._heatRaster) return;
|
||||
if (now && !heatImagery().hasRaster()) {
|
||||
rebuildHeatRaster();
|
||||
return;
|
||||
}
|
||||
clearTimeout(layerState._heatRebuildTimer);
|
||||
layerState._heatRebuildTimer = setTimeout(
|
||||
rebuildHeatRaster,
|
||||
HEAT_REBUILD_MS,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Keep the heatmap draped on the current map stack and current with the
|
||||
* shown set in every band; the hand-off fade decides how much of it shows.
|
||||
* @param {boolean} now The camera is in a far band.
|
||||
*/
|
||||
|
||||
function prepareHeat(now) {
|
||||
const imagery = heatImagery();
|
||||
// The map stack may have changed since the last render.
|
||||
imagery.rehome();
|
||||
ensureHeatRaster(now);
|
||||
imagery.setShow(layerState._enabled);
|
||||
}
|
||||
|
||||
/**
|
||||
* Far bands (global/regional): a Snap Map–style heatmap draped over the
|
||||
* globe, transparent where nothing burns, plus the decluttered "N FIRES"
|
||||
* cards from the coarse aggregation. The nearest band's markers are kept
|
||||
* built underneath for the hand-off fade and hidden once it completes;
|
||||
* cards go through the same screen-space label pipeline as detections
|
||||
* (see {@link rebuildAmbientLabels}).
|
||||
* @param {Object} lod - Active LOD descriptor.
|
||||
* @param {?Object} bounds - Padded view bounds in degrees, or null.
|
||||
*/
|
||||
|
||||
function renderCells(cells, lod, bounds) {
|
||||
ensureDetectionCollections();
|
||||
layerState._dataSource.entities.removeAll();
|
||||
if (layerState._billboards) layerState._billboards.removeAll();
|
||||
layerState._pickIndexById.clear();
|
||||
layerState._cullPositions.length = 0;
|
||||
layerState._cellCount = cells.length;
|
||||
const maxScore = Math.max(1, ...cells.map(components.model.heatScore));
|
||||
function renderHeat(lod, bounds) {
|
||||
paintMarkers(HANDOFF_MARKER_LOD, bounds);
|
||||
|
||||
const cells = aggregateFires(lod, bounds);
|
||||
layerState._cellCount = cells.length;
|
||||
layerState._labelCandidates = [];
|
||||
layerState._labelLodDistance = lod.labelDistance;
|
||||
|
||||
// Cells arrive heat-sorted, so candidate order doubles as label priority.
|
||||
for (const cell of cells) {
|
||||
const score = components.model.heatScore(cell);
|
||||
const normalized = Math.min(1, Math.sqrt(score / maxScore));
|
||||
const alpha = 0.16 + normalized * 0.5;
|
||||
const color = components.model.heatColor(normalized, alpha);
|
||||
const centerLon = cell.lonCell + lod.gridDegrees / 2;
|
||||
const centerLat = cell.latCell + lod.gridDegrees / 2;
|
||||
const position = Cesium.Cartesian3.fromDegrees(centerLon, centerLat, 0);
|
||||
|
||||
layerState._dataSource.entities.add({
|
||||
rectangle: {
|
||||
coordinates: Cesium.Rectangle.fromDegrees(
|
||||
cell.lonCell,
|
||||
cell.latCell,
|
||||
cell.lonCell + lod.gridDegrees,
|
||||
cell.latCell + lod.gridDegrees,
|
||||
),
|
||||
material: new Cesium.ColorMaterialProperty(color),
|
||||
heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
|
||||
},
|
||||
position,
|
||||
properties: {
|
||||
count: cell.count,
|
||||
intensity: score,
|
||||
maxFrp: cell.maxFrp,
|
||||
night: cell.night,
|
||||
},
|
||||
});
|
||||
|
||||
// Cells arrive heat-sorted, so candidate order doubles as label priority.
|
||||
// Accent is resolved here because `normalized` only exists in this walk.
|
||||
layerState._labelCandidates.push({
|
||||
position,
|
||||
position: Cesium.Cartesian3.fromDegrees(centerLon, centerLat, 0),
|
||||
cullPosition: components.model.cellCullPosition(centerLon, centerLat),
|
||||
fire: null,
|
||||
cell,
|
||||
accent: components.model.cellAccent(normalized),
|
||||
accent: components.model.cellCardAccent(cell),
|
||||
});
|
||||
}
|
||||
|
||||
@@ -202,9 +290,48 @@ export function createRendering({
|
||||
*/
|
||||
|
||||
function renderDetections(lod, bounds) {
|
||||
const markers = paintMarkers(lod, bounds);
|
||||
if (!markers) return;
|
||||
const candidates = markers.map((marker) => marker.fire);
|
||||
|
||||
layerState._cellCount = candidates.length;
|
||||
// FRP-sorted walk: marker order doubles as label priority.
|
||||
layerState._labelCandidates = markers;
|
||||
layerState._labelLodDistance = lod.labelDistance;
|
||||
|
||||
components.cards.rebuildAmbientLabels();
|
||||
components.selection.refreshContextRegistrations(
|
||||
candidates.slice(0, CONTEXT_TOP_N),
|
||||
);
|
||||
|
||||
if (lod.id === 'close') {
|
||||
// Batched (chunked ≤200, sequential, session-cached) DEM warm for the
|
||||
// rendered subset; fires are static so each coarse cell resolves once
|
||||
// ever. Re-render ONLY when a floor actually landed — a failed resolve
|
||||
// reports false, so this chain terminates instead of looping against a
|
||||
// down proxy (the next camera-driven rebuild retries).
|
||||
warmFireAnchorFloors(candidates).then((warmed) => {
|
||||
if (!warmed || !layerState._enabled || !layerState._viewer) return;
|
||||
const currentLod = LOD_LEVELS[layerState._currentLodIndex];
|
||||
if (!currentLod || currentLod.mode !== 'detections') return;
|
||||
renderCurrentLod(true);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The glow-sprite markers for a detections band: the strongest fires in
|
||||
* view, capped at the band's maxDetections, horizon-culled.
|
||||
* @param {Object} lod - Detections band descriptor.
|
||||
* @param {?Object} bounds - Padded view bounds in degrees, or null.
|
||||
* @returns {?Array<Object>} Label candidates for the fires drawn,
|
||||
* strongest first; null before the sprite collection exists.
|
||||
*/
|
||||
|
||||
function paintMarkers(lod, bounds) {
|
||||
ensureDetectionCollections();
|
||||
layerState._dataSource.entities.removeAll();
|
||||
if (!layerState._billboards) return;
|
||||
if (!layerState._billboards) return null;
|
||||
layerState._billboards.removeAll();
|
||||
layerState._pickIndexById.clear();
|
||||
layerState._cullPositions.length = 0;
|
||||
@@ -226,17 +353,20 @@ export function createRendering({
|
||||
candidates = layerState._firesByFrp.slice(0, lod.maxDetections);
|
||||
}
|
||||
|
||||
layerState._cellCount = candidates.length;
|
||||
layerState._labelCandidates = [];
|
||||
layerState._labelLodDistance = lod.labelDistance;
|
||||
|
||||
const markers = [];
|
||||
// Only the close band warms terrain floors (renderDetections).
|
||||
const anchor =
|
||||
lod.id === 'close'
|
||||
? components.model.firePosition
|
||||
: components.model.fireBuiltPosition;
|
||||
for (const fire of candidates) {
|
||||
const coreSize = components.model.frpPixelSize(fire.frp);
|
||||
const position = components.model.firePosition(fire);
|
||||
const cullPosition = components.model.fireCullPosition(fire);
|
||||
const position = anchor(fire);
|
||||
const cullPosition = components.model.fireCullPosition(fire, position);
|
||||
const pickId = `firms-${fire.index}`;
|
||||
layerState._pickIndexById.set(pickId, fire);
|
||||
layerState._cullPositions.push(cullPosition);
|
||||
markers.push({ position, cullPosition, fire, cell: null });
|
||||
layerState._billboards.add({
|
||||
id: pickId,
|
||||
position,
|
||||
@@ -248,37 +378,13 @@ export function createRendering({
|
||||
horizontalOrigin: Cesium.HorizontalOrigin.CENTER,
|
||||
disableDepthTestDistance: Number.POSITIVE_INFINITY,
|
||||
});
|
||||
// FRP-sorted walk: candidate order doubles as label priority.
|
||||
layerState._labelCandidates.push({
|
||||
position,
|
||||
cullPosition,
|
||||
fire,
|
||||
cell: null,
|
||||
});
|
||||
}
|
||||
|
||||
// Freshly-added sprites default to show=true; cull the far side now so a
|
||||
// rebuild never flashes through-the-planet detections while the camera
|
||||
// sits still (the moveEnd/preRender hooks only fire on camera motion).
|
||||
refreshHorizonCulling();
|
||||
components.cards.rebuildAmbientLabels();
|
||||
components.selection.refreshContextRegistrations(
|
||||
candidates.slice(0, CONTEXT_TOP_N),
|
||||
);
|
||||
|
||||
if (lod.id === 'close') {
|
||||
// Batched (chunked ≤200, sequential, session-cached) DEM warm for the
|
||||
// rendered subset; fires are static so each coarse cell resolves once
|
||||
// ever. Re-render ONLY when a floor actually landed — a failed resolve
|
||||
// reports false, so this chain terminates instead of looping against a
|
||||
// down proxy (the next camera-driven rebuild retries).
|
||||
warmFireAnchorFloors(candidates).then((warmed) => {
|
||||
if (!warmed || !layerState._enabled || !layerState._viewer) return;
|
||||
const currentLod = LOD_LEVELS[layerState._currentLodIndex];
|
||||
if (!currentLod || currentLod.mode !== 'detections') return;
|
||||
renderCurrentLod(true);
|
||||
});
|
||||
}
|
||||
return markers;
|
||||
}
|
||||
|
||||
function ensureDetectionCollections() {
|
||||
@@ -344,9 +450,11 @@ export function createRendering({
|
||||
}
|
||||
return {
|
||||
renderCurrentLod,
|
||||
renderBand,
|
||||
aggregateFires,
|
||||
renderCells,
|
||||
renderHeat,
|
||||
renderDetections,
|
||||
applyHandoffFade,
|
||||
ensureDetectionCollections,
|
||||
removeDetectionCollections,
|
||||
fireHorizonOccluder,
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import * as Cesium from 'cesium';
|
||||
import { DEFAULT_FIRE_FILTER } from '../../data/firmsIntensity.js';
|
||||
|
||||
export function createFirmsState({ services, config }) {
|
||||
const layerState = {};
|
||||
@@ -39,12 +40,39 @@ export function createFirmsState({ services, config }) {
|
||||
|
||||
layerState._error = null;
|
||||
|
||||
/** Every adapted detection in the current payload, before the filter. */
|
||||
|
||||
layerState._allFires = [];
|
||||
|
||||
/** `_allFires` sorted by FRP descending, once per payload. */
|
||||
|
||||
layerState._allFiresByFrp = [];
|
||||
|
||||
/**
|
||||
* The detections that pass the intensity filter — the ONLY set rendering,
|
||||
* selection, cells, the top-fires query and the analyst records ever walk.
|
||||
*/
|
||||
|
||||
layerState._fires = [];
|
||||
|
||||
layerState._firesByFrp = [];
|
||||
|
||||
/** Shown (filtered) detection count. */
|
||||
|
||||
layerState._count = 0;
|
||||
|
||||
/** Loaded detection count before the filter ("N of M shown"). */
|
||||
|
||||
layerState._totalCount = 0;
|
||||
|
||||
/** Minimum FRP (MW) and confidence mode; see firmsIntensity.js. */
|
||||
|
||||
layerState._filter = { ...DEFAULT_FIRE_FILTER };
|
||||
|
||||
/** Panel callback: repaint the row controls (counter) after a load. */
|
||||
|
||||
layerState._rowControlsListener = null;
|
||||
|
||||
layerState._cellCount = 0;
|
||||
|
||||
layerState._lastUpdate = null;
|
||||
@@ -103,6 +131,29 @@ export function createFirmsState({ services, config }) {
|
||||
|
||||
layerState._cellCacheByGrid = new Map();
|
||||
|
||||
/**
|
||||
* Heat raster for the far bands (firmsHeatRaster.js); null = stale, rebuilt
|
||||
* on the next far render. Cleared with the cell cache on every new shown set.
|
||||
*/
|
||||
|
||||
layerState._heatRaster = null;
|
||||
|
||||
/** Pending debounced heat rebuild (see HEAT_REBUILD_MS). */
|
||||
|
||||
layerState._heatRebuildTimer = null;
|
||||
|
||||
/** Last applied hand-off fade (0 markers … 1 heatmap); -1 forces a reapply. */
|
||||
|
||||
layerState._handoffHeat = -1;
|
||||
|
||||
/** Imagery adapter (heatImagery.js), created on the first far render. */
|
||||
|
||||
layerState._heatImagery = null;
|
||||
|
||||
/** Shell-provided imagery host resolver; falls back to viewer.imageryLayers. */
|
||||
|
||||
layerState._imageryHost = null;
|
||||
|
||||
/** Camera idle snapshot so the throttled LOD check is ~free when parked. */
|
||||
|
||||
layerState._camSnapValid = false;
|
||||
|
||||
@@ -151,6 +151,9 @@ export function createViewport({
|
||||
// on screen throughout it — so the horizon pass below must keep running
|
||||
// while a fetch is in flight. Only the rebuild is gated on fresh data.
|
||||
if (!layerState._enabled) return;
|
||||
// Every frame, ahead of the throttle: a fast zoom crosses the whole
|
||||
// hand-off between two band checks.
|
||||
components.rendering.applyHandoffFade();
|
||||
const now = performance.now();
|
||||
if (now - layerState._lastLodCheck < LOD_CHECK_MS) return;
|
||||
layerState._lastLodCheck = now;
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
import * as Cesium from 'cesium';
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
import { OSM_PLACES_LAYER_ID } from './model.js';
|
||||
import { createNominatimStatus } from '../../sources/nominatimStatus.js';
|
||||
export * from './model.js';
|
||||
|
||||
const OVERLAY_SOURCE_ID = OSM_PLACES_LAYER_ID;
|
||||
/** Named results that get a map label; the rest are points. */
|
||||
const LABEL_LIMIT = 48;
|
||||
const COLOR = '#7fe3ff';
|
||||
|
||||
/**
|
||||
* OSM Places: the results of the last voice OpenStreetMap search ("hospitals
|
||||
* in Kathmandu"), drawn as points with name labels and queryable by
|
||||
* analyst_query. It fetches nothing itself; `setResults` replaces the set.
|
||||
* The search runs only on an operator-configured Overpass, so without one
|
||||
* the layer stays empty. Session-only: never in share links or stored layer
|
||||
* state.
|
||||
* @param {{overlayHost: object, overpassConfigured?: () => Promise<boolean|null>}} options
|
||||
*/
|
||||
export function createOsmPlacesLayer({
|
||||
overlayHost,
|
||||
// The same once-per-page capability probe as Nominatim's, on Overpass.
|
||||
overpassConfigured = createNominatimStatus({ url: '/api/overpass/status' }),
|
||||
} = {}) {
|
||||
if (!overlayHost) throw new TypeError('OSM Places requires an overlay host');
|
||||
let viewer = null;
|
||||
let dataSource = null;
|
||||
let enabled = false;
|
||||
let records = [];
|
||||
let meta = null;
|
||||
let lastUpdate = null;
|
||||
/** true / false from the server's probe, null while unknown. */
|
||||
let configured = null;
|
||||
|
||||
function render() {
|
||||
if (!dataSource) return;
|
||||
dataSource.entities.removeAll();
|
||||
const color = Cesium.Color.fromCssColorString(COLOR);
|
||||
const overlay = [];
|
||||
for (const record of records) {
|
||||
const position = Cesium.Cartesian3.fromDegrees(record.lon, record.lat);
|
||||
dataSource.entities.add({
|
||||
id: `osm-place:${record.id}`,
|
||||
position,
|
||||
point: {
|
||||
pixelSize: 9,
|
||||
color,
|
||||
outlineColor: Cesium.Color.BLACK.withAlpha(0.8),
|
||||
outlineWidth: 2,
|
||||
heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
|
||||
// On top only up close (as bikeshare stations): beyond that the
|
||||
// depth test keeps far-side points from showing through the globe.
|
||||
disableDepthTestDistance: 2500,
|
||||
},
|
||||
});
|
||||
if (record.name && overlay.length < LABEL_LIMIT)
|
||||
overlay.push({
|
||||
id: record.id,
|
||||
position,
|
||||
variant: 'label',
|
||||
title: record.name.slice(0, 40),
|
||||
accent: COLOR,
|
||||
priority: LABEL_LIMIT - overlay.length,
|
||||
collisionGroup: 'ambient-label',
|
||||
paintLane: 'ambient-label',
|
||||
interactive: false,
|
||||
edgeFade: 'keyhole',
|
||||
horizonCull: true,
|
||||
terrainOcclusion: false,
|
||||
gapPx: 12,
|
||||
verticalOnly: true,
|
||||
placement: 'above',
|
||||
});
|
||||
}
|
||||
if (enabled)
|
||||
overlayHost.setEntries(OVERLAY_SOURCE_ID, overlay, {
|
||||
cohortLimit: LABEL_LIMIT,
|
||||
collisionCapacity: LABEL_LIMIT,
|
||||
moving: false,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
id: OSM_PLACES_LAYER_ID,
|
||||
name: 'OSM Places',
|
||||
icon: '⌖',
|
||||
source: 'OpenStreetMap',
|
||||
updateInterval: 0,
|
||||
|
||||
/** Unavailable only once the server says no Overpass is configured. */
|
||||
getSourceAvailability() {
|
||||
return configured === false
|
||||
? {
|
||||
available: false,
|
||||
source: OSM_PLACES_LAYER_ID,
|
||||
reason: 'Needs an operator-configured Overpass server',
|
||||
}
|
||||
: { available: true, source: OSM_PLACES_LAYER_ID, reason: null };
|
||||
},
|
||||
|
||||
init(nextViewer) {
|
||||
viewer = nextViewer;
|
||||
Promise.resolve(overpassConfigured?.())
|
||||
.then((answer) => {
|
||||
if (typeof answer === 'boolean') configured = answer;
|
||||
})
|
||||
.catch(() => {});
|
||||
dataSource = new Cesium.CustomDataSource(OSM_PLACES_LAYER_ID);
|
||||
dataSource.show = false;
|
||||
viewer.dataSources.add(dataSource);
|
||||
overlayHost.setVisible(OVERLAY_SOURCE_ID, false);
|
||||
},
|
||||
|
||||
enable() {
|
||||
enabled = true;
|
||||
if (dataSource) dataSource.show = true;
|
||||
overlayHost.setVisible(OVERLAY_SOURCE_ID, true);
|
||||
render();
|
||||
return true;
|
||||
},
|
||||
|
||||
disable() {
|
||||
enabled = false;
|
||||
if (dataSource) dataSource.show = false;
|
||||
overlayHost.clearSource(OVERLAY_SOURCE_ID);
|
||||
overlayHost.setVisible(OVERLAY_SOURCE_ID, false);
|
||||
return true;
|
||||
},
|
||||
|
||||
/** Nothing to poll: results change only through setResults. */
|
||||
async update() {
|
||||
return true;
|
||||
},
|
||||
|
||||
destroy() {
|
||||
enabled = false;
|
||||
overlayHost.clearSource(OVERLAY_SOURCE_ID);
|
||||
overlayHost.setVisible(OVERLAY_SOURCE_ID, false);
|
||||
if (dataSource && viewer) viewer.dataSources.remove(dataSource, true);
|
||||
dataSource = null;
|
||||
viewer = null;
|
||||
records = [];
|
||||
meta = null;
|
||||
lastUpdate = null;
|
||||
},
|
||||
|
||||
/**
|
||||
* Replace the result set.
|
||||
* @param {object[]} next Records from `mapOsmFeature`.
|
||||
* @param {{kind: string, label: string, area: string}} nextMeta
|
||||
*/
|
||||
setResults(next, nextMeta) {
|
||||
records = Array.isArray(next) ? next.slice() : [];
|
||||
meta = nextMeta ? { ...nextMeta } : null;
|
||||
lastUpdate = Date.now();
|
||||
render();
|
||||
},
|
||||
|
||||
/** The current search, for panels and voice. */
|
||||
getResultsMeta() {
|
||||
return meta ? { ...meta, count: records.length } : null;
|
||||
},
|
||||
|
||||
getAnalystRecords(maxCount = 2000) {
|
||||
if (!enabled) return [];
|
||||
const limit = Number.isFinite(maxCount)
|
||||
? Math.max(1, Math.floor(maxCount))
|
||||
: 2000;
|
||||
return records.slice(0, limit).map((record) => ({ ...record }));
|
||||
},
|
||||
|
||||
getStats() {
|
||||
return {
|
||||
count: records.length,
|
||||
lastUpdate,
|
||||
error: null,
|
||||
statusMessage: meta
|
||||
? `${meta.label} · ${meta.area}`
|
||||
: msg('Voice place search (needs an Overpass server)'),
|
||||
};
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,152 @@
|
||||
// OSM Places holds the last voice search's results: queryable while shown,
|
||||
// labelled through the overlay host, and nothing when switched off.
|
||||
//
|
||||
// Run with: npm test
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { createOsmPlacesLayer } from './index.js';
|
||||
|
||||
function fakeOverlayHost() {
|
||||
const calls = [];
|
||||
return {
|
||||
calls,
|
||||
setEntries: (...args) => calls.push(['setEntries', ...args]),
|
||||
clearSource: (...args) => calls.push(['clearSource', ...args]),
|
||||
setVisible: (...args) => calls.push(['setVisible', ...args]),
|
||||
};
|
||||
}
|
||||
|
||||
const RECORDS = [
|
||||
{
|
||||
id: 'node/1',
|
||||
lat: 27.7,
|
||||
lon: 85.3,
|
||||
name: 'Bir Hospital',
|
||||
kind: 'hospital',
|
||||
},
|
||||
{ id: 'node/2', lat: 27.71, lon: 85.31, name: null, kind: 'hospital' },
|
||||
];
|
||||
|
||||
test('results are queryable only while the layer is on, and labels follow names', () => {
|
||||
const host = fakeOverlayHost();
|
||||
const layer = createOsmPlacesLayer({ overlayHost: host });
|
||||
layer.setResults(RECORDS, {
|
||||
kind: 'hospital',
|
||||
label: 'hospitals',
|
||||
area: 'Kathmandu',
|
||||
});
|
||||
assert.deepEqual(layer.getAnalystRecords(), [], 'off: nothing to count');
|
||||
assert.equal(layer.getStats().count, 2);
|
||||
assert.equal(layer.getStats().statusMessage, 'hospitals · Kathmandu');
|
||||
layer.enable();
|
||||
const records = layer.getAnalystRecords();
|
||||
assert.equal(records.length, 2);
|
||||
records[0].name = 'changed';
|
||||
assert.equal(
|
||||
layer.getAnalystRecords()[0].name,
|
||||
'Bir Hospital',
|
||||
'callers get copies',
|
||||
);
|
||||
assert.deepEqual(layer.getResultsMeta(), {
|
||||
kind: 'hospital',
|
||||
label: 'hospitals',
|
||||
area: 'Kathmandu',
|
||||
count: 2,
|
||||
});
|
||||
layer.disable();
|
||||
assert.ok(
|
||||
host.calls.some(
|
||||
([name, id]) => name === 'clearSource' && id === 'osm-places',
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
test('an empty layer tells the operator how to fill it', () => {
|
||||
const layer = createOsmPlacesLayer({ overlayHost: fakeOverlayHost() });
|
||||
assert.match(layer.getStats().statusMessage, /needs an Overpass server/);
|
||||
assert.throws(() => createOsmPlacesLayer(), TypeError);
|
||||
});
|
||||
|
||||
test('destroy and re-init expose a fresh empty session', () => {
|
||||
const host = fakeOverlayHost();
|
||||
const layer = createOsmPlacesLayer({ overlayHost: host });
|
||||
layer.setResults(RECORDS, {
|
||||
kind: 'hospital',
|
||||
label: 'hospitals',
|
||||
area: 'Kathmandu',
|
||||
});
|
||||
assert.ok(layer.getStats().lastUpdate);
|
||||
layer.destroy();
|
||||
const dataSources = {
|
||||
added: [],
|
||||
removed: [],
|
||||
add(source) {
|
||||
this.added.push(source);
|
||||
return source;
|
||||
},
|
||||
remove(source, destroy) {
|
||||
this.removed.push([source, destroy]);
|
||||
return true;
|
||||
},
|
||||
};
|
||||
layer.init({ dataSources });
|
||||
layer.enable();
|
||||
assert.equal(layer.getResultsMeta(), null);
|
||||
assert.deepEqual(layer.getAnalystRecords(), []);
|
||||
assert.deepEqual(layer.getStats(), {
|
||||
count: 0,
|
||||
lastUpdate: null,
|
||||
error: null,
|
||||
statusMessage: 'Voice place search (needs an Overpass server)',
|
||||
});
|
||||
});
|
||||
|
||||
test('without an operator Overpass the layer shows as unavailable', async () => {
|
||||
const added = [];
|
||||
const viewer = { dataSources: { add: (ds) => added.push(ds), remove() {} } };
|
||||
const off = createOsmPlacesLayer({
|
||||
overlayHost: fakeOverlayHost(),
|
||||
overpassConfigured: async () => false,
|
||||
});
|
||||
assert.equal(
|
||||
off.getSourceAvailability().available,
|
||||
true,
|
||||
'unknown until asked',
|
||||
);
|
||||
off.init(viewer);
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
assert.equal(off.getSourceAvailability().available, false);
|
||||
const unknown = createOsmPlacesLayer({
|
||||
overlayHost: fakeOverlayHost(),
|
||||
overpassConfigured: async () => null,
|
||||
});
|
||||
unknown.init(viewer);
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
assert.equal(
|
||||
unknown.getSourceAvailability().available,
|
||||
true,
|
||||
'an unknown answer keeps it listed',
|
||||
);
|
||||
});
|
||||
|
||||
test('places are depth-tested past close range, so they never show through the globe', () => {
|
||||
const added = [];
|
||||
const viewer = { dataSources: { add: (ds) => added.push(ds), remove() {} } };
|
||||
const layer = createOsmPlacesLayer({
|
||||
overlayHost: fakeOverlayHost(),
|
||||
overpassConfigured: async () => true,
|
||||
});
|
||||
layer.init(viewer);
|
||||
layer.enable();
|
||||
layer.setResults(RECORDS, {
|
||||
kind: 'hospital',
|
||||
label: 'hospitals',
|
||||
area: 'Kathmandu',
|
||||
});
|
||||
const point = added[0].entities.values[0].point;
|
||||
const distance = point.disableDepthTestDistance.getValue();
|
||||
assert.ok(
|
||||
Number.isFinite(distance) && distance <= 5000,
|
||||
`depth test off only within ${distance} m`,
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,111 @@
|
||||
/**
|
||||
* OSM Places records: OpenStreetMap features found by a voice search,
|
||||
* mapped to plain analyst records. Pure — no Cesium.
|
||||
* @module layers/osmPlaces/model
|
||||
*/
|
||||
|
||||
export const OSM_PLACES_LAYER_ID = 'osm-places';
|
||||
/** A node and a way/relation of the same name this close are one site mapped twice. */
|
||||
const SAME_SITE_M = 75;
|
||||
|
||||
/** Longest tag value kept; OSM names are open text that reaches the model. */
|
||||
const MAX_TEXT = 120;
|
||||
|
||||
/**
|
||||
* A tag value as plain bounded text: control characters (newlines, tabs)
|
||||
* become spaces; format characters (bidi overrides, zero-width spaces) are
|
||||
* dropped, except the zero-width (non-)joiners Persian and Indic names spell
|
||||
* with; runs of whitespace collapse, and long values are cut with an
|
||||
* ellipsis.
|
||||
*/
|
||||
function text(value) {
|
||||
if (typeof value !== 'string') return null;
|
||||
const clean = value
|
||||
.replace(/\p{Cc}+/gu, ' ')
|
||||
.replace(/(?![\u200c\u200d])\p{Cf}/gu, '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.trim();
|
||||
if (!clean) return null;
|
||||
// Cut on code points so an emoji's surrogate pair is never split.
|
||||
const chars = Array.from(clean);
|
||||
return chars.length <= MAX_TEXT
|
||||
? clean
|
||||
: `${chars
|
||||
.slice(0, MAX_TEXT - 1)
|
||||
.join('')
|
||||
.trimEnd()}…`;
|
||||
}
|
||||
|
||||
function distanceM(a, b) {
|
||||
const toRad = Math.PI / 180;
|
||||
const x = (b.lon - a.lon) * toRad * Math.cos(((a.lat + b.lat) / 2) * toRad);
|
||||
const y = (b.lat - a.lat) * toRad;
|
||||
return Math.hypot(x, y) * 6_371_000;
|
||||
}
|
||||
|
||||
/**
|
||||
* One feature from `/api/osm/features` → an analyst record.
|
||||
* @param {{id: string, lat: number, lon: number, tags?: object}} feature
|
||||
* @param {{id: string, label: string}} preset
|
||||
* @returns {object|null}
|
||||
*/
|
||||
export function mapOsmFeature(feature, preset) {
|
||||
if (!Number.isFinite(feature?.lat) || !Number.isFinite(feature?.lon))
|
||||
return null;
|
||||
const tags = feature.tags || {};
|
||||
const [osmType] = String(feature.id || '').split('/');
|
||||
return {
|
||||
id: String(feature.id),
|
||||
lat: feature.lat,
|
||||
lon: feature.lon,
|
||||
name: text(tags['name:en']) || text(tags.name),
|
||||
kind: preset.id,
|
||||
operator: text(tags.operator) || text(tags.brand),
|
||||
emergency: text(tags.emergency),
|
||||
wheelchair: text(tags.wheelchair),
|
||||
openingHours: text(tags.opening_hours),
|
||||
city: text(tags['addr:city']),
|
||||
osmType: ['node', 'way', 'relation'].includes(osmType) ? osmType : null,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove double counting without merging distinct places:
|
||||
*
|
||||
* - the same OSM element (identical `type/id`) is counted once;
|
||||
* - a node and a way/relation with the same name within 75 m are one site
|
||||
* mapped twice (a point on the building and the building outline), and
|
||||
* merge;
|
||||
* - two nodes, or two ways, are always distinct places — two neighbouring
|
||||
* cafés of one chain are two cafés — and never merge, whatever their names.
|
||||
*
|
||||
* @param {object[]} records
|
||||
* @returns {{records: object[], merged: number}}
|
||||
*/
|
||||
export function dedupeOsmRecords(records) {
|
||||
const kept = [];
|
||||
const seen = new Set();
|
||||
let merged = 0;
|
||||
for (const record of records) {
|
||||
if (seen.has(record.id)) {
|
||||
merged += 1;
|
||||
continue;
|
||||
}
|
||||
seen.add(record.id);
|
||||
const name = record.name?.toLowerCase();
|
||||
const isNode = record.osmType === 'node';
|
||||
const sameSite =
|
||||
name &&
|
||||
record.osmType &&
|
||||
kept.some(
|
||||
(other) =>
|
||||
other.osmType &&
|
||||
(other.osmType === 'node') !== isNode &&
|
||||
other.name?.toLowerCase() === name &&
|
||||
distanceM(other, record) <= SAME_SITE_M,
|
||||
);
|
||||
if (sameSite) merged += 1;
|
||||
else kept.push(record);
|
||||
}
|
||||
return { records: kept, merged };
|
||||
}
|
||||
@@ -1209,6 +1209,16 @@ export function createRecentImageryLayer({
|
||||
notify('alpha');
|
||||
},
|
||||
|
||||
/** Stop catalog/preview work owned by a cancelled voice action. */
|
||||
cancelPendingSearch() {
|
||||
// Without a note the emptied strip would read as "no imagery".
|
||||
if (_searching) _notice = msg('Search cancelled');
|
||||
cancelSearch();
|
||||
clearPending();
|
||||
syncRender();
|
||||
notify();
|
||||
},
|
||||
|
||||
/**
|
||||
* Forget the box, the candidates, both pins, the preview and any pending
|
||||
* pick; reset opacity and split and cancel the box tool. Mode and
|
||||
|
||||
@@ -1385,3 +1385,13 @@ test('with SELECT BOX armed, Escape clears the preview first and the next Escape
|
||||
assert.equal(f.snap().toolActive, false);
|
||||
await tool.destroy();
|
||||
});
|
||||
|
||||
test('a voice search cancelled mid-flight says so instead of looking empty', async () => {
|
||||
const f = fixture();
|
||||
f.layer.enable();
|
||||
f.layer.setBox(BOX);
|
||||
assert.equal(f.snap().searching, true);
|
||||
f.layer.cancelPendingSearch();
|
||||
assert.equal(f.snap().searching, false);
|
||||
assert.equal(f.snap().notice, 'Search cancelled');
|
||||
});
|
||||
@@ -38,7 +38,15 @@ export function createFlow({ state: layerState, services, parts, source }) {
|
||||
const status = Number.isFinite(error.status)
|
||||
? error.status
|
||||
: Number(message.match(/HTTP (\d{3})/)?.[1]);
|
||||
const code = typeof error.code === 'string' ? error.code : null;
|
||||
// English in state; trafficFeedPresentation translates it for the panel.
|
||||
// A hosted deployment limits each account (code from the server); the
|
||||
// local proxy has one daily budget (`budget`) and answers `no_key`.
|
||||
if (code === 'USAGE_LIMIT_REACHED')
|
||||
return msg('Monthly traffic allowance used');
|
||||
if (code === 'RATE_LIMITED') return msg('Traffic rate limit reached');
|
||||
if (status === 503 && code && code !== 'no_key')
|
||||
return msg('Traffic service unavailable');
|
||||
if (status === 503) return msg('TomTom key unavailable');
|
||||
if (status === 429) return msg('TomTom daily budget reached');
|
||||
if (status === 502 || status === 504)
|
||||
|
||||
@@ -11,6 +11,26 @@ const FLOW_TILE_PATH = (z, x, y) => `/api/tomtom/flow/${z}/${x}/${y}.pbf`;
|
||||
* (STALE-BUDGET once the daily budget is spent, STALE-ERROR when TomTom
|
||||
* fails), and when the proxy fetched it.
|
||||
*/
|
||||
/**
|
||||
* The machine-readable reason a failed tile carries: `code` (hosted usage,
|
||||
* e.g. USAGE_LIMIT_REACHED or RATE_LIMITED) or the local proxy's `error`
|
||||
* (`no_key`, `budget`). Only short identifiers are kept; prose is ignored.
|
||||
*/
|
||||
async function failureCode(response) {
|
||||
if (!/json/i.test(response.headers?.get?.('content-type') || '')) return null;
|
||||
try {
|
||||
const text = await response.text();
|
||||
if (text.length > 4096) return null;
|
||||
const body = JSON.parse(text);
|
||||
const code = body?.code ?? body?.error;
|
||||
return typeof code === 'string' && /^[A-Za-z_]{1,40}$/.test(code)
|
||||
? code
|
||||
: null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function tileFreshness(response) {
|
||||
const status = response.headers?.get?.('x-tomtom-cache') || '';
|
||||
const fetchedAt = Number(response.headers?.get?.('x-tomtom-fetched-at'));
|
||||
@@ -20,6 +40,19 @@ function tileFreshness(response) {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Clip a flow line to a box. Every piece keeps its uncut line as `line`, so
|
||||
* pieces of one line that doubles back are never paired with each other.
|
||||
*/
|
||||
function clipFlowSegment(segment, bbox) {
|
||||
const line = segment.line || segment;
|
||||
return clipTileLine(segment.coords, bbox).map((coords) => ({
|
||||
...segment,
|
||||
coords,
|
||||
line,
|
||||
}));
|
||||
}
|
||||
|
||||
/** Own one bounded decoded flow cache; every request still passes the server tile budget. */
|
||||
export function createFlowTileSource({
|
||||
fetchImpl = (...args) => globalThis.fetch(...args),
|
||||
@@ -41,18 +74,22 @@ export function createFlowTileSource({
|
||||
entry?.release();
|
||||
const segments = decodeFlowTile(bytes, z, x, y, { strict: true })
|
||||
.filter(isDrivableFlowSegment)
|
||||
.flatMap((segment) =>
|
||||
clipTileLine(segment.coords, tileToBBox(z, x, y)).map((coords) => ({
|
||||
...segment,
|
||||
coords,
|
||||
})),
|
||||
);
|
||||
.flatMap((segment) => clipFlowSegment(segment, tileToBBox(z, x, y)));
|
||||
if (mark) freshness.set(segments, mark);
|
||||
return segments;
|
||||
},
|
||||
fetchImpl: async (url, init) => {
|
||||
const response = await fetchImpl(url, init);
|
||||
if (response.ok && !init.signal.aborted) {
|
||||
if (!response.ok) {
|
||||
const code = await failureCode(response);
|
||||
await response.body?.cancel().catch(() => {});
|
||||
throw Object.assign(
|
||||
// Classified for display by deriveTrafficFlowError.
|
||||
new Error(`TomTom flow unavailable (HTTP ${response.status})`),
|
||||
{ status: response.status, code },
|
||||
);
|
||||
}
|
||||
if (!init.signal.aborted) {
|
||||
const path = String(url);
|
||||
const entry = {
|
||||
mark: tileFreshness(response),
|
||||
@@ -87,12 +124,9 @@ export function createFlowTileSource({
|
||||
partial = result.partial;
|
||||
const segments = bounds.coverage
|
||||
? result.tiles.flat()
|
||||
: result.tiles.flat().flatMap((segment) =>
|
||||
clipTileLine(segment.coords, bounds).map((coords) => ({
|
||||
...segment,
|
||||
coords,
|
||||
})),
|
||||
);
|
||||
: result.tiles
|
||||
.flat()
|
||||
.flatMap((segment) => clipFlowSegment(segment, bounds));
|
||||
const marks = result.tiles.map((tile) => freshness.get(tile) || {});
|
||||
const times = marks
|
||||
.map((mark) => mark.fetchedAt)
|
||||
|
||||
@@ -35,6 +35,14 @@ const MIN_FILL_M = 40;
|
||||
* Same-class overlap keeps the full 35 m matcher radius.
|
||||
*/
|
||||
const CLASS_MISMATCH_RADIUS_M = 15;
|
||||
/**
|
||||
* Opposite-direction TomTom lines this close share one street: TomTom draws
|
||||
* both directions of a two-way street a metre or two apart, and a divided
|
||||
* carriageway's sides further apart.
|
||||
*/
|
||||
const PAIRED_SIDE_RADIUS_M = 5;
|
||||
/** Arc-length positions sampled along a `one_side` line for its partner. */
|
||||
const PAIRED_SIDE_SAMPLES = [0.25, 0.5, 0.75];
|
||||
const CONTROLLED_ACCESS_FLOW = new Set(['Motorway', 'International road']);
|
||||
const CONTROLLED_ACCESS_OSM = new Set(['motorway', 'trunk']);
|
||||
|
||||
@@ -85,20 +93,69 @@ export function isDrivableFlowSegment(segment) {
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Share of a `one_side` line's sample points (PAIRED_SIDE_SAMPLES) with an
|
||||
* opposite-direction TomTom line beside them: TomTom draws a two-way street
|
||||
* whose directions differ as two `one_side` lines on one centreline, while a
|
||||
* divided carriageway's other side is further away than PAIRED_SIDE_RADIUS_M.
|
||||
* @returns {number} Paired share in [0, 1].
|
||||
*/
|
||||
function pairedSampleShare(segment, index) {
|
||||
const xs = [];
|
||||
const ys = [];
|
||||
const cum = [0];
|
||||
for (const [lon, lat] of segment.coords) {
|
||||
const [x, y] = index.project(lon, lat);
|
||||
const i = xs.push(x) - 1;
|
||||
ys.push(y);
|
||||
if (i) cum.push(cum[i - 1] + Math.hypot(x - xs[i - 1], y - ys[i - 1]));
|
||||
}
|
||||
const length = cum[cum.length - 1];
|
||||
if (!(length > 0)) return 0;
|
||||
const line = segment.line || segment;
|
||||
let paired = 0;
|
||||
let i = 1;
|
||||
for (const share of PAIRED_SIDE_SAMPLES) {
|
||||
const target = share * length;
|
||||
while (i < cum.length - 1 && cum[i] < target) i++;
|
||||
const dx = xs[i] - xs[i - 1];
|
||||
const dy = ys[i] - ys[i - 1];
|
||||
const t = (target - cum[i - 1]) / (cum[i] - cum[i - 1] || 1);
|
||||
const reverse = (Math.atan2(-dx, -dy) * 180) / Math.PI;
|
||||
if (
|
||||
index.nearest(
|
||||
xs[i - 1] + dx * t,
|
||||
ys[i - 1] + dy * t,
|
||||
reverse,
|
||||
// A line that doubles back beside itself, even clipped into pieces,
|
||||
// is not its own pair.
|
||||
(piece) =>
|
||||
(piece.flow.line || piece.flow) === line ? 0 : PAIRED_SIDE_RADIUS_M,
|
||||
).best
|
||||
)
|
||||
paired++;
|
||||
}
|
||||
return paired / PAIRED_SIDE_SAMPLES.length;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert decoded TomTom flow lines into road records that carry their own
|
||||
* flow. A line with `coverage: 'full'` describes both travel directions;
|
||||
* `one_side` lines describe the direction they are drawn in.
|
||||
* `one_side` lines describe the direction they are drawn in. A `one_side`
|
||||
* line paired with the opposite direction on the same street gets that
|
||||
* direction's half share of dots, as a two-way road's direction does.
|
||||
* @param {Array<{coords:number[][], trafficLevel:number, roadType:string, closure:boolean, coverage?:string}>} segments
|
||||
* @returns {Array<object>} Road records (`directFlow: true`).
|
||||
*/
|
||||
export function flowSegmentsToRoads(segments) {
|
||||
return (segments || [])
|
||||
.filter(
|
||||
(segment) =>
|
||||
segment?.coords?.length >= 2 && isDrivableFlowSegment(segment),
|
||||
)
|
||||
.map((segment) => ({
|
||||
const drivable = (segments || []).filter(
|
||||
(segment) => segment?.coords?.length >= 2 && isDrivableFlowSegment(segment),
|
||||
);
|
||||
const sides = createFlowSegmentIndex(
|
||||
drivable.filter((segment) => segment.coverage !== 'full'),
|
||||
);
|
||||
return drivable.map((segment) => {
|
||||
const road = {
|
||||
coordinates: segment.coords,
|
||||
type: FLOW_ROAD_TYPES[segment.roadType],
|
||||
drivable: true,
|
||||
@@ -110,7 +167,15 @@ export function flowSegmentsToRoads(segments) {
|
||||
oneway: segment.coverage === 'full' ? 0 : 1,
|
||||
flow: { level: segment.trafficLevel, closure: segment.closure === true },
|
||||
directFlow: true,
|
||||
}));
|
||||
};
|
||||
if (
|
||||
segment.coverage !== 'full' &&
|
||||
sides &&
|
||||
pairedSampleShare(segment, sides) >= 0.5
|
||||
)
|
||||
road.densityWeight = 0.5;
|
||||
return road;
|
||||
});
|
||||
}
|
||||
|
||||
/** Cut a projected polyline to the arc-length interval [from, to]. */
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { PbfWriter } from 'pbf';
|
||||
import {
|
||||
flowSegmentsToRoads,
|
||||
resolveRoadMode,
|
||||
selectTrafficRoads,
|
||||
} from './roadModes.js';
|
||||
import { createFlowTileSource } from './flowSource.js';
|
||||
import { createTrafficSource } from './source.js';
|
||||
import { createTrafficLayer } from './index.js';
|
||||
import {
|
||||
@@ -14,6 +16,7 @@ import {
|
||||
serializeStoredLayerState,
|
||||
parseStoredLayerState,
|
||||
} from '../../data/layerState.js';
|
||||
import { tileToBBox } from '../../data/tomtomTiles.js';
|
||||
|
||||
const coordinates = [
|
||||
[-97.744, 30.267],
|
||||
@@ -116,6 +119,133 @@ test('a full-coverage TomTom line is two-way and covers both OSM directions', ()
|
||||
assert.equal(roads.length, 1);
|
||||
assert.equal(roads[0].directFlow, true);
|
||||
});
|
||||
test("opposite TomTom sides of one street share a two-way street's dots", () => {
|
||||
// About 1 m and 20 m north of `coordinates`, drawn westbound.
|
||||
const back = (dLat) => ({
|
||||
...flow,
|
||||
coords: coordinates.map(([lon, lat]) => [lon, lat + dLat]).reverse(),
|
||||
});
|
||||
const weights = (segments) =>
|
||||
flowSegmentsToRoads(segments).map((road) => road.densityWeight ?? 1);
|
||||
assert.deepEqual(weights([flow, back(0.00001)]), [0.5, 0.5]);
|
||||
assert.deepEqual(weights([flow]), [1], 'a lone side keeps the one-way share');
|
||||
assert.deepEqual(
|
||||
weights([flow, back(0.00018)]),
|
||||
[1, 1],
|
||||
'a divided carriageway keeps one-way shares',
|
||||
);
|
||||
assert.deepEqual(
|
||||
weights([
|
||||
flow,
|
||||
{
|
||||
...flow,
|
||||
coords: coordinates.map(([lon, lat]) => [lon, lat + 0.00001]),
|
||||
},
|
||||
]),
|
||||
[1, 1],
|
||||
'same-direction lines are not a pair',
|
||||
);
|
||||
assert.deepEqual(
|
||||
weights([{ ...flow, coverage: 'full' }, back(0.00001)]),
|
||||
[1, 1],
|
||||
'a full-coverage line is not a side, and pairs with nothing',
|
||||
);
|
||||
});
|
||||
test('a TomTom side paired along only part of its length keeps its share', () => {
|
||||
// Westbound partners about 1 m north, from the start of `flow` to 30% and
|
||||
// to 60% of its length: one or two of its three sample points.
|
||||
const partner = (toLon) => ({
|
||||
...flow,
|
||||
coords: [
|
||||
[toLon, 30.26701],
|
||||
[-97.744, 30.26701],
|
||||
],
|
||||
});
|
||||
const weightOfFlow = (other) =>
|
||||
flowSegmentsToRoads([flow, other])[0].densityWeight ?? 1;
|
||||
assert.equal(weightOfFlow(partner(-97.7434)), 1);
|
||||
assert.equal(weightOfFlow(partner(-97.7428)), 0.5);
|
||||
});
|
||||
test('a TomTom side that doubles back beside itself is not its own pair', () => {
|
||||
// East along `coordinates`, then back west about 1 m north.
|
||||
const hairpin = {
|
||||
...flow,
|
||||
coords: [...coordinates, [-97.742, 30.26701], [-97.744, 30.26701]],
|
||||
};
|
||||
assert.equal(flowSegmentsToRoads([hairpin])[0].densityWeight ?? 1, 1);
|
||||
});
|
||||
/** A flow tile of one-way Major roads; each line is [x, y, x, y, ...]. */
|
||||
function flowTile(lines) {
|
||||
const writer = new PbfWriter();
|
||||
writer.writeMessage(3, writeFlowLayer, lines);
|
||||
return writer.finish();
|
||||
}
|
||||
function writeFlowLayer(lines, layer) {
|
||||
layer.writeVarintField(15, 2);
|
||||
layer.writeStringField(1, 'Traffic flow');
|
||||
layer.writeVarintField(5, 4096);
|
||||
layer.writeStringField(3, 'traffic_level');
|
||||
layer.writeMessage(4, (_, value) => value.writeDoubleField(3, 0.6), null);
|
||||
layer.writeStringField(3, 'road_type');
|
||||
layer.writeMessage(
|
||||
4,
|
||||
(_, value) => value.writeStringField(1, 'Major road'),
|
||||
null,
|
||||
);
|
||||
layer.writeStringField(3, 'traffic_road_coverage');
|
||||
layer.writeMessage(
|
||||
4,
|
||||
(_, value) => value.writeStringField(1, 'one_side'),
|
||||
null,
|
||||
);
|
||||
for (const xy of lines) {
|
||||
// MoveTo one point, LineTo the rest, as zigzag deltas.
|
||||
const geometry = [9];
|
||||
for (let i = 0; i < xy.length; i++) {
|
||||
if (i === 2) geometry.push(2 | ((xy.length / 2 - 1) << 3));
|
||||
const delta = xy[i] - (i < 2 ? 0 : xy[i - 2]);
|
||||
geometry.push((delta << 1) ^ (delta >> 31));
|
||||
}
|
||||
layer.writeMessage(
|
||||
2,
|
||||
(_, feature) => {
|
||||
feature.writeVarintField(3, 2);
|
||||
feature.writePackedVarint(2, [0, 0, 1, 1, 2, 2]);
|
||||
feature.writePackedVarint(4, geometry);
|
||||
},
|
||||
null,
|
||||
);
|
||||
}
|
||||
}
|
||||
test('TomTom sides clipped by their tile and the view pair only with other lines', async () => {
|
||||
// A one-way hairpin turning in the tile buffer, its arms one tile unit
|
||||
// (about 2 m) apart, and a separate opposite pair. The tile clip cuts the
|
||||
// hairpin into two arms; the view clip then cuts every line again.
|
||||
const lines = [
|
||||
[500, 1000, 4300, 1000, 4300, 1001, 500, 1001],
|
||||
[-200, 3000, 4300, 3000],
|
||||
[4300, 3001, -200, 3001],
|
||||
];
|
||||
const source = createFlowTileSource({
|
||||
fetchImpl: async () => new Response(flowTile(lines)),
|
||||
});
|
||||
const tile = tileToBBox(12, 935, 1686);
|
||||
const west = tile.west + (tile.east - tile.west) * 0.2;
|
||||
const { segments } = await source.fetchFlowDetail({
|
||||
...tile,
|
||||
west,
|
||||
east: tile.east - 1e-9,
|
||||
south: tile.south + 1e-9,
|
||||
});
|
||||
assert.equal(segments.length, 4);
|
||||
assert.ok(
|
||||
segments.every((s) => s.coords.every(([lon]) => lon >= west - 1e-10)),
|
||||
);
|
||||
assert.deepEqual(
|
||||
flowSegmentsToRoads(segments).map((road) => road.densityWeight ?? 1),
|
||||
[1, 1, 0.5, 0.5],
|
||||
);
|
||||
});
|
||||
test('bearing and distance reject nearby crossing and separate OSM roads', () => {
|
||||
const parallel = {
|
||||
...main,
|
||||
|
||||
@@ -1050,3 +1050,29 @@ test('cancelling a flow body releases its freshness before a new request', async
|
||||
assert.equal(getEventListeners(requestSignal, 'abort').length, 0);
|
||||
assert.equal(source.getFlowSessionStats().cacheEntries, 0);
|
||||
});
|
||||
|
||||
test('a failed flow tile carries the server reason for its label', async () => {
|
||||
for (const [status, body, code] of [
|
||||
[
|
||||
429,
|
||||
{ error: 'Monthly usage limit reached', code: 'USAGE_LIMIT_REACHED' },
|
||||
'USAGE_LIMIT_REACHED',
|
||||
],
|
||||
[
|
||||
429,
|
||||
{ error: 'Request rate limit reached', code: 'RATE_LIMITED' },
|
||||
'RATE_LIMITED',
|
||||
],
|
||||
[503, { error: 'no_key' }, 'no_key'],
|
||||
[503, { error: 'Usage enforcement is temporarily unavailable' }, null],
|
||||
]) {
|
||||
const source = createFlowTileSource({
|
||||
fetchImpl: async () => Response.json(body, { status }),
|
||||
});
|
||||
await assert.rejects(source.fetchFlowForBounds(bounds), (error) => {
|
||||
assert.equal(error.status, status);
|
||||
assert.equal(error.code, code);
|
||||
return true;
|
||||
});
|
||||
}
|
||||
});
|
||||
@@ -12,6 +12,11 @@ import {
|
||||
} from '../../data/transitFeeds.js';
|
||||
import { transitModeTier } from '../../data/transitPresetStyle.js';
|
||||
|
||||
/** Regions, not feeds: one region can carry several feeds (Rio has two). */
|
||||
const TRANSIT_REGION_COUNT = new Set(
|
||||
TRANSIT_ENABLED_FEEDS.map((feed) => feed.region),
|
||||
).size;
|
||||
|
||||
/**
|
||||
* The registry entry behind a vehicle. Live feeds answer first so a feed the
|
||||
* session disabled stops supplying vocabulary; the registry is the fallback,
|
||||
@@ -249,7 +254,7 @@ export function createQueries({ state, parts }) {
|
||||
// English data (the analyst's empty note to the model); the voice
|
||||
// card shows it through NOTE_PATTERNS (voice/resultDisplay.js).
|
||||
coverage: state._altitudeGateOpen
|
||||
? `No feed here yet · ${TRANSIT_ENABLED_FEEDS.length} regions available`
|
||||
? `No feed here yet · ${TRANSIT_REGION_COUNT} regions available`
|
||||
: `Fly below ${Math.round(ACTIVATION_ALTITUDE_M / 1000).toLocaleString('en-US')} km to a covered region`,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { createQueries } from './queries.js';
|
||||
import { TRANSIT_ENABLED_FEEDS } from '../../data/transitFeeds.js';
|
||||
|
||||
test('the empty-coverage note counts regions, not feeds', () => {
|
||||
const rio = TRANSIT_ENABLED_FEEDS.filter(
|
||||
(feed) => feed.region === 'Rio de Janeiro, RJ',
|
||||
);
|
||||
assert.equal(rio.length, 2, 'Rio is one region with two feeds');
|
||||
const regions = new Set(TRANSIT_ENABLED_FEEDS.map((feed) => feed.region));
|
||||
assert.ok(regions.size < TRANSIT_ENABLED_FEEDS.length);
|
||||
|
||||
const stats = createQueries({
|
||||
state: {
|
||||
_activeFeeds: new Map(),
|
||||
_vehicles: new Map(),
|
||||
_enabled: true,
|
||||
_altitudeGateOpen: true,
|
||||
},
|
||||
parts: {},
|
||||
}).methods.getStats();
|
||||
assert.equal(stats.status, 'zoom-in');
|
||||
assert.equal(
|
||||
stats.coverage,
|
||||
`No feed here yet · ${regions.size} regions available`,
|
||||
);
|
||||
});
|
||||
@@ -409,3 +409,15 @@ test('empty coverage cannot hide stale, incomplete or rejected source data', asy
|
||||
assert.ok(layer.getStats().error, JSON.stringify(patch));
|
||||
}
|
||||
});
|
||||
|
||||
test('vessel stats name the provider the last snapshot reported', async () => {
|
||||
const { layer } = setup({
|
||||
label: 'Vessels',
|
||||
async getSnapshot() {
|
||||
return snapshot([observation('111')], { source: 'Datalastic' });
|
||||
},
|
||||
});
|
||||
assert.equal(layer.getStats().source, 'Vessels');
|
||||
await layer.update();
|
||||
assert.equal(layer.getStats().source, 'Datalastic');
|
||||
});
|
||||
@@ -548,6 +548,8 @@ export function createQueries({
|
||||
// backing off, say how long until the next attempt instead of leaving
|
||||
// the user to guess whether anything is still happening.
|
||||
retryInSec: aisRetryInSec(),
|
||||
// Same field as flights and military, so Contacts names the provider.
|
||||
source: layer.source,
|
||||
};
|
||||
},
|
||||
};
|
||||
|
||||
@@ -0,0 +1,155 @@
|
||||
// The regional feed includes sightings outside the layer's Salish Sea coverage.
|
||||
export const ACARTIA_GUARD_BOX = Object.freeze({
|
||||
south: 45.5,
|
||||
west: -126,
|
||||
north: 50.5,
|
||||
east: -121,
|
||||
});
|
||||
|
||||
// Frozen, conservative cetacean species/alias list for this regional feed.
|
||||
// Exact normalized names only: an unfamiliar name must never become a whale
|
||||
// merely because it contains "whale", "dolphin" or a known species name.
|
||||
export const ACARTIA_CETACEAN_NAMES = Object.freeze([
|
||||
'Orcinus orca',
|
||||
'Orca',
|
||||
'Killer whale',
|
||||
'Southern resident killer whale',
|
||||
'Northern resident killer whale',
|
||||
'Resident killer whale',
|
||||
"Bigg's killer whale",
|
||||
'Transient killer whale',
|
||||
'Offshore killer whale',
|
||||
'Megaptera novaeangliae',
|
||||
'Humpback whale',
|
||||
'Humpback',
|
||||
'Eschrichtius robustus',
|
||||
'Gray whale',
|
||||
'Grey whale',
|
||||
'Balaenoptera acutorostrata',
|
||||
'Common minke whale',
|
||||
'Minke whale',
|
||||
'Balaenoptera physalus',
|
||||
'Fin whale',
|
||||
'Finback whale',
|
||||
'Balaenoptera musculus',
|
||||
'Blue whale',
|
||||
'Balaenoptera borealis',
|
||||
'Sei whale',
|
||||
'Eubalaena japonica',
|
||||
'North Pacific right whale',
|
||||
'Physeter macrocephalus',
|
||||
'Sperm whale',
|
||||
'Kogia breviceps',
|
||||
'Pygmy sperm whale',
|
||||
'Kogia sima',
|
||||
'Dwarf sperm whale',
|
||||
'Berardius bairdii',
|
||||
"Baird's beaked whale",
|
||||
'Ziphius cavirostris',
|
||||
"Cuvier's beaked whale",
|
||||
'Mesoplodon carlhubbsi',
|
||||
"Hubbs' beaked whale",
|
||||
'Mesoplodon stejnegeri',
|
||||
"Stejneger's beaked whale",
|
||||
'Mesoplodon ginkgodens',
|
||||
'Ginkgo-toothed beaked whale',
|
||||
'Phocoena phocoena',
|
||||
'Harbor porpoise',
|
||||
'Harbour porpoise',
|
||||
'Phocoenoides dalli',
|
||||
"Dall's porpoise",
|
||||
'Lagenorhynchus obliquidens',
|
||||
'Pacific white-sided dolphin',
|
||||
'Lissodelphis borealis',
|
||||
'Northern right whale dolphin',
|
||||
'Grampus griseus',
|
||||
"Risso's dolphin",
|
||||
'Delphinus delphis',
|
||||
'Short-beaked common dolphin',
|
||||
'Common dolphin',
|
||||
'Delphinus capensis',
|
||||
'Long-beaked common dolphin',
|
||||
'Tursiops truncatus',
|
||||
'Common bottlenose dolphin',
|
||||
'Bottlenose dolphin',
|
||||
'Delphinapterus leucas',
|
||||
'Beluga whale',
|
||||
'Beluga',
|
||||
'Pseudorca crassidens',
|
||||
'False killer whale',
|
||||
'Globicephala macrorhynchus',
|
||||
'Short-finned pilot whale',
|
||||
]);
|
||||
|
||||
// These names clearly identify a marine mammal but do not establish a species
|
||||
// in the cetacean list. Retain them for ALL/MAMMALS, never for WHALES.
|
||||
const OTHER_MARINE_MAMMAL_NAMES = Object.freeze([
|
||||
'Phoca vitulina',
|
||||
'Harbor seal',
|
||||
'Harbour seal',
|
||||
'Mirounga angustirostris',
|
||||
'Northern elephant seal',
|
||||
'Zalophus californianus',
|
||||
'California sea lion',
|
||||
'Eumetopias jubatus',
|
||||
'Steller sea lion',
|
||||
"Steller's sea lion",
|
||||
'Callorhinus ursinus',
|
||||
'Northern fur seal',
|
||||
'Enhydra lutris',
|
||||
'Sea otter',
|
||||
'Seal',
|
||||
'Unidentified seal',
|
||||
'Sea lion',
|
||||
'Unidentified sea lion',
|
||||
'Pinniped',
|
||||
'Unidentified pinniped',
|
||||
'Marine mammal',
|
||||
'Unidentified marine mammal',
|
||||
'Unknown marine mammal',
|
||||
'Cetacean',
|
||||
'Unidentified cetacean',
|
||||
'Unknown cetacean',
|
||||
'Whale',
|
||||
'Unidentified whale',
|
||||
'Unknown whale',
|
||||
'Dolphin',
|
||||
'Unidentified dolphin',
|
||||
'Unknown dolphin',
|
||||
'Porpoise',
|
||||
'Unidentified porpoise',
|
||||
'Unknown porpoise',
|
||||
]);
|
||||
|
||||
function speciesKey(value) {
|
||||
return typeof value === 'string'
|
||||
? value
|
||||
.trim()
|
||||
.toLowerCase()
|
||||
.replace(/[\u2018\u2019]/g, "'")
|
||||
.replace(/[\u2010-\u2015]/g, '-')
|
||||
.replace(/\s+/g, ' ')
|
||||
: '';
|
||||
}
|
||||
|
||||
const CETACEANS = new Set(ACARTIA_CETACEAN_NAMES.map(speciesKey));
|
||||
const OTHER_MARINE_MAMMALS = new Set(OTHER_MARINE_MAMMAL_NAMES.map(speciesKey));
|
||||
|
||||
/** Classify exact normalized species names; ambiguous sightings stay noncetacean. */
|
||||
export function acartiaSpeciesGroup(value) {
|
||||
const key = speciesKey(value);
|
||||
if (CETACEANS.has(key)) return 'cetacean';
|
||||
return OTHER_MARINE_MAMMALS.has(key) ? 'marine-mammal' : null;
|
||||
}
|
||||
|
||||
/** Accept only positions inside the supported Salish Sea coverage. */
|
||||
export function inAcartiaCoverage(lat, lon) {
|
||||
return (
|
||||
Number.isFinite(lat) &&
|
||||
Number.isFinite(lon) &&
|
||||
lat >= ACARTIA_GUARD_BOX.south &&
|
||||
lat <= ACARTIA_GUARD_BOX.north &&
|
||||
lon >= ACARTIA_GUARD_BOX.west &&
|
||||
lon <= ACARTIA_GUARD_BOX.east
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { ACARTIA_CETACEAN_NAMES, acartiaSpeciesGroup } from './acartiaTaxa.js';
|
||||
|
||||
test('frozen cetacean names accept only normalized exact species or aliases', () => {
|
||||
assert.equal(Object.isFrozen(ACARTIA_CETACEAN_NAMES), true);
|
||||
assert.throws(() => ACARTIA_CETACEAN_NAMES.push('Whale shark'), TypeError);
|
||||
for (const name of ACARTIA_CETACEAN_NAMES) {
|
||||
assert.equal(acartiaSpeciesGroup(name), 'cetacean');
|
||||
assert.equal(acartiaSpeciesGroup(` ${name.toUpperCase()} `), 'cetacean');
|
||||
assert.equal(acartiaSpeciesGroup(`${name} or another animal`), null);
|
||||
}
|
||||
assert.equal(acartiaSpeciesGroup('Dall’s porpoise'), 'cetacean');
|
||||
assert.equal(acartiaSpeciesGroup('Pacific white–sided dolphin'), 'cetacean');
|
||||
assert.equal(acartiaSpeciesGroup(' HARBOR PORPOISE '), 'cetacean');
|
||||
});
|
||||
|
||||
test('clearly marine mammal names remain distinct from validated cetacean species', () => {
|
||||
for (const name of [
|
||||
'Harbor seal',
|
||||
'Phoca vitulina',
|
||||
'Sea otter',
|
||||
'Unidentified whale',
|
||||
]) {
|
||||
assert.equal(acartiaSpeciesGroup(name), 'marine-mammal');
|
||||
}
|
||||
for (const name of [
|
||||
'Unknown',
|
||||
'Whale shark',
|
||||
'Elephant',
|
||||
'',
|
||||
null,
|
||||
{ species: 'Orca' },
|
||||
]) {
|
||||
assert.equal(acartiaSpeciesGroup(name), null);
|
||||
}
|
||||
});
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,114 @@
|
||||
import { drainWildlifeWork, WILDLIFE_WORK_UNIT } from './performance.js';
|
||||
import { wildlifeIconicGroup } from './model.js';
|
||||
|
||||
/** Incremental billboard reconciliation, independent of Cesium and the DOM.
|
||||
* A refresh changes only added/removed contacts and properties that differ.
|
||||
* Position sampling and appearance construction run only for changed rows. */
|
||||
export function createWildlifeBillboardModel({
|
||||
collection,
|
||||
pointById,
|
||||
positions,
|
||||
positionForRow,
|
||||
appearanceForGroup,
|
||||
}) {
|
||||
const previous = new Map();
|
||||
|
||||
function update(rows, options = {}) {
|
||||
return drainWildlifeWork(updateWork(rows, options));
|
||||
}
|
||||
|
||||
function* updateWork(rows, { onOperations = null } = {}) {
|
||||
const nextIds = new Set();
|
||||
const result = { created: 0, removed: 0, updated: 0, writes: 0 };
|
||||
let visits = 0;
|
||||
for (const row of rows) {
|
||||
if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'billboard-update';
|
||||
const id = row.stableId;
|
||||
if (nextIds.has(id)) continue;
|
||||
nextIds.add(id);
|
||||
const group = wildlifeIconicGroup(row.iconic);
|
||||
const old = previous.get(id);
|
||||
const point = pointById.get(id);
|
||||
if (
|
||||
old &&
|
||||
point &&
|
||||
old.lat === row.lat &&
|
||||
old.lon === row.lon &&
|
||||
old.group === group
|
||||
)
|
||||
continue;
|
||||
const appearance =
|
||||
old && old.group === group ? old.appearance : appearanceForGroup(group);
|
||||
const positionChanged =
|
||||
!old || old.lat !== row.lat || old.lon !== row.lon;
|
||||
const position = positionChanged
|
||||
? positionForRow(row)
|
||||
: positions.get(id);
|
||||
if (!point) {
|
||||
const options = { id: `wildlife:${id}`, position, ...appearance };
|
||||
pointById.set(id, collection.add(options));
|
||||
positions.set(id, position);
|
||||
result.created += 1;
|
||||
result.writes += Object.keys(options).length;
|
||||
} else {
|
||||
let writes = 0;
|
||||
if (positionChanged) {
|
||||
point.position = position;
|
||||
positions.set(id, position);
|
||||
writes += 1;
|
||||
}
|
||||
for (const key of Object.keys(appearance)) {
|
||||
// Cesium clones Color and NearFarScalar values on assignment. Our
|
||||
// last descriptor, rather than getter reference identity, records
|
||||
// whether the appearance has actually changed.
|
||||
if (old?.appearance?.[key] === appearance[key]) continue;
|
||||
point[key] = appearance[key];
|
||||
writes += 1;
|
||||
}
|
||||
result.writes += writes;
|
||||
if (writes) result.updated += 1;
|
||||
}
|
||||
previous.set(id, {
|
||||
lat: row.lat,
|
||||
lon: row.lon,
|
||||
group,
|
||||
appearance,
|
||||
});
|
||||
}
|
||||
for (const [id, point] of pointById) {
|
||||
if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'billboard-update';
|
||||
if (nextIds.has(id)) continue;
|
||||
collection.remove(point);
|
||||
pointById.delete(id);
|
||||
positions.delete(id);
|
||||
previous.delete(id);
|
||||
result.removed += 1;
|
||||
}
|
||||
onOperations?.({ billboardVisits: visits, billboardWrites: result.writes });
|
||||
return result;
|
||||
}
|
||||
|
||||
function clear() {
|
||||
collection.removeAll();
|
||||
pointById.clear();
|
||||
positions.clear();
|
||||
previous.clear();
|
||||
}
|
||||
|
||||
// Font readiness replaces just the cached texture. Never resample anchors,
|
||||
// clear the collection or allocate replacement billboards for this swap.
|
||||
function refreshImages(imageForGroup) {
|
||||
let writes = 0;
|
||||
for (const [id, old] of previous) {
|
||||
const point = pointById.get(id);
|
||||
const image = imageForGroup(old.group);
|
||||
if (!point || old.appearance.image === image) continue;
|
||||
point.image = image;
|
||||
old.appearance = { ...old.appearance, image };
|
||||
writes += 1;
|
||||
}
|
||||
return writes;
|
||||
}
|
||||
|
||||
return { update, updateWork, clear, refreshImages };
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
// Shared by browser viewport queries and the provider's cache-key validation.
|
||||
export const WILDLIFE_MAX_VIEW_DEGREES = 40;
|
||||
|
||||
const cleanDegree = (value) => Math.round(value * 1e8) / 1e8;
|
||||
const spanOf = (box) => Math.max(box.north - box.south, box.east - box.west);
|
||||
|
||||
/** Snap non-crossing boxes outward to one canonical grid. Validate the final
|
||||
* span too: a legal raw box may expand past the supported query size. */
|
||||
export function snapWildlifeBox(box) {
|
||||
if (
|
||||
!box ||
|
||||
!['south', 'west', 'north', 'east'].every((key) =>
|
||||
Number.isFinite(box[key]),
|
||||
) ||
|
||||
box.south < -90 ||
|
||||
box.north > 90 ||
|
||||
box.west < -180 ||
|
||||
box.east > 180 ||
|
||||
box.north <= box.south ||
|
||||
box.east <= box.west ||
|
||||
spanOf(box) > WILDLIFE_MAX_VIEW_DEGREES + 1e-8
|
||||
)
|
||||
return null;
|
||||
let grid = spanOf(box) > 5 ? 1 : 0.1;
|
||||
const snap = () => ({
|
||||
south: Math.max(
|
||||
-90,
|
||||
cleanDegree(Math.floor((box.south + 1e-10) / grid) * grid),
|
||||
),
|
||||
west: Math.max(
|
||||
-180,
|
||||
cleanDegree(Math.floor((box.west + 1e-10) / grid) * grid),
|
||||
),
|
||||
north: Math.min(
|
||||
90,
|
||||
cleanDegree(Math.ceil((box.north - 1e-10) / grid) * grid),
|
||||
),
|
||||
east: Math.min(
|
||||
180,
|
||||
cleanDegree(Math.ceil((box.east - 1e-10) / grid) * grid),
|
||||
),
|
||||
});
|
||||
let snapped = snap();
|
||||
// Crossing the five-degree boundary while snapping must pick the same grid
|
||||
// on the browser and proxy, and on every subsequent snap of this box.
|
||||
if (grid === 0.1 && spanOf(snapped) > 5 + 1e-8) {
|
||||
grid = 1;
|
||||
snapped = snap();
|
||||
}
|
||||
return spanOf(snapped) <= WILDLIFE_MAX_VIEW_DEGREES ? snapped : null;
|
||||
}
|
||||
@@ -0,0 +1,111 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { inaturalistProxy } from '../../../server/providers/inaturalist/observations.js';
|
||||
import { syntheticGrid } from '../../../server/providers/inaturalist/grid.fixture.mjs';
|
||||
import {
|
||||
createWildlifeSightingsSource,
|
||||
WILDLIFE_GRID_TTL_MS,
|
||||
} from './source.js';
|
||||
|
||||
// Exercise both real cache owners through their projected response contract.
|
||||
// Only the HTTP transport and upstream data are synthetic; no socket is needed.
|
||||
test('client and proxy share stale revalidation and publish its fresh result in the same view', async () => {
|
||||
let now = Date.parse('2026-11-04T18:05:00Z');
|
||||
let upstreamCalls = 0;
|
||||
let proxyCalls = 0;
|
||||
let finishRefresh;
|
||||
let handler;
|
||||
inaturalistProxy({
|
||||
now: () => now,
|
||||
cacheDir: null,
|
||||
queueOptions: { intervalMs: 0, windowMs: 0 },
|
||||
warn() {},
|
||||
fetchImpl() {
|
||||
upstreamCalls++;
|
||||
return upstreamCalls === 1
|
||||
? Response.json(syntheticGrid())
|
||||
: new Promise((resolve) => {
|
||||
finishRefresh = resolve;
|
||||
});
|
||||
},
|
||||
}).configureServer({
|
||||
middlewares: {
|
||||
use(_mount, middleware) {
|
||||
handler = middleware;
|
||||
},
|
||||
},
|
||||
});
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
async fetchImpl(url) {
|
||||
proxyCalls++;
|
||||
let status;
|
||||
let headers;
|
||||
let response;
|
||||
await handler(
|
||||
{
|
||||
method: 'GET',
|
||||
url: url.slice('/api/inaturalist'.length),
|
||||
headers: {},
|
||||
socket: { remoteAddress: 'synthetic' },
|
||||
},
|
||||
{
|
||||
writeHead(code, values) {
|
||||
status = code;
|
||||
headers = values;
|
||||
},
|
||||
end(body) {
|
||||
response = new Response(body, { status, headers });
|
||||
},
|
||||
},
|
||||
);
|
||||
return response;
|
||||
},
|
||||
});
|
||||
const options = { tiles: [{ z: 2, x: 1, y: 1 }], taxa: 'Aves' };
|
||||
const first = await source.getGridSnapshot(options);
|
||||
assert.equal(first.cells.length, 2);
|
||||
await source.getGridSnapshot(options);
|
||||
assert.equal(upstreamCalls, 1);
|
||||
assert.equal(proxyCalls, 1, 'client hits do not even call the proxy');
|
||||
now += WILDLIFE_GRID_TTL_MS;
|
||||
const publications = [];
|
||||
let settled = false;
|
||||
const refreshing = source
|
||||
.getGridSnapshot({
|
||||
...options,
|
||||
onTile: (value) => publications.push(value),
|
||||
})
|
||||
.then((value) => {
|
||||
settled = true;
|
||||
return value;
|
||||
});
|
||||
try {
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
assert.equal(settled, false, 'revalidation is still waiting for upstream');
|
||||
assert.equal(
|
||||
publications[0]?.stale,
|
||||
true,
|
||||
'old cells already reached the renderer',
|
||||
);
|
||||
assert.deepEqual(publications[0].cells, first.cells);
|
||||
assert.equal(
|
||||
upstreamCalls,
|
||||
2,
|
||||
'normal stale GET and refresh=wait share one upstream attempt',
|
||||
);
|
||||
finishRefresh(Response.json(syntheticGrid()));
|
||||
const fresh = await refreshing;
|
||||
assert.equal(fresh.stale, false);
|
||||
assert.equal(fresh.fetchedAt, now);
|
||||
assert.equal(publications.at(-1).fetchedAt, now);
|
||||
assert.notEqual(publications.at(-1).stale, true);
|
||||
const before = proxyCalls;
|
||||
await source.getGridSnapshot(options);
|
||||
assert.equal(proxyCalls, before);
|
||||
assert.equal(upstreamCalls, 2);
|
||||
} finally {
|
||||
finishRefresh?.(Response.json(syntheticGrid()));
|
||||
await refreshing;
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,281 @@
|
||||
import { photoCreator } from './photoText.js';
|
||||
import { getLocale, t, translateKnown } from '../../i18n/index.js';
|
||||
import { CCTV_THUMBNAIL_STYLE } from '../../overlays/worldOverlayTokens.js';
|
||||
import { truncateOverlayTitle } from '../../overlays/worldOverlayDraw.js';
|
||||
import { isOpenPhoto } from './records.js';
|
||||
import { compareWildlifeIds, wildlifeIconicGroup } from './model.js';
|
||||
import {
|
||||
ICONIC_TINTS,
|
||||
WILDLIFE_CARD_LIMIT,
|
||||
WILDLIFE_CARD_MIN_SEP_PX,
|
||||
WILDLIFE_CARD_REGION_COLUMNS,
|
||||
WILDLIFE_CARD_REGION_ROWS,
|
||||
WILDLIFE_CARD_ALTITUDE_SCALE,
|
||||
WILDLIFE_CARD_FADE_LOW_METERS,
|
||||
WILDLIFE_CARD_FADE_HIGH_METERS,
|
||||
WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS,
|
||||
WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
|
||||
WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
WILDLIFE_CARD_MAX_DISTANCE_METERS,
|
||||
WILDLIFE_LABEL_LIMIT,
|
||||
} from './policy.js';
|
||||
|
||||
export const WILDLIFE_OVERLAY_SOURCE_ID = 'wildlife-sightings';
|
||||
export const WILDLIFE_LABEL_SOURCE_ID = 'wildlife-sightings-labels';
|
||||
export const WILDLIFE_SELECTED_SOURCE_ID = 'wildlife-sightings-selected';
|
||||
export const WILDLIFE_LABEL_SOURCE_OPTIONS = Object.freeze({
|
||||
cohortLimit: WILDLIFE_LABEL_LIMIT,
|
||||
collisionCapacity: WILDLIFE_LABEL_LIMIT,
|
||||
moving: false,
|
||||
});
|
||||
export const WILDLIFE_OVERLAY_SOURCE_OPTIONS = Object.freeze({
|
||||
cohortLimit: WILDLIFE_CARD_LIMIT,
|
||||
collisionCapacity: WILDLIFE_CARD_LIMIT,
|
||||
moving: false,
|
||||
});
|
||||
export const WILDLIFE_SELECTED_SOURCE_OPTIONS = Object.freeze({
|
||||
cohortLimit: 1,
|
||||
collisionCapacity: 1,
|
||||
moving: false,
|
||||
});
|
||||
|
||||
/** Match cards and labels to the sighting sprite's taxon tint. */
|
||||
export function wildlifeAccent(iconic) {
|
||||
return ICONIC_TINTS[wildlifeIconicGroup(iconic)];
|
||||
}
|
||||
|
||||
/** Importance score for open, non-sensitive iNaturalist photos. Other rows
|
||||
* cannot consume a slot, even if an accidental photo field reaches a caller. */
|
||||
export function ambientScore(row, nowMs) {
|
||||
if (row?.obscured || !isOpenPhoto(row?.photo) || !photoCreator(row.photo))
|
||||
return -Infinity;
|
||||
const nonnegative = (n) => (Number.isFinite(n) ? Math.max(0, n) : 0);
|
||||
const time = Number.isFinite(row.observedAt)
|
||||
? row.observedAt
|
||||
: Date.parse(row.observedOn);
|
||||
const ageH =
|
||||
Number.isFinite(time) && Number.isFinite(nowMs)
|
||||
? Math.max(0, (nowMs - time) / 3_600_000)
|
||||
: Infinity;
|
||||
return (
|
||||
(row.quality === 'research' ? 2 : 0) +
|
||||
(row.threatened ? 1 : 0) +
|
||||
Math.log1p(nonnegative(row.favesCount)) +
|
||||
0.5 * Math.log1p(nonnegative(row.identificationAgreements)) +
|
||||
2 * 0.5 ** (ageH / 12)
|
||||
);
|
||||
}
|
||||
|
||||
/** Named rows without eligible photos rank below eligible photo rows. */
|
||||
export function wildlifeLabelScore(row, nowMs) {
|
||||
const score = ambientScore(row, nowMs);
|
||||
return Number.isFinite(score) ? score : -1;
|
||||
}
|
||||
|
||||
/** Visible incumbents own their slots until they leave the view/window. A new
|
||||
* random sample or a higher-scoring challenger can only fill a free slot. */
|
||||
function rankWildlifeAmbientRows(rows, currentIds, nowMs) {
|
||||
const incumbent = new Map(currentIds.map((id, index) => [id, index]));
|
||||
const scored = rows
|
||||
.map((row) => ({
|
||||
row,
|
||||
score: ambientScore(row, nowMs),
|
||||
current: incumbent.get(row.stableId),
|
||||
}))
|
||||
.filter((item) => Number.isFinite(item.score));
|
||||
scored.sort((a, b) => {
|
||||
if (a.current !== undefined || b.current !== undefined) {
|
||||
if (a.current === undefined) return 1;
|
||||
if (b.current === undefined) return -1;
|
||||
return a.current - b.current;
|
||||
}
|
||||
return (
|
||||
b.score - a.score || compareWildlifeIds(a.row.stableId, b.row.stableId)
|
||||
);
|
||||
});
|
||||
return scored.map((item) => item.row);
|
||||
}
|
||||
|
||||
/** Spread newly admitted cards over screen regions. Once shown, a card stays
|
||||
* even when a pan moves it into another incumbent's region; region quotas only
|
||||
* govern free slots, so a camera movement never replaces a visible photo. */
|
||||
export function selectWildlifeAmbientRows(
|
||||
rows,
|
||||
currentIds = [],
|
||||
nowMs,
|
||||
limit = WILDLIFE_CARD_LIMIT,
|
||||
{ screens = null, width = 0, height = 0 } = {},
|
||||
) {
|
||||
const incumbent = new Set(currentIds);
|
||||
const accepted = [];
|
||||
const regions = new Set();
|
||||
const regionFor = (screen) =>
|
||||
`${Math.min(WILDLIFE_CARD_REGION_COLUMNS - 1, Math.floor((screen.x / width) * WILDLIFE_CARD_REGION_COLUMNS))}:${Math.min(WILDLIFE_CARD_REGION_ROWS - 1, Math.floor((screen.y / height) * WILDLIFE_CARD_REGION_ROWS))}`;
|
||||
for (const row of rankWildlifeAmbientRows(rows, currentIds, nowMs)) {
|
||||
if (accepted.length >= Math.max(0, limit)) break;
|
||||
const screen = screens?.get(row.stableId);
|
||||
const region = screen && width > 0 && height > 0 ? regionFor(screen) : null;
|
||||
if (!incumbent.has(row.stableId)) {
|
||||
if (region !== null && regions.has(region)) continue;
|
||||
if (
|
||||
screen &&
|
||||
accepted.some((other) => {
|
||||
const prior = screens.get(other.stableId);
|
||||
return (
|
||||
prior &&
|
||||
Math.hypot(prior.x - screen.x, prior.y - screen.y) <
|
||||
WILDLIFE_CARD_MIN_SEP_PX
|
||||
);
|
||||
})
|
||||
)
|
||||
continue;
|
||||
}
|
||||
accepted.push(row);
|
||||
if (region !== null) regions.add(region);
|
||||
}
|
||||
return accepted;
|
||||
}
|
||||
|
||||
function nameFor(row) {
|
||||
return translateKnown(row.commonName || row.scientificName) || t('SIGHTING');
|
||||
}
|
||||
|
||||
/** Return a trimmed common name, or null for unnamed observations. */
|
||||
export function wildlifeCommonName(row) {
|
||||
const name = row.commonName;
|
||||
return typeof name === 'string' && name.trim() ? name.trim() : null;
|
||||
}
|
||||
|
||||
/** Full translated display name, shared by titles and screen-space deduping. */
|
||||
export function wildlifeDisplayName(row) {
|
||||
const commonName = wildlifeCommonName(row);
|
||||
const name = commonName ? translateKnown(commonName).trim() : '';
|
||||
return name.replace(/\s+/g, ' ').trim().toLocaleUpperCase(getLocale());
|
||||
}
|
||||
|
||||
function compactName(row) {
|
||||
return truncateOverlayTitle(
|
||||
wildlifeDisplayName(row),
|
||||
WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
);
|
||||
}
|
||||
|
||||
/** One-line common names for identified observations. The caller adds the
|
||||
* Cartesian anchor after ranking and front-side/screen-space filtering. */
|
||||
export function buildWildlifeLabelEntry(
|
||||
row,
|
||||
{ select, hasRow, nowMs = Date.now() } = {},
|
||||
) {
|
||||
if (!wildlifeCommonName(row)) return null;
|
||||
return {
|
||||
id: `wildlife-sightings-label:${row.stableId}`,
|
||||
variant: 'label',
|
||||
title: compactName(row),
|
||||
accent: wildlifeAccent(row.iconic),
|
||||
priority: wildlifeLabelScore(row, nowMs),
|
||||
collisionGroup: 'ambient-label',
|
||||
// The host checks actual card placements, including sticky/fading cards,
|
||||
// before spending the remaining space on labels in score order.
|
||||
yieldToCollisionGroup: 'ambient-card',
|
||||
stateless: true,
|
||||
paintLane: 'ambient-label',
|
||||
gapPx: 15,
|
||||
verticalOnly: true,
|
||||
placement: 'above',
|
||||
horizonCull: true,
|
||||
edgeFade: 'keyhole',
|
||||
interactive: false,
|
||||
accessibilityLabel: nameFor(row),
|
||||
...selectionAction(row, { select, hasRow }),
|
||||
};
|
||||
}
|
||||
|
||||
function selectionAction(row, { select, hasRow } = {}) {
|
||||
if (typeof select !== 'function') return {};
|
||||
return {
|
||||
interactive: true,
|
||||
accessibilityLabel: t('Show {name} sighting', { name: nameFor(row) }),
|
||||
activate() {
|
||||
if (typeof hasRow === 'function' && !hasRow(row.stableId)) return false;
|
||||
return select(row.stableId) !== false;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** Build an attributed ambient photo; the runtime supplies the decoded image. */
|
||||
export function buildWildlifeThumbnailEntry(
|
||||
row,
|
||||
nowMs,
|
||||
{ image = null, select, hasRow, selected = false } = {},
|
||||
) {
|
||||
const score = ambientScore(row, nowMs);
|
||||
if (!Number.isFinite(score)) return null;
|
||||
return {
|
||||
id: `sighting:${row.stableId}`,
|
||||
variant: 'thumbnail',
|
||||
title: nameFor(row),
|
||||
image,
|
||||
requireImage: true,
|
||||
accent: wildlifeAccent(row.iconic),
|
||||
interactive: false,
|
||||
accessibilityLabel: t('Show {name} sighting', { name: nameFor(row) }),
|
||||
collisionGroup: 'ambient-card',
|
||||
horizonCull: true,
|
||||
edgeFade: 'keyhole',
|
||||
verticalOnly: true,
|
||||
gapPx: 15,
|
||||
thumbnailPadX: CCTV_THUMBNAIL_STYLE.padding,
|
||||
thumbnailPadTop: CCTV_THUMBNAIL_STYLE.padding,
|
||||
thumbnailPadBottom: CCTV_THUMBNAIL_STYLE.padding,
|
||||
thumbnailTitleGap: 2,
|
||||
thumbnailTitleHeight: CCTV_THUMBNAIL_STYLE.titleHeight,
|
||||
thumbnailTitleChars: CCTV_THUMBNAIL_STYLE.titleChars,
|
||||
thumbnailTitleWordBoundary: true,
|
||||
thumbnailBackground: CCTV_THUMBNAIL_STYLE.background,
|
||||
thumbnailTitleColor: CCTV_THUMBNAIL_STYLE.titleColor,
|
||||
thumbnailTitleFont: CCTV_THUMBNAIL_STYLE.titleFont,
|
||||
thumbnailLeaderColor: CCTV_THUMBNAIL_STYLE.leader,
|
||||
thumbnailRuleColor: CCTV_THUMBNAIL_STYLE.rule,
|
||||
thumbnailRuleHeight: CCTV_THUMBNAIL_STYLE.ruleHeight,
|
||||
thumbnailRadius: CCTV_THUMBNAIL_STYLE.radius,
|
||||
...selectionAction(row, { select, hasRow }),
|
||||
// i18n-ignore: the creator is verbatim feed attribution with a copyright mark
|
||||
details: [`© ${photoCreator(row.photo)}`],
|
||||
thumbnailFixedWidth: true,
|
||||
thumbnailFit: 'contain',
|
||||
thumbnailWidth: 96,
|
||||
thumbnailHeight: 72,
|
||||
priority: selected ? Number.MAX_SAFE_INTEGER : score,
|
||||
minAnchorSeparationPx: WILDLIFE_CARD_MIN_SEP_PX,
|
||||
maxDistance: WILDLIFE_CARD_MAX_DISTANCE_METERS,
|
||||
altitudeScale: WILDLIFE_CARD_ALTITUDE_SCALE,
|
||||
altitudeFadeStart: WILDLIFE_CARD_FADE_LOW_METERS,
|
||||
altitudeFadeEnd: WILDLIFE_CARD_FADE_HIGH_METERS,
|
||||
...(selected ? { selected: true, paintLane: 'selected' } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
/** A bounded selected name uses the host's shared selected card treatment. */
|
||||
export function buildWildlifeSelectedLabel(row) {
|
||||
if (!wildlifeCommonName(row)) return null;
|
||||
return {
|
||||
id: `wildlife-sightings-label:${row.stableId}`,
|
||||
variant: 'label',
|
||||
selected: true,
|
||||
protected: true,
|
||||
yieldToCollisionGroup: 'ambient-card',
|
||||
paintLane: 'selected',
|
||||
priority: Number.MAX_SAFE_INTEGER,
|
||||
title: compactName(row),
|
||||
accent: wildlifeAccent(row.iconic),
|
||||
gapPx: 15,
|
||||
verticalOnly: true,
|
||||
placement: 'above',
|
||||
horizonCull: true,
|
||||
edgeFade: 'keyhole',
|
||||
interactive: false,
|
||||
accessibilityLabel: nameFor(row),
|
||||
altitudeFadeStart: WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS,
|
||||
altitudeFadeEnd: WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,627 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
ambientScore,
|
||||
selectWildlifeAmbientRows,
|
||||
buildWildlifeThumbnailEntry,
|
||||
buildWildlifeLabelEntry,
|
||||
buildWildlifeSelectedLabel,
|
||||
wildlifeAccent,
|
||||
WILDLIFE_OVERLAY_SOURCE_OPTIONS,
|
||||
WILDLIFE_LABEL_SOURCE_ID,
|
||||
WILDLIFE_LABEL_SOURCE_OPTIONS,
|
||||
WILDLIFE_SELECTED_SOURCE_OPTIONS,
|
||||
} from './cards.js';
|
||||
import { CCTV_THUMBNAIL_STYLE } from '../../overlays/worldOverlayTokens.js';
|
||||
import {
|
||||
WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
WILDLIFE_CARD_SHOW_MAX_METERS,
|
||||
WILDLIFE_CARD_HIDE_MAX_METERS,
|
||||
WILDLIFE_LABEL_LIMIT,
|
||||
} from './policy.js';
|
||||
import { formatAge } from './photoText.js';
|
||||
import { createSelection } from './selection.js';
|
||||
import { setLocale } from '../../i18n/index.js';
|
||||
import {
|
||||
altitudeFade,
|
||||
altitudeScale,
|
||||
measureOverlayEntry,
|
||||
} from '../../overlays/worldOverlayDraw.js';
|
||||
|
||||
const now = Date.UTC(2026, 10, 4, 18, 40);
|
||||
const hour = 3_600_000;
|
||||
const photo = {
|
||||
square:
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpeg',
|
||||
medium:
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/medium.jpeg',
|
||||
licence: 'cc-by-nc',
|
||||
attribution: '(c) Synthetic Photographer, some rights reserved',
|
||||
};
|
||||
const row = (overrides = {}) => ({
|
||||
stableId: 'inat:123',
|
||||
origin: 'inaturalist',
|
||||
lat: 47.6,
|
||||
lon: -122.3,
|
||||
observedAt: now - 2 * hour,
|
||||
observedOn: '2026-11-04',
|
||||
obscured: false,
|
||||
cell: null,
|
||||
quality: 'research',
|
||||
accuracyM: 12,
|
||||
commonName: "Anna's Hummingbird",
|
||||
scientificName: 'Calypte anna',
|
||||
iconic: 'Aves',
|
||||
threatened: false,
|
||||
conservation: null,
|
||||
count: null,
|
||||
provider: null,
|
||||
obsLicence: 'cc-by-nc',
|
||||
link: 'https://www.inaturalist.org/observations/123',
|
||||
photo,
|
||||
favesCount: 0,
|
||||
identificationAgreements: 0,
|
||||
...overrides,
|
||||
});
|
||||
const acartia = (overrides = {}) =>
|
||||
row({
|
||||
stableId: 'acartia:abc',
|
||||
origin: 'acartia',
|
||||
iconic: 'Mammalia',
|
||||
commonName: 'Orca',
|
||||
scientificName: null,
|
||||
accuracyM: null,
|
||||
count: 5,
|
||||
provider: { name: 'Synthetic Network', entity: 'Whale Alert' },
|
||||
obsLicence: null,
|
||||
photo: null,
|
||||
link: 'https://acartia.io',
|
||||
...overrides,
|
||||
});
|
||||
|
||||
test('ambient photo score prioritizes grade, threat, appreciation and recency exactly', () => {
|
||||
const base = row({ quality: 'needs_id' });
|
||||
assert.ok(
|
||||
Math.abs(ambientScore(row(), now) - ambientScore(base, now) - 2) < 1e-12,
|
||||
);
|
||||
assert.equal(
|
||||
ambientScore(row({ threatened: true, observedAt: now }), now) -
|
||||
ambientScore(row({ observedAt: now }), now),
|
||||
1,
|
||||
);
|
||||
assert.ok(
|
||||
ambientScore(row({ favesCount: 8 }), now) >
|
||||
ambientScore(row({ favesCount: 1 }), now),
|
||||
);
|
||||
assert.ok(
|
||||
Math.abs(
|
||||
ambientScore(row({ identificationAgreements: 3 }), now) -
|
||||
ambientScore(row(), now) -
|
||||
0.5 * Math.log1p(3),
|
||||
) < 1e-12,
|
||||
);
|
||||
assert.ok(
|
||||
ambientScore(row({ quality: 'needs_id', observedAt: now - hour }), now) >
|
||||
ambientScore(
|
||||
row({ quality: 'needs_id', observedAt: now - 48 * hour }),
|
||||
now,
|
||||
),
|
||||
);
|
||||
for (const input of [
|
||||
row({ obscured: true }),
|
||||
row({ photo: null }),
|
||||
row({ photo: { ...photo, licence: 'cc-by-nd' } }),
|
||||
])
|
||||
assert.equal(ambientScore(input, now), -Infinity);
|
||||
});
|
||||
|
||||
test('ambient ranking ties by stable id and never replaces a visible incumbent', () => {
|
||||
const a = row({ stableId: 'inat:a' });
|
||||
const b = row({ stableId: 'inat:b' });
|
||||
assert.deepEqual(
|
||||
selectWildlifeAmbientRows([b, a], [], now).map((item) => item.stableId),
|
||||
['inat:a', 'inat:b'],
|
||||
);
|
||||
const slightlyBetter = row({ stableId: 'inat:b', observedAt: now - hour });
|
||||
assert.ok(ambientScore(slightlyBetter, now) - ambientScore(a, now) < 0.5);
|
||||
assert.equal(
|
||||
selectWildlifeAmbientRows([a, slightlyBetter], ['inat:a'], now, 1)[0]
|
||||
.stableId,
|
||||
'inat:a',
|
||||
);
|
||||
assert.equal(
|
||||
selectWildlifeAmbientRows(
|
||||
[a, row({ stableId: 'inat:b', threatened: true })],
|
||||
['inat:a'],
|
||||
now,
|
||||
1,
|
||||
)[0].stableId,
|
||||
'inat:a',
|
||||
);
|
||||
assert.equal(
|
||||
selectWildlifeAmbientRows([a], ['gone'], now, 24)[0].stableId,
|
||||
a.stableId,
|
||||
);
|
||||
});
|
||||
|
||||
test('ambient entries are stable, accessible and select in place until their row is gone', () => {
|
||||
const selected = [];
|
||||
let exists = true;
|
||||
const entry = buildWildlifeThumbnailEntry(row(), now, {
|
||||
select(id) {
|
||||
selected.push(id);
|
||||
},
|
||||
hasRow: () => exists,
|
||||
});
|
||||
assert.equal(entry.id, 'sighting:inat:123');
|
||||
assert.equal(entry.interactive, true);
|
||||
assert.equal(entry.accessibilityLabel, "Show Anna's Hummingbird sighting");
|
||||
assert.equal(entry.activate(), true);
|
||||
assert.deepEqual(selected, ['inat:123']);
|
||||
exists = false;
|
||||
assert.equal(entry.activate(), false);
|
||||
assert.equal(selected.length, 1);
|
||||
assert.equal(buildWildlifeThumbnailEntry(row({ obscured: true }), now), null);
|
||||
});
|
||||
|
||||
test('all wildlife name labels prefer a complete word before their ellipsis and retain the full accessible name', () => {
|
||||
const commonName =
|
||||
'Great Blue Heron With An Unusually Lengthy Synthetic Common Name';
|
||||
for (const build of [buildWildlifeLabelEntry, buildWildlifeSelectedLabel]) {
|
||||
const entry = build(row({ commonName }));
|
||||
assert.equal(entry.title, 'GREAT BLUE HERON WITH AN UNUSUALLY…');
|
||||
assert.ok(
|
||||
Array.from(entry.title).length <= WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
);
|
||||
assert.ok(entry.accessibilityLabel.includes(commonName));
|
||||
const unbroken = build(row({ commonName: '𓅃'.repeat(60) }));
|
||||
assert.equal(
|
||||
Array.from(unbroken.title).length,
|
||||
WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
);
|
||||
assert.ok(unbroken.title.endsWith('…'));
|
||||
assert.ok(!unbroken.title.includes('\ufffd'));
|
||||
}
|
||||
});
|
||||
|
||||
test('thumbnail entries use every shared thumbnail token and wildlife altitude curves', () => {
|
||||
const entry = buildWildlifeThumbnailEntry(row(), now);
|
||||
assert.deepEqual([entry.thumbnailWidth, entry.thumbnailHeight], [96, 72]);
|
||||
for (const key of ['thumbnailPadX', 'thumbnailPadTop', 'thumbnailPadBottom'])
|
||||
assert.equal(entry[key], CCTV_THUMBNAIL_STYLE.padding);
|
||||
const mapping = {
|
||||
thumbnailTitleHeight: 'titleHeight',
|
||||
thumbnailTitleChars: 'titleChars',
|
||||
thumbnailBackground: 'background',
|
||||
thumbnailTitleColor: 'titleColor',
|
||||
thumbnailTitleFont: 'titleFont',
|
||||
thumbnailLeaderColor: 'leader',
|
||||
thumbnailRuleColor: 'rule',
|
||||
thumbnailRuleHeight: 'ruleHeight',
|
||||
thumbnailRadius: 'radius',
|
||||
};
|
||||
for (const [field, token] of Object.entries(mapping))
|
||||
assert.equal(entry[field], CCTV_THUMBNAIL_STYLE[token]);
|
||||
assert.equal(entry.altitudeScale.fullEnd, 20_000);
|
||||
assert.equal(entry.altitudeScale.midEnd, 120_000);
|
||||
assert.equal(entry.altitudeFadeStart, 70_000);
|
||||
assert.equal(entry.altitudeFadeEnd, 125_000);
|
||||
assert.equal(entry.maxDistance, 600_000);
|
||||
assert.equal(entry.minAnchorSeparationPx, 112);
|
||||
assert.equal(entry.accent, wildlifeAccent('Aves'));
|
||||
assert.equal(entry.horizonCull, true);
|
||||
assert.equal(entry.requireImage, true);
|
||||
assert.deepEqual(entry.details, ['© Synthetic Photographer']);
|
||||
assert.equal(entry.thumbnailFixedWidth, true);
|
||||
assert.equal(entry.thumbnailFit, 'contain');
|
||||
assert.deepEqual(JSON.parse(JSON.stringify(entry)), entry);
|
||||
assert.equal(entry.interactive, false);
|
||||
assert.equal(Object.isFrozen(WILDLIFE_OVERLAY_SOURCE_OPTIONS), true);
|
||||
assert.equal(WILDLIFE_OVERLAY_SOURCE_OPTIONS.cohortLimit, 24);
|
||||
assert.equal(WILDLIFE_SELECTED_SOURCE_OPTIONS.cohortLimit, 1);
|
||||
assert.equal(WILDLIFE_SELECTED_SOURCE_OPTIONS.collisionCapacity, 1);
|
||||
});
|
||||
|
||||
test('ambient cards retain only the credited creator and leave names for host truncation', () => {
|
||||
const commonName = 'An extremely long synthetic organism name';
|
||||
for (const [attribution, creator] of [
|
||||
[
|
||||
'(c) Synthetic Photographer, some rights reserved (CC BY-NC)',
|
||||
'Synthetic Photographer',
|
||||
],
|
||||
['© Doe, Jane, some rights reserved (CC BY)', 'Doe, Jane'],
|
||||
['(c) Synthetic Observer, no rights reserved (CC0)', 'Synthetic Observer'],
|
||||
['Doe, Jane, CC BY', 'Doe, Jane'],
|
||||
['Synthetic Photographer, CC BY-NC', 'Synthetic Photographer'],
|
||||
['© Synthetic Photographer (CC BY-SA 4.0)', 'Synthetic Photographer'],
|
||||
['Synthetic Photographer, CC0', 'Synthetic Photographer'],
|
||||
['Synthetic Photographer', 'Synthetic Photographer'],
|
||||
]) {
|
||||
const input = row({ commonName, photo: { ...photo, attribution } });
|
||||
const entry = buildWildlifeThumbnailEntry(input, now);
|
||||
assert.equal(
|
||||
entry.title,
|
||||
commonName,
|
||||
'the overlay host truncates the title',
|
||||
);
|
||||
assert.equal(entry.thumbnailFixedWidth, true);
|
||||
assert.deepEqual(entry.details, [`© ${creator}`]);
|
||||
assert.doesNotMatch(
|
||||
entry.details.join(' '),
|
||||
/Photo:|reserved|CC BY|Not a census/,
|
||||
);
|
||||
}
|
||||
for (const attribution of [
|
||||
'some rights reserved (CC BY)',
|
||||
'(c) ',
|
||||
'CC BY',
|
||||
'CC-BY-NC',
|
||||
'© (CC BY)',
|
||||
]) {
|
||||
assert.equal(
|
||||
buildWildlifeThumbnailEntry(
|
||||
row({ photo: { ...photo, attribution } }),
|
||||
now,
|
||||
),
|
||||
null,
|
||||
'a missing creator never becomes a made-up ambient credit',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('ambient cards fade and scale gradually through the 120 km height band', () => {
|
||||
const entry = buildWildlifeThumbnailEntry(row(), now);
|
||||
const options = {
|
||||
fadeStart: entry.altitudeFadeStart,
|
||||
fadeEnd: entry.altitudeFadeEnd,
|
||||
};
|
||||
assert.equal(altitudeFade(70_000, options), 1);
|
||||
assert.ok(altitudeFade(100_000, options) > altitudeFade(120_000, options));
|
||||
assert.ok(altitudeFade(120_000, options) > 0);
|
||||
assert.equal(altitudeFade(125_000, options), 0);
|
||||
assert.equal(altitudeScale(20_000, entry.altitudeScale), 1);
|
||||
assert.equal(altitudeScale(120_000, entry.altitudeScale), 0.9);
|
||||
assert.ok(
|
||||
Math.abs(
|
||||
altitudeScale(119_999, entry.altitudeScale) -
|
||||
altitudeScale(120_001, entry.altitudeScale),
|
||||
) < 0.001,
|
||||
);
|
||||
});
|
||||
|
||||
test('selected rows use the shared selected treatment without duplicating photo content', () => {
|
||||
for (const input of [
|
||||
row(),
|
||||
row({ photo: null }),
|
||||
row({ obscured: true, observedAt: null, accuracyM: null }),
|
||||
acartia(),
|
||||
]) {
|
||||
const label = buildWildlifeSelectedLabel(input);
|
||||
assert.equal(label.id, `wildlife-sightings-label:${input.stableId}`);
|
||||
assert.equal(label.title, input.commonName.toLocaleUpperCase('en'));
|
||||
assert.equal(label.variant, 'label');
|
||||
assert.equal(label.placement, 'above');
|
||||
assert.equal(label.verticalOnly, true);
|
||||
assert.equal(label.protected, true);
|
||||
assert.equal(label.paintLane, 'selected');
|
||||
assert.equal(label.priority, Number.MAX_SAFE_INTEGER);
|
||||
assert.equal(label.interactive, false);
|
||||
assert.equal(label.selected, true);
|
||||
assert.equal(label.details, undefined, 'no link line on canvas cards');
|
||||
assert.equal(label.horizonCull, true);
|
||||
assert.equal(label.edgeFade, 'keyhole');
|
||||
assert.equal(label.accent, wildlifeAccent(input.iconic));
|
||||
for (const field of ['image', 'thumbnailWidth', 'pinned', 'activate'])
|
||||
assert.equal(
|
||||
Object.hasOwn(label, field),
|
||||
false,
|
||||
`${field} is absent from the selected name label`,
|
||||
);
|
||||
assert.deepEqual(JSON.parse(JSON.stringify(label)), label);
|
||||
}
|
||||
const ctx = { measureText: (value) => ({ width: String(value).length * 6 }) };
|
||||
const measured = measureOverlayEntry(ctx, buildWildlifeSelectedLabel(row()));
|
||||
assert.equal(
|
||||
measured.titleH,
|
||||
15,
|
||||
'selected names use the shared selected title metrics',
|
||||
);
|
||||
assert.equal(measured.padX, 12);
|
||||
assert.equal(measured.padY, 8);
|
||||
});
|
||||
|
||||
test('selected labels normalize one bounded common-name line and stay absent when unnamed', () => {
|
||||
const label = buildWildlifeSelectedLabel(
|
||||
row({
|
||||
commonName: `Synthetic\n ${'organism '.repeat(10)}`,
|
||||
}),
|
||||
);
|
||||
assert.doesNotMatch(label.title, /\n| /);
|
||||
assert.ok(
|
||||
Array.from(label.title).length <= WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
);
|
||||
assert.equal(label.title, 'SYNTHETIC ORGANISM ORGANISM ORGANISM…');
|
||||
assert.ok(label.title.endsWith('…'));
|
||||
assert.equal(buildWildlifeSelectedLabel(row({ commonName: null })), null);
|
||||
assert.equal(
|
||||
buildWildlifeSelectedLabel(row({ commonName: null, scientificName: null })),
|
||||
null,
|
||||
);
|
||||
});
|
||||
|
||||
test('detail labels show only common names, with no age, grade, accuracy or photo details', () => {
|
||||
const label = buildWildlifeLabelEntry(row());
|
||||
assert.equal(label.id, 'wildlife-sightings-label:inat:123');
|
||||
assert.equal(label.title, "ANNA'S HUMMINGBIRD");
|
||||
assert.equal(label.variant, 'label');
|
||||
assert.equal(label.collisionGroup, 'ambient-label');
|
||||
assert.equal(label.yieldToCollisionGroup, 'ambient-card');
|
||||
assert.equal(
|
||||
label.stateless,
|
||||
true,
|
||||
'labels never retain overlapping incumbent or exit placements',
|
||||
);
|
||||
assert.equal(label.paintLane, 'ambient-label');
|
||||
assert.equal(label.horizonCull, true);
|
||||
assert.equal(label.edgeFade, 'keyhole');
|
||||
assert.equal(label.interactive, false);
|
||||
assert.equal(label.accent, wildlifeAccent('Aves'));
|
||||
for (const field of [
|
||||
'details',
|
||||
'image',
|
||||
'accuracyM',
|
||||
'quality',
|
||||
'observedAt',
|
||||
'maxDistance',
|
||||
'altitudeFadeStart',
|
||||
'altitudeFadeEnd',
|
||||
'selected',
|
||||
])
|
||||
assert.equal(Object.hasOwn(label, field), false, field);
|
||||
assert.equal(WILDLIFE_LABEL_SOURCE_ID, 'wildlife-sightings-labels');
|
||||
assert.equal(WILDLIFE_LABEL_LIMIT, 150);
|
||||
assert.equal(Object.isFrozen(WILDLIFE_LABEL_SOURCE_OPTIONS), true);
|
||||
assert.equal(WILDLIFE_LABEL_SOURCE_OPTIONS.cohortLimit, WILDLIFE_LABEL_LIMIT);
|
||||
assert.equal(
|
||||
WILDLIFE_LABEL_SOURCE_OPTIONS.collisionCapacity,
|
||||
WILDLIFE_LABEL_LIMIT,
|
||||
);
|
||||
assert.deepEqual(JSON.parse(JSON.stringify(label)), label);
|
||||
});
|
||||
|
||||
test('unnamed observations have no ambient label and names come only from the row', () => {
|
||||
for (const commonName of [null, undefined, '', ' \n\t '])
|
||||
assert.equal(buildWildlifeLabelEntry({ ...row(), commonName }), null);
|
||||
assert.equal(
|
||||
buildWildlifeLabelEntry({ ...row(), commonName: 'Red-tailed hawk' }).title,
|
||||
'RED-TAILED HAWK',
|
||||
);
|
||||
});
|
||||
|
||||
test('ambient names select in place and reject activation after their row disappears', () => {
|
||||
let selectedId = null;
|
||||
let exists = true;
|
||||
const label = buildWildlifeLabelEntry(row(), {
|
||||
select(id) {
|
||||
selectedId = id;
|
||||
},
|
||||
hasRow: () => exists,
|
||||
});
|
||||
assert.equal(label.interactive, true);
|
||||
assert.equal(label.accessibilityLabel, "Show Anna's Hummingbird sighting");
|
||||
assert.equal(label.activate(), true);
|
||||
assert.equal(selectedId, 'inat:123');
|
||||
exists = false;
|
||||
assert.equal(label.activate(), false);
|
||||
});
|
||||
|
||||
test('selected name labels retain the existing altitude fade through 400 km', () => {
|
||||
for (const input of [row(), row({ photo: null }), acartia()]) {
|
||||
const entry = buildWildlifeSelectedLabel(input);
|
||||
const options = {
|
||||
fadeStart: entry.altitudeFadeStart,
|
||||
fadeEnd: entry.altitudeFadeEnd,
|
||||
};
|
||||
assert.equal(altitudeFade(30_000, options), 1);
|
||||
assert.ok(altitudeFade(300_000, options) > 0);
|
||||
assert.equal(altitudeFade(400_000, options), 0);
|
||||
assert.equal(altitudeFade(5_000_000, options), 0);
|
||||
}
|
||||
});
|
||||
|
||||
test('compact ages follow shared translated minute, hour and day forms', () => {
|
||||
assert.equal(formatAge(59_999), '1m');
|
||||
assert.equal(formatAge(60 * 60_000), '1h');
|
||||
assert.equal(formatAge(2 * 24 * hour), '2d');
|
||||
assert.equal(formatAge(-1), null);
|
||||
assert.equal(formatAge(NaN), null);
|
||||
assert.equal(wildlifeAccent('Protozoa'), '#9aa7b3');
|
||||
});
|
||||
|
||||
function ambientFixture(rows, screens) {
|
||||
const state = {
|
||||
enabled: true,
|
||||
renderedRows: rows,
|
||||
ambientRows: [],
|
||||
ambientIds: [],
|
||||
labelRows: [],
|
||||
selectedId: null,
|
||||
positions: new Map(
|
||||
rows.map((row) => [row.stableId, screens.get(row.stableId)]),
|
||||
),
|
||||
pointById: new Map(),
|
||||
rowById: new Map(rows.map((row) => [row.stableId, row])),
|
||||
viewer: {
|
||||
scene: { canvas: { clientWidth: 1200, clientHeight: 900 } },
|
||||
camera: { positionCartographic: { height: 30_000 } },
|
||||
},
|
||||
};
|
||||
const photos = [];
|
||||
const painted = [];
|
||||
const entries = new Map();
|
||||
let cardSourceOptions;
|
||||
const selection = createSelection({
|
||||
state,
|
||||
services: {
|
||||
now: () => now,
|
||||
project: (_scene, position) => position,
|
||||
overlayHost: {
|
||||
setEntries(id, _entries, options) {
|
||||
entries.set(id, _entries);
|
||||
if (id === 'wildlife-sightings') cardSourceOptions = options;
|
||||
},
|
||||
},
|
||||
},
|
||||
parts: {
|
||||
rendering: {
|
||||
occluder: () => null,
|
||||
requestRender() {},
|
||||
setPhotoCardVisibility: (ids) => painted.push([...ids]),
|
||||
},
|
||||
photos: { get: () => null, setAmbient: (rows) => photos.push(rows) },
|
||||
},
|
||||
});
|
||||
return {
|
||||
state,
|
||||
selection,
|
||||
photos,
|
||||
painted,
|
||||
entries,
|
||||
get cardSourceOptions() {
|
||||
return cardSourceOptions;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('label candidates and host priorities use ambientScore before the candidate cap', () => {
|
||||
const rows = Array.from({ length: WILDLIFE_LABEL_LIMIT + 20 }, (_, i) =>
|
||||
row({
|
||||
stableId: `inat:${String(i).padStart(3, '0')}`,
|
||||
commonName: `Synthetic bird ${i}`,
|
||||
favesCount: i,
|
||||
}),
|
||||
);
|
||||
const f = ambientFixture(
|
||||
rows,
|
||||
new Map(
|
||||
rows.map((r, i) => [
|
||||
r.stableId,
|
||||
{ x: 10 + (i % 40) * 28, y: 200 + Math.floor(i / 40) * 28 },
|
||||
]),
|
||||
),
|
||||
);
|
||||
f.selection.refreshAmbient();
|
||||
const entries = f.entries.get('wildlife-sightings-labels');
|
||||
assert.equal(entries.length, WILDLIFE_LABEL_LIMIT);
|
||||
assert.deepEqual(
|
||||
entries.map((entry) => entry.id),
|
||||
rows
|
||||
.slice(20)
|
||||
.reverse()
|
||||
.map((r) => `wildlife-sightings-label:${r.stableId}`),
|
||||
);
|
||||
for (const r of f.state.labelRows)
|
||||
assert.equal(
|
||||
buildWildlifeLabelEntry(r, { nowMs: now }).priority,
|
||||
ambientScore(r, now),
|
||||
);
|
||||
});
|
||||
|
||||
test('ambient source forwards actual painted membership to badge visibility', () => {
|
||||
const r = row();
|
||||
const f = ambientFixture([r], new Map([[r.stableId, { x: 150, y: 150 }]]));
|
||||
f.selection.refreshAmbient();
|
||||
assert.deepEqual(f.painted, [], 'a queued photo is not a painted card');
|
||||
f.cardSourceOptions.onVisibilityChange(new Set([`sighting:${r.stableId}`]));
|
||||
assert.deepEqual(f.painted, [[`sighting:${r.stableId}`]]);
|
||||
f.cardSourceOptions.onVisibilityChange(new Set());
|
||||
assert.deepEqual(f.painted.at(-1), []);
|
||||
});
|
||||
|
||||
test('new ambient cards admit at most one highest-score photo per screen region', () => {
|
||||
const rows = Array.from({ length: 24 }, (_, i) =>
|
||||
row({ stableId: `inat:${i}`, favesCount: i }),
|
||||
);
|
||||
const screens = new Map(
|
||||
rows.map((row, i) => [
|
||||
row.stableId,
|
||||
{
|
||||
x: 150 + (Math.floor(i / 2) % 4) * 300,
|
||||
y: 150 + Math.floor(i / 8) * 300,
|
||||
},
|
||||
]),
|
||||
);
|
||||
const f = ambientFixture(rows, screens);
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 12);
|
||||
assert.ok(
|
||||
f.state.ambientRows.every(
|
||||
(row) => Number(row.stableId.split(':')[1]) % 2 === 1,
|
||||
),
|
||||
);
|
||||
assert.equal(
|
||||
new Set(
|
||||
f.state.ambientRows.map((row) => {
|
||||
const p = screens.get(row.stableId);
|
||||
return `${Math.floor(p.x / 300)}:${Math.floor(p.y / 300)}`;
|
||||
}),
|
||||
).size,
|
||||
12,
|
||||
);
|
||||
});
|
||||
|
||||
test('pans retain every on-screen photo and refreshes only fill free slots', () => {
|
||||
const a = row({ stableId: 'inat:a' });
|
||||
const b = row({ stableId: 'inat:b' });
|
||||
const c = row({ stableId: 'inat:c', favesCount: 1000 });
|
||||
const screens = new Map([
|
||||
[a.stableId, { x: 150, y: 150 }],
|
||||
[b.stableId, { x: 450, y: 150 }],
|
||||
[c.stableId, { x: 170, y: 150 }],
|
||||
]);
|
||||
const f = ambientFixture([a, b], screens);
|
||||
f.selection.refreshAmbient();
|
||||
const initial = f.state.ambientIds.slice();
|
||||
// This pan moves the two incumbents into one region. Neither may be evicted.
|
||||
f.state.positions.set(b.stableId, { x: 200, y: 160 });
|
||||
f.selection.refreshAmbient();
|
||||
assert.deepEqual(f.state.ambientIds, initial);
|
||||
f.state.rowById.set(c.stableId, c);
|
||||
f.state.positions.set(c.stableId, screens.get(c.stableId));
|
||||
// A new random sample can omit both incumbent rows from the rendered batch.
|
||||
f.state.renderedRows = [c];
|
||||
f.selection.refreshAmbient();
|
||||
assert.deepEqual(f.state.ambientIds, initial);
|
||||
assert.deepEqual(
|
||||
new Set(f.selection.retainedAmbientRows().map((row) => row.stableId)),
|
||||
new Set(initial),
|
||||
);
|
||||
f.state.positions.set(a.stableId, { x: -1, y: 150 });
|
||||
assert.deepEqual(
|
||||
f.selection.retainedAmbientRows().map((row) => row.stableId),
|
||||
[b.stableId],
|
||||
);
|
||||
});
|
||||
|
||||
test('ambient show/hide thresholds have hysteresis without small-zoom toggles', () => {
|
||||
const a = row();
|
||||
const f = ambientFixture([a], new Map([[a.stableId, { x: 150, y: 150 }]]));
|
||||
const height = f.state.viewer.camera.positionCartographic;
|
||||
height.height = WILDLIFE_CARD_SHOW_MAX_METERS - 1;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 1);
|
||||
for (const altitude of [110_001, 119_999, 120_001, 124_999, 110_001]) {
|
||||
height.height = altitude;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 1);
|
||||
}
|
||||
height.height = WILDLIFE_CARD_HIDE_MAX_METERS;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 0);
|
||||
height.height = WILDLIFE_CARD_HIDE_MAX_METERS - 1;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 0);
|
||||
height.height = WILDLIFE_CARD_SHOW_MAX_METERS;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 1);
|
||||
});
|
||||
+250
@@ -0,0 +1,250 @@
|
||||
import { t, formatNumber, translateKnown } from '../../i18n/index.js';
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
import { translateFeedError } from '../../ui/statusText.js';
|
||||
import { wildlifeIconicGroup } from './model.js';
|
||||
import { formatAge } from './photoText.js';
|
||||
import {
|
||||
ICONIC_TINTS,
|
||||
ICONIC_LEGEND_ORDER,
|
||||
TAXA_PRESETS,
|
||||
WILDLIFE_CONFIRMED_CHIP_ID,
|
||||
WILDLIFE_GRID_HEIGHT_METERS,
|
||||
WILDLIFE_UPDATE_INTERVAL_MS,
|
||||
} from './policy.js';
|
||||
|
||||
const LEGEND_LABELS = Object.freeze({
|
||||
Aves: msg('Birds'),
|
||||
Mammalia: msg('Mammals'),
|
||||
Reptilia: msg('Reptiles'),
|
||||
Amphibia: msg('Amphibians'),
|
||||
Actinopterygii: msg('Ray-finned fishes'),
|
||||
Insecta: msg('Insects'),
|
||||
Arachnida: msg('Arachnids'),
|
||||
Plantae: msg('Plants'),
|
||||
Fungi: msg('Fungi'),
|
||||
Animalia: msg('Other animals'),
|
||||
Unknown: msg('Other or unknown'),
|
||||
});
|
||||
|
||||
/** Own layer-row descriptors and serializable filter options. */
|
||||
export function createControls({ state, services, parts }) {
|
||||
function notify() {
|
||||
try {
|
||||
state.controlsListener?.();
|
||||
} catch {
|
||||
/* repaint listeners are optional */
|
||||
}
|
||||
}
|
||||
|
||||
function chip({ id, label, title, params, key, value }) {
|
||||
const pending =
|
||||
state.pendingParams?.keys.includes(key) &&
|
||||
(key === 'confirmed' || state.pendingParams[key] === value);
|
||||
const failedKey = state.failedParams?.keys.includes(key);
|
||||
const failed =
|
||||
failedKey && (key === 'confirmed' || state.failedParams[key] === value);
|
||||
const active =
|
||||
!pending &&
|
||||
(failedKey
|
||||
? state[key] === value
|
||||
: !!state.drawnParams && state.drawnParams[key] === value);
|
||||
return {
|
||||
id,
|
||||
label: `${label}${pending ? ' ···' : failed ? ' ✕' : ''}`,
|
||||
title: failed
|
||||
? t('{label} {detail} — click to retry', {
|
||||
label,
|
||||
detail: translateFeedError(
|
||||
state.error || msg('Wildlife sightings source unavailable'),
|
||||
),
|
||||
})
|
||||
: title,
|
||||
active,
|
||||
busy: !!pending,
|
||||
disabled: !!pending,
|
||||
state: pending
|
||||
? 'loading'
|
||||
: failed
|
||||
? 'error'
|
||||
: active
|
||||
? 'active'
|
||||
: 'idle',
|
||||
params,
|
||||
};
|
||||
}
|
||||
|
||||
const methods = {
|
||||
id: 'wildlife-sightings',
|
||||
name: 'Wildlife Sightings',
|
||||
icon: '🦉',
|
||||
source: 'iNaturalist',
|
||||
updateInterval: WILDLIFE_UPDATE_INTERVAL_MS,
|
||||
|
||||
/** Route camera refreshes through the application's lifecycle manager. */
|
||||
attachDataManager(manager) {
|
||||
state.manager = manager;
|
||||
},
|
||||
/** Connect the layer row's repaint listener. */
|
||||
setRowControlsListener(listener) {
|
||||
state.controlsListener = typeof listener === 'function' ? listener : null;
|
||||
},
|
||||
/** Snapshot the requested filters for share links and restoration. */
|
||||
getParams() {
|
||||
return { confirmed: state.confirmed, taxa: state.taxa };
|
||||
},
|
||||
/** Apply filters while retaining the last accepted display until success. */
|
||||
setParams(params = {}) {
|
||||
const next = {
|
||||
confirmed:
|
||||
typeof params.confirmed === 'boolean'
|
||||
? params.confirmed
|
||||
: state.confirmed,
|
||||
taxa: TAXA_PRESETS.some((preset) => preset.value === params.taxa)
|
||||
? params.taxa
|
||||
: state.taxa,
|
||||
};
|
||||
const changed = ['confirmed', 'taxa'].filter(
|
||||
(key) => next[key] !== state[key],
|
||||
);
|
||||
if (!changed.length && !state.failedParams) return true;
|
||||
// Compare with the displayed filters so disjoint edits stay pending.
|
||||
// Initially taxa awaits data while the default-off toggle remains idle.
|
||||
const drawn = state.drawnParams || { confirmed: false, taxa: null };
|
||||
const keys = ['confirmed', 'taxa'].filter(
|
||||
(key) => next[key] !== drawn[key],
|
||||
);
|
||||
if (!changed.length && state.failedParams) {
|
||||
for (const key of state.failedParams.keys) {
|
||||
if (!keys.includes(key)) keys.push(key);
|
||||
}
|
||||
}
|
||||
state.confirmed = next.confirmed;
|
||||
state.taxa = next.taxa;
|
||||
state.pendingParams = keys.length ? { ...next, keys } : null;
|
||||
state.failedParams = null;
|
||||
// Replace the LRU with the accepted result so taxa never get mixed.
|
||||
state.pendingClear = true;
|
||||
state.lastQueryKey = null;
|
||||
state.request?.abort();
|
||||
state.background?.abort();
|
||||
parts.lifecycle.scheduleRefresh();
|
||||
notify();
|
||||
return true;
|
||||
},
|
||||
/** Describe filter chips, nonempty legend groups and provider attribution. */
|
||||
getRowControls() {
|
||||
const confirmedFailed = state.failedParams?.keys.includes('confirmed');
|
||||
const chips = [
|
||||
chip({
|
||||
id: WILDLIFE_CONFIRMED_CHIP_ID,
|
||||
label: t('CONFIRMED'),
|
||||
title: t('Show only community-confirmed (research-grade) sightings'),
|
||||
params: {
|
||||
confirmed: confirmedFailed ? state.confirmed : !state.confirmed,
|
||||
},
|
||||
key: 'confirmed',
|
||||
value: true,
|
||||
}),
|
||||
...TAXA_PRESETS.map((preset) =>
|
||||
chip({
|
||||
id: preset.id,
|
||||
label: translateKnown(preset.label),
|
||||
title: translateKnown(preset.title),
|
||||
params: { taxa: preset.value },
|
||||
key: 'taxa',
|
||||
value: preset.value,
|
||||
}),
|
||||
),
|
||||
];
|
||||
const counts = new Map();
|
||||
for (const row of state.renderedRows) {
|
||||
const group = wildlifeIconicGroup(row.iconic);
|
||||
counts.set(group, (counts.get(group) || 0) + 1);
|
||||
}
|
||||
const legend = ICONIC_LEGEND_ORDER.filter((key) => counts.has(key)).map(
|
||||
(key, index) => ({
|
||||
label: translateKnown(LEGEND_LABELS[key]),
|
||||
color: ICONIC_TINTS[key],
|
||||
count: counts.get(key),
|
||||
...(index === 0
|
||||
? {
|
||||
blurb: t(
|
||||
'Wildlife observed within 48 h (whales 7 d). Color and badge glyph show the taxon group. Sensitive species are shown only as 0.2° cells; Salish Sea marine mammal reports via Acartia are rounded to 0.01°. Not a census.',
|
||||
),
|
||||
}
|
||||
: {}),
|
||||
}),
|
||||
);
|
||||
if (!state.lastUpdate && !legend.length) return { chips, legend: [] };
|
||||
const acartiaCount = state.renderedRows.filter(
|
||||
(row) => row.origin === 'acartia',
|
||||
).length;
|
||||
const info = acartiaCount
|
||||
? t(
|
||||
'iNaturalist contributors · Acartia {count} (Salish Sea) · licences per record',
|
||||
{ count: formatNumber(acartiaCount) },
|
||||
)
|
||||
: t('iNaturalist contributors · licences per record');
|
||||
return { chips, legend, info };
|
||||
},
|
||||
/** Report the visible count, feed state and retry guidance. */
|
||||
getStats() {
|
||||
const grid = state.gridAvailable === true;
|
||||
const count =
|
||||
state.sightingCount ??
|
||||
(grid ? (state.gridTotal ?? 0) : state.renderedRows.length);
|
||||
const loading = state.loading && !state.lastUpdate;
|
||||
const refreshing = state.loading && !!state.lastUpdate;
|
||||
const age = state.lastUpdate
|
||||
? formatAge(services.now() - state.lastUpdate)
|
||||
: '';
|
||||
const minutes = state.lastUpdate
|
||||
? Math.max(0, (services.now() - state.lastUpdate) / 60_000)
|
||||
: 0;
|
||||
const liveAge =
|
||||
minutes < 1
|
||||
? t('<1m ago')
|
||||
: minutes < 90
|
||||
? t('{count}m ago', { count: Math.floor(minutes) })
|
||||
: t('{count}h ago', { count: Math.round(minutes / 60) });
|
||||
const stats = {
|
||||
count,
|
||||
lastUpdate: state.lastUpdate,
|
||||
error: state.error,
|
||||
stale: state.stale,
|
||||
loading,
|
||||
refreshing,
|
||||
countLabel: t('{count} sightings in view', {
|
||||
count: formatNumber(count),
|
||||
}),
|
||||
loadingLabel: loading
|
||||
? t('loading...')
|
||||
: refreshing
|
||||
? t('refreshing...')
|
||||
: state.stale
|
||||
? t('STALE · cached {age}', { age })
|
||||
: state.lastUpdate
|
||||
? t('LIVE · updated {age}', { age: liveAge })
|
||||
: '',
|
||||
};
|
||||
if (
|
||||
!state.error &&
|
||||
!state.query &&
|
||||
state.viewer?.camera?.positionCartographic?.height >
|
||||
WILDLIFE_GRID_HEIGHT_METERS
|
||||
) {
|
||||
// i18n-ignore: feed-state protocol value
|
||||
stats.status = 'zoom-in';
|
||||
stats.statusMessage = msg('Zoom in for local sightings');
|
||||
} else if (!state.error && state.lastUpdate && !count) {
|
||||
// i18n-ignore: feed-state protocol value
|
||||
stats.status = 'empty';
|
||||
stats.statusMessage = msg('No recent sightings in view');
|
||||
}
|
||||
if (state.retryAt > services.now())
|
||||
stats.retryInSec = Math.ceil((state.retryAt - services.now()) / 1000);
|
||||
return stats;
|
||||
},
|
||||
};
|
||||
return { methods, notify };
|
||||
}
|
||||
@@ -0,0 +1,462 @@
|
||||
import { wildlifeGridCellBounds } from './gridViewport.js';
|
||||
import {
|
||||
createWildlifeWorkQueue,
|
||||
drainWildlifeWork,
|
||||
WILDLIFE_WORK_UNIT,
|
||||
} from './performance.js';
|
||||
|
||||
export const WILDLIFE_DENSITY_OVERLAP = 4;
|
||||
const KERNEL_SIGMA = 0.7;
|
||||
export const WILDLIFE_DENSITY_MAX_ALPHA = 0.34;
|
||||
const DENSITY_MIN_ALPHA = 0.012;
|
||||
const DENSITY_RAMP_GAMMA = 3;
|
||||
const METERS_PER_DEGREE = (2 * Math.PI * 6378137) / 360;
|
||||
const FADE_STEPS = 3;
|
||||
const FADE_STEP_MS = 60;
|
||||
const SPRITE_SIZE = 128;
|
||||
// Fade coarse splats before they read as haze across the whole Earth disc.
|
||||
const ALTITUDE_FADE_START = 3_000_000;
|
||||
const ALTITUDE_FADE_END = 8_000_000;
|
||||
// Sparse cells read cool teal; hotspots warm toward amber. Sensor styles keep
|
||||
// one neutral or phosphor tint.
|
||||
const NORMAL_TINT = { low: [0.3, 0.8, 0.78], high: [1, 0.78, 0.38] };
|
||||
const MONO_TINT = { low: [0.96, 0.96, 0.96], high: [0.96, 0.96, 0.96] };
|
||||
const CRT_TINT = { low: [0.48, 1, 0.72], high: [0.48, 1, 0.72] };
|
||||
|
||||
/** View-relative alpha keeps hotspots distinct as cell counts grow on zoom-out. */
|
||||
export function wildlifeDensityIntensity(rank) {
|
||||
if (!(rank > 0) || !Number.isFinite(rank)) return 0;
|
||||
return (
|
||||
DENSITY_MIN_ALPHA +
|
||||
(WILDLIFE_DENSITY_MAX_ALPHA - DENSITY_MIN_ALPHA) *
|
||||
Math.min(1, rank) ** DENSITY_RAMP_GAMMA
|
||||
);
|
||||
}
|
||||
|
||||
/** Rank function over the snapshot's positive counts: the share of cells with
|
||||
* a count at or below the given one. */
|
||||
export function wildlifeDensityRanks(cells = []) {
|
||||
const counts = [];
|
||||
for (const cell of cells)
|
||||
if (Number.isSafeInteger(cell?.cellCount) && cell.cellCount > 0)
|
||||
counts.push(cell.cellCount);
|
||||
counts.sort((a, b) => a - b);
|
||||
return (count) => {
|
||||
if (!counts.length || !(count > 0)) return 0;
|
||||
let low = 0;
|
||||
let high = counts.length;
|
||||
while (low < high) {
|
||||
const mid = (low + high) >>> 1;
|
||||
if (counts[mid] <= count) low = mid + 1;
|
||||
else high = mid;
|
||||
}
|
||||
return low / counts.length;
|
||||
};
|
||||
}
|
||||
|
||||
/** Truncated Gaussian in source-cell widths; overlapping splats hide the grid. */
|
||||
export function wildlifeDensityKernel(distance) {
|
||||
const radius = WILDLIFE_DENSITY_OVERLAP / 2;
|
||||
if (!Number.isFinite(distance) || distance < 0 || distance >= radius)
|
||||
return 0;
|
||||
const edge = Math.exp(-(radius ** 2) / (2 * KERNEL_SIGMA ** 2));
|
||||
return (
|
||||
(Math.exp(-(distance ** 2) / (2 * KERNEL_SIGMA ** 2)) - edge) / (1 - edge)
|
||||
);
|
||||
}
|
||||
|
||||
const DENSITY_IMAGE = `data:image/svg+xml,${encodeURIComponent(
|
||||
`<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128"><defs><radialGradient id="g">${Array.from(
|
||||
{ length: 33 },
|
||||
(_, i) =>
|
||||
`<stop offset="${i / 32}" stop-color="white" stop-opacity="${wildlifeDensityKernel(((i / 32) * WILDLIFE_DENSITY_OVERLAP) / 2).toFixed(5)}"/>`,
|
||||
).join(
|
||||
'',
|
||||
)}</radialGradient></defs><circle cx="64" cy="64" r="64" fill="url(#g)"/></svg>`,
|
||||
)}`;
|
||||
|
||||
function tintForStyle(style) {
|
||||
if (['mono', 'surveillance', 'thermal', 'noir', 'nvg'].includes(style))
|
||||
return MONO_TINT;
|
||||
return ['crt', 'retro'].includes(style) ? CRT_TINT : NORMAL_TINT;
|
||||
}
|
||||
|
||||
function intersects(bounds, boxes, padding = 0) {
|
||||
if (!boxes?.length) return true;
|
||||
const latitude = (bounds.north - bounds.south) * padding;
|
||||
const longitude = (bounds.east - bounds.west) * padding;
|
||||
for (const box of boxes) {
|
||||
if (
|
||||
bounds.north + latitude < box.south ||
|
||||
bounds.south - latitude > box.north
|
||||
)
|
||||
continue;
|
||||
// Both a padded splat and the viewport can straddle the antimeridian.
|
||||
const east = box.east < box.west ? box.east + 360 : box.east;
|
||||
const left = bounds.west - longitude;
|
||||
const right = bounds.east + longitude;
|
||||
if (
|
||||
(right >= box.west && left <= east) ||
|
||||
(right + 360 >= box.west && left + 360 <= east) ||
|
||||
(right - 360 >= box.west && left - 360 <= east)
|
||||
)
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
// Fit the entire kernel inside the globe's tangent cone, plus 5% of its radius.
|
||||
// A visible centre alone lets a depth-free billboard bleed across the limb.
|
||||
// The inscribed sphere is conservative for WGS84 and needs no projections.
|
||||
function horizonTest(cameraPosition, radius) {
|
||||
const { x, y, z } = cameraPosition || {};
|
||||
const distance = Math.hypot(x, y, z);
|
||||
if (!Number.isFinite(distance) || distance <= radius) return null;
|
||||
const nx = x / distance;
|
||||
const ny = y / distance;
|
||||
const nz = z / distance;
|
||||
const sinAngle = radius / distance;
|
||||
const cosAngleSquared = 1 - sinAngle ** 2;
|
||||
const horizonPlane = radius * sinAngle;
|
||||
return (position, kernelRadius) => {
|
||||
const along = position.x * nx + position.y * ny + position.z * nz;
|
||||
if (along <= horizonPlane) return false;
|
||||
const clearance = sinAngle * (distance - along) - kernelRadius * 1.05;
|
||||
const acrossSquared = Math.max(
|
||||
0,
|
||||
position.x ** 2 + position.y ** 2 + position.z ** 2 - along ** 2,
|
||||
);
|
||||
return clearance > 0 && acrossSquared * cosAngleSquared < clearance ** 2;
|
||||
};
|
||||
}
|
||||
|
||||
/** Own noninteractive, world-sized glow splats, arrival fades and style changes. */
|
||||
/** A world-sized kernel fills the screen once the camera is inside it, e.g.
|
||||
* while flying in before the closer view's tiles arrive. Cesium fades it on the
|
||||
* GPU: gone within half its width, full beyond twice its width. */
|
||||
export const WILDLIFE_DENSITY_NEAR_FADE = Object.freeze({ near: 0.5, far: 2 });
|
||||
|
||||
export function createWildlifeDensity({
|
||||
cesium: C,
|
||||
viewer,
|
||||
positionForCell = (cell) => C.Cartesian3.fromDegrees(cell.lon, cell.lat),
|
||||
requestRender = () => {},
|
||||
setTimer = (fn, delay) => setTimeout(fn, delay),
|
||||
clearTimer = (timer) => clearTimeout(timer),
|
||||
requestIdle,
|
||||
cancelIdle,
|
||||
eventTarget = globalThis.window,
|
||||
documentRef = globalThis.document,
|
||||
} = {}) {
|
||||
let collection = null;
|
||||
const nearFade = (width) =>
|
||||
new C.NearFarScalar(
|
||||
width * WILDLIFE_DENSITY_NEAR_FADE.near,
|
||||
0,
|
||||
width * WILDLIFE_DENSITY_NEAR_FADE.far,
|
||||
1,
|
||||
);
|
||||
let metadata = new WeakMap();
|
||||
const entries = new Map();
|
||||
const fading = new Set();
|
||||
let fadeTimer = null;
|
||||
let destroyed = false;
|
||||
let generation = 0;
|
||||
let cockpitVision = false;
|
||||
let tint = tintForStyle(documentRef?.documentElement?.dataset?.gevStyle);
|
||||
let listening = false;
|
||||
const fadeQueue = createWildlifeWorkQueue({ requestIdle, cancelIdle });
|
||||
const styleQueue = createWildlifeWorkQueue({ requestIdle, cancelIdle });
|
||||
|
||||
// BillboardCollection does not implement Primitive's allowPicking option.
|
||||
// Skipping its public pick update prevents its translucent quads from
|
||||
// intercepting observations, including pixels with a faint glow alpha.
|
||||
class DensityCollection extends C.BillboardCollection {
|
||||
constructor() {
|
||||
// Cesium's TRANSLUCENT-only option writes depth and occludes badges.
|
||||
super();
|
||||
this.allowPicking = false;
|
||||
}
|
||||
update(frameState) {
|
||||
if (frameState.passes?.pick) return;
|
||||
return super.update(frameState);
|
||||
}
|
||||
}
|
||||
|
||||
function color(entry) {
|
||||
const mix = (i) => tint.low[i] + (tint.high[i] - tint.low[i]) * entry.rank;
|
||||
return new C.Color(
|
||||
mix(0),
|
||||
mix(1),
|
||||
mix(2),
|
||||
(wildlifeDensityIntensity(entry.rank) * entry.opacity * entry.fade) /
|
||||
FADE_STEPS,
|
||||
);
|
||||
}
|
||||
|
||||
function* styleWork() {
|
||||
let visits = 0;
|
||||
for (const entry of entries.values()) {
|
||||
if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'density-style';
|
||||
entry.point.color = color(entry);
|
||||
}
|
||||
}
|
||||
|
||||
function setStyle(style) {
|
||||
const next = tintForStyle(style);
|
||||
if (next === tint) return;
|
||||
tint = next;
|
||||
if (entries.size)
|
||||
styleQueue.start(styleWork(), () => requestRender('density-style'));
|
||||
}
|
||||
|
||||
function onStyle(event) {
|
||||
if (!cockpitVision) setStyle(event?.detail?.style);
|
||||
}
|
||||
|
||||
function onVision(event) {
|
||||
cockpitVision = event?.detail?.cockpit === true;
|
||||
setStyle(event?.detail?.style);
|
||||
}
|
||||
|
||||
function ensureCollection() {
|
||||
if (collection) return;
|
||||
collection = new DensityCollection();
|
||||
viewer.scene.primitives.add(collection);
|
||||
if (!listening) {
|
||||
tint = tintForStyle(documentRef?.documentElement?.dataset?.gevStyle);
|
||||
eventTarget?.addEventListener?.('gev:style-change', onStyle);
|
||||
eventTarget?.addEventListener?.('gev:vision-change', onVision);
|
||||
listening = true;
|
||||
}
|
||||
}
|
||||
|
||||
function* fadeWork() {
|
||||
let visits = 0;
|
||||
for (const entry of fading) {
|
||||
if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'density-fade';
|
||||
entry.fade++;
|
||||
entry.point.color = color(entry);
|
||||
if (entry.fade >= FADE_STEPS) fading.delete(entry);
|
||||
}
|
||||
}
|
||||
|
||||
function scheduleFade() {
|
||||
if (fadeTimer !== null || fadeQueue.pending || !fading.size || destroyed)
|
||||
return;
|
||||
fadeTimer = setTimer(() => {
|
||||
fadeTimer = null;
|
||||
fadeQueue.start(fadeWork(), () => {
|
||||
requestRender('density-fade');
|
||||
scheduleFade();
|
||||
});
|
||||
}, FADE_STEP_MS);
|
||||
}
|
||||
|
||||
function dataForCell(cell, operations) {
|
||||
if (
|
||||
!cell ||
|
||||
!Number.isFinite(cell.lat) ||
|
||||
Math.abs(cell.lat) > 90 ||
|
||||
!Number.isFinite(cell.lon) ||
|
||||
Math.abs(cell.lon) > 180 ||
|
||||
!Number.isSafeInteger(cell.cellCount) ||
|
||||
cell.cellCount <= 0
|
||||
)
|
||||
return null;
|
||||
const old = metadata.get(cell);
|
||||
if (
|
||||
old?.id === cell.id &&
|
||||
old.lat === cell.lat &&
|
||||
old.lon === cell.lon &&
|
||||
old.count === cell.cellCount
|
||||
)
|
||||
return old;
|
||||
const bounds =
|
||||
old?.id === cell.id ? old.bounds : wildlifeGridCellBounds(cell.id);
|
||||
if (!bounds) return null;
|
||||
const samePosition = old?.lat === cell.lat && old?.lon === cell.lon;
|
||||
const data = {
|
||||
id: cell.id,
|
||||
lat: cell.lat,
|
||||
lon: cell.lon,
|
||||
count: cell.cellCount,
|
||||
bounds,
|
||||
width:
|
||||
WILDLIFE_DENSITY_OVERLAP *
|
||||
METERS_PER_DEGREE *
|
||||
Math.max(
|
||||
(bounds.east - bounds.west) * Math.cos((cell.lat * Math.PI) / 180),
|
||||
bounds.north - bounds.south,
|
||||
),
|
||||
position: samePosition ? old.position : positionForCell(cell),
|
||||
};
|
||||
operations.densityMetadataBuilds++;
|
||||
if (!samePosition) operations.densityPositionBuilds++;
|
||||
metadata.set(cell, data);
|
||||
return data;
|
||||
}
|
||||
|
||||
/** Reconcile the authoritative snapshot, including successful empty tiles. */
|
||||
function* updateWork(
|
||||
cells = [],
|
||||
{ boxes, isPointVisible, onOperations = () => {} } = {},
|
||||
) {
|
||||
const token = ++generation;
|
||||
const operations = {
|
||||
densityVisits: 0,
|
||||
densityRetirementVisits: 0,
|
||||
densityMetadataBuilds: 0,
|
||||
densityPositionBuilds: 0,
|
||||
densityWrites: 0,
|
||||
densityCreated: 0,
|
||||
densityRemoved: 0,
|
||||
};
|
||||
let sightingCount = 0;
|
||||
let changed = false;
|
||||
const height = viewer.camera?.positionCartographic?.height ?? 0;
|
||||
const opacity = Math.max(
|
||||
0,
|
||||
Math.min(
|
||||
1,
|
||||
(ALTITUDE_FADE_END - height) /
|
||||
(ALTITUDE_FADE_END - ALTITUDE_FADE_START),
|
||||
),
|
||||
);
|
||||
const insideHorizon = horizonTest(
|
||||
viewer.camera?.positionWC,
|
||||
C.Ellipsoid?.WGS84?.minimumRadius ?? 6_356_752.314245,
|
||||
);
|
||||
const rankOf = wildlifeDensityRanks(cells);
|
||||
for (const cell of cells) {
|
||||
if (operations.densityVisits++ % WILDLIFE_WORK_UNIT === 0) {
|
||||
yield 'density';
|
||||
if (destroyed || token !== generation)
|
||||
return { sightingCount: 0, changed: false, size: entries.size };
|
||||
}
|
||||
const data = dataForCell(cell, operations);
|
||||
if (
|
||||
!data ||
|
||||
!intersects(data.bounds, boxes, (WILDLIFE_DENSITY_OVERLAP - 1) / 2) ||
|
||||
isPointVisible?.(data.position) === false
|
||||
)
|
||||
continue;
|
||||
if (intersects(data.bounds, boxes))
|
||||
sightingCount = Math.min(
|
||||
Number.MAX_SAFE_INTEGER,
|
||||
sightingCount + data.count,
|
||||
);
|
||||
// These are visual decisions only; counts retain every visible cell.
|
||||
if (
|
||||
opacity === 0 ||
|
||||
insideHorizon?.(data.position, data.width / 2) === false
|
||||
)
|
||||
continue;
|
||||
const rank = rankOf(data.count);
|
||||
let entry = entries.get(data.id);
|
||||
if (!entry) {
|
||||
ensureCollection();
|
||||
entry = { data, rank, opacity, fade: 1, seen: token, point: null };
|
||||
entry.point = collection.add({
|
||||
position: data.position,
|
||||
image: DENSITY_IMAGE,
|
||||
// Cesium packs width in 16 bits even for meter-sized billboards.
|
||||
// Put the world diameter in its unrestricted scale attribute so
|
||||
// continental kernels never clamp into thin vertical ellipses.
|
||||
width: SPRITE_SIZE,
|
||||
height: SPRITE_SIZE,
|
||||
scale: data.width / SPRITE_SIZE,
|
||||
sizeInMeters: true,
|
||||
color: color(entry),
|
||||
disableDepthTestDistance: Number.POSITIVE_INFINITY,
|
||||
translucencyByDistance: nearFade(data.width),
|
||||
});
|
||||
entries.set(data.id, entry);
|
||||
fading.add(entry);
|
||||
operations.densityCreated++;
|
||||
changed = true;
|
||||
} else {
|
||||
entry.seen = token;
|
||||
if (entry.data.position !== data.position) {
|
||||
entry.point.position = data.position;
|
||||
operations.densityWrites++;
|
||||
changed = true;
|
||||
}
|
||||
if (entry.data.width !== data.width) {
|
||||
entry.point.scale = data.width / SPRITE_SIZE;
|
||||
entry.point.translucencyByDistance = nearFade(data.width);
|
||||
operations.densityWrites++;
|
||||
changed = true;
|
||||
}
|
||||
if (entry.rank !== rank || entry.opacity !== opacity) {
|
||||
entry.rank = rank;
|
||||
entry.opacity = opacity;
|
||||
entry.point.color = color(entry);
|
||||
operations.densityWrites++;
|
||||
changed = true;
|
||||
}
|
||||
entry.data = data;
|
||||
}
|
||||
}
|
||||
for (const [id, entry] of entries) {
|
||||
if (operations.densityRetirementVisits++ % WILDLIFE_WORK_UNIT === 0) {
|
||||
yield 'density';
|
||||
if (destroyed || token !== generation)
|
||||
return { sightingCount: 0, changed: false, size: entries.size };
|
||||
}
|
||||
if (entry.seen === token) continue;
|
||||
collection.remove(entry.point);
|
||||
fading.delete(entry);
|
||||
entries.delete(id);
|
||||
operations.densityRemoved++;
|
||||
changed = true;
|
||||
}
|
||||
if (!entries.size && collection) clear(true);
|
||||
else scheduleFade();
|
||||
if (changed) requestRender('density');
|
||||
onOperations(operations);
|
||||
return { sightingCount, changed, size: entries.size };
|
||||
}
|
||||
|
||||
/** Release the texture atlas, billboards, cached coordinates and all work. */
|
||||
function clear(keepMetadata = false) {
|
||||
generation++;
|
||||
fadeQueue.cancel();
|
||||
styleQueue.cancel();
|
||||
if (fadeTimer !== null) clearTimer(fadeTimer);
|
||||
fadeTimer = null;
|
||||
entries.clear();
|
||||
fading.clear();
|
||||
if (!keepMetadata) metadata = new WeakMap();
|
||||
if (collection) {
|
||||
if (
|
||||
viewer.scene.primitives.remove(collection) !== true &&
|
||||
!collection.isDestroyed?.()
|
||||
)
|
||||
collection.destroy();
|
||||
collection = null;
|
||||
}
|
||||
if (listening) {
|
||||
eventTarget?.removeEventListener?.('gev:style-change', onStyle);
|
||||
eventTarget?.removeEventListener?.('gev:vision-change', onVision);
|
||||
listening = false;
|
||||
}
|
||||
cockpitVision = false;
|
||||
}
|
||||
|
||||
return {
|
||||
updateWork,
|
||||
update: (cells, options) => drainWildlifeWork(updateWork(cells, options)),
|
||||
clear,
|
||||
destroy() {
|
||||
clear();
|
||||
destroyed = true;
|
||||
},
|
||||
get collection() {
|
||||
return collection;
|
||||
},
|
||||
get size() {
|
||||
return entries.size;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,508 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import * as Cesium from 'cesium';
|
||||
import { wildlifeGridCellBounds } from './gridViewport.js';
|
||||
import {
|
||||
createWildlifeDensity,
|
||||
wildlifeDensityIntensity,
|
||||
wildlifeDensityRanks,
|
||||
wildlifeDensityKernel,
|
||||
WILDLIFE_DENSITY_MAX_ALPHA,
|
||||
WILDLIFE_DENSITY_NEAR_FADE,
|
||||
WILDLIFE_DENSITY_OVERLAP,
|
||||
} from './density.js';
|
||||
import { WILDLIFE_WORK_UNIT } from './performance.js';
|
||||
|
||||
function cell(column, count = 1, options = {}) {
|
||||
const id = `grid:3/4/2:31:${column * 2 + 1}`;
|
||||
const bounds = wildlifeGridCellBounds(id);
|
||||
return {
|
||||
id,
|
||||
lat: (bounds.south + bounds.north) / 2,
|
||||
lon: (bounds.west + bounds.east) / 2,
|
||||
cellCount: count,
|
||||
...options,
|
||||
};
|
||||
}
|
||||
|
||||
function harness({ documentStyle = 'normal', camera = {} } = {}) {
|
||||
const counts = { positions: 0, writes: 0, created: 0, updates: 0 };
|
||||
class BillboardCollection extends Cesium.BillboardCollection {
|
||||
add(options) {
|
||||
counts.created++;
|
||||
const point = super.add(options);
|
||||
return new Proxy(point, {
|
||||
get: (target, key) => Reflect.get(target, key, target),
|
||||
set(target, key, value) {
|
||||
counts.writes++;
|
||||
return Reflect.set(target, key, value, target);
|
||||
},
|
||||
});
|
||||
}
|
||||
update() {
|
||||
counts.updates++;
|
||||
}
|
||||
}
|
||||
const primitives = new Cesium.PrimitiveCollection();
|
||||
let handle = 0;
|
||||
const timers = new Map();
|
||||
const idle = new Map();
|
||||
const renders = [];
|
||||
const listeners = new Map();
|
||||
const eventTarget = {
|
||||
addEventListener(name, listener) {
|
||||
if (!listeners.has(name)) listeners.set(name, new Set());
|
||||
listeners.get(name).add(listener);
|
||||
},
|
||||
removeEventListener(name, listener) {
|
||||
listeners.get(name)?.delete(listener);
|
||||
},
|
||||
emit(name, detail) {
|
||||
for (const listener of listeners.get(name) || []) listener({ detail });
|
||||
},
|
||||
};
|
||||
const density = createWildlifeDensity({
|
||||
cesium: { ...Cesium, BillboardCollection },
|
||||
viewer: { scene: { primitives }, camera },
|
||||
positionForCell(row) {
|
||||
counts.positions++;
|
||||
return Cesium.Cartesian3.fromDegrees(row.lon, row.lat);
|
||||
},
|
||||
requestRender: (reason) => renders.push(reason),
|
||||
setTimer(fn) {
|
||||
timers.set(++handle, fn);
|
||||
return handle;
|
||||
},
|
||||
clearTimer: (id) => timers.delete(id),
|
||||
requestIdle(fn) {
|
||||
idle.set(++handle, fn);
|
||||
return handle;
|
||||
},
|
||||
cancelIdle: (id) => idle.delete(id),
|
||||
eventTarget,
|
||||
documentRef: { documentElement: { dataset: { gevStyle: documentStyle } } },
|
||||
});
|
||||
function flushIdle() {
|
||||
while (idle.size) {
|
||||
const [id, fn] = idle.entries().next().value;
|
||||
idle.delete(id);
|
||||
fn();
|
||||
}
|
||||
}
|
||||
function fadeStep() {
|
||||
for (const [id, fn] of [...timers]) {
|
||||
timers.delete(id);
|
||||
fn();
|
||||
}
|
||||
flushIdle();
|
||||
}
|
||||
return {
|
||||
density,
|
||||
primitives,
|
||||
counts,
|
||||
renders,
|
||||
timers,
|
||||
idle,
|
||||
listeners,
|
||||
eventTarget,
|
||||
flushIdle,
|
||||
fadeStep,
|
||||
settle() {
|
||||
while (timers.size || idle.size) {
|
||||
fadeStep();
|
||||
flushIdle();
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('density intensity rises with view rank, is bounded, and leaves no background for zero data', () => {
|
||||
for (const empty of [0, -1, null, undefined, NaN, Infinity])
|
||||
assert.equal(wildlifeDensityIntensity(empty), 0);
|
||||
const ranks = [0.01, 0.1, 0.25, 0.5, 0.75, 0.9, 1];
|
||||
const values = ranks.map(wildlifeDensityIntensity);
|
||||
assert.ok(values[0] > 0, 'the sparsest cell still leaves a trace');
|
||||
assert.ok(values[0] < 0.02, 'sparse cells stay a trace, not a haze');
|
||||
for (let i = 1; i < values.length; i++) assert.ok(values[i] > values[i - 1]);
|
||||
assert.equal(values.at(-1), WILDLIFE_DENSITY_MAX_ALPHA);
|
||||
assert.ok(
|
||||
values[3] < WILDLIFE_DENSITY_MAX_ALPHA / 3,
|
||||
'a median cell is well below a hotspot',
|
||||
);
|
||||
});
|
||||
|
||||
test('density ranks are relative to the view, so hotspots stay distinct at any zoom', () => {
|
||||
const cells = (counts) => counts.map((cellCount) => ({ cellCount }));
|
||||
const near = wildlifeDensityRanks(cells([1, 2, 3, 40]));
|
||||
const far = wildlifeDensityRanks(cells([100, 200, 300, 4000]));
|
||||
assert.equal(near(40), 1);
|
||||
assert.equal(far(4000), 1, 'the top cell is brightest whatever its count');
|
||||
assert.equal(near(1), far(100), 'the same position ranks the same');
|
||||
assert.equal(wildlifeDensityRanks(cells([0, -1]))(5), 0);
|
||||
assert.equal(wildlifeDensityRanks([])(5), 0);
|
||||
});
|
||||
|
||||
test('an empty density snapshot creates no glow', () => {
|
||||
const h = harness();
|
||||
assert.deepEqual(h.density.update([]), {
|
||||
sightingCount: 0,
|
||||
changed: false,
|
||||
size: 0,
|
||||
});
|
||||
h.density.update([
|
||||
cell(0, 0),
|
||||
cell(1, -1),
|
||||
cell(2, 0.5),
|
||||
cell(3, 1, { id: 'invalid' }),
|
||||
]);
|
||||
assert.equal(h.density.collection, null);
|
||||
assert.equal(h.primitives.length, 0);
|
||||
assert.equal(h.timers.size, 0);
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('uniform occupied cells make a continuous field with no visible lattice', () => {
|
||||
assert.ok(WILDLIFE_DENSITY_OVERLAP >= 1.5);
|
||||
assert.equal(wildlifeDensityKernel(0), 1);
|
||||
assert.equal(wildlifeDensityKernel(WILDLIFE_DENSITY_OVERLAP / 2), 0);
|
||||
const samples = [];
|
||||
for (let x = 0; x < 1; x += 0.1)
|
||||
for (let y = 0; y < 1; y += 0.1) {
|
||||
let value = 0;
|
||||
for (let dx = -3; dx <= 3; dx++)
|
||||
for (let dy = -3; dy <= 3; dy++)
|
||||
value += wildlifeDensityKernel(Math.hypot(x - dx, y - dy));
|
||||
samples.push(value);
|
||||
}
|
||||
const modulation =
|
||||
(Math.max(...samples) - Math.min(...samples)) / Math.max(...samples);
|
||||
assert.ok(modulation < 0.007, `${(100 * modulation).toFixed(3)}% modulation`);
|
||||
});
|
||||
|
||||
test('each glow kernel fades on the GPU as the camera comes inside it, scaled to its own width', () => {
|
||||
const h = harness();
|
||||
h.density.update([cell(0, 4), cell(1, 9)]);
|
||||
const collection = h.density.collection;
|
||||
assert.equal(collection.length, 2);
|
||||
for (let i = 0; i < collection.length; i++) {
|
||||
const point = collection.get(i);
|
||||
const width = point.scale * point.width;
|
||||
const fade = point.translucencyByDistance;
|
||||
assert.ok(fade, 'no screen-filling kernel when zoomed inside it');
|
||||
assert.ok(
|
||||
Math.abs(fade.near - width * WILDLIFE_DENSITY_NEAR_FADE.near) < 1e-6,
|
||||
);
|
||||
assert.equal(fade.nearValue, 0);
|
||||
assert.ok(
|
||||
Math.abs(fade.far - width * WILDLIFE_DENSITY_NEAR_FADE.far) < 1e-6,
|
||||
);
|
||||
assert.equal(fade.farValue, 1);
|
||||
}
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('occupied grid counts produce unlabelled world-sized glow billboards that never enter Cesium picking', () => {
|
||||
const h = harness();
|
||||
const rows = [cell(0, 1), cell(1, 100), cell(2, 1000000)];
|
||||
const result = h.density.update(rows);
|
||||
assert.equal(result.sightingCount, 1000101);
|
||||
assert.equal(h.primitives.length, 1);
|
||||
const collection = h.density.collection;
|
||||
assert.equal(collection.allowPicking, false);
|
||||
assert.equal(collection.length, 3);
|
||||
const first = collection.get(0);
|
||||
assert.equal(
|
||||
first.id,
|
||||
undefined,
|
||||
'density has no sighting identity or pick payload',
|
||||
);
|
||||
assert.equal(first.sizeInMeters, true);
|
||||
assert.equal(first.scaleByDistance, undefined);
|
||||
assert.match(decodeURIComponent(first.image), /radialGradient/);
|
||||
assert.doesNotMatch(decodeURIComponent(first.image), /text|badge|raven/);
|
||||
const bounds = wildlifeGridCellBounds(rows[0].id);
|
||||
const logicalHeight =
|
||||
(((bounds.north - bounds.south) * Math.PI) / 180) * 6378137;
|
||||
assert.ok(first.width * first.scale >= 1.5 * logicalHeight);
|
||||
assert.equal(first.width, first.height);
|
||||
assert.ok(
|
||||
first.width <= 65536,
|
||||
'encoded dimensions fit Cesium width packing',
|
||||
);
|
||||
assert.ok(
|
||||
first.width * first.scale > 65536,
|
||||
'continental splats retain their true footprint through scale',
|
||||
);
|
||||
collection.update({ passes: { pick: true } });
|
||||
assert.equal(
|
||||
h.counts.updates,
|
||||
0,
|
||||
'the real public pick update is suppressed',
|
||||
);
|
||||
collection.update({ passes: { render: true } });
|
||||
assert.equal(h.counts.updates, 1);
|
||||
h.settle();
|
||||
const rankOf = wildlifeDensityRanks(rows);
|
||||
for (let i = 0; i < collection.length; i++)
|
||||
assert.ok(
|
||||
Math.abs(
|
||||
collection.get(i).color.alpha -
|
||||
wildlifeDensityIntensity(rankOf(rows[i].cellCount)),
|
||||
) < 1e-12,
|
||||
);
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('progressive tile arrival fades only new cells and reuses existing glow without flashing', () => {
|
||||
const h = harness();
|
||||
const one = cell(0, 4);
|
||||
const two = cell(1, 10);
|
||||
h.density.update([one]);
|
||||
const first = h.density.collection.get(0);
|
||||
const starting = first.color.alpha;
|
||||
h.fadeStep();
|
||||
assert.ok(first.color.alpha > starting);
|
||||
const middle = first.color.alpha;
|
||||
h.density.update([one, two]);
|
||||
// The arriving tile re-ranks the incumbent (alone it was the hotspot; now
|
||||
// it is the median) but its fade progress is kept, not restarted.
|
||||
const progress = middle / wildlifeDensityIntensity(1);
|
||||
assert.ok(
|
||||
Math.abs(first.color.alpha - wildlifeDensityIntensity(0.5) * progress) <
|
||||
1e-12,
|
||||
'a streamed tile re-ranks but does not restart incumbents',
|
||||
);
|
||||
assert.equal(h.density.collection.get(0), first);
|
||||
assert.equal(h.density.size, 2);
|
||||
h.settle();
|
||||
const settled = first.color.alpha;
|
||||
h.density.update([one, two]);
|
||||
assert.equal(first.color.alpha, settled);
|
||||
h.density.update([two]);
|
||||
assert.equal(h.density.size, 1);
|
||||
assert.equal(h.density.collection.length, 1);
|
||||
h.density.update([]);
|
||||
assert.equal(h.density.size, 0);
|
||||
assert.equal(
|
||||
h.density.collection,
|
||||
null,
|
||||
'empty data releases the atlas and collection',
|
||||
);
|
||||
assert.equal(
|
||||
h.primitives.length,
|
||||
0,
|
||||
'no full-view fill remains over empty data',
|
||||
);
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('visibility and antimeridian padding are applied on data/moveEnd work only', () => {
|
||||
const h = harness();
|
||||
const west = cell(1);
|
||||
const east = cell(28);
|
||||
const box = { ...wildlifeGridCellBounds(west.id) };
|
||||
assert.equal(h.density.update([west, east], { boxes: [box] }).size, 1);
|
||||
assert.equal(
|
||||
h.density.update([west], { boxes: [box], isPointVisible: () => false })
|
||||
.size,
|
||||
0,
|
||||
);
|
||||
const id = 'grid:3/0/2:31:1';
|
||||
const bounds = wildlifeGridCellBounds(id);
|
||||
const wrapped = {
|
||||
...west,
|
||||
id,
|
||||
lat: (bounds.south + bounds.north) / 2,
|
||||
lon: -179.3,
|
||||
};
|
||||
const crossed = {
|
||||
south: bounds.south,
|
||||
north: bounds.north,
|
||||
west: 179,
|
||||
east: -179,
|
||||
};
|
||||
assert.equal(h.density.update([wrapped], { boxes: [crossed] }).size, 1);
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('density culls far-side cells and front-side kernels that would spill over the limb', () => {
|
||||
const camera = {
|
||||
positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 5_000_000),
|
||||
positionCartographic: { height: 5_000_000 },
|
||||
};
|
||||
const h = harness({ camera });
|
||||
const occluder = new Cesium.EllipsoidalOccluder(
|
||||
Cesium.Ellipsoid.WGS84,
|
||||
camera.positionWC,
|
||||
);
|
||||
const cells = [
|
||||
cell(0, 1, { lat: 0, lon: 0 }),
|
||||
cell(1, 2, { lat: 0, lon: 54 }),
|
||||
cell(2, 4, { lat: 0, lon: 110 }),
|
||||
];
|
||||
assert.equal(
|
||||
occluder.isPointVisible(Cesium.Cartesian3.fromDegrees(54, 0)),
|
||||
true,
|
||||
'the limb fixture has a visible centre but an overflowing footprint',
|
||||
);
|
||||
const result = h.density.update(cells, {
|
||||
isPointVisible: (anchor) => occluder.isPointVisible(anchor),
|
||||
});
|
||||
assert.equal(result.size, 1, 'only the fully front-side kernel can glow');
|
||||
assert.equal(
|
||||
result.sightingCount,
|
||||
3,
|
||||
'visual limb padding never removes visible counts',
|
||||
);
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('density fades from regional detail to a clear whole-globe view without frame work or count loss', () => {
|
||||
const camera = { positionCartographic: { height: 3_000_000 } };
|
||||
const h = harness({ camera });
|
||||
const cells = [cell(0, 12)];
|
||||
h.density.update(cells);
|
||||
h.settle();
|
||||
const point = h.density.collection.get(0);
|
||||
const fullAlpha = point.color.alpha;
|
||||
camera.positionCartographic.height = 5_500_000;
|
||||
h.density.update(cells);
|
||||
assert.equal(h.density.collection.get(0), point);
|
||||
assert.ok(Math.abs(point.color.alpha - fullAlpha / 2) < 1e-12);
|
||||
const writes = h.counts.writes;
|
||||
h.density.update(cells);
|
||||
assert.equal(h.counts.writes, writes, 'unchanged height writes nothing');
|
||||
camera.positionCartographic.height = 8_000_000;
|
||||
assert.equal(h.density.update(cells).sightingCount, 12);
|
||||
assert.equal(h.density.collection, null);
|
||||
assert.equal(h.timers.size, 0, 'no invisible fade or frame loop');
|
||||
const positions = h.counts.positions;
|
||||
camera.positionCartographic.height = 3_000_000;
|
||||
h.density.update(cells);
|
||||
h.settle();
|
||||
assert.equal(
|
||||
h.counts.positions,
|
||||
positions,
|
||||
'altitude changes reuse decoded positions',
|
||||
);
|
||||
assert.equal(h.density.collection.get(0).color.alpha, fullAlpha);
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('styles follow persisted mono/CRT and cockpit vision overrides, without adding a second ramp', () => {
|
||||
const h = harness({ documentStyle: 'thermal' });
|
||||
h.density.update([cell(0)]);
|
||||
h.settle();
|
||||
const point = h.density.collection.get(0);
|
||||
assert.equal(point.color.red, point.color.green);
|
||||
assert.equal(point.color.green, point.color.blue);
|
||||
const alpha = point.color.alpha;
|
||||
h.eventTarget.emit('gev:style-change', { style: 'retro' });
|
||||
h.flushIdle();
|
||||
assert.ok(point.color.green > point.color.red);
|
||||
h.eventTarget.emit('gev:vision-change', { cockpit: true, style: 'nvg' });
|
||||
h.flushIdle();
|
||||
assert.equal(point.color.red, point.color.green);
|
||||
h.eventTarget.emit('gev:style-change', { style: 'normal' });
|
||||
h.flushIdle();
|
||||
assert.equal(
|
||||
point.color.red,
|
||||
point.color.green,
|
||||
'cockpit vision wins while active',
|
||||
);
|
||||
h.eventTarget.emit('gev:vision-change', { cockpit: false, style: 'normal' });
|
||||
h.flushIdle();
|
||||
assert.notEqual(point.color.red, point.color.green);
|
||||
assert.equal(point.color.alpha, alpha);
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('clear/disable and destroy release the atlas, primitives, coordinates, timers and listeners', () => {
|
||||
const h = harness();
|
||||
const row = cell(0);
|
||||
h.density.update([row]);
|
||||
const old = h.density.collection;
|
||||
assert.equal(h.timers.size, 1);
|
||||
h.fadeStep();
|
||||
h.density.clear();
|
||||
assert.equal(old.isDestroyed(), true);
|
||||
assert.equal(h.density.collection, null);
|
||||
assert.equal(h.density.size, 0);
|
||||
assert.equal(h.primitives.length, 0);
|
||||
assert.equal(h.timers.size, 0);
|
||||
assert.equal(h.idle.size, 0);
|
||||
for (const values of h.listeners.values()) assert.equal(values.size, 0);
|
||||
const priorPositions = h.counts.positions;
|
||||
h.density.update([row]);
|
||||
assert.equal(
|
||||
h.counts.positions,
|
||||
priorPositions + 1,
|
||||
'disable released cached coordinates',
|
||||
);
|
||||
const work = h.density.updateWork([cell(2)]);
|
||||
work.next();
|
||||
h.density.destroy();
|
||||
assert.equal(
|
||||
work.next().done,
|
||||
true,
|
||||
'obsolete data work cannot resurrect a destroyed layer',
|
||||
);
|
||||
assert.equal(h.density.collection, null);
|
||||
assert.equal(h.primitives.length, 0);
|
||||
assert.equal(h.timers.size, 0);
|
||||
assert.equal(h.idle.size, 0);
|
||||
});
|
||||
|
||||
test('dense six-tile updates have a deterministic linear operation budget and no warmed writes/projections', (t) => {
|
||||
const h = harness();
|
||||
const cells = [];
|
||||
for (let x = 1; x < 3; x++)
|
||||
for (let y = 1; y < 4; y++)
|
||||
for (let row = 1; row < 64; row += 2)
|
||||
for (let column = 1; column < 64; column += 2) {
|
||||
const id = `grid:3/${x}/${y}:${row}:${column}`;
|
||||
const box = wildlifeGridCellBounds(id);
|
||||
cells.push({
|
||||
id,
|
||||
lat: (box.south + box.north) / 2,
|
||||
lon: (box.west + box.east) / 2,
|
||||
cellCount: row * 64 + column,
|
||||
});
|
||||
}
|
||||
let operations;
|
||||
h.density.update(cells, {
|
||||
onOperations: (value) => {
|
||||
operations = value;
|
||||
},
|
||||
});
|
||||
h.settle();
|
||||
assert.equal(operations.densityVisits, 6144);
|
||||
assert.equal(operations.densityMetadataBuilds, 6144);
|
||||
assert.equal(operations.densityPositionBuilds, 6144);
|
||||
assert.equal(operations.densityCreated, 6144);
|
||||
const positions = h.counts.positions;
|
||||
const writes = h.counts.writes;
|
||||
let units = 0;
|
||||
const work = h.density.updateWork(cells, {
|
||||
onOperations: (value) => {
|
||||
operations = value;
|
||||
},
|
||||
});
|
||||
while (!work.next().done) units++;
|
||||
assert.deepEqual(operations, {
|
||||
densityVisits: 6144,
|
||||
densityRetirementVisits: 6144,
|
||||
densityMetadataBuilds: 0,
|
||||
densityPositionBuilds: 0,
|
||||
densityWrites: 0,
|
||||
densityCreated: 0,
|
||||
densityRemoved: 0,
|
||||
});
|
||||
assert.equal(units, Math.ceil(6144 / WILDLIFE_WORK_UNIT) * 2);
|
||||
assert.equal(h.counts.positions, positions);
|
||||
assert.equal(h.counts.writes, writes);
|
||||
t.diagnostic(
|
||||
`6,144 occupied cells: ${units} bounded units, 12,288 linear visits, zero warmed metadata/Cartesian builds, projections or billboard writes`,
|
||||
);
|
||||
h.density.destroy();
|
||||
});
|
||||
@@ -0,0 +1,129 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { VOICE_OFF_LAYERS } from '../../voice/layerManifest.js';
|
||||
import { ANALYST_LAYERS } from '../../data/analystEngine.js';
|
||||
|
||||
const read = (path) =>
|
||||
readFileSync(new URL(`../../../${path}`, import.meta.url), 'utf8');
|
||||
const current = read('docs/CURRENT-STATE.md');
|
||||
const start = current.indexOf('## Wildlife Sightings —');
|
||||
const section = current
|
||||
.slice(start, current.indexOf('\n## ', start + 1))
|
||||
.replace(/\s+/g, ' ');
|
||||
|
||||
test('Wildlife docs name the permanent token, voice policy and coverage limits', () => {
|
||||
const token = JSON.parse(
|
||||
read('src/data/layerStateTokenReservations.json'),
|
||||
).find(([id]) => id === 'wildlife-sightings')?.[1];
|
||||
assert.ok(token);
|
||||
assert.match(section, new RegExp(`share-link token \`${token}\``));
|
||||
assert.match(section, /Voice is off for this layer for now/);
|
||||
assert.ok(Object.hasOwn(VOICE_OFF_LAYERS, 'wildlife-sightings'));
|
||||
assert.ok(!Object.hasOwn(ANALYST_LAYERS, 'wildlife-sightings'));
|
||||
assert.match(section, /not a census/i);
|
||||
assert.match(section, /Salish Sea/);
|
||||
assert.match(section, /0\.01°/);
|
||||
assert.match(section, /private records are excluded/);
|
||||
});
|
||||
|
||||
test('Wildlife documentation defines recency by observation time and compact ambient credit', () => {
|
||||
assert.match(section, /observation time/i);
|
||||
assert.match(section, /\bd1\b/);
|
||||
assert.match(section, /48 h/);
|
||||
assert.match(section, /96 px/);
|
||||
assert.match(section, /creator name/i);
|
||||
assert.match(section, /110\/125 km/);
|
||||
assert.match(section, /120 km/);
|
||||
assert.match(section, /random sample/);
|
||||
assert.match(section, /bounded frame cache/);
|
||||
assert.match(read('DATA_SOURCES.md'), /observation time/i);
|
||||
});
|
||||
|
||||
test('Wildlife docs describe direct photo selection and text-only privacy rows', () => {
|
||||
assert.match(section, /compact anchored\s+photo card/);
|
||||
assert.match(section, /object-fit: contain/);
|
||||
assert.match(section, /preserving zoom/);
|
||||
assert.match(section, /compact observed\s+age/);
|
||||
assert.match(section, /Obscured sightings also stay\s+text-only/);
|
||||
assert.match(section, /Acartia stays text-only/);
|
||||
assert.match(section, /closes the card and clears selection/);
|
||||
assert.match(
|
||||
section,
|
||||
/shell teardown also removes its host and subscription/,
|
||||
);
|
||||
assert.doesNotMatch(
|
||||
section,
|
||||
/opens\s+the \*\*Sighting\*\* panel|Clicking the panel photo/,
|
||||
);
|
||||
});
|
||||
|
||||
test('Wildlife docs record queue failure isolation and the complete badge mapping', () => {
|
||||
assert.match(section, /recovered queue tail/);
|
||||
assert.match(section, /ordinary grid failures/);
|
||||
assert.match(section, /DEGRADED/);
|
||||
assert.match(section, /1.5 px dark outline/);
|
||||
for (const glyph of [
|
||||
'raven',
|
||||
'pets',
|
||||
'egg_alt',
|
||||
'water_drop',
|
||||
'set_meal',
|
||||
'bug_report',
|
||||
'pest_control',
|
||||
'eco',
|
||||
'umbrella',
|
||||
'category',
|
||||
'question_mark',
|
||||
])
|
||||
assert.ok(section.includes('`' + glyph + '`'), glyph);
|
||||
});
|
||||
|
||||
test('Wildlife docs separate density from real observation icons and define persistent selection', () => {
|
||||
assert.match(section, /dedicated, nonpickable billboard/);
|
||||
assert.match(section, /view-relative density ramp/);
|
||||
assert.match(section, /four logical cell widths/);
|
||||
assert.match(
|
||||
section,
|
||||
/Only real sampled observation rows produce taxon badges/,
|
||||
);
|
||||
assert.match(
|
||||
section,
|
||||
/Grid tiles publish even while the independent observation/,
|
||||
);
|
||||
assert.match(section, /until explicit\s+deselection or layer disable/);
|
||||
assert.match(
|
||||
section,
|
||||
/releases\s+the glow collection, texture atlas, timers, queues and style listeners/,
|
||||
);
|
||||
assert.doesNotMatch(section, /grid badge|Clicking a grid cell/);
|
||||
});
|
||||
|
||||
test('Wildlife docs describe one source link, name declutter and globe glow limits', () => {
|
||||
assert.match(section, /selected chrome and paint lane/);
|
||||
assert.match(section, /single source link/);
|
||||
assert.match(section, /80 screen pixels/);
|
||||
assert.match(section, /word boundary/);
|
||||
assert.match(section, /3,000 km/);
|
||||
assert.match(section, /8,000 km/);
|
||||
assert.match(section, /5% radius margin/);
|
||||
assert.match(section, /add no per-frame work/);
|
||||
});
|
||||
|
||||
test('Wildlife docs cite the documented UTFGrid endpoint and the Acartia key request', () => {
|
||||
for (const path of [
|
||||
'docs/KNOWN-ISSUES.md',
|
||||
'DATA_SOURCES.md',
|
||||
'docs/CURRENT-STATE.md',
|
||||
]) {
|
||||
const text = read(path);
|
||||
assert.doesNotMatch(text, /undocumented (iNaturalist|UTFGrid) endpoint/i);
|
||||
assert.doesNotMatch(text, /grid \(undocumented/i);
|
||||
}
|
||||
for (const path of ['docs/KNOWN-ISSUES.md', 'DATA_SOURCES.md'])
|
||||
assert.match(read(path), /Grid Tiles UTFGrid/);
|
||||
assert.match(
|
||||
read('DATA_SOURCES.md'),
|
||||
/create an account and generate an API key/,
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,178 @@
|
||||
// Observation icons share 28px screen buckets. The density glow uses finer
|
||||
// 8–14px logical cells, coarsened until the complete view fits the tile budget.
|
||||
export const WILDLIFE_GRID_TARGET_SPACING_PX = 28;
|
||||
export const WILDLIFE_GRID_SAMPLE_SPACING_PX = 14;
|
||||
export const WILDLIFE_GRID_TILE_CAP = 6;
|
||||
export const WILDLIFE_GRID_MAX_ZOOM = 22;
|
||||
// The 64×64 UTFGrid is a hit mask: each logical 8px observation bin
|
||||
// occupies 2×2 of its 4px pixels, plus a dilated hit outline. Returned centres
|
||||
// are at odd pixel coordinates. Count logical bins once, not hit-mask pixels.
|
||||
export const WILDLIFE_GRID_LOGICAL_SIZE = 32;
|
||||
const MAX_LATITUDE = 85.0511287798066;
|
||||
const degrees = (radians) => (radians * 180) / Math.PI;
|
||||
const latitudeY = (latitude) => {
|
||||
const radians =
|
||||
(Math.max(-MAX_LATITUDE, Math.min(MAX_LATITUDE, latitude)) * Math.PI) / 180;
|
||||
return (1 - Math.asinh(Math.tan(radians)) / Math.PI) / 2;
|
||||
};
|
||||
const yLatitude = (value) =>
|
||||
degrees(Math.atan(Math.sinh(Math.PI * (1 - 2 * value))));
|
||||
const validBox = (box) =>
|
||||
!!box &&
|
||||
['south', 'west', 'north', 'east'].every((key) =>
|
||||
Number.isFinite(box[key]),
|
||||
) &&
|
||||
box.south >= -90 &&
|
||||
box.north <= 90 &&
|
||||
box.north > box.south &&
|
||||
box.west >= -180 &&
|
||||
box.west <= 180 &&
|
||||
box.east >= -180 &&
|
||||
box.east <= 180 &&
|
||||
box.west !== box.east;
|
||||
|
||||
function normalizedBoxes(boxes) {
|
||||
if (!Array.isArray(boxes) || !boxes.length || !boxes.every(validBox))
|
||||
return [];
|
||||
return boxes
|
||||
.flatMap((box) =>
|
||||
box.west < box.east
|
||||
? [box]
|
||||
: [
|
||||
{ ...box, east: 180 },
|
||||
{ ...box, west: -180 },
|
||||
],
|
||||
)
|
||||
.filter((box) => box.east > box.west);
|
||||
}
|
||||
|
||||
function tileRanges(boxes, z) {
|
||||
const count = 2 ** z;
|
||||
const index = (value) => Math.max(0, Math.min(count - 1, Math.floor(value)));
|
||||
return normalizedBoxes(boxes).map((box) => ({
|
||||
left: index(((box.west + 180) / 360) * count),
|
||||
right: index(((box.east + 180) / 360) * count - 1e-9),
|
||||
top: index(latitudeY(box.north) * count),
|
||||
bottom: index(latitudeY(box.south) * count - 1e-9),
|
||||
}));
|
||||
}
|
||||
|
||||
function tileCount(boxes, z) {
|
||||
// Split antimeridian ranges cannot overlap except at z=0. Counting that
|
||||
// shared tile twice merely makes the request cap slightly conservative.
|
||||
return tileRanges(boxes, z).reduce(
|
||||
(sum, range) =>
|
||||
sum + (range.right - range.left + 1) * (range.bottom - range.top + 1),
|
||||
0,
|
||||
);
|
||||
}
|
||||
|
||||
/** Choose the finest glow spacing whose full viewport fits the tile budget. */
|
||||
export function chooseWildlifeGridZoom({ boxes, width, height } = {}) {
|
||||
const visible = normalizedBoxes(boxes);
|
||||
if (!visible.length || !(width > 0) || !(height > 0)) return 0;
|
||||
const horizontalSpan = Math.min(
|
||||
1,
|
||||
visible.reduce((sum, box) => sum + (box.east - box.west) / 360, 0),
|
||||
);
|
||||
const verticalSpan = Math.max(
|
||||
...visible.map((box) => latitudeY(box.south) - latitudeY(box.north)),
|
||||
);
|
||||
const pixelsPerWorld = Math.min(
|
||||
width / horizontalSpan,
|
||||
height / Math.max(1e-9, verticalSpan),
|
||||
);
|
||||
let z = Math.max(
|
||||
0,
|
||||
Math.min(
|
||||
WILDLIFE_GRID_MAX_ZOOM,
|
||||
Math.ceil(
|
||||
Math.log2(
|
||||
pixelsPerWorld /
|
||||
(WILDLIFE_GRID_LOGICAL_SIZE * WILDLIFE_GRID_SAMPLE_SPACING_PX),
|
||||
) - 1e-9,
|
||||
),
|
||||
),
|
||||
);
|
||||
while (z > 0 && tileCount(visible, z) > WILDLIFE_GRID_TILE_CAP) z -= 1;
|
||||
return z;
|
||||
}
|
||||
|
||||
/** Only intersecting tiles, in stable XYZ order, with no neighboring padding.
|
||||
* Direct oversized requests fail closed; zoom selection coarsens beforehand. */
|
||||
export function wildlifeGridTiles({ boxes, z } = {}) {
|
||||
if (!Number.isInteger(z) || z < 0 || z > WILDLIFE_GRID_MAX_ZOOM) return [];
|
||||
if (tileCount(boxes, z) > WILDLIFE_GRID_TILE_CAP) return [];
|
||||
const tiles = new Map();
|
||||
for (const range of tileRanges(boxes, z)) {
|
||||
for (let x = range.left; x <= range.right; x += 1) {
|
||||
for (let y = range.top; y <= range.bottom; y += 1) {
|
||||
tiles.set(`${x}/${y}`, { z, x, y });
|
||||
}
|
||||
}
|
||||
}
|
||||
return [...tiles.values()].sort((a, b) => a.x - b.x || a.y - b.y);
|
||||
}
|
||||
|
||||
/** Unlike detail-row viewport queries, grids cover full globe views too. */
|
||||
export function wildlifeGridViewportBoxes(viewer) {
|
||||
const rectangle = viewer?.camera?.computeViewRectangle?.(
|
||||
viewer?.scene?.globe?.ellipsoid,
|
||||
);
|
||||
if (!rectangle) return [];
|
||||
return normalizedBoxes([
|
||||
Object.fromEntries(
|
||||
['south', 'west', 'north', 'east'].map((key) => [
|
||||
key,
|
||||
Math.round(degrees(rectangle[key]) * 1e8) / 1e8,
|
||||
]),
|
||||
),
|
||||
]);
|
||||
}
|
||||
|
||||
/** Return the geographic footprint of one logical occupied cell. */
|
||||
export function wildlifeGridCellBounds(id) {
|
||||
const match = /^grid:(\d+)\/(\d+)\/(\d+):(\d+):(\d+)$/.exec(id);
|
||||
if (!match) return null;
|
||||
const [z, x, y, row, column] = match.slice(1).map(Number);
|
||||
const count = 2 ** z;
|
||||
if (
|
||||
z > WILDLIFE_GRID_MAX_ZOOM ||
|
||||
x >= count ||
|
||||
y >= count ||
|
||||
row >= 64 ||
|
||||
column >= 64
|
||||
)
|
||||
return null;
|
||||
return {
|
||||
south: yLatitude((y + (Math.floor(row / 2) + 1) / 32) / count),
|
||||
west: ((x + Math.floor(column / 2) / 32) / count) * 360 - 180,
|
||||
north: yLatitude((y + Math.floor(row / 2) / 32) / count),
|
||||
east: ((x + (Math.floor(column / 2) + 1) / 32) / count) * 360 - 180,
|
||||
};
|
||||
}
|
||||
|
||||
/** Shared with the proxy and cached-coverage matching. A tile's hit area can
|
||||
* bleed into its neighbor; the geographic owner makes ids stable. */
|
||||
export function wildlifeGridCellId(lat, lon, z) {
|
||||
if (
|
||||
!Number.isFinite(lat) ||
|
||||
Math.abs(lat) > 90 ||
|
||||
!Number.isFinite(lon) ||
|
||||
Math.abs(lon) > 180 ||
|
||||
!Number.isInteger(z) ||
|
||||
z < 0 ||
|
||||
z > WILDLIFE_GRID_MAX_ZOOM
|
||||
)
|
||||
return null;
|
||||
const count = 2 ** z;
|
||||
const worldX = ((((lon + 180) / 360) % 1) + 1) % 1;
|
||||
const worldY = Math.max(0, Math.min(1 - Number.EPSILON, latitudeY(lat)));
|
||||
const tileX = Math.min(count - 1, Math.floor(worldX * count));
|
||||
const tileY = Math.min(count - 1, Math.floor(worldY * count));
|
||||
const column =
|
||||
Math.min(31, Math.floor((worldX * count - tileX) * 32 + 1e-8)) * 2 + 1;
|
||||
const row =
|
||||
Math.min(31, Math.floor((worldY * count - tileY) * 32 + 1e-8)) * 2 + 1;
|
||||
return `grid:${z}/${tileX}/${tileY}:${row}:${column}`;
|
||||
}
|
||||
@@ -0,0 +1,142 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
chooseWildlifeGridZoom,
|
||||
wildlifeGridTiles,
|
||||
wildlifeGridViewportBoxes,
|
||||
wildlifeGridCellBounds,
|
||||
wildlifeGridCellId,
|
||||
WILDLIFE_GRID_LOGICAL_SIZE,
|
||||
WILDLIFE_GRID_TILE_CAP,
|
||||
} from './gridViewport.js';
|
||||
|
||||
const globe = [
|
||||
{ south: -85.0511287798066, west: -180, north: 85.0511287798066, east: 180 },
|
||||
];
|
||||
const regional = [{ south: 0, west: 0, north: 40.979898069620134, east: 45 }];
|
||||
|
||||
test('glow sampling uses roughly 8–14px cells independently of the 28px icon buckets', () => {
|
||||
for (const [boxes, width, height, expected] of [
|
||||
[globe, 448, 448, 0],
|
||||
[regional, 448, 448, 3],
|
||||
[
|
||||
[{ south: 0, west: 0, north: 0.08789059053082508, east: 0.087890625 }],
|
||||
448,
|
||||
448,
|
||||
12,
|
||||
],
|
||||
]) {
|
||||
const zoom = chooseWildlifeGridZoom({ boxes, width, height });
|
||||
assert.equal(zoom, expected);
|
||||
const worldPixels = (width * 360) / (boxes[0].east - boxes[0].west);
|
||||
const spacing = worldPixels / 2 ** zoom / WILDLIFE_GRID_LOGICAL_SIZE;
|
||||
assert.ok(spacing >= 8 && spacing <= 14, `${zoom}: ${spacing}px`);
|
||||
assert.ok(
|
||||
wildlifeGridTiles({ boxes, z: zoom }).length <= WILDLIFE_GRID_TILE_CAP,
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('the named six-tile budget preserves complete coverage for common views', () => {
|
||||
for (const [boxes, width, height, expected] of [
|
||||
[globe, 896, 896, 1],
|
||||
[regional, 896, 896, 4],
|
||||
[[{ south: 7, west: -168, north: 72, east: -48 }], 1400, 900, 2],
|
||||
[globe, 4000, 4000, 1],
|
||||
[globe, 30_000, 400, 0],
|
||||
]) {
|
||||
const z = chooseWildlifeGridZoom({ boxes, width, height });
|
||||
assert.equal(z, expected);
|
||||
const tiles = wildlifeGridTiles({ boxes, z });
|
||||
assert.ok(tiles.length > 0 && tiles.length <= WILDLIFE_GRID_TILE_CAP);
|
||||
}
|
||||
});
|
||||
|
||||
test('tile ranges contain only intersecting tiles, no offscreen neighbors or duplicate boundary tiles', () => {
|
||||
assert.deepEqual(wildlifeGridTiles({ boxes: regional, z: 3 }), [
|
||||
{ z: 3, x: 4, y: 3 },
|
||||
]);
|
||||
assert.deepEqual(wildlifeGridTiles({ boxes: globe, z: 0 }), [
|
||||
{ z: 0, x: 0, y: 0 },
|
||||
]);
|
||||
const crossing = [{ south: 10, west: 179, north: 12, east: -178 }];
|
||||
const split = [
|
||||
{ south: 10, west: 179, north: 12, east: 180 },
|
||||
{ south: 10, west: -180, north: 12, east: -178 },
|
||||
];
|
||||
const z = chooseWildlifeGridZoom({
|
||||
boxes: crossing,
|
||||
width: 896,
|
||||
height: 600,
|
||||
});
|
||||
assert.deepEqual(
|
||||
wildlifeGridTiles({ boxes: crossing, z }),
|
||||
wildlifeGridTiles({ boxes: split, z }),
|
||||
);
|
||||
assert.ok(
|
||||
wildlifeGridTiles({ boxes: crossing, z }).every(
|
||||
(tile) =>
|
||||
((tile.x + 1) / 2 ** z) * 360 - 180 > 179 ||
|
||||
(tile.x / 2 ** z) * 360 - 180 < -178,
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
test('tile cap degrades zoom to preserve complete coverage and oversized direct requests fail closed', () => {
|
||||
const z = chooseWildlifeGridZoom({
|
||||
boxes: globe,
|
||||
width: 30_000,
|
||||
height: 400,
|
||||
});
|
||||
assert.ok(
|
||||
wildlifeGridTiles({ boxes: globe, z }).length <= WILDLIFE_GRID_TILE_CAP,
|
||||
);
|
||||
assert.deepEqual(wildlifeGridTiles({ boxes: globe, z: 12 }), []);
|
||||
assert.equal(chooseWildlifeGridZoom({ boxes: [], width: 0, height: 0 }), 0);
|
||||
assert.deepEqual(wildlifeGridTiles({ boxes: [], z: 2 }), []);
|
||||
});
|
||||
|
||||
test('grid camera viewport supports globe and antimeridian without detail-query degree limits', () => {
|
||||
const radians = (value) => (value * Math.PI) / 180;
|
||||
const viewer = {
|
||||
camera: {
|
||||
computeViewRectangle: () => ({
|
||||
south: radians(-80),
|
||||
west: radians(120),
|
||||
north: radians(80),
|
||||
east: radians(-120),
|
||||
}),
|
||||
},
|
||||
};
|
||||
const boxes = wildlifeGridViewportBoxes(viewer);
|
||||
assert.equal(boxes.length, 2);
|
||||
assert.ok(Math.abs(boxes[0].west - 120) < 1e-8);
|
||||
assert.equal(boxes[0].east, 180);
|
||||
assert.equal(boxes[1].west, -180);
|
||||
assert.deepEqual(wildlifeGridViewportBoxes({}), []);
|
||||
});
|
||||
|
||||
test('logical cell ids and bounds share geographic coverage and wrap antimeridian', () => {
|
||||
const id = wildlifeGridCellId(65.94004866768753, -18.28125, 2);
|
||||
assert.equal(id, 'grid:2/1/1:1:51');
|
||||
const bounds = wildlifeGridCellBounds(id);
|
||||
assert.equal(bounds.west, -19.6875);
|
||||
assert.equal(bounds.east, -16.875);
|
||||
assert.ok(bounds.south < 65.94 && bounds.north > 65.94);
|
||||
assert.equal(
|
||||
wildlifeGridCellId(
|
||||
(bounds.south + bounds.north) / 2,
|
||||
(bounds.west + bounds.east) / 2,
|
||||
2,
|
||||
),
|
||||
id,
|
||||
);
|
||||
assert.equal(wildlifeGridCellId(0, 180, 2), wildlifeGridCellId(0, -180, 2));
|
||||
for (const invalid of [
|
||||
'bad',
|
||||
'grid:23/0/0:1:1',
|
||||
'grid:2/4/0:1:1',
|
||||
'grid:2/0/0:64:1',
|
||||
])
|
||||
assert.equal(wildlifeGridCellBounds(invalid), null);
|
||||
});
|
||||
@@ -0,0 +1,130 @@
|
||||
import * as Cesium from 'cesium';
|
||||
import { horizonOccluder } from '../../data/iconOrientation.js';
|
||||
import { createPhotoSlots } from './photos.js';
|
||||
import { createRendering } from './rendering.js';
|
||||
import { createSelection } from './selection.js';
|
||||
import { createControls } from './controls.js';
|
||||
import { createLifecycle } from './lifecycle.js';
|
||||
|
||||
/** Compose recent wildlife observations without acquiring data at construction. */
|
||||
export function createWildlifeSightingsLayer({
|
||||
source,
|
||||
overlayHost = null,
|
||||
screenSpaceEventHandlerFactory = null,
|
||||
picking = null,
|
||||
pointer = null,
|
||||
sprites = null,
|
||||
badgeSprites = null,
|
||||
render = null,
|
||||
context = null,
|
||||
focus = null,
|
||||
groundFloor = null,
|
||||
now = () => Date.now(),
|
||||
setTimer = (fn, delay) => setTimeout(fn, delay),
|
||||
clearTimer = (timer) => clearTimeout(timer),
|
||||
requestIdleCallback,
|
||||
cancelIdleCallback,
|
||||
imageFactory,
|
||||
eventTarget = globalThis.window,
|
||||
cesium = Cesium,
|
||||
project = (scene, position) =>
|
||||
Cesium.SceneTransforms.worldToWindowCoordinates(scene, position),
|
||||
occluderFactory = horizonOccluder,
|
||||
} = {}) {
|
||||
if (typeof source?.getSnapshot !== 'function')
|
||||
throw new TypeError('Wildlife sightings require a snapshot source');
|
||||
const state = {
|
||||
viewer: null,
|
||||
enabled: false,
|
||||
destroyed: false,
|
||||
manager: null,
|
||||
request: null,
|
||||
background: null,
|
||||
cameraTimer: null,
|
||||
removeCamera: null,
|
||||
removeContext: null,
|
||||
clickHandler: null,
|
||||
rows: new Map(),
|
||||
renderedRows: [],
|
||||
rowById: new Map(),
|
||||
points: null,
|
||||
pointById: new Map(),
|
||||
positions: new Map(),
|
||||
cells: [],
|
||||
staging: null,
|
||||
selectedId: null,
|
||||
selectedRow: null,
|
||||
carriers: new Map(),
|
||||
contextIds: new Set(),
|
||||
publishingContext: false,
|
||||
ambientIds: [],
|
||||
ambientRows: [],
|
||||
confirmed: false,
|
||||
taxa: 'all',
|
||||
drawnParams: null,
|
||||
pendingParams: null,
|
||||
failedParams: null,
|
||||
controlsListener: null,
|
||||
lastUpdate: null,
|
||||
error: null,
|
||||
stale: false,
|
||||
loading: false,
|
||||
gridCells: [],
|
||||
gridParams: null,
|
||||
gridAvailable: false,
|
||||
gridTotal: 0,
|
||||
labelRows: [],
|
||||
query: null,
|
||||
band: null,
|
||||
lastQueryKey: null,
|
||||
retryAt: 0,
|
||||
failures: 0,
|
||||
};
|
||||
const parts = {};
|
||||
const services = {
|
||||
source,
|
||||
overlayHost,
|
||||
screenSpaceEventHandlerFactory,
|
||||
picking,
|
||||
pointer,
|
||||
sprites,
|
||||
badgeSprites,
|
||||
render,
|
||||
context,
|
||||
focus,
|
||||
groundFloor,
|
||||
now,
|
||||
setTimer,
|
||||
clearTimer,
|
||||
requestIdleCallback,
|
||||
cancelIdleCallback,
|
||||
eventTarget,
|
||||
cesium,
|
||||
project,
|
||||
occluderFactory,
|
||||
};
|
||||
const owner = { state, services, parts };
|
||||
parts.photos = createPhotoSlots({
|
||||
imageFactory,
|
||||
now,
|
||||
setTimer,
|
||||
clearTimer,
|
||||
onChange() {
|
||||
if (!state.enabled) return;
|
||||
parts.selection.publishAmbient();
|
||||
},
|
||||
});
|
||||
parts.rendering = createRendering(owner);
|
||||
parts.selection = createSelection(owner);
|
||||
parts.controls = createControls(owner);
|
||||
parts.lifecycle = createLifecycle(owner);
|
||||
return Object.assign({}, parts.controls.methods, parts.lifecycle.methods, {
|
||||
selectSighting: parts.selection.selectAndFocus,
|
||||
clearSightingSelection: parts.selection.clearAndRebuild,
|
||||
subscribeSelection: parts.selection.subscribe,
|
||||
/** Return the current surface anchor for a retained observation. */
|
||||
getSightingPosition(id) {
|
||||
return state.positions.get(id) || null;
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,851 @@
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
import { getWildlifeHeightBand, rowInWildlifeBoxes } from './model.js';
|
||||
import {
|
||||
combineWildlifeGridSnapshots,
|
||||
preferredWildlifeFailure,
|
||||
wildlifeFailureDelayMs,
|
||||
wildlifeFailures,
|
||||
wildlifeRetryAfterMs,
|
||||
} from './source.js';
|
||||
import { wildlifeMeasure } from './performance.js';
|
||||
import { isRecentWildlifeSighting } from './records.js';
|
||||
import {
|
||||
wildlifeGridViewportBoxes,
|
||||
chooseWildlifeGridZoom,
|
||||
wildlifeGridTiles,
|
||||
wildlifeGridCellId,
|
||||
} from './gridViewport.js';
|
||||
import { wildlifeViewportBoxes, snapWildlifeBox } from './viewport.js';
|
||||
import {
|
||||
WILDLIFE_DEBOUNCE_MS,
|
||||
WILDLIFE_MAX_ROWS,
|
||||
WILDLIFE_GRID_HEIGHT_METERS,
|
||||
} from './policy.js';
|
||||
|
||||
/** Manager-owned acquisition with camera debounce and guarded transactions. */
|
||||
export function createLifecycle({ state, services, parts }) {
|
||||
let requestQueryKey = null;
|
||||
let removeManagerListener = null;
|
||||
let lifetimeEpoch = 0;
|
||||
let initialCameraDeadline = 0;
|
||||
let initialSettle = null;
|
||||
// The manager invokes update immediately after enable. Settle startup camera
|
||||
// events before dispatching anything, then acquire only the resulting view.
|
||||
const INITIAL_CAMERA_SETTLE_MS = 300;
|
||||
|
||||
function settleInitialCamera(signal) {
|
||||
if (!initialCameraDeadline || services.now() >= initialCameraDeadline) {
|
||||
initialCameraDeadline = 0;
|
||||
return Promise.resolve();
|
||||
}
|
||||
return new Promise((resolve) => {
|
||||
const finish = () => {
|
||||
services.clearTimer(state.cameraTimer);
|
||||
state.cameraTimer = null;
|
||||
initialSettle = null;
|
||||
initialCameraDeadline = 0;
|
||||
signal?.removeEventListener('abort', finish);
|
||||
resolve();
|
||||
};
|
||||
initialSettle = {
|
||||
schedule() {
|
||||
services.clearTimer(state.cameraTimer);
|
||||
state.cameraTimer = services.setTimer(
|
||||
finish,
|
||||
Math.max(0, initialCameraDeadline - services.now()),
|
||||
);
|
||||
},
|
||||
finish,
|
||||
};
|
||||
signal?.addEventListener('abort', finish, { once: true });
|
||||
initialSettle.schedule();
|
||||
});
|
||||
}
|
||||
|
||||
function renderBatch(fn) {
|
||||
parts.rendering.beginBatch?.();
|
||||
try {
|
||||
return fn();
|
||||
} finally {
|
||||
parts.rendering.endBatch?.();
|
||||
}
|
||||
}
|
||||
|
||||
function clearPending() {
|
||||
if (!state.pendingParams) return;
|
||||
if (state.error) state.failedParams = state.pendingParams;
|
||||
state.pendingParams = null;
|
||||
parts.controls.notify();
|
||||
}
|
||||
|
||||
function failParams(params) {
|
||||
// An acquisition can fail during an ordinary refresh, when no option is
|
||||
// pending. Keep the chosen taxa visible and retryable in that case too.
|
||||
state.failedParams = {
|
||||
...params,
|
||||
keys: [
|
||||
...new Set([
|
||||
...(state.pendingParams?.keys || []),
|
||||
'taxa',
|
||||
...(params.confirmed ? ['confirmed'] : []),
|
||||
]),
|
||||
],
|
||||
};
|
||||
state.pendingParams = null;
|
||||
}
|
||||
|
||||
function applyRetry(
|
||||
errors,
|
||||
retryAfterSec = null,
|
||||
previousMs = state.failures || 0,
|
||||
) {
|
||||
// Only 429/5xx failures impose cooldown; client, network and schema
|
||||
// errors retry on pan. Several requests can fail together: wait for the
|
||||
// longest effective delay among them.
|
||||
const delays = [
|
||||
...wildlifeFailures(errors).map((error) =>
|
||||
wildlifeFailureDelayMs(error, previousMs),
|
||||
),
|
||||
wildlifeRetryAfterMs(retryAfterSec),
|
||||
].filter((delay) => delay !== null);
|
||||
if (!delays.length) {
|
||||
state.failures = 0;
|
||||
state.retryAt = 0;
|
||||
return;
|
||||
}
|
||||
const backoff = Math.max(...delays);
|
||||
state.failures = backoff;
|
||||
state.retryAt = services.now() + backoff;
|
||||
}
|
||||
|
||||
function pageHidden() {
|
||||
return (
|
||||
services.eventTarget?.document?.hidden || globalThis.document?.hidden
|
||||
);
|
||||
}
|
||||
|
||||
function currentQuery() {
|
||||
const height = state.viewer?.camera?.positionCartographic?.height;
|
||||
state.band = getWildlifeHeightBand(height ?? Infinity, state.band);
|
||||
const boxes =
|
||||
state.band === 'global'
|
||||
? null
|
||||
: wildlifeViewportBoxes(state.viewer)?.map((box) =>
|
||||
snapWildlifeBox(box),
|
||||
);
|
||||
const visibleBoxes = wildlifeGridViewportBoxes(state.viewer);
|
||||
const scope =
|
||||
state.band === 'global' ||
|
||||
(!boxes && (height ?? Infinity) > WILDLIFE_GRID_HEIGHT_METERS)
|
||||
? 'global'
|
||||
: 'view';
|
||||
if (scope === 'view' && (!boxes?.length || boxes.some((box) => !box)))
|
||||
return null;
|
||||
const baseKey = JSON.stringify([
|
||||
scope,
|
||||
scope === 'global' ? null : boxes,
|
||||
state.confirmed,
|
||||
state.taxa,
|
||||
]);
|
||||
const canvas = state.viewer?.scene?.canvas;
|
||||
const zoom = visibleBoxes?.length
|
||||
? chooseWildlifeGridZoom({
|
||||
boxes: visibleBoxes,
|
||||
width: canvas?.clientWidth || 1400,
|
||||
height: canvas?.clientHeight || 900,
|
||||
})
|
||||
: 0;
|
||||
const tiles = visibleBoxes?.length
|
||||
? wildlifeGridTiles({ boxes: visibleBoxes, z: zoom })
|
||||
: [];
|
||||
return {
|
||||
scope,
|
||||
boxes: scope === 'global' ? null : boxes,
|
||||
visibleBoxes,
|
||||
tiles,
|
||||
key: JSON.stringify([baseKey, tiles]),
|
||||
};
|
||||
}
|
||||
|
||||
function refreshView() {
|
||||
const query = currentQuery();
|
||||
const superseded = state.query?.key !== query?.key;
|
||||
state.query = query;
|
||||
if (superseded) {
|
||||
state.request?.abort();
|
||||
state.background?.abort();
|
||||
}
|
||||
// Keep the previous validated display while changing filters. Its rows
|
||||
// and parameter chips are replaced together when acquisition succeeds.
|
||||
renderBatch(() => {
|
||||
const pending =
|
||||
!state.pendingClear && parts.rendering.rebuild() === 'pending';
|
||||
parts.rendering.cull();
|
||||
if (pending) return;
|
||||
parts.selection.refreshAmbient();
|
||||
parts.selection.refreshContexts();
|
||||
parts.selection.syncCredits();
|
||||
});
|
||||
return query;
|
||||
}
|
||||
|
||||
async function refresh() {
|
||||
if (!state.enabled || pageHidden()) {
|
||||
clearPending();
|
||||
return;
|
||||
}
|
||||
const controller = new AbortController();
|
||||
const pendingParams = state.pendingParams;
|
||||
state.background?.abort();
|
||||
state.background = controller;
|
||||
try {
|
||||
if (state.manager)
|
||||
await state.manager.refreshLayer('wildlife-sightings', {
|
||||
signal: controller.signal,
|
||||
});
|
||||
else await methods.update(undefined, { signal: controller.signal });
|
||||
} catch {
|
||||
// update exposes expected source errors through stats; manager failures
|
||||
// already have their own normalized status path.
|
||||
} finally {
|
||||
if (state.background === controller) {
|
||||
state.background = null;
|
||||
// A manager may decline acquisition while it is enabling, or the view
|
||||
// may disappear before update. Only queued/in-flight work is busy.
|
||||
if (
|
||||
state.pendingParams === pendingParams &&
|
||||
!state.loading &&
|
||||
state.cameraTimer == null
|
||||
)
|
||||
clearPending();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function scheduleRefresh() {
|
||||
services.clearTimer(state.cameraTimer);
|
||||
state.cameraTimer = null;
|
||||
if (!state.enabled || pageHidden()) {
|
||||
clearPending();
|
||||
return;
|
||||
}
|
||||
if (initialSettle) {
|
||||
initialSettle.schedule();
|
||||
return;
|
||||
}
|
||||
const query = currentQuery();
|
||||
if (!query || query.key === state.lastQueryKey) {
|
||||
clearPending();
|
||||
return;
|
||||
}
|
||||
if (
|
||||
query.key === requestQueryKey &&
|
||||
state.request &&
|
||||
!state.request.signal.aborted
|
||||
)
|
||||
return;
|
||||
state.cameraTimer = services.setTimer(
|
||||
() => {
|
||||
state.cameraTimer = null;
|
||||
if (!state.enabled || pageHidden()) {
|
||||
clearPending();
|
||||
return;
|
||||
}
|
||||
const query = currentQuery();
|
||||
if (!query || query.key === state.lastQueryKey) {
|
||||
clearPending();
|
||||
return;
|
||||
}
|
||||
if (
|
||||
query.key === requestQueryKey &&
|
||||
state.request &&
|
||||
!state.request.signal.aborted
|
||||
)
|
||||
return;
|
||||
if (services.now() < state.retryAt) {
|
||||
scheduleRefresh();
|
||||
return;
|
||||
}
|
||||
void refresh();
|
||||
},
|
||||
Math.max(WILDLIFE_DEBOUNCE_MS, state.retryAt - services.now()),
|
||||
);
|
||||
}
|
||||
|
||||
function applyAccepted({
|
||||
snapshot,
|
||||
grid,
|
||||
gridError,
|
||||
query,
|
||||
params,
|
||||
request,
|
||||
signal,
|
||||
epoch,
|
||||
previousFailures,
|
||||
replaceRows = true,
|
||||
}) {
|
||||
const current = currentQuery();
|
||||
if (
|
||||
!state.enabled ||
|
||||
state.destroyed ||
|
||||
epoch !== lifetimeEpoch ||
|
||||
request.signal.aborted ||
|
||||
signal?.aborted ||
|
||||
params.taxa !== state.taxa ||
|
||||
params.confirmed !== state.confirmed ||
|
||||
current?.key !== query.key
|
||||
)
|
||||
return;
|
||||
renderBatch(() => {
|
||||
const sameParams =
|
||||
params.taxa === state.drawnParams?.taxa &&
|
||||
params.confirmed === state.drawnParams?.confirmed;
|
||||
const gridParams = state.gridParams || state.drawnParams;
|
||||
const sameGridParams =
|
||||
params.taxa === gridParams?.taxa &&
|
||||
params.confirmed === gridParams?.confirmed;
|
||||
// Tiles may beat a slow observation page. Publish their density without
|
||||
// replacing observations or claiming their filter transaction succeeded.
|
||||
// A pending filter keeps its previous display until both paths agree.
|
||||
if (!snapshot) {
|
||||
if (state.drawnParams && !sameParams) return;
|
||||
if (grid) {
|
||||
state.gridCells = grid.cells || [];
|
||||
state.gridParams = params;
|
||||
state.gridAvailable = true;
|
||||
state.gridTotal = grid.totalResults || 0;
|
||||
if (state.lastUpdate == null)
|
||||
state.lastUpdate = Number.isFinite(grid.fetchedAt)
|
||||
? grid.fetchedAt
|
||||
: services.now();
|
||||
const pendingRender = parts.rendering.rebuild() === 'pending';
|
||||
if (!pendingRender) {
|
||||
parts.selection.refreshAmbient();
|
||||
parts.selection.publishSelected();
|
||||
parts.selection.refreshContexts();
|
||||
parts.selection.syncCredits();
|
||||
}
|
||||
parts.controls.notify();
|
||||
}
|
||||
return;
|
||||
}
|
||||
if (replaceRows) {
|
||||
if (state.selectedId && !state.selectedRow)
|
||||
state.selectedRow =
|
||||
state.rowById.get(state.selectedId) ||
|
||||
state.rows.get(state.selectedId) ||
|
||||
null;
|
||||
const retainedRows = sameParams
|
||||
? (parts.selection.retainedAmbientRows?.() || []).filter(
|
||||
(row) =>
|
||||
state.rows.has(row.stableId) &&
|
||||
isRecentWildlifeSighting(row, services.now(), params.taxa),
|
||||
)
|
||||
: [];
|
||||
const retainedIds = new Set(retainedRows.map((row) => row.stableId));
|
||||
if (state.selectedRow) retainedIds.add(state.selectedRow.stableId);
|
||||
if (state.pendingClear || state.loadedScope !== query.scope)
|
||||
state.rows.clear();
|
||||
state.loadedScope = query.scope;
|
||||
state.pendingClear = false;
|
||||
// A successful page replaces this queried area, including a healthy
|
||||
// empty page. Keep only other visited areas in the bounded LRU. Areas
|
||||
// whose iNaturalist request failed keep their last iNaturalist rows.
|
||||
const inat = snapshot.sources?.inaturalist;
|
||||
const failedInatBoxes =
|
||||
inat?.ok === false ? inat.failedBoxes || query.boxes : null;
|
||||
for (const [id, row] of state.rows) {
|
||||
if (
|
||||
failedInatBoxes &&
|
||||
row.origin === 'inaturalist' &&
|
||||
rowInWildlifeBoxes(row, failedInatBoxes, 0)
|
||||
)
|
||||
continue;
|
||||
if (rowInWildlifeBoxes(row, query.boxes, 0)) state.rows.delete(id);
|
||||
}
|
||||
for (const row of snapshot.rows) {
|
||||
state.rows.delete(row.stableId);
|
||||
state.rows.set(row.stableId, row);
|
||||
if (row.stableId === state.selectedId) state.selectedRow = row;
|
||||
}
|
||||
// Selection owns a real observation until explicit deselection. It is
|
||||
// independent of sample/window/filter and ambient-card eligibility.
|
||||
if (state.selectedRow && !state.rows.has(state.selectedId))
|
||||
state.rows.set(state.selectedId, state.selectedRow);
|
||||
// Random samples may omit a photograph already displayed. Its bounded
|
||||
// incumbent row stays selectable until the card leaves the view/window.
|
||||
for (const row of retainedRows) {
|
||||
if (!state.rows.has(row.stableId)) state.rows.set(row.stableId, row);
|
||||
}
|
||||
if (state.rows.size > WILDLIFE_MAX_ROWS) {
|
||||
for (const id of state.rows.keys()) {
|
||||
if (!retainedIds.has(id)) state.rows.delete(id);
|
||||
if (state.rows.size <= WILDLIFE_MAX_ROWS) break;
|
||||
}
|
||||
}
|
||||
if (state.rows.size > WILDLIFE_MAX_ROWS) {
|
||||
for (const id of state.rows.keys()) {
|
||||
if (id !== state.selectedId) state.rows.delete(id);
|
||||
if (state.rows.size <= WILDLIFE_MAX_ROWS) break;
|
||||
}
|
||||
}
|
||||
}
|
||||
const failedStale = [snapshot, grid].filter(
|
||||
(value) =>
|
||||
value?.stale === true &&
|
||||
Number.isFinite(value.retryAfterSec) &&
|
||||
(value.upstreamStatus === undefined ||
|
||||
value.upstreamStatus === 429 ||
|
||||
value.upstreamStatus >= 500),
|
||||
);
|
||||
// The filter above admits only 429/5xx or an unmarked stale answer.
|
||||
const staleError = failedStale.length
|
||||
? Object.assign(
|
||||
new Error(msg('Wildlife sightings source unavailable')),
|
||||
{
|
||||
upstreamStatus: Math.max(
|
||||
...failedStale.map((value) => value.upstreamStatus || 503),
|
||||
),
|
||||
retryAfterSec: Math.max(
|
||||
...failedStale.map((value) => value.retryAfterSec),
|
||||
),
|
||||
},
|
||||
)
|
||||
: null;
|
||||
const inat = snapshot.sources?.inaturalist;
|
||||
const acartia = snapshot.sources?.acartia;
|
||||
// Keep each failed request's status and Retry-After; the displayed
|
||||
// error is the one whose effective delay sets the cooldown.
|
||||
const sourceErrors = [
|
||||
gridError,
|
||||
staleError,
|
||||
inat?.ok === false
|
||||
? inat.error ||
|
||||
new Error(msg('Wildlife sightings source unavailable'))
|
||||
: null,
|
||||
acartia?.ok === false
|
||||
? Object.assign(new Error(msg('Acartia feed unavailable')), {
|
||||
...(acartia.error?.status
|
||||
? { status: acartia.error.status }
|
||||
: {}),
|
||||
...(acartia.error?.upstreamStatus
|
||||
? { upstreamStatus: acartia.error.upstreamStatus }
|
||||
: {}),
|
||||
...(Number.isFinite(acartia.error?.retryAfterSec)
|
||||
? { retryAfterSec: acartia.error.retryAfterSec }
|
||||
: {}),
|
||||
})
|
||||
: null,
|
||||
].filter(Boolean);
|
||||
const sourceError = preferredWildlifeFailure(
|
||||
sourceErrors,
|
||||
previousFailures,
|
||||
);
|
||||
state.stale =
|
||||
!sourceError && (snapshot.stale === true || grid?.stale === true);
|
||||
const fetchedAt = [snapshot.fetchedAt, grid?.fetchedAt].filter(
|
||||
Number.isFinite,
|
||||
);
|
||||
state.lastUpdate =
|
||||
(snapshot.stale === true || grid?.stale === true) && fetchedAt.length
|
||||
? Math.min(...fetchedAt)
|
||||
: services.now();
|
||||
state.error = sourceError?.message || null;
|
||||
state.drawnParams = params;
|
||||
const retryAfter = [snapshot, grid]
|
||||
.filter(
|
||||
(value) =>
|
||||
value &&
|
||||
(value.upstreamStatus === undefined ||
|
||||
value.upstreamStatus === 429 ||
|
||||
value.upstreamStatus >= 500),
|
||||
)
|
||||
.map((value) => value.retryAfterSec)
|
||||
.filter(Number.isFinite);
|
||||
if (sourceError) {
|
||||
failParams(params);
|
||||
applyRetry(
|
||||
sourceErrors,
|
||||
retryAfter.length ? Math.max(...retryAfter) : null,
|
||||
previousFailures,
|
||||
);
|
||||
} else {
|
||||
state.pendingParams = null;
|
||||
state.failedParams = null;
|
||||
state.retryAt = retryAfter.length
|
||||
? services.now() + wildlifeRetryAfterMs(Math.max(...retryAfter))
|
||||
: 0;
|
||||
state.failures = 0;
|
||||
}
|
||||
state.query = currentQuery();
|
||||
if (grid !== undefined || !sameGridParams) {
|
||||
state.gridCells = grid?.cells || [];
|
||||
state.gridParams = grid ? params : null;
|
||||
state.gridAvailable = !!grid;
|
||||
state.gridTotal = grid?.totalResults || 0;
|
||||
}
|
||||
const pendingRender = parts.rendering.rebuild() === 'pending';
|
||||
if (pendingRender) {
|
||||
state.lastQueryKey = sourceError ? null : state.query?.key || query.key;
|
||||
parts.controls.notify();
|
||||
return;
|
||||
}
|
||||
parts.selection.refreshAmbient();
|
||||
parts.selection.publishSelected();
|
||||
parts.selection.notify();
|
||||
parts.selection.refreshContexts();
|
||||
parts.selection.syncCredits();
|
||||
state.lastQueryKey = sourceError ? null : state.query?.key || query.key;
|
||||
parts.controls.notify();
|
||||
});
|
||||
}
|
||||
|
||||
function disable() {
|
||||
lifetimeEpoch += 1;
|
||||
initialSettle?.finish();
|
||||
initialCameraDeadline = 0;
|
||||
state.enabled = false;
|
||||
services.clearTimer(state.cameraTimer);
|
||||
state.cameraTimer = null;
|
||||
state.request?.abort();
|
||||
state.request = null;
|
||||
requestQueryKey = null;
|
||||
state.background?.abort();
|
||||
state.background = null;
|
||||
state.loading = false;
|
||||
clearPending();
|
||||
state.removeCamera?.();
|
||||
state.removeCamera = null;
|
||||
parts.rendering.deactivate?.();
|
||||
removeManagerListener?.();
|
||||
removeManagerListener = null;
|
||||
parts.selection.remove();
|
||||
services.picking?.unregisterPickOwner?.('wildlife-sightings');
|
||||
parts.rendering.clear();
|
||||
parts.photos.clear();
|
||||
parts.controls.notify();
|
||||
parts.rendering.requestRender('disable');
|
||||
return true;
|
||||
}
|
||||
|
||||
const methods = {
|
||||
/** Attach this layer's Cesium resources to one viewer. */
|
||||
init(viewer, { signal } = {}) {
|
||||
if (state.viewer)
|
||||
throw new Error('Wildlife sightings layer is already initialized');
|
||||
if (state.destroyed || signal?.aborted) return false;
|
||||
state.viewer = viewer;
|
||||
parts.rendering.init();
|
||||
return true;
|
||||
},
|
||||
/** Show retained observations and acquire the settled camera view. */
|
||||
enable(_viewer, { signal } = {}) {
|
||||
if (state.destroyed || signal?.aborted) return false;
|
||||
if (!state.viewer)
|
||||
throw new Error('Wildlife sightings layer must be initialized');
|
||||
if (state.enabled) return true;
|
||||
state.enabled = true;
|
||||
initialCameraDeadline = services.now() + INITIAL_CAMERA_SETTLE_MS;
|
||||
parts.rendering.activate?.();
|
||||
state.points.show = true;
|
||||
refreshView();
|
||||
for (const id of parts.selection.sourceIds)
|
||||
services.overlayHost?.setVisible?.(id, true);
|
||||
parts.selection.install();
|
||||
services.picking?.registerPickOwner?.(
|
||||
'wildlife-sightings',
|
||||
(id) =>
|
||||
typeof id === 'string' &&
|
||||
id.startsWith('wildlife:') &&
|
||||
state.rowById.has(id.slice(9)),
|
||||
);
|
||||
state.removeCamera = state.viewer.camera?.moveEnd?.addEventListener?.(
|
||||
() => {
|
||||
if (!state.enabled) return;
|
||||
wildlifeMeasure('moveEnd', () => {
|
||||
if (
|
||||
initialCameraDeadline &&
|
||||
services.now() < initialCameraDeadline
|
||||
) {
|
||||
initialCameraDeadline = services.now() + INITIAL_CAMERA_SETTLE_MS;
|
||||
refreshView();
|
||||
initialSettle?.schedule();
|
||||
} else {
|
||||
refreshView();
|
||||
scheduleRefresh();
|
||||
}
|
||||
parts.controls.notify();
|
||||
});
|
||||
},
|
||||
);
|
||||
// A debounce can expire while the manager is still enabling and cannot
|
||||
// accept refreshLayer yet. Its settled visibility event is the one
|
||||
// catch-up edge; completed initial queries are skipped by their key.
|
||||
removeManagerListener =
|
||||
state.manager?.subscribe?.((change) => {
|
||||
if (
|
||||
change.type === 'visibility' &&
|
||||
change.layerId === 'wildlife-sightings' &&
|
||||
change.enabled === true &&
|
||||
state.enabled
|
||||
)
|
||||
scheduleRefresh();
|
||||
}) || null;
|
||||
if (services.sprites?.restoreSpriteOrderOnEnable)
|
||||
services.sprites.restoreSpriteOrderOnEnable(
|
||||
'wildlife-sightings',
|
||||
state.viewer,
|
||||
);
|
||||
else services.sprites?.restoreSpriteOrder?.(state.viewer);
|
||||
return true;
|
||||
},
|
||||
/** Refresh observations and density independently for the current filters. */
|
||||
async update(_viewer, { signal } = {}) {
|
||||
if (
|
||||
!state.enabled ||
|
||||
!state.points ||
|
||||
state.destroyed ||
|
||||
signal?.aborted
|
||||
) {
|
||||
if (!state.request) clearPending();
|
||||
return false;
|
||||
}
|
||||
if (initialCameraDeadline && services.now() < initialCameraDeadline)
|
||||
await settleInitialCamera(signal);
|
||||
initialCameraDeadline = 0;
|
||||
if (!state.enabled || state.destroyed || signal?.aborted) return false;
|
||||
const query = currentQuery();
|
||||
state.query = query;
|
||||
if (!query || pageHidden()) {
|
||||
clearPending();
|
||||
return true;
|
||||
}
|
||||
if (services.now() < state.retryAt) {
|
||||
if (state.pendingParams && state.cameraTimer == null) scheduleRefresh();
|
||||
return true;
|
||||
}
|
||||
if (
|
||||
requestQueryKey === query.key &&
|
||||
state.request &&
|
||||
!state.request.signal.aborted
|
||||
)
|
||||
return true;
|
||||
state.request?.abort();
|
||||
const request = new AbortController();
|
||||
const requestLifetime = lifetimeEpoch;
|
||||
// One acquisition publishes several times (tiles, rows, final grid).
|
||||
// Each derives its default backoff from the backoff before it started.
|
||||
const previousFailures = state.failures || 0;
|
||||
const supersededResult = () =>
|
||||
state.enabled &&
|
||||
!state.destroyed &&
|
||||
lifetimeEpoch === requestLifetime &&
|
||||
!signal?.aborted;
|
||||
state.request = request;
|
||||
requestQueryKey = query.key;
|
||||
const onAbort = () => request.abort(signal.reason);
|
||||
signal?.addEventListener?.('abort', onAbort, { once: true });
|
||||
const params = { confirmed: state.confirmed, taxa: state.taxa };
|
||||
state.loading = true;
|
||||
if (!state.pendingParams) {
|
||||
const drawn = state.drawnParams || { confirmed: false, taxa: null };
|
||||
const keys = ['confirmed', 'taxa'].filter(
|
||||
(key) => params[key] !== drawn[key],
|
||||
);
|
||||
if (keys.length) state.pendingParams = { ...params, keys };
|
||||
}
|
||||
parts.controls.notify();
|
||||
let received = false;
|
||||
let gridPending = false;
|
||||
let acceptedSnapshot = null;
|
||||
let gridRequest = null;
|
||||
let gridResult = null;
|
||||
const tileSnapshots = new Map();
|
||||
const gridParams = state.gridParams || state.drawnParams;
|
||||
const retainedGrid =
|
||||
params.taxa === gridParams?.taxa &&
|
||||
params.confirmed === gridParams?.confirmed
|
||||
? state.gridCells || []
|
||||
: [];
|
||||
function aggregateTiles(complete = false) {
|
||||
if (!tileSnapshots.size) return undefined;
|
||||
const grid = combineWildlifeGridSnapshots([...tileSnapshots.values()]);
|
||||
if (!complete && retainedGrid.length) {
|
||||
const zoom = query.tiles[0]?.z;
|
||||
const covered = new Set(tileSnapshots.keys());
|
||||
const retained = retainedGrid.filter(
|
||||
(cell) =>
|
||||
!covered.has(
|
||||
wildlifeGridCellId(cell.lat, cell.lon, zoom)?.split(':')[1],
|
||||
),
|
||||
);
|
||||
return combineWildlifeGridSnapshots([
|
||||
{ ...grid, cells: [...retained, ...grid.cells] },
|
||||
]);
|
||||
}
|
||||
return grid;
|
||||
}
|
||||
function completedGrid(value) {
|
||||
if (!value) return value;
|
||||
const aggregate = aggregateTiles(!value.error);
|
||||
return aggregate
|
||||
? combineWildlifeGridSnapshots([aggregate, value], value.error)
|
||||
: value;
|
||||
}
|
||||
function publish(grid, gridError = null, replaceRows = false) {
|
||||
applyAccepted({
|
||||
snapshot: acceptedSnapshot,
|
||||
grid,
|
||||
gridError,
|
||||
replaceRows,
|
||||
query,
|
||||
params,
|
||||
request,
|
||||
signal,
|
||||
epoch: requestLifetime,
|
||||
previousFailures,
|
||||
});
|
||||
}
|
||||
function finishTiles() {
|
||||
signal?.removeEventListener?.('abort', onAbort);
|
||||
if (state.request === request) {
|
||||
state.request = null;
|
||||
requestQueryKey = null;
|
||||
state.loading = false;
|
||||
if (request.signal.aborted && state.cameraTimer == null)
|
||||
clearPending();
|
||||
parts.controls.notify();
|
||||
}
|
||||
}
|
||||
function continueTiles() {
|
||||
if (!gridRequest || gridResult) return;
|
||||
gridPending = true;
|
||||
void gridRequest
|
||||
.then((result) => {
|
||||
if (
|
||||
acceptedSnapshot &&
|
||||
!request.signal.aborted &&
|
||||
state.request === request &&
|
||||
state.enabled
|
||||
)
|
||||
publish(result?.value, result?.error || result?.value?.error);
|
||||
})
|
||||
.finally(finishTiles);
|
||||
}
|
||||
try {
|
||||
const options = {
|
||||
signal: request.signal,
|
||||
boxes: query.boxes,
|
||||
box: query.boxes?.[0] || null,
|
||||
scope: query.scope,
|
||||
...params,
|
||||
};
|
||||
// Observation requests enter the shared proxy queue first. A slow tile
|
||||
// never holds the manager's initial enable or the first observations.
|
||||
const observationRequest =
|
||||
typeof services.source.getSnapshotDetail === 'function'
|
||||
? services.source.getSnapshotDetail(options)
|
||||
: Promise.resolve(services.source.getSnapshot(options)).then(
|
||||
(rows) => ({ rows, stale: false, fetchedAt: services.now() }),
|
||||
);
|
||||
const hasGrid =
|
||||
typeof services.source.getGridSnapshot === 'function' &&
|
||||
query.tiles.length;
|
||||
gridRequest = hasGrid
|
||||
? services.source
|
||||
.getGridSnapshot({
|
||||
signal: request.signal,
|
||||
tiles: query.tiles,
|
||||
...params,
|
||||
onTile(value, { tile }) {
|
||||
if (request.signal.aborted || state.request !== request)
|
||||
return;
|
||||
tileSnapshots.set(`${tile.z}/${tile.x}/${tile.y}`, value);
|
||||
publish(aggregateTiles());
|
||||
},
|
||||
})
|
||||
.then(
|
||||
(value) => {
|
||||
gridResult = { value: completedGrid(value) };
|
||||
if (!acceptedSnapshot)
|
||||
publish(gridResult.value, value?.error);
|
||||
return gridResult;
|
||||
},
|
||||
(error) => (gridResult = { error }),
|
||||
)
|
||||
: null;
|
||||
const snapshot = await observationRequest;
|
||||
if (
|
||||
request.signal.aborted ||
|
||||
state.request !== request ||
|
||||
!state.enabled
|
||||
)
|
||||
return supersededResult();
|
||||
if (!Array.isArray(snapshot?.rows))
|
||||
throw new Error('Malformed iNaturalist response');
|
||||
received = true;
|
||||
acceptedSnapshot = snapshot;
|
||||
publish(
|
||||
gridResult?.value || aggregateTiles(),
|
||||
gridResult?.error || gridResult?.value?.error,
|
||||
true,
|
||||
);
|
||||
if (hasGrid && !gridResult) {
|
||||
continueTiles();
|
||||
} else if (gridResult && !gridResult.value && gridResult.error) {
|
||||
// Observation rows remain visible when the first tile set fails.
|
||||
publish(undefined, gridResult.error);
|
||||
}
|
||||
return true;
|
||||
} catch (error) {
|
||||
if (
|
||||
request.signal.aborted ||
|
||||
state.request !== request ||
|
||||
!state.enabled
|
||||
)
|
||||
return supersededResult();
|
||||
if (received) throw error;
|
||||
// Observation failures must not cancel independent density tiles.
|
||||
continueTiles();
|
||||
state.stale = false;
|
||||
state.error =
|
||||
preferredWildlifeFailure(error, previousFailures)?.message ||
|
||||
msg('Wildlife sightings source unavailable');
|
||||
failParams(params);
|
||||
state.lastQueryKey = null;
|
||||
requestQueryKey = null;
|
||||
applyRetry(error, null, previousFailures);
|
||||
console.warn('[Data:WildlifeSightings] Update failed:', state.error);
|
||||
return true;
|
||||
} finally {
|
||||
if (!gridPending) finishTiles();
|
||||
}
|
||||
},
|
||||
/** Stop acquisition and release visible resources while retaining filters. */
|
||||
disable,
|
||||
/** Release requests, subscriptions, caches and scene resources. */
|
||||
destroy() {
|
||||
if (state.destroyed) return;
|
||||
disable();
|
||||
state.destroyed = true;
|
||||
parts.selection.destroy();
|
||||
parts.photos.destroy();
|
||||
parts.rendering.destroy();
|
||||
state.rows.clear();
|
||||
state.lastUpdate = null;
|
||||
state.error = null;
|
||||
state.stale = false;
|
||||
state.drawnParams = null;
|
||||
state.gridParams = null;
|
||||
state.pendingParams = null;
|
||||
state.failedParams = null;
|
||||
state.controlsListener = null;
|
||||
state.manager = null;
|
||||
state.viewer = null;
|
||||
},
|
||||
};
|
||||
return {
|
||||
methods,
|
||||
scheduleRefresh,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,208 @@
|
||||
import {
|
||||
WILDLIFE_HEIGHT_BANDS,
|
||||
WILDLIFE_HEIGHT_HYSTERESIS,
|
||||
WILDLIFE_RENDER_LIMIT,
|
||||
WILDLIFE_VIEW_PADDING,
|
||||
} from './policy.js';
|
||||
import { WILDLIFE_GRID_TARGET_SPACING_PX } from './gridViewport.js';
|
||||
import { drainWildlifeWork, WILDLIFE_WORK_UNIT } from './performance.js';
|
||||
|
||||
const BAND_ORDER = Object.freeze(['cards', 'cells', 'regional', 'global']);
|
||||
const BAND_THRESHOLDS = Object.freeze([
|
||||
WILDLIFE_HEIGHT_BANDS.cards,
|
||||
WILDLIFE_HEIGHT_BANDS.cells,
|
||||
WILDLIFE_HEIGHT_BANDS.global,
|
||||
]);
|
||||
|
||||
/** A previous band is retained until a boundary is crossed by ten percent. */
|
||||
export function getWildlifeHeightBand(heightM, previous) {
|
||||
const height = Number.isFinite(heightM) ? Math.max(0, heightM) : 0;
|
||||
let index = BAND_ORDER.indexOf(previous);
|
||||
if (index < 0)
|
||||
return BAND_ORDER[
|
||||
BAND_THRESHOLDS.filter((boundary) => height > boundary).length
|
||||
];
|
||||
while (
|
||||
index < BAND_ORDER.length - 1 &&
|
||||
height > BAND_THRESHOLDS[index] * (1 + WILDLIFE_HEIGHT_HYSTERESIS)
|
||||
)
|
||||
index += 1;
|
||||
while (
|
||||
index > 0 &&
|
||||
height < BAND_THRESHOLDS[index - 1] * (1 - WILDLIFE_HEIGHT_HYSTERESIS)
|
||||
)
|
||||
index -= 1;
|
||||
return BAND_ORDER[index];
|
||||
}
|
||||
|
||||
/** Share the legend's animal grouping and unknown fallback with sprites. */
|
||||
export function wildlifeIconicGroup(iconic) {
|
||||
if (iconic === 'Mollusca' || iconic === 'Animalia') return 'Animalia';
|
||||
return [
|
||||
'Aves',
|
||||
'Mammalia',
|
||||
'Reptilia',
|
||||
'Amphibia',
|
||||
'Actinopterygii',
|
||||
'Insecta',
|
||||
'Arachnida',
|
||||
'Plantae',
|
||||
'Fungi',
|
||||
].includes(iconic)
|
||||
? iconic
|
||||
: 'Unknown';
|
||||
}
|
||||
|
||||
function validIconPosition(row) {
|
||||
return (
|
||||
Number.isFinite(row?.lat) &&
|
||||
Math.abs(row.lat) <= 90 &&
|
||||
Number.isFinite(row?.lon) &&
|
||||
Math.abs(row.lon) <= 180
|
||||
);
|
||||
}
|
||||
|
||||
/** Compare provider IDs consistently across locales. */
|
||||
export function compareWildlifeIds(a, b) {
|
||||
return a < b ? -1 : a > b ? 1 : 0;
|
||||
}
|
||||
|
||||
/** Prefer a selected/identified recent contact when a population exceeds its
|
||||
* cap. Density is never converted into a larger billboard. */
|
||||
export function wildlifeIconRelevance(row, selectedId = null) {
|
||||
return (
|
||||
(row.stableId === selectedId ? 1e15 : 0) +
|
||||
(row.commonName ? 1e13 : 0) +
|
||||
(row.quality === 'research' ? 1e12 : 0) +
|
||||
(Number.isFinite(row.observedAt) ? row.observedAt / 1000 : 0)
|
||||
);
|
||||
}
|
||||
|
||||
/** Real observations alone compete for 28px screen buckets. Density is an
|
||||
* independent visual and can never supply or suppress a sighting's identity.
|
||||
* A selected observation keeps its slot even outside the new camera view. */
|
||||
export function buildWildlifeIconModel(options = {}) {
|
||||
return drainWildlifeWork(wildlifeIconModelWork(options));
|
||||
}
|
||||
|
||||
/** Yield bounded units while selecting real observations for screen buckets. */
|
||||
export function* wildlifeIconModelWork({
|
||||
rows = [],
|
||||
boxes = null,
|
||||
selectedId = null,
|
||||
selectedRow = null,
|
||||
preferredIds = [],
|
||||
limit = WILDLIFE_RENDER_LIMIT,
|
||||
projectRow = null,
|
||||
onOperations = null,
|
||||
} = {}) {
|
||||
const operations = {
|
||||
observationVisits: 0,
|
||||
projections: 0,
|
||||
rankComparisons: 0,
|
||||
};
|
||||
const preferred = new Set(preferredIds);
|
||||
const seen = new Set();
|
||||
const buckets = new Map();
|
||||
let sightingCount = 0;
|
||||
let acartiaCount = 0;
|
||||
const score = (row) =>
|
||||
wildlifeIconRelevance(row, selectedId) +
|
||||
(preferred.has(row.stableId) ? 1e14 : 0);
|
||||
const candidates =
|
||||
selectedRow && !rows.includes(selectedRow) ? [...rows, selectedRow] : rows;
|
||||
yield 'bucket';
|
||||
for (const row of candidates) {
|
||||
if (
|
||||
operations.observationVisits &&
|
||||
operations.observationVisits % WILDLIFE_WORK_UNIT === 0
|
||||
)
|
||||
yield 'bucket';
|
||||
operations.observationVisits++;
|
||||
if (
|
||||
typeof row?.stableId !== 'string' ||
|
||||
!row.stableId.length ||
|
||||
!validIconPosition(row) ||
|
||||
seen.has(row.stableId)
|
||||
)
|
||||
continue;
|
||||
seen.add(row.stableId);
|
||||
const selected = row.stableId === selectedId;
|
||||
const inView = rowInWildlifeBoxes(row, boxes, 0);
|
||||
if (!selected && !inView) continue;
|
||||
let key = row.stableId;
|
||||
let visible = inView;
|
||||
if (typeof projectRow === 'function') {
|
||||
operations.projections++;
|
||||
const screen = projectRow(row);
|
||||
visible &&=
|
||||
!!screen && Number.isFinite(screen.x) && Number.isFinite(screen.y);
|
||||
if (!visible && !selected) continue;
|
||||
if (visible) {
|
||||
const x = Math.floor(screen.x / WILDLIFE_GRID_TARGET_SPACING_PX);
|
||||
const y = Math.floor(screen.y / WILDLIFE_GRID_TARGET_SPACING_PX);
|
||||
key =
|
||||
Math.abs(x) < 1048576 && Math.abs(y) < 1048576
|
||||
? x * 2097152 + y
|
||||
: `${x}:${y}`;
|
||||
}
|
||||
}
|
||||
if (visible) {
|
||||
sightingCount++;
|
||||
if (row.origin === 'acartia') acartiaCount++;
|
||||
}
|
||||
const incumbent = buckets.get(key);
|
||||
if (
|
||||
!incumbent ||
|
||||
score(row) > score(incumbent) ||
|
||||
(score(row) === score(incumbent) && row.stableId < incumbent.stableId)
|
||||
)
|
||||
buckets.set(key, row);
|
||||
}
|
||||
yield 'rank';
|
||||
const population = [...buckets.values()];
|
||||
const cap = Math.max(selectedId ? 1 : 0, Math.floor(limit));
|
||||
const saturated = population.length > cap;
|
||||
if (saturated)
|
||||
population.sort((a, b) => {
|
||||
operations.rankComparisons++;
|
||||
return score(b) - score(a) || compareWildlifeIds(a.stableId, b.stableId);
|
||||
});
|
||||
onOperations?.(operations);
|
||||
return {
|
||||
rows: saturated ? population.slice(0, cap) : population,
|
||||
saturated,
|
||||
totalPoints: population.length,
|
||||
sightingCount,
|
||||
acartiaCount,
|
||||
};
|
||||
}
|
||||
|
||||
/** Test the padded view in degrees, including across the antimeridian. Null
|
||||
* boxes are the global sample, whose rows all remain candidates. */
|
||||
export function rowInWildlifeBoxes(
|
||||
row,
|
||||
boxes,
|
||||
padding = WILDLIFE_VIEW_PADDING,
|
||||
) {
|
||||
if (!Number.isFinite(row?.lat) || !Number.isFinite(row?.lon)) return false;
|
||||
if (!Array.isArray(boxes)) return true;
|
||||
for (const box of boxes) {
|
||||
const latPad = (box.north - box.south) * padding;
|
||||
const width =
|
||||
box.east >= box.west ? box.east - box.west : 360 - box.west + box.east;
|
||||
const lonPad = width * padding;
|
||||
if (
|
||||
row.lat < Math.max(-90, box.south - latPad) ||
|
||||
row.lat > Math.min(90, box.north + latPad)
|
||||
)
|
||||
continue;
|
||||
const relative = row.lon - box.west;
|
||||
if (relative >= -lonPad && relative <= width + lonPad) return true;
|
||||
if (relative + 360 >= -lonPad && relative + 360 <= width + lonPad)
|
||||
return true;
|
||||
if (relative - 360 >= -lonPad && relative - 360 <= width + lonPad)
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { performance } from 'node:perf_hooks';
|
||||
import test from 'node:test';
|
||||
import { perfBudgetTestOptions } from '../../../scripts/run-perf-tests.mjs';
|
||||
import {
|
||||
harness,
|
||||
syntheticRows,
|
||||
changePositions,
|
||||
WILDLIFE_BENCHMARK_REFRESHES,
|
||||
} from '../../testSupport/wildlifeBillboardModel.mjs';
|
||||
|
||||
// Pure model and incremental reconciliation, measured after warmup.
|
||||
// The 2,000-contact allowance is a fraction of one 60Hz frame; the 5,000 cap
|
||||
// gets a proportional allowance. No renderer, network or real sightings run.
|
||||
const WILDLIFE_MODEL_UPDATE_BUDGET_MS = Object.freeze({
|
||||
500: 4,
|
||||
2000: 8,
|
||||
5000: 20,
|
||||
});
|
||||
test(
|
||||
'500 / 2,000 / 5,000 icon model updates stay within their named timing budgets',
|
||||
perfBudgetTestOptions(),
|
||||
(t) => {
|
||||
// Warm the same pure hot paths before recording CPU time.
|
||||
const warm = harness();
|
||||
let warmRows = syntheticRows(2000);
|
||||
warm.apply(warmRows);
|
||||
for (let i = 0; i < 25; i++) {
|
||||
warmRows = changePositions(warmRows, i);
|
||||
warm.apply(warmRows);
|
||||
}
|
||||
for (const n of [500, 2000, 5000]) {
|
||||
const h = harness();
|
||||
let rows = syntheticRows(n);
|
||||
const start = performance.now();
|
||||
const initial = h.apply(rows);
|
||||
const initialMs = performance.now() - start;
|
||||
assert.equal(initial.created, n);
|
||||
const durations = [];
|
||||
for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
|
||||
rows = changePositions(rows, refresh);
|
||||
const before = performance.now();
|
||||
const update = h.apply(rows);
|
||||
durations.push(performance.now() - before);
|
||||
assert.deepEqual(update, {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: n / 10,
|
||||
writes: n / 10,
|
||||
});
|
||||
}
|
||||
const meanMs =
|
||||
durations.reduce((sum, value) => sum + value, 0) / durations.length;
|
||||
const maxMs = Math.max(...durations);
|
||||
assert.ok(
|
||||
maxMs <= WILDLIFE_MODEL_UPDATE_BUDGET_MS[n],
|
||||
`${n}: ${maxMs.toFixed(3)}ms update exceeds ${WILDLIFE_MODEL_UPDATE_BUDGET_MS[n]}ms`,
|
||||
);
|
||||
const before = { ...h.counters };
|
||||
assert.deepEqual(h.apply([...rows].reverse()), {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: 0,
|
||||
writes: 0,
|
||||
});
|
||||
assert.deepEqual(
|
||||
h.counters,
|
||||
before,
|
||||
'unchanged content performs zero billboard writes or allocations',
|
||||
);
|
||||
t.diagnostic(
|
||||
`N=${n}; initial=${initialMs.toFixed(3)}ms; incremental10% mean=${meanMs.toFixed(3)}ms, max=${maxMs.toFixed(3)}ms; budget=${WILDLIFE_MODEL_UPDATE_BUDGET_MS[n]}ms; unchanged writes=0`,
|
||||
);
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,162 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
wildlifeIconicGroup,
|
||||
rowInWildlifeBoxes,
|
||||
buildWildlifeIconModel,
|
||||
} from './model.js';
|
||||
import { ICONIC_TINTS, ICONIC_LEGEND_ORDER, TAXA_PRESETS } from './policy.js';
|
||||
|
||||
const row = {
|
||||
stableId: 'inat:1',
|
||||
lat: 47.6,
|
||||
lon: -122.3,
|
||||
cell: null,
|
||||
iconic: 'Aves',
|
||||
quality: 'research',
|
||||
count: null,
|
||||
obscured: false,
|
||||
};
|
||||
|
||||
test('unknown groups are slate and molluscs fold into other animals', () => {
|
||||
assert.equal(wildlifeIconicGroup('Mollusca'), 'Animalia');
|
||||
for (const iconic of ['Unknown', 'Protozoa', 'Chromista', undefined])
|
||||
assert.equal(wildlifeIconicGroup(iconic), 'Unknown');
|
||||
assert.equal(ICONIC_TINTS.Unknown, '#9aa7b3');
|
||||
assert.equal(ICONIC_LEGEND_ORDER.at(-1), 'Unknown');
|
||||
assert.equal(ICONIC_LEGEND_ORDER.length, 11);
|
||||
assert.equal(TAXA_PRESETS.length, 6);
|
||||
assert.equal(TAXA_PRESETS.filter((item) => item.label === 'ALL').length, 1);
|
||||
assert.equal(Object.isFrozen(ICONIC_TINTS), true);
|
||||
assert.equal(Object.isFrozen(TAXA_PRESETS[0]), true);
|
||||
});
|
||||
|
||||
test('view filtering includes padding and both sides of the antimeridian', () => {
|
||||
const boxes = [{ south: 47, west: -123, north: 48, east: -122 }];
|
||||
assert.equal(rowInWildlifeBoxes(row, boxes), true);
|
||||
assert.equal(rowInWildlifeBoxes({ ...row, lat: 48.2 }, boxes), true);
|
||||
assert.equal(rowInWildlifeBoxes({ ...row, lat: 48.4 }, boxes), false);
|
||||
assert.equal(
|
||||
rowInWildlifeBoxes({ ...row, lat: 10.5, lon: -179.9 }, [
|
||||
{ south: 10, west: 179, north: 11, east: 180 },
|
||||
]),
|
||||
true,
|
||||
);
|
||||
assert.equal(rowInWildlifeBoxes(row, null), true);
|
||||
assert.equal(rowInWildlifeBoxes(row, []), false);
|
||||
});
|
||||
|
||||
test('grid cells never enter the observation icon model', () => {
|
||||
const cells = [
|
||||
{ id: 'grid:2/0/0:1:1', lat: 47.6, lon: -122.3, cellCount: 999 },
|
||||
];
|
||||
assert.deepEqual(buildWildlifeIconModel({ rows: cells }).rows, []);
|
||||
assert.deepEqual(buildWildlifeIconModel({ rows: [...cells, row] }).rows, [
|
||||
row,
|
||||
]);
|
||||
});
|
||||
|
||||
test('screen buckets retain incumbent photos at their real sighting positions', () => {
|
||||
const incumbent = {
|
||||
...row,
|
||||
commonName: 'Incumbent',
|
||||
photo: { square: 'synthetic.jpg' },
|
||||
};
|
||||
const challenger = {
|
||||
...row,
|
||||
stableId: 'inat:2',
|
||||
commonName: 'Challenger',
|
||||
observedAt: Date.UTC(2026, 10, 4),
|
||||
};
|
||||
const distant = { ...row, stableId: 'inat:3', lon: row.lon + 1 };
|
||||
const model = buildWildlifeIconModel({
|
||||
rows: [challenger, incumbent, distant],
|
||||
preferredIds: [incumbent.stableId],
|
||||
projectRow: (item) => ({ x: (item.lon - row.lon) * 28 + 14, y: 14 }),
|
||||
});
|
||||
assert.deepEqual(model.rows, [incumbent, distant]);
|
||||
assert.equal(model.sightingCount, 3);
|
||||
assert.equal(model.rows[0].photo, incumbent.photo);
|
||||
});
|
||||
|
||||
test('visible observation counts precede per-area and global caps', () => {
|
||||
const rows = Array.from({ length: 6000 }, (_, i) => ({
|
||||
...row,
|
||||
stableId: `inat:${i}`,
|
||||
lon: -160 + i * 0.01,
|
||||
}));
|
||||
let projections = 0;
|
||||
const model = buildWildlifeIconModel({
|
||||
rows,
|
||||
projectRow(item) {
|
||||
projections++;
|
||||
return { x: (item.lon + 160) * 5600 + 14, y: 14 };
|
||||
},
|
||||
});
|
||||
assert.equal(projections, 6000);
|
||||
assert.equal(model.rows.length, 5000);
|
||||
assert.equal(model.totalPoints, 6000);
|
||||
assert.equal(model.saturated, true);
|
||||
assert.equal(model.sightingCount, 6000);
|
||||
});
|
||||
|
||||
test('selected observations win their bucket and survive a sample, viewport and projection change', () => {
|
||||
const selected = { ...row, commonName: 'Selected sighting' };
|
||||
const challenger = {
|
||||
...row,
|
||||
stableId: 'inat:2',
|
||||
commonName: 'Newer',
|
||||
observedAt: Date.UTC(2026, 10, 4),
|
||||
};
|
||||
const input = {
|
||||
selectedId: row.stableId,
|
||||
selectedRow: selected,
|
||||
rows: [challenger],
|
||||
limit: 1,
|
||||
};
|
||||
assert.deepEqual(
|
||||
buildWildlifeIconModel({ ...input, projectRow: () => ({ x: 14, y: 14 }) })
|
||||
.rows,
|
||||
[selected],
|
||||
);
|
||||
const offscreen = buildWildlifeIconModel({
|
||||
...input,
|
||||
boxes: [{ south: 0, west: 0, north: 1, east: 1 }],
|
||||
projectRow: () => null,
|
||||
});
|
||||
assert.deepEqual(offscreen.rows, [selected]);
|
||||
assert.equal(
|
||||
offscreen.sightingCount,
|
||||
0,
|
||||
'an offscreen pin is not a visible observation',
|
||||
);
|
||||
});
|
||||
|
||||
test('observation reduction is stable under input order, selected priority and visible filtering', () => {
|
||||
const named = { ...row, stableId: 'inat:2', commonName: 'Known bird' };
|
||||
const outside = { ...row, stableId: 'inat:3', lat: 0 };
|
||||
const input = {
|
||||
boxes: [{ south: 47, west: -123, north: 48, east: -122 }],
|
||||
limit: 1,
|
||||
};
|
||||
const model = buildWildlifeIconModel({
|
||||
...input,
|
||||
rows: [row, named, outside],
|
||||
});
|
||||
assert.equal(model.saturated, true);
|
||||
assert.equal(model.totalPoints, 2);
|
||||
assert.equal(model.sightingCount, 2);
|
||||
assert.deepEqual(model.rows, [named]);
|
||||
assert.deepEqual(
|
||||
buildWildlifeIconModel({ ...input, rows: [outside, named, row] }),
|
||||
model,
|
||||
);
|
||||
assert.deepEqual(
|
||||
buildWildlifeIconModel({
|
||||
...input,
|
||||
rows: [named, row],
|
||||
selectedId: row.stableId,
|
||||
}).rows,
|
||||
[row],
|
||||
);
|
||||
});
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,115 @@
|
||||
/** Camera work runs on moveEnd/data arrival only. Measures remain observable
|
||||
* through PerformanceObserver while clearing entries prevents a long session
|
||||
* accumulating one timing record for every pan and streamed tile. */
|
||||
export const WILDLIFE_MOVE_END_BUDGET_MS = 4;
|
||||
const measureSpans = new Map();
|
||||
|
||||
function measureSpan(stage) {
|
||||
let span = measureSpans.get(stage);
|
||||
if (!span) {
|
||||
span = { name: `wildlife-sightings:${stage}`, depth: 0, frames: [] };
|
||||
measureSpans.set(stage, span);
|
||||
}
|
||||
const depth = span.depth++;
|
||||
if (!span.frames[depth]) {
|
||||
const start = `${span.name}:start:${depth}`;
|
||||
span.frames[depth] = { start, options: { start } };
|
||||
}
|
||||
return span;
|
||||
}
|
||||
|
||||
/** Measure a render phase without accumulating performance entries. */
|
||||
export function wildlifeMeasure(stage, work) {
|
||||
const clock = globalThis.performance;
|
||||
if (typeof clock?.mark !== 'function' || typeof clock?.measure !== 'function')
|
||||
return work();
|
||||
// Reuse names/options; nesting depth distinguishes simultaneous spans.
|
||||
const span = measureSpan(stage);
|
||||
const frame = span.frames[span.depth - 1];
|
||||
clock.mark(frame.start);
|
||||
try {
|
||||
return work();
|
||||
} finally {
|
||||
clock.measure(span.name, frame.options);
|
||||
clock.clearMarks?.(frame.start);
|
||||
clock.clearMeasures?.(span.name);
|
||||
span.depth--;
|
||||
}
|
||||
}
|
||||
|
||||
// A unit is at most 128 cells/billboards. The one-millisecond target leaves
|
||||
// room for the last unit, Cesium setters and the overlay host within 4ms.
|
||||
export const WILDLIFE_WORK_UNIT = 128;
|
||||
const WILDLIFE_WORK_SLICE_MS = 1;
|
||||
export const WILDLIFE_SYNC_CELL_LIMIT = 256;
|
||||
|
||||
function wildlifeWorkStep(work, stage = 'bucket') {
|
||||
return wildlifeMeasure(stage, () => work.next());
|
||||
}
|
||||
|
||||
/** Run bounded work synchronously for a small population. */
|
||||
export function drainWildlifeWork(work) {
|
||||
let stage = 'bucket';
|
||||
for (;;) {
|
||||
const step = wildlifeWorkStep(work, stage);
|
||||
if (step.done) return step.value;
|
||||
stage = step.value || stage;
|
||||
}
|
||||
}
|
||||
|
||||
/** A cancellable idle queue, never a frame listener. Superseding a camera view
|
||||
* drops unrun work. No network or requestAnimationFrame enters this queue. */
|
||||
export function createWildlifeWorkQueue({
|
||||
requestIdle = globalThis.requestIdleCallback?.bind(globalThis),
|
||||
cancelIdle = globalThis.cancelIdleCallback?.bind(globalThis),
|
||||
now = () => performance.now(),
|
||||
onSlice = () => {},
|
||||
} = {}) {
|
||||
let active = null;
|
||||
function cancel() {
|
||||
if (!active) return;
|
||||
const old = active;
|
||||
active = null;
|
||||
if (requestIdle) cancelIdle?.(old.handle);
|
||||
else clearTimeout(old.handle);
|
||||
old.work.return?.();
|
||||
}
|
||||
function start(work, complete) {
|
||||
cancel();
|
||||
const job = { work, handle: null, stage: 'bucket' };
|
||||
active = job;
|
||||
function schedule() {
|
||||
job.handle = requestIdle
|
||||
? requestIdle(run, { timeout: 32 })
|
||||
: setTimeout(run, 0);
|
||||
}
|
||||
function run() {
|
||||
if (active !== job) return;
|
||||
const began = now();
|
||||
let units = 0;
|
||||
let result;
|
||||
wildlifeMeasure('moveEnd:slice', () => {
|
||||
do {
|
||||
result = wildlifeWorkStep(work, job.stage);
|
||||
units++;
|
||||
if (result.done) {
|
||||
active = null;
|
||||
complete(result.value);
|
||||
break;
|
||||
}
|
||||
job.stage = result.value || job.stage;
|
||||
} while (units < 8 && now() - began < WILDLIFE_WORK_SLICE_MS);
|
||||
});
|
||||
onSlice({ startTimeMs: began, durationMs: now() - began, units });
|
||||
if (!result.done && active === job) schedule();
|
||||
}
|
||||
schedule();
|
||||
}
|
||||
return {
|
||||
start,
|
||||
cancel,
|
||||
get pending() {
|
||||
return active !== null;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,299 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import {
|
||||
harness,
|
||||
syntheticRows,
|
||||
changePositions,
|
||||
WILDLIFE_BENCHMARK_REFRESHES,
|
||||
} from '../../testSupport/wildlifeBillboardModel.mjs';
|
||||
|
||||
test('500 / 2,000 / 5,000 contacts write only position deltas and do no work for unchanged input', () => {
|
||||
for (const n of [500, 2000, 5000]) {
|
||||
const h = harness();
|
||||
let rows = syntheticRows(n);
|
||||
assert.equal(h.apply(rows).created, n);
|
||||
const retained = h.pointById.get(rows[1].stableId);
|
||||
for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
|
||||
rows = changePositions(rows, refresh);
|
||||
assert.deepEqual(h.apply(rows), {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: n / 10,
|
||||
writes: n / 10,
|
||||
});
|
||||
assert.equal(h.pointById.get(rows[1].stableId), retained);
|
||||
}
|
||||
assert.equal(h.counters.created, n);
|
||||
assert.equal(h.counters.destroyed, 0);
|
||||
const before = { ...h.counters };
|
||||
assert.deepEqual(h.apply([...rows].reverse()), {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: 0,
|
||||
writes: 0,
|
||||
});
|
||||
assert.deepEqual(
|
||||
h.counters,
|
||||
before,
|
||||
'unchanged content writes and allocates nothing',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('ten 10% membership refreshes allocate and remove exactly their delta', (t) => {
|
||||
const n = 2000;
|
||||
const h = harness();
|
||||
let rows = syntheticRows(n);
|
||||
h.apply(rows);
|
||||
const retainedId = rows[1].stableId;
|
||||
const retained = h.pointById.get(retainedId);
|
||||
for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
|
||||
rows = rows.map((row, i) =>
|
||||
i % 10 === 0 ? { ...row, stableId: `replacement:${refresh}:${i}` } : row,
|
||||
);
|
||||
assert.deepEqual(h.apply(rows), {
|
||||
created: n / 10,
|
||||
removed: n / 10,
|
||||
updated: 0,
|
||||
writes: (n / 10) * 5,
|
||||
});
|
||||
assert.equal(h.pointById.get(retainedId), retained);
|
||||
assert.equal(h.points.size, n);
|
||||
}
|
||||
assert.equal(h.counters.created, n + (n / 10) * WILDLIFE_BENCHMARK_REFRESHES);
|
||||
assert.equal(h.counters.destroyed, (n / 10) * WILDLIFE_BENCHMARK_REFRESHES);
|
||||
t.diagnostic(
|
||||
`N=${n}, 10 refreshes: initial creates=${n}, delta creates=2000, delta removes=2000, retained billboard identity unchanged`,
|
||||
);
|
||||
});
|
||||
|
||||
test('count, grade and name edits produce no billboard writes or resampling', () => {
|
||||
const h = harness();
|
||||
const rows = syntheticRows(500);
|
||||
h.model.update(rows);
|
||||
const before = { ...h.counters };
|
||||
assert.deepEqual(
|
||||
h.model.update(
|
||||
rows.map((row) => ({
|
||||
...row,
|
||||
count: 1000,
|
||||
quality: 'needs_id',
|
||||
commonName: 'Synthetic name',
|
||||
})),
|
||||
),
|
||||
{ created: 0, removed: 0, updated: 0, writes: 0 },
|
||||
);
|
||||
assert.deepEqual(h.counters, before);
|
||||
});
|
||||
|
||||
import { PerformanceObserver } from 'node:perf_hooks';
|
||||
import {
|
||||
denseContinentalRendering,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
DENSE_CONTINENT_ROWS,
|
||||
} from './renderPerformanceFixtures.mjs';
|
||||
import {
|
||||
WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
WILDLIFE_WORK_UNIT,
|
||||
createWildlifeWorkQueue,
|
||||
} from './performance.js';
|
||||
|
||||
test('dense continental moveEnd has a deterministic linear operation budget and reuses decoded metadata/coordinates', () => {
|
||||
const h = denseContinentalRendering();
|
||||
try {
|
||||
assert.equal(
|
||||
h.moveEnd(),
|
||||
'pending',
|
||||
'dense work must yield before blocking camera input',
|
||||
);
|
||||
assert.equal(
|
||||
h.metrics.projections,
|
||||
0,
|
||||
'moveEnd enqueues work without processing a tile',
|
||||
);
|
||||
const cold = h.flush();
|
||||
assert.ok(
|
||||
cold.glowPrimitives > 4000 &&
|
||||
cold.billboards > 50 &&
|
||||
cold.billboards <= DENSE_CONTINENT_ROWS,
|
||||
'benchmark exercises a dense glow with only real sampled sighting badges',
|
||||
);
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.densityVisits,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
);
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.densityMetadataBuilds,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
);
|
||||
assert.ok(cold.slices.length > 1);
|
||||
for (let move = 1; move <= 4; move++) {
|
||||
h.moveEnd(move * 3);
|
||||
const result = h.flush();
|
||||
const ops = h.state.renderPipelineOperations;
|
||||
assert.equal(ops.densityVisits, DENSE_CONTINENT_CELLS);
|
||||
assert.equal(ops.observationVisits, DENSE_CONTINENT_ROWS);
|
||||
assert.equal(ops.densityMetadataBuilds, 0);
|
||||
assert.equal(ops.densityWrites, 0);
|
||||
assert.equal(ops.densityPositionBuilds, 0);
|
||||
assert.ok(ops.densityRetirementVisits <= DENSE_CONTINENT_CELLS);
|
||||
assert.equal(ops.densityCreated, 0);
|
||||
assert.equal(ops.densityRemoved, 0);
|
||||
assert.equal(
|
||||
result.cartesianBuilds,
|
||||
0,
|
||||
'no repeated longitude/latitude trig per camera pass',
|
||||
);
|
||||
assert.ok(ops.projections <= DENSE_CONTINENT_ROWS);
|
||||
assert.ok(result.projections <= DENSE_CONTINENT_ROWS + 150);
|
||||
assert.ok(
|
||||
ops.billboardVisits <= result.billboards * 3 + WILDLIFE_WORK_UNIT,
|
||||
);
|
||||
assert.equal(
|
||||
ops.rankComparisons,
|
||||
0,
|
||||
'continental buckets never sort the source population',
|
||||
);
|
||||
assert.ok(ops.spacingTests <= result.billboards * 9);
|
||||
assert.ok(result.slices.length <= 144);
|
||||
assert.ok(result.slices.every((slice) => slice.units <= 8));
|
||||
assert.equal(
|
||||
result.publications,
|
||||
3,
|
||||
'publish overlays once after the accepted view is ready',
|
||||
);
|
||||
}
|
||||
h.moveEnd(12);
|
||||
h.flush();
|
||||
assert.equal(h.state.renderPipelineOperations.billboardWrites, 0);
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.billboardVisits,
|
||||
h.state.renderedRows.length * 2,
|
||||
'the delta owner scans each row and retained billboard once',
|
||||
);
|
||||
} finally {
|
||||
h.destroy();
|
||||
}
|
||||
});
|
||||
|
||||
test('superseded dense camera work is dropped and idle callbacks are removed at teardown', () => {
|
||||
const h = denseContinentalRendering();
|
||||
assert.equal(h.moveEnd(0), 'pending');
|
||||
assert.equal(h.moveEnd(12), 'pending');
|
||||
const result = h.flush();
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.densityVisits,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
);
|
||||
assert.equal(result.publications, 3);
|
||||
assert.equal(h.moveEnd(24), 'pending');
|
||||
h.destroy();
|
||||
assert.equal(h.flush().slices.length, 0);
|
||||
});
|
||||
|
||||
test('performance marks cover each render phase and leave no accumulated entries', async () => {
|
||||
const observed = [];
|
||||
const observer = new PerformanceObserver((list) =>
|
||||
observed.push(...list.getEntries()),
|
||||
);
|
||||
observer.observe({ entryTypes: ['measure'] });
|
||||
const h = denseContinentalRendering();
|
||||
try {
|
||||
h.moveEnd();
|
||||
h.flush();
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (const phase of [
|
||||
'density',
|
||||
'bucket',
|
||||
'rank',
|
||||
'billboard-update',
|
||||
'overlay-publish',
|
||||
'moveEnd:slice',
|
||||
])
|
||||
assert.ok(
|
||||
observed.some((entry) => entry.name === `wildlife-sightings:${phase}`),
|
||||
phase,
|
||||
);
|
||||
assert.deepEqual(
|
||||
performance
|
||||
.getEntriesByType('mark')
|
||||
.filter((entry) => entry.name.startsWith('wildlife-sightings:')),
|
||||
[],
|
||||
);
|
||||
assert.deepEqual(
|
||||
performance
|
||||
.getEntriesByType('measure')
|
||||
.filter((entry) => entry.name.startsWith('wildlife-sightings:')),
|
||||
[],
|
||||
);
|
||||
assert.equal(WILDLIFE_MOVE_END_BUDGET_MS, 4);
|
||||
} finally {
|
||||
observer.disconnect();
|
||||
h.destroy();
|
||||
}
|
||||
});
|
||||
|
||||
test('idle work has a fixed unit ceiling even when the clock does not advance', () => {
|
||||
const callbacks = new Map();
|
||||
let id = 0;
|
||||
let slices = 0;
|
||||
let done = false;
|
||||
const queue = createWildlifeWorkQueue({
|
||||
requestIdle(fn) {
|
||||
callbacks.set(++id, fn);
|
||||
return id;
|
||||
},
|
||||
cancelIdle(handle) {
|
||||
callbacks.delete(handle);
|
||||
},
|
||||
now: () => 0,
|
||||
onSlice({ units }) {
|
||||
assert.ok(units <= 8);
|
||||
slices++;
|
||||
},
|
||||
});
|
||||
function* work() {
|
||||
for (let i = 0; i < 20; i++) yield 'bucket';
|
||||
return 42;
|
||||
}
|
||||
queue.start(work(), (result) => {
|
||||
assert.equal(result, 42);
|
||||
done = true;
|
||||
});
|
||||
assert.equal(done, false);
|
||||
while (callbacks.size) {
|
||||
const [handle, fn] = callbacks.entries().next().value;
|
||||
callbacks.delete(handle);
|
||||
fn();
|
||||
}
|
||||
assert.equal(done, true);
|
||||
assert.equal(slices, 3);
|
||||
assert.equal(queue.pending, false);
|
||||
});
|
||||
|
||||
test('returning to a previous camera after partially applying a billboard delta still reconciles the collection', (t) => {
|
||||
// Slices end after eight units or 1 ms. A clock that advances 2 ms per read
|
||||
// makes every slice one unit, so the half-applied delta is observable.
|
||||
let clock = 0;
|
||||
t.mock.method(performance, 'now', () => (clock += 2));
|
||||
const h = denseContinentalRendering();
|
||||
try {
|
||||
h.moveEnd(0);
|
||||
h.flush();
|
||||
const originalIds = [...h.state.pointById.keys()].sort();
|
||||
const membership = () => [...h.state.pointById.keys()].sort();
|
||||
h.moveEnd(12);
|
||||
// Advance just until real billboard mutations begin, then supersede the
|
||||
// partially applied view by returning to the original camera.
|
||||
for (let i = 0; i < 5000; i++) {
|
||||
h.flush(1);
|
||||
if (JSON.stringify(membership()) !== JSON.stringify(originalIds)) break;
|
||||
}
|
||||
assert.notDeepEqual(membership(), originalIds);
|
||||
h.moveEnd(0);
|
||||
h.flush();
|
||||
assert.deepEqual(membership(), originalIds);
|
||||
} finally {
|
||||
h.destroy();
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,36 @@
|
||||
import { t } from '../../i18n/index.js';
|
||||
|
||||
/** Compact card ages in translated minutes, hours or days. */
|
||||
export function formatAge(deltaMs) {
|
||||
if (!Number.isFinite(deltaMs) || deltaMs < 0) return null;
|
||||
const hours = Math.floor(deltaMs / 3_600_000);
|
||||
if (hours < 1)
|
||||
return t('{count}m', {
|
||||
context: 'age',
|
||||
count: Math.max(1, Math.floor(deltaMs / 60_000)),
|
||||
});
|
||||
if (hours < 24) return t('{count}h', { context: 'age', count: hours });
|
||||
return t('{count}d', { context: 'age', count: Math.floor(hours / 24) });
|
||||
}
|
||||
|
||||
/** Use the creator portion of the supplied attribution, never a guessed
|
||||
* observer/login. iNaturalist appends rights and licence text after it. */
|
||||
export function photoCreator(photo) {
|
||||
if (typeof photo?.attribution !== 'string') return null;
|
||||
const creator = photo.attribution
|
||||
.replace(/^\s*(?:\(c\)|©|copyright)\s*/i, '')
|
||||
.replace(/,\s*(?:some|no|all)\s+rights\s+reserved\b.*$/i, '')
|
||||
.replace(
|
||||
/(?:,\s*|\s*\()(?:CC[\s-]+BY(?:[\s-]+(?:NC|SA|ND))*|CC0|public\s+domain)(?:\s+\d(?:\.\d)?)?\)?\s*$/i,
|
||||
'',
|
||||
)
|
||||
.trim();
|
||||
if (
|
||||
!creator ||
|
||||
/^(?:(?:some|no|all)\s+rights\s+reserved\b|CC(?:0|[\s-]+BY)\b)/i.test(
|
||||
creator,
|
||||
)
|
||||
)
|
||||
return null;
|
||||
return creator;
|
||||
}
|
||||
@@ -0,0 +1,183 @@
|
||||
import { ambientScore } from './cards.js';
|
||||
import { compareWildlifeIds } from './model.js';
|
||||
import { WILDLIFE_PHOTO_FETCH, WILDLIFE_PHOTO_CACHE_MAX } from './policy.js';
|
||||
|
||||
/** Own decoded ambient images and their cancellable, ranked queue. */
|
||||
export function createPhotoSlots({
|
||||
imageFactory = () => new Image(),
|
||||
now = () => Date.now(),
|
||||
setTimer = (fn, delay) => setTimeout(fn, delay),
|
||||
clearTimer = (timer) => clearTimeout(timer),
|
||||
onChange = null,
|
||||
} = {}) {
|
||||
const slots = new Map();
|
||||
let queue = [];
|
||||
let timer = null;
|
||||
let destroyed = false;
|
||||
let liveKeys = new Set();
|
||||
let cohortKey = null;
|
||||
|
||||
function notify() {
|
||||
if (!destroyed) onChange?.();
|
||||
}
|
||||
|
||||
function release(slot) {
|
||||
slot.cancelled = true;
|
||||
if (!slot.image) return;
|
||||
slot.image.onload = null;
|
||||
slot.image.onerror = null;
|
||||
// Detaching listeners alone would leave pending network and decoded data.
|
||||
slot.image.src = '';
|
||||
}
|
||||
|
||||
function prune() {
|
||||
if (slots.size <= WILDLIFE_PHOTO_CACHE_MAX) return;
|
||||
const ranked = [...slots].sort(([a, slotA], [b, slotB]) => {
|
||||
const keepA = liveKeys.has(a);
|
||||
const keepB = liveKeys.has(b);
|
||||
const frameA = slotA.displayed;
|
||||
const frameB = slotB.displayed;
|
||||
// Decoded photographs that have actually been painted outrank unseen
|
||||
// prefetches. Preserve their Image objects for a flash-free return pan.
|
||||
return Number(keepA) - Number(keepB) || Number(frameA) - Number(frameB);
|
||||
});
|
||||
for (const [key, slot] of ranked) {
|
||||
if (slots.size <= WILDLIFE_PHOTO_CACHE_MAX) break;
|
||||
release(slot);
|
||||
slots.delete(key);
|
||||
}
|
||||
}
|
||||
|
||||
function ensure(row) {
|
||||
const url = row?.photo?.square;
|
||||
if (!url) return null;
|
||||
const key = row.stableId;
|
||||
let slot = slots.get(key);
|
||||
if (slot && slot.url !== url) {
|
||||
release(slot);
|
||||
slots.delete(key);
|
||||
slot = null;
|
||||
}
|
||||
if (!slot) {
|
||||
slot = {
|
||||
key,
|
||||
url,
|
||||
image: null,
|
||||
state: 'queued',
|
||||
cancelled: false,
|
||||
displayed: false,
|
||||
};
|
||||
} else slots.delete(key);
|
||||
slots.set(key, slot);
|
||||
return slot;
|
||||
}
|
||||
|
||||
function launch(slot) {
|
||||
if (
|
||||
destroyed ||
|
||||
slot.cancelled ||
|
||||
slots.get(slot.key) !== slot ||
|
||||
slot.state !== 'queued'
|
||||
)
|
||||
return;
|
||||
slot.state = 'loading';
|
||||
let image;
|
||||
try {
|
||||
image = imageFactory();
|
||||
slot.image = image;
|
||||
// Deliberately non-CORS: the overlay canvas is display-only and is
|
||||
// never read back. Viewport capture reads the separate Cesium canvas.
|
||||
image.onload = () => {
|
||||
if (destroyed || slot.cancelled || slots.get(slot.key) !== slot) return;
|
||||
slot.state = 'ready';
|
||||
image.onload = null;
|
||||
image.onerror = null;
|
||||
notify();
|
||||
};
|
||||
image.onerror = () => {
|
||||
if (destroyed || slot.cancelled || slots.get(slot.key) !== slot) return;
|
||||
slot.state = 'error';
|
||||
image.onload = null;
|
||||
image.onerror = null;
|
||||
notify();
|
||||
};
|
||||
image.src = slot.url;
|
||||
} catch {
|
||||
slot.state = 'error';
|
||||
notify();
|
||||
}
|
||||
}
|
||||
|
||||
function pace() {
|
||||
timer = null;
|
||||
if (destroyed) return;
|
||||
while (queue.length) {
|
||||
const slot = queue.shift();
|
||||
if (slot.cancelled || slots.get(slot.key) !== slot) continue;
|
||||
launch(slot);
|
||||
break;
|
||||
}
|
||||
if (queue.length) timer = setTimer(pace, WILDLIFE_PHOTO_FETCH.intervalMs);
|
||||
}
|
||||
|
||||
function setAmbient(rows) {
|
||||
if (destroyed) return;
|
||||
const ranked = [...rows].sort(
|
||||
(a, b) =>
|
||||
ambientScore(b, now()) - ambientScore(a, now()) ||
|
||||
compareWildlifeIds(a.stableId, b.stableId),
|
||||
);
|
||||
const nextKey = JSON.stringify(
|
||||
ranked.map((row) => [row.stableId, row.photo?.square]),
|
||||
);
|
||||
// A same-cohort refresh must not turn the paced tail into another burst.
|
||||
if (cohortKey === nextKey) return;
|
||||
cohortKey = nextKey;
|
||||
clearTimer(timer);
|
||||
timer = null;
|
||||
liveKeys = new Set(ranked.map((row) => row.stableId));
|
||||
queue = ranked.map(ensure).filter(Boolean);
|
||||
prune();
|
||||
queue = queue.filter(
|
||||
(slot) => slots.get(slot.key) === slot && slot.state === 'queued',
|
||||
);
|
||||
for (
|
||||
let index = 0;
|
||||
index < WILDLIFE_PHOTO_FETCH.burst && queue.length;
|
||||
index++
|
||||
)
|
||||
launch(queue.shift());
|
||||
if (queue.length) timer = setTimer(pace, WILDLIFE_PHOTO_FETCH.intervalMs);
|
||||
}
|
||||
|
||||
function get(row) {
|
||||
const key = row?.stableId;
|
||||
const slot = slots.get(key);
|
||||
if (!slot || slot.state !== 'ready') return null;
|
||||
slot.displayed = true;
|
||||
slots.delete(key);
|
||||
slots.set(key, slot);
|
||||
return slot.image;
|
||||
}
|
||||
|
||||
function clear() {
|
||||
clearTimer(timer);
|
||||
timer = null;
|
||||
queue = [];
|
||||
for (const slot of slots.values()) release(slot);
|
||||
slots.clear();
|
||||
liveKeys.clear();
|
||||
cohortKey = null;
|
||||
}
|
||||
|
||||
return {
|
||||
setAmbient,
|
||||
get,
|
||||
clear,
|
||||
destroy() {
|
||||
destroyed = true;
|
||||
clear();
|
||||
},
|
||||
diagnostics: () => ({ slots: slots.size, queued: queue.length }),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,147 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { createPhotoSlots } from './photos.js';
|
||||
|
||||
function clock() {
|
||||
let time = 0;
|
||||
let next = 0;
|
||||
const timers = new Map();
|
||||
return {
|
||||
now: () => time,
|
||||
setTimer(fn, delay) {
|
||||
const id = ++next;
|
||||
timers.set(id, { fn, at: time + delay });
|
||||
return id;
|
||||
},
|
||||
clearTimer(id) {
|
||||
timers.delete(id);
|
||||
},
|
||||
tick(ms) {
|
||||
const until = time + ms;
|
||||
while (true) {
|
||||
const pending = [...timers].sort((a, b) => a[1].at - b[1].at)[0];
|
||||
if (!pending || pending[1].at > until) break;
|
||||
time = pending[1].at;
|
||||
timers.delete(pending[0]);
|
||||
pending[1].fn();
|
||||
}
|
||||
time = until;
|
||||
},
|
||||
count: () => timers.size,
|
||||
};
|
||||
}
|
||||
|
||||
const row = (index) => ({
|
||||
stableId: `inat:${index}`,
|
||||
quality: 'research',
|
||||
observedAt: 0,
|
||||
favesCount: 100 - index,
|
||||
identificationAgreements: 0,
|
||||
photo: {
|
||||
square: `https://inaturalist-open-data.s3.amazonaws.com/photos/${index}/square.jpg`,
|
||||
medium: `https://inaturalist-open-data.s3.amazonaws.com/photos/${index}/medium.jpg`,
|
||||
licence: 'cc-by',
|
||||
attribution: '(c) Synthetic Photographer',
|
||||
},
|
||||
});
|
||||
|
||||
function harness() {
|
||||
const time = clock();
|
||||
const launches = [];
|
||||
const images = [];
|
||||
let changes = 0;
|
||||
const slots = createPhotoSlots({
|
||||
...time,
|
||||
onChange: () => changes++,
|
||||
imageFactory: () => {
|
||||
const image = {
|
||||
set src(url) {
|
||||
this.url = url;
|
||||
if (url) launches.push({ at: time.now(), url });
|
||||
},
|
||||
};
|
||||
images.push(image);
|
||||
return image;
|
||||
},
|
||||
});
|
||||
return { slots, time, images, launches, changes: () => changes };
|
||||
}
|
||||
|
||||
test('24 photos start in rank order: eight immediately, then one per 250 ms', () => {
|
||||
const h = harness();
|
||||
const rows = Array.from({ length: 24 }, (_, index) => row(index + 1));
|
||||
h.slots.setAmbient([...rows].reverse());
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(249);
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(1);
|
||||
assert.equal(h.launches.length, 9);
|
||||
h.time.tick(3750);
|
||||
assert.equal(h.launches.length, 24);
|
||||
assert.deepEqual(
|
||||
h.launches.map(({ url }) => Number(url.match(/photos\/(\d+)/)[1])),
|
||||
rows.map((_, index) => index + 1),
|
||||
);
|
||||
assert.deepEqual(
|
||||
h.launches.slice(8).map(({ at }) => at),
|
||||
Array.from({ length: 16 }, (_, i) => (i + 1) * 250),
|
||||
);
|
||||
h.slots.destroy();
|
||||
});
|
||||
|
||||
test('same-cohort refresh keeps the ambient queue pacing without restarting its burst', () => {
|
||||
const h = harness();
|
||||
const rows = Array.from({ length: 24 }, (_, i) => row(i + 1));
|
||||
h.slots.setAmbient(rows);
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(100);
|
||||
h.slots.setAmbient(rows);
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(150);
|
||||
assert.equal(h.launches.length, 9);
|
||||
assert.ok(h.launches.every(({ url }) => /square.jpg$/.test(url)));
|
||||
h.slots.destroy();
|
||||
});
|
||||
|
||||
test('images settle through slots, are pruned to 96, and late loads cannot publish after clear', () => {
|
||||
const h = harness();
|
||||
h.slots.setAmbient([row(1)]);
|
||||
const loaded = h.images[0];
|
||||
loaded.onload();
|
||||
assert.equal(h.slots.get(row(1)), loaded);
|
||||
assert.equal(h.changes(), 1);
|
||||
for (let index = 2; index <= 130; index++) h.slots.setAmbient([row(index)]);
|
||||
assert.equal(h.slots.diagnostics().slots, 96);
|
||||
const last = h.images.at(-1);
|
||||
const late = last.onload;
|
||||
h.slots.clear();
|
||||
late();
|
||||
assert.equal(h.changes(), 1);
|
||||
assert.equal(h.slots.diagnostics().slots, 0);
|
||||
assert.equal(h.time.count(), 0);
|
||||
assert.ok(h.images.every((image) => image.url === ''));
|
||||
});
|
||||
|
||||
test('returning cards reuse their decoded frame after a pan or height-band hide', () => {
|
||||
const h = harness();
|
||||
const first = row(1);
|
||||
h.slots.setAmbient([first]);
|
||||
const frame = h.images[0];
|
||||
frame.onload();
|
||||
assert.equal(h.slots.get(first), frame);
|
||||
h.slots.setAmbient([]);
|
||||
h.slots.setAmbient([row(2)]);
|
||||
h.images[1].onload();
|
||||
for (let index = 3; index < 105; index++) h.slots.setAmbient([row(index)]);
|
||||
h.slots.setAmbient([first]);
|
||||
assert.equal(
|
||||
h.slots.get(first),
|
||||
frame,
|
||||
'the returning image is already ready, with no empty frame',
|
||||
);
|
||||
assert.equal(
|
||||
h.launches.filter(({ url }) => url.includes('/photos/1/')).length,
|
||||
1,
|
||||
);
|
||||
h.slots.destroy();
|
||||
});
|
||||
@@ -0,0 +1,145 @@
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
|
||||
export const WILDLIFE_UNKNOWN_COLOR = '#9aa7b3';
|
||||
export const WILDLIFE_ACCENT = '#7bd88f';
|
||||
export const ICONIC_TINTS = Object.freeze({
|
||||
Aves: '#9fa8ff',
|
||||
Mammalia: '#e0a96d',
|
||||
Reptilia: '#c5d86d',
|
||||
Amphibia: '#5fd3bc',
|
||||
Actinopterygii: '#6fa8dc',
|
||||
Insecta: '#f0b35a',
|
||||
Arachnida: '#d98c6a',
|
||||
Plantae: WILDLIFE_ACCENT,
|
||||
Fungi: '#e8a0a8',
|
||||
Animalia: '#b0bec5',
|
||||
Unknown: WILDLIFE_UNKNOWN_COLOR,
|
||||
});
|
||||
|
||||
export const ICONIC_LEGEND_ORDER = Object.freeze([
|
||||
'Aves',
|
||||
'Mammalia',
|
||||
'Reptilia',
|
||||
'Amphibia',
|
||||
'Actinopterygii',
|
||||
'Insecta',
|
||||
'Arachnida',
|
||||
'Plantae',
|
||||
'Fungi',
|
||||
'Animalia',
|
||||
'Unknown',
|
||||
]);
|
||||
|
||||
// Keep badges compact among dense anchors, labels and photo cards.
|
||||
export const WILDLIFE_SCALE_BY_DISTANCE = Object.freeze([
|
||||
1_000, 1.1, 8_000_000, 0.6,
|
||||
]);
|
||||
export const WILDLIFE_SPRITE_PX = 20;
|
||||
export const WILDLIFE_BADGE_MAX_PX =
|
||||
WILDLIFE_SPRITE_PX * WILDLIFE_SCALE_BY_DISTANCE[1];
|
||||
|
||||
export const WILDLIFE_GRID_HEIGHT_METERS = 400_000;
|
||||
// Bound billboard population after screen bucketing.
|
||||
export const WILDLIFE_RENDER_LIMIT = 5_000;
|
||||
// Bound candidates before the overlay host's final declutter.
|
||||
export const WILDLIFE_LABEL_LIMIT = 150;
|
||||
export const WILDLIFE_LABEL_NAME_SEPARATION_PX = 80;
|
||||
// Hidden ground batches may need several render passes to compile. Retire a
|
||||
// failed staging batch after a bounded number instead of holding rendering.
|
||||
export const WILDLIFE_GROUND_READY_MAX_CHECKS = 16;
|
||||
|
||||
// Camera-height thresholds use +/-10% hysteresis to keep representations still
|
||||
// while a camera settles near a boundary.
|
||||
export const WILDLIFE_HEIGHT_HYSTERESIS = 0.1;
|
||||
export const WILDLIFE_HEIGHT_BANDS = Object.freeze({
|
||||
global: 3_000_000,
|
||||
cells: 1_500_000,
|
||||
cards: 400_000,
|
||||
});
|
||||
export const WILDLIFE_MAX_ROWS = 2_000;
|
||||
export const WILDLIFE_CARD_LIMIT = 24;
|
||||
export const WILDLIFE_CARD_MIN_SEP_PX = 112;
|
||||
export const WILDLIFE_CARD_REGION_COLUMNS = 4;
|
||||
export const WILDLIFE_CARD_REGION_ROWS = 3;
|
||||
export const WILDLIFE_PHOTO_CACHE_MAX = 96;
|
||||
|
||||
// Static S3 thumbnails do not spend the API quota.
|
||||
export const WILDLIFE_PHOTO_FETCH = Object.freeze({
|
||||
burst: 8,
|
||||
intervalMs: 250,
|
||||
});
|
||||
|
||||
export const WILDLIFE_DEBOUNCE_MS = 600;
|
||||
export { WILDLIFE_MAX_VIEW_DEGREES } from './bounds.js';
|
||||
export const WILDLIFE_VIEW_PADDING = 0.3;
|
||||
export const WILDLIFE_RETRY_MIN_MS = 30_000;
|
||||
export const WILDLIFE_RETRY_MAX_MS = 240_000;
|
||||
// Cap a Retry-After so one reply can never stall refresh forever. The proxy's
|
||||
// daily-budget reply waits until the next UTC midnight, so allow one day.
|
||||
export const WILDLIFE_RETRY_AFTER_MAX_SEC = 86_400;
|
||||
|
||||
// Faster polling would reread the proxy's five-minute cache.
|
||||
export const WILDLIFE_UPDATE_INTERVAL_MS = 5 * 60_000;
|
||||
|
||||
export const WILDLIFE_CARD_SCALE_FULL_METERS = 20_000;
|
||||
export const WILDLIFE_CARD_SCALE_MID_METERS = 120_000;
|
||||
export const WILDLIFE_CARD_SCALE_END_METERS = 125_000;
|
||||
// Separate entry and exit thresholds prevent churn during small zooms.
|
||||
export const WILDLIFE_CARD_SHOW_MAX_METERS = 110_000;
|
||||
export const WILDLIFE_CARD_HIDE_MAX_METERS = 125_000;
|
||||
export const WILDLIFE_CARD_FADE_LOW_METERS = 70_000;
|
||||
export const WILDLIFE_CARD_FADE_HIGH_METERS = 125_000;
|
||||
export const WILDLIFE_SELECTED_LABEL_MAX_CHARS = 40;
|
||||
export const WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS = 250_000;
|
||||
export const WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS = 400_000;
|
||||
export const WILDLIFE_CARD_MAX_DISTANCE_METERS = 600_000;
|
||||
export const WILDLIFE_CARD_ALTITUDE_SCALE = Object.freeze({
|
||||
fullEnd: WILDLIFE_CARD_SCALE_FULL_METERS,
|
||||
midEnd: WILDLIFE_CARD_SCALE_MID_METERS,
|
||||
end: WILDLIFE_CARD_SCALE_END_METERS,
|
||||
midValue: 0.9,
|
||||
endValue: 0.85,
|
||||
smoothToMid: true,
|
||||
});
|
||||
|
||||
export { ACARTIA_GUARD_BOX } from './acartiaTaxa.js';
|
||||
export const WILDLIFE_CONFIRMED_CHIP_ID = 'quality-confirmed';
|
||||
|
||||
export const TAXA_PRESETS = Object.freeze([
|
||||
Object.freeze({
|
||||
value: 'all',
|
||||
id: 'taxa-all',
|
||||
label: msg('ALL'),
|
||||
title: msg('Show all taxa'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Aves',
|
||||
id: 'taxa-birds',
|
||||
label: msg('BIRDS'),
|
||||
title: msg('Show only birds'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Mammalia',
|
||||
id: 'taxa-mammals',
|
||||
label: msg('MAMMALS'),
|
||||
title: msg('Show only mammals'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'whales',
|
||||
id: 'taxa-whales',
|
||||
label: msg('WHALES'),
|
||||
title: msg('Show only whales and dolphins (7 days)'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Insecta',
|
||||
id: 'taxa-insects',
|
||||
label: msg('INSECTS'),
|
||||
title: msg('Show only insects'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Plantae',
|
||||
id: 'taxa-plants',
|
||||
label: msg('PLANTS'),
|
||||
title: msg('Show only plants'),
|
||||
}),
|
||||
]);
|
||||
@@ -0,0 +1,341 @@
|
||||
// The server imports this module. Keep the projection independent of Cesium,
|
||||
// DOM and the translation catalog, and never copy an upstream record wholesale.
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
import { acartiaSpeciesGroup, inAcartiaCoverage } from './acartiaTaxa.js';
|
||||
|
||||
const OPEN_PHOTO_LICENCES = Object.freeze([
|
||||
'cc0',
|
||||
'cc-by',
|
||||
'cc-by-sa',
|
||||
'cc-by-nc',
|
||||
'cc-by-nc-sa',
|
||||
]);
|
||||
|
||||
const DAY_MS = 86_400_000;
|
||||
const ACARTIA_MAX_AGE_MS = 8 * DAY_MS;
|
||||
const OBSERVATION_FUTURE_TOLERANCE_MS = 10 * 60_000;
|
||||
// A JavaScript $ can match before a final newline; require the true end too.
|
||||
const INAT_PHOTO =
|
||||
/^https:\/\/inaturalist-open-data\.s3\.amazonaws\.com\/photos\/\d+\/square\.(jpe?g|png)$(?![\s\S])/i;
|
||||
const INAT_OBSERVATION =
|
||||
/^https:\/\/www\.inaturalist\.org\/observations\/\d+$(?![\s\S])/;
|
||||
|
||||
/** Accept only canonical iNaturalist observation pages, without URL suffixes. */
|
||||
function inatObservationUri(value) {
|
||||
return typeof value === 'string' && INAT_OBSERVATION.test(value)
|
||||
? value
|
||||
: null;
|
||||
}
|
||||
|
||||
function cleanText(value, maxLength) {
|
||||
if (typeof value !== 'string') return null;
|
||||
const text = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim();
|
||||
return text ? text.slice(0, maxLength) : null;
|
||||
}
|
||||
|
||||
function numberOrNull(value) {
|
||||
if (typeof value !== 'number' && typeof value !== 'string') return null;
|
||||
if (typeof value === 'string' && !value.trim()) return null;
|
||||
const number = Number(value);
|
||||
return Number.isFinite(number) ? number : null;
|
||||
}
|
||||
|
||||
function validPosition(lat, lon) {
|
||||
return (
|
||||
Number.isFinite(lat) &&
|
||||
Math.abs(lat) <= 90 &&
|
||||
Number.isFinite(lon) &&
|
||||
Math.abs(lon) <= 180
|
||||
);
|
||||
}
|
||||
|
||||
function dateOnly(value) {
|
||||
if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
|
||||
return null;
|
||||
const time = Date.parse(value);
|
||||
return Number.isFinite(time) &&
|
||||
new Date(time).toISOString().slice(0, 10) === value
|
||||
? value
|
||||
: null;
|
||||
}
|
||||
|
||||
/** Date-only records cannot prove a time within a partly expired cutoff day.
|
||||
* Use its start conservatively, including for privacy-preserving cached cells. */
|
||||
function withinObservationWindow(observedAt, observedOn, nowMs, windowMs) {
|
||||
const time = Number.isFinite(observedAt)
|
||||
? observedAt
|
||||
: dateOnly(observedOn)
|
||||
? Date.parse(`${observedOn}T00:00:00Z`)
|
||||
: NaN;
|
||||
return (
|
||||
Number.isFinite(time) &&
|
||||
Number.isFinite(nowMs) &&
|
||||
Number.isFinite(windowMs) &&
|
||||
windowMs >= 0 &&
|
||||
time >= nowMs - windowMs &&
|
||||
time <= nowMs + OBSERVATION_FUTURE_TOLERANCE_MS
|
||||
);
|
||||
}
|
||||
|
||||
/** Apply the displayed observation window to projected and retained LRU rows. */
|
||||
export function isRecentWildlifeSighting(row, nowMs, taxa = 'all') {
|
||||
return withinObservationWindow(
|
||||
row?.observedAt,
|
||||
row?.observedOn,
|
||||
nowMs,
|
||||
(taxa === 'whales' ? 7 : 2) * DAY_MS,
|
||||
);
|
||||
}
|
||||
|
||||
/** Strictly parse the two documented Acartia forms. A timezone-free SQL-style
|
||||
* value is UTC; ISO timestamps must carry a timezone rather than using the host's. */
|
||||
export function parseAcartiaTime(value) {
|
||||
if (typeof value !== 'string') return null;
|
||||
const text = value.trim();
|
||||
const sql = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(text);
|
||||
const iso =
|
||||
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/i.test(
|
||||
text,
|
||||
);
|
||||
if (!sql && !iso) return null;
|
||||
const day = dateOnly(text.slice(0, 10));
|
||||
if (!day) return null;
|
||||
const [hour, minute, second] = text.slice(11, 19).split(':').map(Number);
|
||||
if (hour > 23 || minute > 59 || second > 59) return null;
|
||||
const time = Date.parse(sql ? `${text.replace(' ', 'T')}Z` : text);
|
||||
return Number.isFinite(time) ? time : null;
|
||||
}
|
||||
|
||||
function coarsen(value, precision = 2) {
|
||||
const scale = 10 ** precision;
|
||||
return Math.round(value * scale) / scale;
|
||||
}
|
||||
|
||||
/** Public iNaturalist obscuration is a 0.2-degree cell aligned to zero. The
|
||||
* rounding removes floating-point noise, including at negative longitudes. */
|
||||
export function obscuredCell(lat, lon) {
|
||||
if (!validPosition(lat, lon)) return null;
|
||||
const south = Math.min(89.8, Math.floor(lat * 5) / 5);
|
||||
const west = Math.min(179.8, Math.floor(lon * 5) / 5);
|
||||
return {
|
||||
south: coarsen(south, 1),
|
||||
north: coarsen(south + 0.2, 1),
|
||||
west: coarsen(west, 1),
|
||||
east: coarsen(west + 0.2, 1),
|
||||
};
|
||||
}
|
||||
|
||||
/** Only the documented open-data square URL can be transformed to a display size. */
|
||||
export function inatPhotoUrl(url, size = 'square') {
|
||||
if (typeof url !== 'string' || !INAT_PHOTO.test(url)) return null;
|
||||
if (size !== 'square' && size !== 'medium') return null;
|
||||
return size === 'square' ? url : url.replace(/\/square\./i, `/${size}.`);
|
||||
}
|
||||
|
||||
/** Accept either the first upstream photo or the explicitly projected photo. */
|
||||
export function isOpenPhoto(photo) {
|
||||
if (!photo || typeof photo !== 'object') return false;
|
||||
const licence = photo.license_code ?? photo.licence;
|
||||
return (
|
||||
OPEN_PHOTO_LICENCES.includes(licence) &&
|
||||
inatPhotoUrl(photo.url ?? photo.square) !== null &&
|
||||
cleanText(photo.attribution, 160) !== null
|
||||
);
|
||||
}
|
||||
|
||||
/** Licence codes remain provider data; the all-rights-reserved fallback is
|
||||
* marked for translation when cards display it. */
|
||||
export function inatLicenceLabel(code) {
|
||||
switch (code) {
|
||||
case 'cc0':
|
||||
return 'CC0';
|
||||
case 'cc-by':
|
||||
return 'CC BY';
|
||||
case 'cc-by-sa':
|
||||
return 'CC BY-SA';
|
||||
case 'cc-by-nc':
|
||||
return 'CC BY-NC';
|
||||
case 'cc-by-nc-sa':
|
||||
return 'CC BY-NC-SA';
|
||||
case 'cc-by-nd':
|
||||
return 'CC BY-ND';
|
||||
case 'cc-by-nc-nd':
|
||||
return 'CC BY-NC-ND';
|
||||
default:
|
||||
return msg('All rights reserved');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Project API-v1 observation results (the results ARRAY, not the response
|
||||
* envelope). Malformed rows are skipped; only a non-array rejects a snapshot.
|
||||
*/
|
||||
export function normalizeInatObservations(
|
||||
payload,
|
||||
{ nowMs, windowMs = 2 * DAY_MS } = {},
|
||||
) {
|
||||
if (!Array.isArray(payload)) return null;
|
||||
const rows = [];
|
||||
const ids = new Set();
|
||||
for (const raw of payload) {
|
||||
if (!raw || !Number.isSafeInteger(raw.id) || raw.id <= 0) continue;
|
||||
if (raw.geoprivacy === 'private' || raw.taxon_geoprivacy === 'private')
|
||||
continue;
|
||||
if (raw.quality_grade !== 'research' && raw.quality_grade !== 'needs_id')
|
||||
continue;
|
||||
const stableId = `inat:${raw.id}`;
|
||||
if (ids.has(stableId)) continue;
|
||||
let lon = raw.geojson?.coordinates?.[0];
|
||||
let lat = raw.geojson?.coordinates?.[1];
|
||||
if (!validPosition(lat, lon) && typeof raw.location === 'string') {
|
||||
const parts = raw.location.split(',');
|
||||
if (parts.length === 2) [lat, lon] = parts.map(numberOrNull);
|
||||
}
|
||||
if (!validPosition(lat, lon)) continue;
|
||||
const obscured =
|
||||
raw.obscured === true ||
|
||||
raw.geoprivacy === 'obscured' ||
|
||||
raw.taxon_geoprivacy === 'obscured';
|
||||
const cell = obscured ? obscuredCell(lat, lon) : null;
|
||||
const time = parseAcartiaTime(raw.time_observed_at);
|
||||
const observedOn =
|
||||
dateOnly(raw.observed_on) ||
|
||||
(time !== null ? new Date(time).toISOString().slice(0, 10) : null);
|
||||
// The v1 d1 parameter is a DATE filter, so its first day over-fetches the
|
||||
// exact rolling window. Filter before hiding an obscured record's time.
|
||||
if (
|
||||
Number.isFinite(nowMs) &&
|
||||
!withinObservationWindow(time, observedOn, nowMs, windowMs)
|
||||
)
|
||||
continue;
|
||||
const photo = Array.isArray(raw.photos) ? raw.photos[0] : null;
|
||||
const taxon = raw.taxon;
|
||||
const faves = numberOrNull(raw.faves_count);
|
||||
const agreements = numberOrNull(raw.num_identification_agreements);
|
||||
ids.add(stableId);
|
||||
rows.push({
|
||||
stableId,
|
||||
origin: 'inaturalist',
|
||||
lat: cell ? coarsen((cell.south + cell.north) / 2, 1) : lat,
|
||||
lon: cell ? coarsen((cell.west + cell.east) / 2, 1) : lon,
|
||||
obscured,
|
||||
cell,
|
||||
observedAt: obscured ? null : time,
|
||||
observedOn,
|
||||
quality: raw.quality_grade,
|
||||
commonName: cleanText(taxon?.preferred_common_name, 100),
|
||||
scientificName: cleanText(taxon?.name, 100),
|
||||
iconic: cleanText(taxon?.iconic_taxon_name, 40) || 'Unknown',
|
||||
threatened: taxon?.threatened === true,
|
||||
provider: null,
|
||||
link:
|
||||
inatObservationUri(raw.uri) ||
|
||||
`https://www.inaturalist.org/observations/${raw.id}`,
|
||||
photo: isOpenPhoto(photo)
|
||||
? {
|
||||
square: inatPhotoUrl(photo.url),
|
||||
licence: photo.license_code,
|
||||
attribution: cleanText(photo.attribution, 160),
|
||||
}
|
||||
: null,
|
||||
// These public aggregate counters are used only for ambient photo rank.
|
||||
favesCount: faves !== null && faves >= 0 ? Math.floor(faves) : 0,
|
||||
identificationAgreements:
|
||||
agreements !== null && agreements >= 0 ? Math.floor(agreements) : 0,
|
||||
});
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
// Acartia has no documented per-sighting page, and photo_url is supplied by the
|
||||
// contributor. The source link is therefore always the Acartia site itself.
|
||||
export const ACARTIA_SITE = 'https://acartia.io/';
|
||||
|
||||
/** Acartia documents flat rows only. Name and entity are text fields; unknown
|
||||
* shapes are skipped rather than guessing nested provider data. */
|
||||
export function normalizeAcartiaSightings(payload, nowMs) {
|
||||
if (!Array.isArray(payload)) return null;
|
||||
const rows = [];
|
||||
const ids = new Set();
|
||||
for (const raw of payload) {
|
||||
const id =
|
||||
typeof raw?.entry_id === 'string'
|
||||
? cleanText(raw.entry_id, 120)
|
||||
: Number.isFinite(raw?.entry_id)
|
||||
? String(raw.entry_id)
|
||||
: null;
|
||||
if (!id) continue;
|
||||
const stableId = `acartia:${id}`;
|
||||
if (ids.has(stableId)) continue;
|
||||
const lat = numberOrNull(raw.latitude);
|
||||
const lon = numberOrNull(raw.longitude);
|
||||
const observedAt = parseAcartiaTime(raw.created);
|
||||
const name = cleanText(raw.data_source_name, 60);
|
||||
const species = cleanText(raw.type, 100);
|
||||
// Validate the original field: truncating a long, ambiguous name could
|
||||
// otherwise turn a prefix such as "Orca ... or seal" into a valid species.
|
||||
const speciesGroup = acartiaSpeciesGroup(raw.type);
|
||||
if (
|
||||
!validPosition(lat, lon) ||
|
||||
!inAcartiaCoverage(lat, lon) ||
|
||||
!name ||
|
||||
!speciesGroup ||
|
||||
observedAt === null ||
|
||||
!Number.isFinite(nowMs) ||
|
||||
nowMs - observedAt > ACARTIA_MAX_AGE_MS ||
|
||||
observedAt - nowMs > OBSERVATION_FUTURE_TOLERANCE_MS
|
||||
)
|
||||
continue;
|
||||
ids.add(stableId);
|
||||
rows.push({
|
||||
stableId,
|
||||
origin: 'acartia',
|
||||
lat: coarsen(lat),
|
||||
lon: coarsen(lon),
|
||||
obscured: false,
|
||||
cell: null,
|
||||
observedAt,
|
||||
observedOn: new Date(observedAt).toISOString().slice(0, 10),
|
||||
quality:
|
||||
raw.trusted === true || raw.trusted === 1 || raw.trusted === 'true'
|
||||
? 'research'
|
||||
: 'needs_id',
|
||||
commonName: species,
|
||||
scientificName: null,
|
||||
iconic: 'Mammalia',
|
||||
cetacean: speciesGroup === 'cetacean',
|
||||
threatened: false,
|
||||
provider: { name, entity: cleanText(raw.data_source_entity, 60) },
|
||||
link: ACARTIA_SITE,
|
||||
photo: null,
|
||||
favesCount: 0,
|
||||
identificationAgreements: 0,
|
||||
});
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
/** Recheck observation age on projected snapshots, including stale cache rows. */
|
||||
export function mergeSightings(
|
||||
inatRows,
|
||||
acartiaRows,
|
||||
{ nowMs, taxa = 'all', confirmed = false } = {},
|
||||
) {
|
||||
const byId = new Map();
|
||||
for (const row of Array.isArray(inatRows) ? inatRows : []) {
|
||||
if (isRecentWildlifeSighting(row, nowMs, taxa)) byId.set(row.stableId, row);
|
||||
}
|
||||
for (const row of Array.isArray(acartiaRows) ? acartiaRows : []) {
|
||||
if (
|
||||
!inAcartiaCoverage(row.lat, row.lon) ||
|
||||
!isRecentWildlifeSighting(row, nowMs, taxa)
|
||||
)
|
||||
continue;
|
||||
if (confirmed && row.quality !== 'research') continue;
|
||||
if (/inaturalist/i.test(row.provider?.name || '')) continue;
|
||||
if (!['all', 'Mammalia', 'whales'].includes(taxa)) continue;
|
||||
if (taxa === 'whales' && row.cetacean !== true) continue;
|
||||
byId.set(row.stableId, row);
|
||||
}
|
||||
return [...byId.values()];
|
||||
}
|
||||
@@ -0,0 +1,546 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
normalizeInatObservations,
|
||||
normalizeAcartiaSightings,
|
||||
parseAcartiaTime,
|
||||
inatPhotoUrl,
|
||||
isOpenPhoto,
|
||||
obscuredCell,
|
||||
inatLicenceLabel,
|
||||
mergeSightings,
|
||||
isRecentWildlifeSighting,
|
||||
} from './records.js';
|
||||
|
||||
const now = Date.UTC(2026, 10, 4, 18);
|
||||
const hour = 3_600_000;
|
||||
const photo = {
|
||||
url: 'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpeg',
|
||||
license_code: 'cc-by-nc',
|
||||
attribution: '(c) Synthetic Photographer, some rights reserved',
|
||||
};
|
||||
const observation = (overrides = {}) => ({
|
||||
id: 123,
|
||||
uri: 'https://www.inaturalist.org/observations/123',
|
||||
geojson: { coordinates: [-122.351, 47.613] },
|
||||
positional_accuracy: 12,
|
||||
public_positional_accuracy: 12,
|
||||
obscured: false,
|
||||
geoprivacy: null,
|
||||
taxon_geoprivacy: null,
|
||||
time_observed_at: '2026-11-04T16:00:00Z',
|
||||
observed_on: '2026-11-04',
|
||||
created_at: '2026-11-04T17:00:00Z',
|
||||
quality_grade: 'research',
|
||||
license_code: 'cc-by-nc',
|
||||
faves_count: 6,
|
||||
num_identification_agreements: 3,
|
||||
taxon: {
|
||||
name: 'Calypte anna',
|
||||
preferred_common_name: "Anna's Hummingbird",
|
||||
iconic_taxon_name: 'Aves',
|
||||
threatened: false,
|
||||
},
|
||||
photos: [photo],
|
||||
user: { login: 'SHOULD_NEVER_ESCAPE' },
|
||||
...overrides,
|
||||
});
|
||||
const sighting = (overrides = {}) => ({
|
||||
entry_id: 'abc',
|
||||
latitude: 48.12345,
|
||||
longitude: -122.54321,
|
||||
created: '2026-11-04 16:00:00',
|
||||
type: 'Orca',
|
||||
no_sighted: '5',
|
||||
photo_url: 'https://provider.example/photo.jpg',
|
||||
data_source_name: 'Synthetic Network',
|
||||
data_source_entity: 'Whale Alert',
|
||||
trusted: true,
|
||||
data_source_comments: 'PRIVATE PHONE AND NAME',
|
||||
...overrides,
|
||||
});
|
||||
|
||||
test('normalizers reject only non-array snapshots and dedupe validated ids', () => {
|
||||
for (const input of [null, {}, { results: [] }, '']) {
|
||||
assert.equal(normalizeInatObservations(input), null);
|
||||
assert.equal(normalizeAcartiaSightings(input, now), null);
|
||||
}
|
||||
assert.deepEqual(normalizeInatObservations([]), []);
|
||||
assert.equal(
|
||||
normalizeInatObservations([null, observation(), observation()]).length,
|
||||
1,
|
||||
);
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([null, sighting(), sighting()], now).length,
|
||||
1,
|
||||
);
|
||||
});
|
||||
|
||||
test('iNaturalist projection retains only the listed display fields and aggregate photo rank', () => {
|
||||
const [row] = normalizeInatObservations([observation()]);
|
||||
assert.equal(row.stableId, 'inat:123');
|
||||
assert.equal(row.favesCount, 6);
|
||||
assert.equal(row.identificationAgreements, 3);
|
||||
assert.equal(row.photo.attribution, photo.attribution);
|
||||
assert.equal(row.observedAt, now - 2 * hour);
|
||||
for (const key of [
|
||||
'user',
|
||||
'login',
|
||||
'public_positional_accuracy',
|
||||
'geojson',
|
||||
'created_at',
|
||||
])
|
||||
assert.equal(key in row, false);
|
||||
assert.doesNotMatch(JSON.stringify(row), /SHOULD_NEVER_ESCAPE/);
|
||||
});
|
||||
|
||||
test('observation links accept only canonical source pages and fall back to the id', () => {
|
||||
for (const uri of [
|
||||
undefined,
|
||||
'https://www.inaturalist.org/observations/123\n',
|
||||
'https://www.inaturalist.org/observations/123?redirect=elsewhere',
|
||||
'http://www.inaturalist.org/observations/123',
|
||||
'https://www.inaturalist.org.evil.example/observations/123',
|
||||
]) {
|
||||
const [row] = normalizeInatObservations([observation({ uri })]);
|
||||
assert.equal(
|
||||
row.link,
|
||||
observation().uri,
|
||||
'the existing detail card keeps its canonical fallback',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('wildlife package entries construct without acquiring data or a DOM', async () => {
|
||||
const api = await import('gods-eye-view/layers/wildlife-sightings');
|
||||
const sources =
|
||||
await import('gods-eye-view/layers/wildlife-sightings/source');
|
||||
const layer = api.createWildlifeSightingsLayer({
|
||||
source: sources.createWildlifeSightingsSource({
|
||||
fetchImpl() {
|
||||
assert.fail('construction must not acquire');
|
||||
},
|
||||
}),
|
||||
});
|
||||
assert.equal(layer.id, 'wildlife-sightings');
|
||||
layer.destroy();
|
||||
});
|
||||
|
||||
test('only allow-listed photo licences with square open-data hosts and attribution render', () => {
|
||||
for (const license_code of [
|
||||
'cc0',
|
||||
'cc-by',
|
||||
'cc-by-sa',
|
||||
'cc-by-nc',
|
||||
'cc-by-nc-sa',
|
||||
]) {
|
||||
assert.equal(isOpenPhoto({ ...photo, license_code }), true);
|
||||
assert.ok(
|
||||
normalizeInatObservations([
|
||||
observation({ photos: [{ ...photo, license_code }] }),
|
||||
])[0].photo,
|
||||
);
|
||||
}
|
||||
for (const badPhoto of [
|
||||
{ ...photo, license_code: null },
|
||||
{ ...photo, license_code: 'cc-by-nd' },
|
||||
{ ...photo, license_code: 'cc-by-nc-nd' },
|
||||
{ ...photo, license_code: 'all rights reserved' },
|
||||
{ ...photo, url: 'https://static.inaturalist.org/photos/123/square.jpg' },
|
||||
{ ...photo, url: `${photo.url}?size=square` },
|
||||
{ ...photo, url: photo.url.replace('https:', 'http:') },
|
||||
{ ...photo, attribution: '' },
|
||||
{ ...photo, url: photo.url.replace('/square.', '/medium.') },
|
||||
]) {
|
||||
assert.equal(isOpenPhoto(badPhoto), false);
|
||||
assert.equal(
|
||||
normalizeInatObservations([observation({ photos: [badPhoto] })])[0].photo,
|
||||
null,
|
||||
);
|
||||
}
|
||||
assert.equal(
|
||||
inatPhotoUrl(photo.url, 'medium'),
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/medium.jpeg',
|
||||
);
|
||||
for (const extension of ['jpg', 'jpeg', 'PNG']) {
|
||||
const square = photo.url.replace('square.jpeg', `square.${extension}`);
|
||||
assert.equal(
|
||||
inatPhotoUrl(square, 'medium'),
|
||||
square.replace('/square.', '/medium.'),
|
||||
);
|
||||
}
|
||||
for (const invalid of [
|
||||
null,
|
||||
new URL(photo.url),
|
||||
photo.url.replace('https:', 'http:'),
|
||||
photo.url.replace('amazonaws.com', 'amazonaws.com.evil.example'),
|
||||
photo.url.replace('https://', 'https://user:secret@'),
|
||||
photo.url.replace('https://', 'https://evil.example@'),
|
||||
photo.url.replace('/photos/', '/other/photos/'),
|
||||
photo.url.replace('/123/', '/abc/'),
|
||||
photo.url.replace('/square.', '/medium.'),
|
||||
photo.url.replace('/square.', '/large.'),
|
||||
photo.url.replace('.jpeg', '.webp'),
|
||||
`${photo.url}?size=large`,
|
||||
`${photo.url}#large`,
|
||||
`${photo.url}\n`,
|
||||
]) {
|
||||
assert.equal(inatPhotoUrl(invalid, 'medium'), null, String(invalid));
|
||||
}
|
||||
for (const invalidSize of [
|
||||
'original',
|
||||
'small',
|
||||
'large',
|
||||
'Medium',
|
||||
'../medium',
|
||||
'medium?query=1',
|
||||
null,
|
||||
]) {
|
||||
assert.equal(inatPhotoUrl(photo.url, invalidSize), null);
|
||||
}
|
||||
assert.equal(inatLicenceLabel('cc-by-nc-sa'), 'CC BY-NC-SA');
|
||||
assert.equal(inatLicenceLabel(null), 'All rights reserved');
|
||||
});
|
||||
|
||||
test('photo attribution is trimmed, control-free and bounded', () => {
|
||||
const attribution = ` Photo\u0000\n${'A'.repeat(200)} `;
|
||||
const [row] = normalizeInatObservations([
|
||||
observation({ photos: [{ ...photo, attribution }] }),
|
||||
]);
|
||||
assert.equal(row.photo.attribution.length, 160);
|
||||
assert.match(row.photo.attribution, /^PhotoA/);
|
||||
assert.doesNotMatch(row.photo.attribution, /[\u0000-\u001f]/);
|
||||
});
|
||||
|
||||
test('obscured rows reveal only cell centres and date, without accuracy', () => {
|
||||
assert.deepEqual(obscuredCell(47.613, -122.351), {
|
||||
south: 47.6,
|
||||
north: 47.8,
|
||||
west: -122.4,
|
||||
east: -122.2,
|
||||
});
|
||||
for (const hiding of [
|
||||
{ obscured: true },
|
||||
{ geoprivacy: 'obscured' },
|
||||
{ taxon_geoprivacy: 'obscured' },
|
||||
]) {
|
||||
const [row] = normalizeInatObservations([observation(hiding)]);
|
||||
assert.equal(row.obscured, true);
|
||||
assert.equal(row.lat, 47.7);
|
||||
assert.equal(row.lon, -122.3);
|
||||
assert.equal('accuracyM' in row, false);
|
||||
assert.equal(row.observedAt, null);
|
||||
assert.equal(row.observedOn, '2026-11-04');
|
||||
assert.doesNotMatch(JSON.stringify(row), /47\.613|-122\.351|16:00/);
|
||||
}
|
||||
assert.deepEqual(obscuredCell(90, 180), {
|
||||
south: 89.8,
|
||||
north: 90,
|
||||
west: 179.8,
|
||||
east: 180,
|
||||
});
|
||||
});
|
||||
|
||||
test('private, casual, invalid coordinates and invalid ids are skipped', () => {
|
||||
const invalid = [
|
||||
observation({ geoprivacy: 'private' }),
|
||||
observation({ taxon_geoprivacy: 'private' }),
|
||||
observation({ quality_grade: 'casual' }),
|
||||
observation({ id: -1 }),
|
||||
observation({ id: 1.5 }),
|
||||
observation({ geojson: { coordinates: [181, 47] } }),
|
||||
observation({ geojson: null }),
|
||||
];
|
||||
assert.deepEqual(normalizeInatObservations(invalid), []);
|
||||
const [fallback] = normalizeInatObservations([
|
||||
observation({
|
||||
geojson: null,
|
||||
location: '47.613,-122.351',
|
||||
uri: 'https://bad.example',
|
||||
}),
|
||||
]);
|
||||
assert.equal(fallback.lat, 47.613);
|
||||
assert.equal(fallback.link, 'https://www.inaturalist.org/observations/123');
|
||||
assert.deepEqual(
|
||||
normalizeInatObservations([observation({ geojson: null, location: ',0' })]),
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('Acartia accepts only the two stated UTC timestamp formats', () => {
|
||||
assert.equal(parseAcartiaTime('2026-11-04 16:00:00'), now - 2 * hour);
|
||||
assert.equal(parseAcartiaTime('2026-11-04T16:00:00Z'), now - 2 * hour);
|
||||
assert.equal(parseAcartiaTime('2026-11-04T18:00:00+02:00'), now - 2 * hour);
|
||||
for (const value of [
|
||||
'2026-11-04T16:00:00',
|
||||
'11/04/2026',
|
||||
'2026-02-30 12:00:00',
|
||||
'2026-11-04 25:00:00',
|
||||
123,
|
||||
null,
|
||||
])
|
||||
assert.equal(parseAcartiaTime(value), null);
|
||||
});
|
||||
|
||||
test('Acartia coarsens before returning data, keeps provider, and never reads comments', () => {
|
||||
const raw = sighting();
|
||||
Object.defineProperty(raw, 'data_source_comments', {
|
||||
get() {
|
||||
assert.fail('comments read');
|
||||
},
|
||||
});
|
||||
const [row] = normalizeAcartiaSightings([raw], now);
|
||||
assert.equal(row.lat, 48.12);
|
||||
assert.equal(row.lon, -122.54);
|
||||
assert.deepEqual(row.provider, {
|
||||
name: 'Synthetic Network',
|
||||
entity: 'Whale Alert',
|
||||
});
|
||||
assert.equal(row.quality, 'research');
|
||||
assert.equal(row.photo, null);
|
||||
assert.doesNotMatch(
|
||||
JSON.stringify(row),
|
||||
/data_source_comments|PRIVATE|48\.12345|-122\.54321/,
|
||||
);
|
||||
});
|
||||
|
||||
test('Acartia requires flat provider text, handles trust, and sanitizes type', () => {
|
||||
for (const provider of ['', null, {}, { name: 'Invented nested shape' }]) {
|
||||
assert.deepEqual(
|
||||
normalizeAcartiaSightings(
|
||||
[sighting({ data_source_name: provider })],
|
||||
now,
|
||||
),
|
||||
[],
|
||||
);
|
||||
}
|
||||
for (const trusted of [true, 1, 'true'])
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting({ trusted })], now)[0].quality,
|
||||
'research',
|
||||
);
|
||||
for (const trusted of [false, 0, 'false', '1'])
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting({ trusted })], now)[0].quality,
|
||||
'needs_id',
|
||||
);
|
||||
assert.deepEqual(
|
||||
normalizeAcartiaSightings([sighting({ type: ' \u0000 ' })], now),
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('Acartia rejects invalid times/positions and its link is always the Acartia site', () => {
|
||||
for (const overrides of [
|
||||
{ created: new Date(now - 8 * 24 * hour - 1).toISOString() },
|
||||
{ created: new Date(now + 10 * 60_000 + 1).toISOString() },
|
||||
{ created: 'not a timestamp' },
|
||||
{ latitude: 91 },
|
||||
{ longitude: -181 },
|
||||
{ entry_id: '' },
|
||||
])
|
||||
assert.deepEqual(normalizeAcartiaSightings([sighting(overrides)], now), []);
|
||||
for (const photo_url of [
|
||||
// A contributor-supplied URL is never labelled as the Acartia source.
|
||||
'https://provider.example/photo.jpg',
|
||||
'https://phishing.example/acartia.io/login',
|
||||
'https://acartia.io.attacker.example/',
|
||||
'http://provider.example/p.jpg',
|
||||
'https://user:[email protected]/p.jpg',
|
||||
'javascript:bad()',
|
||||
'https://' + 'x'.repeat(501),
|
||||
null,
|
||||
]) {
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting({ photo_url })], now)[0].link,
|
||||
'https://acartia.io/',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('merge applies Acartia windows, trust, preset and iNat dedupe', () => {
|
||||
const inat = normalizeInatObservations([observation()]);
|
||||
const rows = normalizeAcartiaSightings(
|
||||
[
|
||||
sighting(),
|
||||
sighting({
|
||||
entry_id: 'old',
|
||||
created: new Date(now - 3 * 24 * hour).toISOString(),
|
||||
}),
|
||||
sighting({ entry_id: 'untrusted', trusted: false }),
|
||||
sighting({
|
||||
entry_id: 'inat',
|
||||
data_source_name: 'iNaturalist observations',
|
||||
}),
|
||||
],
|
||||
now,
|
||||
);
|
||||
const ids = (options) =>
|
||||
mergeSightings(inat, rows, { nowMs: now, ...options }).map(
|
||||
(row) => row.stableId,
|
||||
);
|
||||
assert.deepEqual(ids({}), ['inat:123', 'acartia:abc', 'acartia:untrusted']);
|
||||
assert.deepEqual(ids({ confirmed: true }), ['inat:123', 'acartia:abc']);
|
||||
assert.ok(ids({ taxa: 'whales' }).includes('acartia:old'));
|
||||
assert.deepEqual(ids({ taxa: 'Aves' }), ['inat:123']);
|
||||
});
|
||||
|
||||
test('iNaturalist recency uses observation time and the exact preset window', () => {
|
||||
const raw = [
|
||||
observation({
|
||||
id: 1,
|
||||
time_observed_at: '2010-11-04T16:00:00Z',
|
||||
observed_on: '2010-11-04',
|
||||
created_at: new Date(now).toISOString(),
|
||||
}),
|
||||
observation({
|
||||
id: 2,
|
||||
time_observed_at: new Date(now - 48 * hour - 1).toISOString(),
|
||||
observed_on: '2026-11-02',
|
||||
}),
|
||||
observation({
|
||||
id: 3,
|
||||
time_observed_at: new Date(now - 48 * hour).toISOString(),
|
||||
observed_on: '2026-11-02',
|
||||
created_at: '2026-10-01T00:00:00Z',
|
||||
}),
|
||||
observation({
|
||||
id: 4,
|
||||
time_observed_at: new Date(now - 3 * 24 * hour).toISOString(),
|
||||
observed_on: '2026-11-01',
|
||||
}),
|
||||
];
|
||||
const ids = (rows) => rows.map((row) => row.stableId);
|
||||
assert.deepEqual(ids(normalizeInatObservations(raw, { nowMs: now })), [
|
||||
'inat:3',
|
||||
]);
|
||||
assert.deepEqual(
|
||||
ids(
|
||||
normalizeInatObservations(raw, { nowMs: now, windowMs: 7 * 24 * hour }),
|
||||
),
|
||||
['inat:2', 'inat:3', 'inat:4'],
|
||||
);
|
||||
// Recheck cached/projected rows as the clock moves between server refreshes.
|
||||
assert.deepEqual(
|
||||
ids(mergeSightings(normalizeInatObservations(raw), [], { nowMs: now })),
|
||||
['inat:3'],
|
||||
);
|
||||
assert.deepEqual(
|
||||
mergeSightings(normalizeInatObservations([raw[2]]), [], { nowMs: now + 1 }),
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('date-only and obscured iNaturalist recency never includes a partly expired date', () => {
|
||||
const rows = normalizeInatObservations(
|
||||
[
|
||||
observation({ id: 1, time_observed_at: null, observed_on: '2026-11-02' }),
|
||||
observation({ id: 2, time_observed_at: null, observed_on: '2026-11-03' }),
|
||||
observation({ id: 3, time_observed_at: null, observed_on: null }),
|
||||
observation({
|
||||
id: 4,
|
||||
obscured: true,
|
||||
time_observed_at: '2010-11-04T16:00:00Z',
|
||||
observed_on: '2010-11-04',
|
||||
}),
|
||||
],
|
||||
{ nowMs: now },
|
||||
);
|
||||
assert.deepEqual(
|
||||
rows.map((row) => row.stableId),
|
||||
['inat:2'],
|
||||
);
|
||||
});
|
||||
|
||||
test('retained sightings use the same exact, date-only and preset recency limits', () => {
|
||||
const boundary = { observedAt: now - 48 * hour };
|
||||
assert.equal(isRecentWildlifeSighting(boundary, now), true);
|
||||
assert.equal(isRecentWildlifeSighting(boundary, now + 1), false);
|
||||
assert.equal(isRecentWildlifeSighting(boundary, now + 1, 'whales'), true);
|
||||
const whaleBoundary = { observedAt: now - 7 * 24 * hour };
|
||||
assert.equal(isRecentWildlifeSighting(whaleBoundary, now, 'whales'), true);
|
||||
assert.equal(
|
||||
isRecentWildlifeSighting(whaleBoundary, now + 1, 'whales'),
|
||||
false,
|
||||
);
|
||||
assert.equal(isRecentWildlifeSighting(whaleBoundary, now, 'Mammalia'), false);
|
||||
for (const [observedOn, expected] of [
|
||||
['2026-11-02', false],
|
||||
['2026-11-03', true],
|
||||
['2026-11-04', true],
|
||||
]) {
|
||||
assert.equal(
|
||||
isRecentWildlifeSighting({ observedAt: null, observedOn }, now),
|
||||
expected,
|
||||
);
|
||||
}
|
||||
assert.equal(
|
||||
isRecentWildlifeSighting({ observedOn: '2026-11-03' }, now + 24 * hour),
|
||||
false,
|
||||
);
|
||||
for (const row of [
|
||||
null,
|
||||
{},
|
||||
{ observedOn: '2010-11-04' },
|
||||
{ observedOn: 'invalid' },
|
||||
]) {
|
||||
assert.equal(isRecentWildlifeSighting(row, now), false);
|
||||
}
|
||||
assert.equal(isRecentWildlifeSighting(boundary, NaN), false);
|
||||
});
|
||||
|
||||
test('Acartia validates the documented type field before applying the WHALES preset', () => {
|
||||
const rows = normalizeAcartiaSightings(
|
||||
[
|
||||
sighting({ entry_id: 'orca', type: 'Orca' }),
|
||||
sighting({ entry_id: 'scientific', type: 'Phocoena phocoena' }),
|
||||
sighting({ entry_id: 'seal', type: 'Harbor seal' }),
|
||||
sighting({
|
||||
entry_id: 'unidentified',
|
||||
type: 'Unidentified marine mammal',
|
||||
}),
|
||||
sighting({ entry_id: 'unknown-whale', type: 'Unidentified whale' }),
|
||||
sighting({ entry_id: 'unknown', type: 'Unknown' }),
|
||||
sighting({ entry_id: 'empty', type: '' }),
|
||||
sighting({ entry_id: 'fish', type: 'Whale shark' }),
|
||||
sighting({ entry_id: 'text', type: 'Maybe an Orca or a seal' }),
|
||||
sighting({ entry_id: 'prefix', type: `Orca${' '.repeat(120)}or a seal` }),
|
||||
sighting({ entry_id: 'invented-shape', type: { species: 'Orca' } }),
|
||||
],
|
||||
now,
|
||||
);
|
||||
const ids = (taxa) =>
|
||||
mergeSightings([], rows, { nowMs: now, taxa }).map((row) => row.stableId);
|
||||
assert.deepEqual(ids('whales'), ['acartia:orca', 'acartia:scientific']);
|
||||
const mammals = [
|
||||
'acartia:orca',
|
||||
'acartia:scientific',
|
||||
'acartia:seal',
|
||||
'acartia:unidentified',
|
||||
'acartia:unknown-whale',
|
||||
];
|
||||
assert.deepEqual(ids('all'), mammals);
|
||||
assert.deepEqual(ids('Mammalia'), mammals);
|
||||
assert.deepEqual(ids('Aves'), []);
|
||||
});
|
||||
|
||||
test('Acartia rejects out-of-coverage rows before rounding or caching', () => {
|
||||
for (const position of [
|
||||
{ latitude: 45.49999 },
|
||||
{ latitude: 50.50001 },
|
||||
{ longitude: -126.00001 },
|
||||
{ longitude: -120.99999 },
|
||||
{ latitude: 37.8, longitude: -122.4 },
|
||||
]) {
|
||||
assert.deepEqual(normalizeAcartiaSightings([sighting(position)], now), []);
|
||||
}
|
||||
for (const position of [
|
||||
{ latitude: 45.5, longitude: -126 },
|
||||
{ latitude: 50.5, longitude: -121 },
|
||||
]) {
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting(position)], now).length,
|
||||
1,
|
||||
);
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,166 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { performance, PerformanceObserver } from 'node:perf_hooks';
|
||||
import test from 'node:test';
|
||||
import { perfBudgetTestOptions } from '../../../scripts/run-perf-tests.mjs';
|
||||
import { denseContinentalRendering } from './renderPerformanceFixtures.mjs';
|
||||
import { WILDLIFE_MOVE_END_BUDGET_MS } from './performance.js';
|
||||
|
||||
const median = (values) =>
|
||||
[...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
|
||||
const percentile95 = (values) =>
|
||||
[...values].sort((a, b) => a - b)[Math.floor(values.length * 0.95)];
|
||||
|
||||
// A GC pause is outside the layer's CPU work. Keep raw wall times in the
|
||||
// diagnostic and subtract only directly observed, overlapping GC intervals
|
||||
// for the strict CPU budget; never hide a slow layer phase as an outlier.
|
||||
function activeMs(slice, collections) {
|
||||
const start = slice.startTimeMs;
|
||||
const end = start + slice.durationMs;
|
||||
return (
|
||||
slice.durationMs -
|
||||
collections.reduce(
|
||||
(sum, gc) =>
|
||||
sum +
|
||||
Math.max(
|
||||
0,
|
||||
Math.min(end, gc.startTime + gc.duration) -
|
||||
Math.max(start, gc.startTime),
|
||||
),
|
||||
0,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
test(
|
||||
'dense continental production moveEnd pipeline yields every 4ms, including cold tiles and real Cesium billboard updates',
|
||||
perfBudgetTestOptions(),
|
||||
async (t) => {
|
||||
// Settle CPU-triggered runtime startup before creating the cold layer;
|
||||
// cells, coordinates and billboard collections remain unwarmed.
|
||||
const calibrationStart = performance.now();
|
||||
let calibrationChecksum = 0;
|
||||
for (;;) {
|
||||
const cpu = process.threadCpuUsage();
|
||||
if (cpu.user + cpu.system >= 1_100_000) break;
|
||||
for (let i = 0; i < 65536; i++)
|
||||
calibrationChecksum =
|
||||
(calibrationChecksum + i) ^ (calibrationChecksum >>> 16);
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
}
|
||||
const runtimeSettleMs = performance.now() - calibrationStart;
|
||||
const collections = [];
|
||||
const phases = [];
|
||||
const observer = new PerformanceObserver((list) => {
|
||||
for (const entry of list.getEntries())
|
||||
(entry.entryType === 'gc' ? collections : phases).push(entry);
|
||||
});
|
||||
observer.observe({ entryTypes: ['gc', 'measure'] });
|
||||
const h = denseContinentalRendering();
|
||||
const runs = [];
|
||||
try {
|
||||
for (let i = 0; i < 65; i++) {
|
||||
const start = performance.now();
|
||||
assert.equal(h.moveEnd((i % 4) * 3), 'pending');
|
||||
const enqueueMs = performance.now() - start;
|
||||
const result = h.flush();
|
||||
runs.push({
|
||||
startTimeMs: start,
|
||||
endTimeMs: performance.now(),
|
||||
enqueueMs,
|
||||
...result,
|
||||
});
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
}
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (const entry of observer.takeRecords())
|
||||
(entry.entryType === 'gc' ? collections : phases).push(entry);
|
||||
const warm = runs.slice(25);
|
||||
const allSlices = runs.flatMap((run) => run.slices);
|
||||
const warmSlices = warm.flatMap((run) => run.slices);
|
||||
const activeSlices = allSlices.map((slice) =>
|
||||
activeMs(slice, collections),
|
||||
);
|
||||
const warmTotal = warm.map((run) =>
|
||||
run.slices.reduce(
|
||||
(sum, slice) => sum + activeMs(slice, collections),
|
||||
run.enqueueMs,
|
||||
),
|
||||
);
|
||||
const enqueueMax = Math.max(...runs.map((run) => run.enqueueMs));
|
||||
const coldMax = Math.max(
|
||||
...runs[0].slices.map((slice) => activeMs(slice, collections)),
|
||||
);
|
||||
const sliceMax = Math.max(...activeSlices);
|
||||
if (sliceMax > WILDLIFE_MOVE_END_BUDGET_MS) {
|
||||
const slow = allSlices[activeSlices.indexOf(sliceMax)];
|
||||
const entries = phases
|
||||
.filter(
|
||||
(entry) =>
|
||||
entry.entryType === 'measure' &&
|
||||
entry.name !== 'wildlife-sightings:moveEnd:slice' &&
|
||||
entry.startTime >= slow.startTimeMs &&
|
||||
entry.startTime < slow.startTimeMs + slow.durationMs,
|
||||
)
|
||||
.map((entry) => ({
|
||||
phase: entry.name,
|
||||
durationMs: entry.duration,
|
||||
activeMs: activeMs(
|
||||
{ startTimeMs: entry.startTime, durationMs: entry.duration },
|
||||
collections,
|
||||
),
|
||||
}));
|
||||
t.diagnostic(
|
||||
`Slow slice ${JSON.stringify({ slice: slow, phases: entries, gc: collections.map((entry) => ({ start: entry.startTime, duration: entry.duration })), now: performance.now(), uptimeMs: process.uptime() * 1000 })}`,
|
||||
);
|
||||
}
|
||||
assert.ok(
|
||||
enqueueMax <= WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
`moveEnd enqueue ${enqueueMax.toFixed(3)}ms`,
|
||||
);
|
||||
assert.ok(
|
||||
sliceMax <= WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
`longest layer CPU slice ${sliceMax.toFixed(3)}ms exceeds 4ms`,
|
||||
);
|
||||
assert.ok(
|
||||
median(warmTotal) <= WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
`median full moveEnd CPU ${median(warmTotal).toFixed(3)}ms exceeds 4ms`,
|
||||
);
|
||||
assert.equal(warm.at(-1).cartesianBuilds, 0);
|
||||
const phaseMeans = Object.fromEntries(
|
||||
[
|
||||
'density',
|
||||
'bucket',
|
||||
'rank',
|
||||
'billboard-update',
|
||||
'overlay-publish',
|
||||
].map((name) => {
|
||||
const duration = phases
|
||||
.filter(
|
||||
(entry) =>
|
||||
entry.name === `wildlife-sightings:${name}` &&
|
||||
entry.startTime >= warm[0].startTimeMs,
|
||||
)
|
||||
.reduce(
|
||||
(sum, entry) =>
|
||||
sum +
|
||||
activeMs(
|
||||
{
|
||||
startTimeMs: entry.startTime,
|
||||
durationMs: entry.duration,
|
||||
},
|
||||
collections,
|
||||
),
|
||||
0,
|
||||
);
|
||||
return [name, (duration / warm.length).toFixed(3)];
|
||||
}),
|
||||
);
|
||||
t.diagnostic(
|
||||
`6,144 cells + 500 observations, ${runs.at(-1).glowPrimitives} glow splats + ${runs.at(-1).billboards} real icons; moveEnd enqueue max=${enqueueMax.toFixed(3)}ms; cold max CPU slice=${coldMax.toFixed(3)}ms; all max CPU slice=${sliceMax.toFixed(3)}ms; warm total CPU median=${median(warmTotal).toFixed(3)}ms; warm slice p95=${percentile95(warmSlices.map((slice) => activeMs(slice, collections))).toFixed(3)}ms; raw wall slice max=${Math.max(...allSlices.map((slice) => slice.durationMs)).toFixed(3)}ms; observed GC pauses=${collections.length}; repeated Cartesian builds=0; CPU startup calibration=${runtimeSettleMs.toFixed(0)}ms, checksum=${calibrationChecksum} (cold fixture created afterward); warm phase mean ms=${JSON.stringify(phaseMeans)}`,
|
||||
);
|
||||
} finally {
|
||||
h.destroy();
|
||||
observer.disconnect();
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,185 @@
|
||||
import * as Cesium from 'cesium';
|
||||
import { createRendering } from './rendering.js';
|
||||
import { createSelection } from './selection.js';
|
||||
|
||||
export const DENSE_CONTINENT_CELLS = 6 * 32 * 32;
|
||||
export const DENSE_CONTINENT_ROWS = 500;
|
||||
const NOW = Date.parse('2026-11-04T18:00:00Z');
|
||||
|
||||
/** The real render + selection pipeline with Cesium coordinates/billboards.
|
||||
* Only the WebGL scene and external overlay host are replaced. Six fully
|
||||
* occupied logical tiles deliberately include off-window cells and collisions. */
|
||||
export function denseContinentalRendering({ onOperations } = {}) {
|
||||
const cells = [];
|
||||
const z = 3;
|
||||
for (let x = 1; x < 3; x++)
|
||||
for (let y = 1; y < 4; y++)
|
||||
for (let row = 1; row < 64; row += 2)
|
||||
for (let column = 1; column < 64; column += 2)
|
||||
cells.push({
|
||||
id: `grid:${z}/${x}/${y}:${row}:${column}`,
|
||||
lat:
|
||||
(Math.atan(
|
||||
Math.sinh(Math.PI * (1 - (2 * (y + row / 64)) / 2 ** z)),
|
||||
) *
|
||||
180) /
|
||||
Math.PI,
|
||||
lon: ((x + column / 64) / 2 ** z) * 360 - 180,
|
||||
cellCount: row * 64 + column,
|
||||
});
|
||||
const rows = cells
|
||||
.slice(1200, 1200 + DENSE_CONTINENT_ROWS)
|
||||
.map((cell, i) => ({
|
||||
stableId: `synthetic:continent:${i}`,
|
||||
origin: 'inaturalist',
|
||||
lat: cell.lat,
|
||||
lon: cell.lon,
|
||||
iconic: 'Aves',
|
||||
commonName: i % 2 ? `Synthetic bird ${i}` : null,
|
||||
observedAt: NOW - i * 1000,
|
||||
quality: 'research',
|
||||
obscured: false,
|
||||
cell: null,
|
||||
}));
|
||||
const primitives = {
|
||||
add: (value) => value,
|
||||
remove(value) {
|
||||
value.destroy();
|
||||
return true;
|
||||
},
|
||||
};
|
||||
const scene = {
|
||||
canvas: { clientWidth: 1440, clientHeight: 900 },
|
||||
primitives,
|
||||
};
|
||||
const state = {
|
||||
enabled: true,
|
||||
viewer: {
|
||||
scene,
|
||||
camera: { positionWC: {}, positionCartographic: { height: 2_000_000 } },
|
||||
},
|
||||
rows: new Map(rows.map((row) => [row.stableId, row])),
|
||||
gridCells: cells,
|
||||
gridAvailable: true,
|
||||
renderedRows: [],
|
||||
rowById: new Map(),
|
||||
pointById: new Map(),
|
||||
positions: new Map(),
|
||||
cells: [],
|
||||
staging: null,
|
||||
taxa: 'all',
|
||||
selectedId: null,
|
||||
query: { visibleBoxes: [{ south: 5, west: -130, north: 75, east: -50 }] },
|
||||
band: 'regional',
|
||||
ambientRows: [],
|
||||
ambientIds: [],
|
||||
labelRows: [],
|
||||
carriers: new Map(),
|
||||
contextIds: new Set(),
|
||||
};
|
||||
const centre = Cesium.Cartesian3.fromDegrees(-90, 42);
|
||||
const frame = Cesium.Transforms.eastNorthUpToFixedFrame(centre);
|
||||
const east = Cesium.Matrix4.getColumn(frame, 0, new Cesium.Cartesian4());
|
||||
const north = Cesium.Matrix4.getColumn(frame, 1, new Cesium.Cartesian4());
|
||||
const metrics = { projections: 0, publications: 0, cartesianBuilds: 0 };
|
||||
let pan = 0;
|
||||
let nextIdle = 0;
|
||||
const idle = new Map();
|
||||
const slices = [];
|
||||
const timers = new Map();
|
||||
let nextTimer = 0;
|
||||
const parts = {};
|
||||
const services = {
|
||||
now: () => NOW,
|
||||
setTimer(fn, delay) {
|
||||
timers.set(++nextTimer, { fn, delay });
|
||||
return nextTimer;
|
||||
},
|
||||
clearTimer: (id) => timers.delete(id),
|
||||
requestIdleCallback(fn) {
|
||||
idle.set(++nextIdle, fn);
|
||||
return nextIdle;
|
||||
},
|
||||
cancelIdleCallback(id) {
|
||||
idle.delete(id);
|
||||
},
|
||||
performanceSlice(slice) {
|
||||
slices.push(slice);
|
||||
},
|
||||
cesium: {
|
||||
...Cesium,
|
||||
Cartesian3: class extends Cesium.Cartesian3 {
|
||||
static fromDegrees(...args) {
|
||||
metrics.cartesianBuilds++;
|
||||
return Cesium.Cartesian3.fromDegrees(...args);
|
||||
}
|
||||
},
|
||||
},
|
||||
project(_scene, anchor) {
|
||||
metrics.projections++;
|
||||
return {
|
||||
x:
|
||||
720 +
|
||||
(anchor.x * east.x + anchor.y * east.y + anchor.z * east.z) / 8000 +
|
||||
pan,
|
||||
y:
|
||||
450 -
|
||||
(anchor.x * north.x + anchor.y * north.y + anchor.z * north.z) / 8000,
|
||||
};
|
||||
},
|
||||
occluderFactory: () => ({ isPointVisible: () => true }),
|
||||
badgeSprites: {
|
||||
get: (group) => `data:image/svg+xml,${group}`,
|
||||
subscribe: () => () => {},
|
||||
},
|
||||
render: { governorRequestRender() {} },
|
||||
overlayHost: {
|
||||
setEntries() {
|
||||
metrics.publications++;
|
||||
},
|
||||
},
|
||||
performanceOperations: onOperations,
|
||||
};
|
||||
parts.rendering = createRendering({ state, services, parts });
|
||||
parts.photos = { get: () => null, setAmbient() {} };
|
||||
parts.selection = createSelection({ state, services, parts });
|
||||
parts.rendering.init();
|
||||
return {
|
||||
state,
|
||||
metrics,
|
||||
moveEnd(offset = 0) {
|
||||
pan = offset;
|
||||
metrics.projections = metrics.publications = metrics.cartesianBuilds = 0;
|
||||
slices.length = 0;
|
||||
const result = parts.rendering.rebuild();
|
||||
if (result !== 'pending') {
|
||||
parts.selection.refreshAmbient();
|
||||
parts.selection.publishSelected();
|
||||
parts.selection.refreshContexts();
|
||||
}
|
||||
return result;
|
||||
},
|
||||
flush(maxSlices = Infinity) {
|
||||
let count = 0;
|
||||
while (idle.size && count++ < maxSlices) {
|
||||
const [id, fn] = idle.entries().next().value;
|
||||
idle.delete(id);
|
||||
const threadStart = process.threadCpuUsage();
|
||||
fn({ timeRemaining: () => 8, didTimeout: false });
|
||||
const threadUsed = process.threadCpuUsage(threadStart);
|
||||
if (slices.length)
|
||||
slices.at(-1).threadCpuMs =
|
||||
(threadUsed.user + threadUsed.system) / 1000;
|
||||
}
|
||||
return {
|
||||
...metrics,
|
||||
billboards: state.renderedRows.length,
|
||||
glowPrimitives: parts.rendering.density?.size ?? 0,
|
||||
slices: [...slices],
|
||||
};
|
||||
},
|
||||
destroy() {
|
||||
parts.rendering.destroy();
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,691 @@
|
||||
import { wildlifeAccent } from './cards.js';
|
||||
import {
|
||||
wildlifeIconModelWork,
|
||||
wildlifeIconRelevance,
|
||||
compareWildlifeIds,
|
||||
} from './model.js';
|
||||
import { createWildlifeBillboardModel } from './billboardModel.js';
|
||||
import { createWildlifeDensity } from './density.js';
|
||||
import { wildlifeSpriteCache } from './sprites.js';
|
||||
import { isRecentWildlifeSighting } from './records.js';
|
||||
import {
|
||||
drainWildlifeWork,
|
||||
createWildlifeWorkQueue,
|
||||
WILDLIFE_SYNC_CELL_LIMIT,
|
||||
WILDLIFE_WORK_UNIT,
|
||||
} from './performance.js';
|
||||
import {
|
||||
WILDLIFE_SCALE_BY_DISTANCE,
|
||||
WILDLIFE_BADGE_MAX_PX,
|
||||
WILDLIFE_GROUND_READY_MAX_CHECKS,
|
||||
WILDLIFE_SPRITE_PX,
|
||||
} from './policy.js';
|
||||
|
||||
/** Own sighting billboards, density glow and batched privacy cells. */
|
||||
export function createRendering({ state, services, parts }) {
|
||||
const C = services.cesium;
|
||||
const badgeSprites = services.badgeSprites ?? wildlifeSpriteCache();
|
||||
let batchDepth = 0;
|
||||
let pendingRenderReason = null;
|
||||
let billboards = null;
|
||||
let density = null;
|
||||
let cellsSignature = null;
|
||||
let ambientAnchorIds = new Set();
|
||||
const badgeScreens = new Map();
|
||||
const crowdedBadgeIds = new Set();
|
||||
const photoCardIds = new Set();
|
||||
const appearances = new Map();
|
||||
const surfaceAnchors = new WeakMap();
|
||||
let operations = null;
|
||||
const workQueue = createWildlifeWorkQueue({
|
||||
requestIdle: services.requestIdleCallback,
|
||||
cancelIdle: services.cancelIdleCallback,
|
||||
onSlice: (slice) => services.performanceSlice?.(slice),
|
||||
});
|
||||
|
||||
function surfaceAnchor(row) {
|
||||
const old = surfaceAnchors.get(row);
|
||||
if (old && old.lat === row.lat && old.lon === row.lon) return old.anchor;
|
||||
const anchor = C.Cartesian3.fromDegrees(row.lon, row.lat);
|
||||
surfaceAnchors.set(row, { lat: row.lat, lon: row.lon, anchor });
|
||||
if (operations) operations.positionBuilds++;
|
||||
return anchor;
|
||||
}
|
||||
const requestRender = (reason) => {
|
||||
if (batchDepth) {
|
||||
pendingRenderReason = reason;
|
||||
return;
|
||||
}
|
||||
services.render?.governorRequestRender?.(`wildlife-sightings-${reason}`);
|
||||
};
|
||||
function beginBatch() {
|
||||
batchDepth += 1;
|
||||
}
|
||||
function endBatch() {
|
||||
batchDepth = Math.max(0, batchDepth - 1);
|
||||
if (batchDepth || !pendingRenderReason) return;
|
||||
const reason = pendingRenderReason;
|
||||
pendingRenderReason = null;
|
||||
requestRender(reason);
|
||||
}
|
||||
const surfaceRemovers = [];
|
||||
const tilesetRemovers = new Map();
|
||||
|
||||
// Reuse the shared ground cache. One bounded resolve lifts cold anchors
|
||||
// without per-sighting scene renders and pixel readback.
|
||||
let floorResolve = null;
|
||||
let floorColdPending = false;
|
||||
function position(row) {
|
||||
if (row.origin === 'acartia') return surfaceAnchor(row);
|
||||
const floor = services.groundFloor?.cachedGroundFloor?.(row.lat, row.lon);
|
||||
if (floor == null && !floorColdPending) {
|
||||
// Anchors are built after the rows publish; warm once the pass ends.
|
||||
floorColdPending = true;
|
||||
queueMicrotask(warmColdFloors);
|
||||
}
|
||||
return Number.isFinite(floor) && floor !== 0
|
||||
? C.Cartesian3.fromDegrees(row.lon, row.lat, floor)
|
||||
: surfaceAnchor(row);
|
||||
}
|
||||
|
||||
function warmColdFloors() {
|
||||
if (!floorColdPending || floorResolve) return;
|
||||
floorColdPending = false;
|
||||
const resolve = services.groundFloor?.resolveGroundFloorCellsBounded;
|
||||
if (!state.enabled || typeof resolve !== 'function') return;
|
||||
const points = state.renderedRows
|
||||
.filter((row) => row.origin !== 'acartia')
|
||||
.map((row) => ({ lat: row.lat, lon: row.lon }));
|
||||
if (!points.length) return;
|
||||
floorResolve = Promise.resolve(resolve(points))
|
||||
.catch(() => {})
|
||||
.then(() => {
|
||||
floorResolve = null;
|
||||
resampleAnchors();
|
||||
});
|
||||
}
|
||||
|
||||
function occluder() {
|
||||
const camera = state.viewer?.camera;
|
||||
return camera?.positionWC ? services.occluderFactory?.(camera) : null;
|
||||
}
|
||||
|
||||
function cull() {
|
||||
if (!state.enabled) return false;
|
||||
const horizon = occluder();
|
||||
let changed = false;
|
||||
// Only observation badges yield at adjacent bucket edges or to a painted
|
||||
// card. Density never participates in picking or icon spacing.
|
||||
for (const [id, point] of state.pointById) {
|
||||
const anchor = state.positions.get(id);
|
||||
const show =
|
||||
!photoCardIds.has(id) &&
|
||||
!crowdedBadgeIds.has(id) &&
|
||||
(!horizon || horizon.isPointVisible(anchor) === true);
|
||||
if (point.show === show) continue;
|
||||
point.show = show;
|
||||
changed = true;
|
||||
}
|
||||
if (changed) requestRender('cull');
|
||||
return changed;
|
||||
}
|
||||
|
||||
function updateBadgeSpacing() {
|
||||
return drainWildlifeWork(updateBadgeSpacingWork());
|
||||
}
|
||||
|
||||
function* updateBadgeSpacingWork() {
|
||||
yield 'rank';
|
||||
crowdedBadgeIds.clear();
|
||||
const buckets = new Map();
|
||||
const rows = [...state.renderedRows].sort(
|
||||
(a, b) =>
|
||||
wildlifeIconRelevance(b, state.selectedId) -
|
||||
wildlifeIconRelevance(a, state.selectedId) ||
|
||||
compareWildlifeIds(a.stableId, b.stableId),
|
||||
);
|
||||
yield 'rank';
|
||||
let visits = 0;
|
||||
for (const row of rows) {
|
||||
if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'rank';
|
||||
if (photoCardIds.has(row.stableId)) continue;
|
||||
const screen = badgeScreens.get(row.stableId);
|
||||
if (!screen) continue;
|
||||
const x = Math.floor(screen.x / WILDLIFE_BADGE_MAX_PX);
|
||||
const y = Math.floor(screen.y / WILDLIFE_BADGE_MAX_PX);
|
||||
let overlaps = false;
|
||||
for (let dx = -1; dx <= 1 && !overlaps; dx++) {
|
||||
for (let dy = -1; dy <= 1 && !overlaps; dy++) {
|
||||
for (const other of buckets.get((x + dx) * 65536 + y + dy) || []) {
|
||||
if (operations) operations.spacingTests++;
|
||||
if (
|
||||
(screen.x - other.x) ** 2 + (screen.y - other.y) ** 2 <
|
||||
WILDLIFE_BADGE_MAX_PX ** 2
|
||||
) {
|
||||
overlaps = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if (overlaps) crowdedBadgeIds.add(row.stableId);
|
||||
else {
|
||||
const key = x * 65536 + y;
|
||||
if (!buckets.has(key)) buckets.set(key, []);
|
||||
buckets.get(key).push(screen);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Called only when the host's painted membership changes, never per idle
|
||||
// frame. Requested/loading/rejected cards must leave their badges visible.
|
||||
function setPhotoCardVisibility(entryIds) {
|
||||
const next = new Set();
|
||||
for (const id of entryIds)
|
||||
if (id.startsWith('sighting:')) next.add(id.slice(9));
|
||||
const changed =
|
||||
next.size !== photoCardIds.size ||
|
||||
[...next].some((id) => !photoCardIds.has(id));
|
||||
photoCardIds.clear();
|
||||
for (const id of next) photoCardIds.add(id);
|
||||
if (!state.enabled) return;
|
||||
updateBadgeSpacing();
|
||||
cull();
|
||||
// A painted thumbnail already names its sighting; drop the repeat label.
|
||||
if (changed) parts.selection?.photoCardsChanged?.();
|
||||
}
|
||||
|
||||
function resampleAnchors() {
|
||||
if (!state.enabled || !state.points) return;
|
||||
let changed = false;
|
||||
for (const row of state.renderedRows) {
|
||||
if (row.origin === 'acartia') continue;
|
||||
const point = state.pointById.get(row.stableId);
|
||||
if (!point) continue;
|
||||
const anchor = position(row);
|
||||
if (C.Cartesian3.equals(anchor, state.positions.get(row.stableId)))
|
||||
continue;
|
||||
point.position = anchor;
|
||||
state.positions.set(row.stableId, anchor);
|
||||
changed = true;
|
||||
}
|
||||
if (!changed) return;
|
||||
beginBatch();
|
||||
try {
|
||||
cull();
|
||||
parts.selection.refreshAmbient();
|
||||
parts.selection.publishSelected();
|
||||
parts.selection.notify?.();
|
||||
parts.selection.refreshContexts();
|
||||
requestRender('terrain');
|
||||
} finally {
|
||||
endBatch();
|
||||
}
|
||||
}
|
||||
|
||||
function trackTileset(primitive) {
|
||||
if (
|
||||
tilesetRemovers.has(primitive) ||
|
||||
typeof primitive?.allTilesLoaded?.addEventListener !== 'function'
|
||||
)
|
||||
return false;
|
||||
tilesetRemovers.set(
|
||||
primitive,
|
||||
primitive.allTilesLoaded.addEventListener(resampleAnchors),
|
||||
);
|
||||
return true;
|
||||
}
|
||||
|
||||
function deactivate() {
|
||||
workQueue.cancel();
|
||||
operations = null;
|
||||
for (const remove of surfaceRemovers.splice(0)) remove?.();
|
||||
for (const remove of tilesetRemovers.values()) remove?.();
|
||||
tilesetRemovers.clear();
|
||||
}
|
||||
|
||||
function activate() {
|
||||
deactivate();
|
||||
if (!state.enabled || !state.viewer) return;
|
||||
const scene = state.viewer.scene;
|
||||
const refreshBadgeImages = () => {
|
||||
if (!state.enabled) return;
|
||||
appearances.clear();
|
||||
if (billboards?.refreshImages((group) => badgeSprites.get(group)))
|
||||
requestRender('font-ready');
|
||||
};
|
||||
surfaceRemovers.push(badgeSprites.subscribe(refreshBadgeImages));
|
||||
refreshBadgeImages();
|
||||
const ownEvent = (event, listener) => {
|
||||
const remove = event?.addEventListener?.(listener);
|
||||
if (typeof remove === 'function') surfaceRemovers.push(remove);
|
||||
};
|
||||
ownEvent(scene.globe?.tileLoadProgressEvent, (pending) => {
|
||||
if (pending === 0) resampleAnchors();
|
||||
});
|
||||
// Scene forwards the globe event in Cesium; deduplicate that alias.
|
||||
for (const event of new Set([
|
||||
scene.terrainProviderChanged,
|
||||
scene.globe?.terrainProviderChanged,
|
||||
]))
|
||||
ownEvent(event, resampleAnchors);
|
||||
const primitives = scene.primitives;
|
||||
for (let i = 0; i < (primitives?.length || 0); i++)
|
||||
trackTileset(primitives.get(i));
|
||||
ownEvent(primitives?.primitiveAdded, (primitive) => {
|
||||
if (trackTileset(primitive)) resampleAnchors();
|
||||
});
|
||||
ownEvent(primitives?.primitiveRemoved, (primitive) => {
|
||||
if (!tilesetRemovers.has(primitive)) return;
|
||||
tilesetRemovers.get(primitive)?.();
|
||||
tilesetRemovers.delete(primitive);
|
||||
resampleAnchors();
|
||||
});
|
||||
services.eventTarget?.addEventListener?.(
|
||||
'gev:map-stack-changed',
|
||||
resampleAnchors,
|
||||
);
|
||||
surfaceRemovers.push(() =>
|
||||
services.eventTarget?.removeEventListener?.(
|
||||
'gev:map-stack-changed',
|
||||
resampleAnchors,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
function removeCell(primitive) {
|
||||
const owners =
|
||||
state.viewer?.scene?.groundPrimitives || state.viewer?.scene?.primitives;
|
||||
if (owners?.remove?.(primitive) !== true && !primitive.isDestroyed?.())
|
||||
primitive.destroy?.();
|
||||
}
|
||||
|
||||
function cancelStaging() {
|
||||
const pending = state.staging;
|
||||
if (!pending) return;
|
||||
state.staging = null;
|
||||
pending.remove?.();
|
||||
for (const primitive of pending.primitives) removeCell(primitive);
|
||||
}
|
||||
|
||||
function clearCells() {
|
||||
cancelStaging();
|
||||
for (const primitive of state.cells) removeCell(primitive);
|
||||
state.cells = [];
|
||||
cellsSignature = null;
|
||||
}
|
||||
|
||||
function stageCells(rows) {
|
||||
const cellsVisible = state.band === 'cells' || state.band === 'cards';
|
||||
const unique = new Map();
|
||||
if (cellsVisible) {
|
||||
for (const row of rows) {
|
||||
if (!row.cell) continue;
|
||||
const cell = row.cell;
|
||||
const key = `${cell.south},${cell.west},${cell.north},${cell.east}:${wildlifeAccent(row.iconic)}`;
|
||||
if (!unique.has(key)) unique.set(key, row);
|
||||
}
|
||||
}
|
||||
const signature = JSON.stringify([...unique.keys()].sort());
|
||||
if (signature === cellsSignature) return false;
|
||||
cancelStaging();
|
||||
if (!unique.size) {
|
||||
clearCells();
|
||||
cellsSignature = signature;
|
||||
return true;
|
||||
}
|
||||
cellsSignature = signature;
|
||||
const fills = [];
|
||||
const outlines = [];
|
||||
for (const row of unique.values()) {
|
||||
const { south, west, north, east } = row.cell;
|
||||
const tint = C.Color.fromCssColorString(wildlifeAccent(row.iconic));
|
||||
fills.push(
|
||||
new C.GeometryInstance({
|
||||
geometry: new C.RectangleGeometry({
|
||||
rectangle: C.Rectangle.fromDegrees(west, south, east, north),
|
||||
vertexFormat: C.PerInstanceColorAppearance.VERTEX_FORMAT,
|
||||
}),
|
||||
attributes: {
|
||||
color: C.ColorGeometryInstanceAttribute.fromColor(
|
||||
tint.withAlpha(0.25),
|
||||
),
|
||||
},
|
||||
}),
|
||||
);
|
||||
outlines.push(
|
||||
new C.GeometryInstance({
|
||||
geometry: new C.GroundPolylineGeometry({
|
||||
positions: C.Cartesian3.fromDegreesArray([
|
||||
west,
|
||||
south,
|
||||
east,
|
||||
south,
|
||||
east,
|
||||
north,
|
||||
west,
|
||||
north,
|
||||
west,
|
||||
south,
|
||||
]),
|
||||
width: 2,
|
||||
}),
|
||||
attributes: {
|
||||
color: C.ColorGeometryInstanceAttribute.fromColor(
|
||||
tint.withAlpha(0.8),
|
||||
),
|
||||
},
|
||||
}),
|
||||
);
|
||||
}
|
||||
// Hidden primitives still compile their geometry. Poll only these two
|
||||
// nonempty batches, then atomically retire the previous privacy cells.
|
||||
const primitives = [
|
||||
new C.GroundPrimitive({
|
||||
geometryInstances: fills,
|
||||
appearance: new C.PerInstanceColorAppearance({
|
||||
flat: true,
|
||||
translucent: true,
|
||||
}),
|
||||
classificationType: C.ClassificationType.BOTH,
|
||||
allowPicking: false,
|
||||
releaseGeometryInstances: false,
|
||||
show: false,
|
||||
}),
|
||||
new C.GroundPolylinePrimitive({
|
||||
geometryInstances: outlines,
|
||||
appearance: new C.PolylineColorAppearance(),
|
||||
classificationType: C.ClassificationType.BOTH,
|
||||
allowPicking: false,
|
||||
releaseGeometryInstances: false,
|
||||
show: false,
|
||||
}),
|
||||
];
|
||||
const owners =
|
||||
state.viewer.scene.groundPrimitives || state.viewer.scene.primitives;
|
||||
for (const primitive of primitives) owners.add(primitive);
|
||||
const pending = { primitives, remove: null, checks: 0 };
|
||||
state.staging = pending;
|
||||
const ready = () => {
|
||||
if (state.staging !== pending || !state.enabled) return;
|
||||
if (!primitives.every((primitive) => primitive.ready === true)) {
|
||||
pending.checks += 1;
|
||||
if (pending.checks >= WILDLIFE_GROUND_READY_MAX_CHECKS) {
|
||||
cancelStaging();
|
||||
cellsSignature = null;
|
||||
return;
|
||||
}
|
||||
requestRender('staging');
|
||||
return;
|
||||
}
|
||||
pending.remove?.();
|
||||
state.staging = null;
|
||||
for (const primitive of state.cells) removeCell(primitive);
|
||||
state.cells = primitives;
|
||||
for (const primitive of primitives) primitive.show = true;
|
||||
requestRender('render');
|
||||
};
|
||||
pending.remove = state.viewer.scene.postRender?.addEventListener?.(ready);
|
||||
ready();
|
||||
return true;
|
||||
}
|
||||
|
||||
function init() {
|
||||
density = createWildlifeDensity({
|
||||
cesium: C,
|
||||
viewer: state.viewer,
|
||||
positionForCell: surfaceAnchor,
|
||||
requestRender,
|
||||
setTimer: services.setTimer,
|
||||
clearTimer: services.clearTimer,
|
||||
requestIdle: services.requestIdleCallback,
|
||||
cancelIdle: services.cancelIdleCallback,
|
||||
eventTarget: services.eventTarget,
|
||||
});
|
||||
state.points = new C.BillboardCollection();
|
||||
state.points.show = false;
|
||||
state.viewer.scene.primitives.add(state.points);
|
||||
services.sprites?.registerSpriteCollection?.(
|
||||
'wildlife-sightings',
|
||||
state.points,
|
||||
);
|
||||
const distanceScale = new C.NearFarScalar(...WILDLIFE_SCALE_BY_DISTANCE);
|
||||
billboards = createWildlifeBillboardModel({
|
||||
collection: state.points,
|
||||
pointById: state.pointById,
|
||||
positions: state.positions,
|
||||
positionForRow: position,
|
||||
appearanceForGroup(group) {
|
||||
if (!appearances.has(group))
|
||||
appearances.set(group, {
|
||||
image: badgeSprites.get(group),
|
||||
width: WILDLIFE_SPRITE_PX,
|
||||
height: WILDLIFE_SPRITE_PX,
|
||||
// The sprite includes its tint and white glyph. Multiplication
|
||||
// by a taxon colour would tint the glyph as well.
|
||||
color: C.Color.WHITE,
|
||||
scale: 1,
|
||||
scaleByDistance: distanceScale,
|
||||
disableDepthTestDistance: Number.POSITIVE_INFINITY,
|
||||
});
|
||||
return appearances.get(group);
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function rebuild() {
|
||||
if (!state.enabled || !state.points) return false;
|
||||
workQueue.cancel();
|
||||
operations = null;
|
||||
const work = rebuildWork();
|
||||
if (
|
||||
(state.gridCells?.length || 0) > WILDLIFE_SYNC_CELL_LIMIT ||
|
||||
state.rows.size > WILDLIFE_SYNC_CELL_LIMIT
|
||||
) {
|
||||
workQueue.start(work, () => {
|
||||
if (!state.enabled) return;
|
||||
parts.selection.refreshAmbient();
|
||||
parts.selection.publishSelected();
|
||||
parts.selection.refreshContexts();
|
||||
parts.selection.syncCredits?.();
|
||||
parts.selection.notify?.();
|
||||
parts.controls?.notify?.();
|
||||
});
|
||||
return 'pending';
|
||||
}
|
||||
return drainWildlifeWork(work);
|
||||
}
|
||||
|
||||
function* rebuildWork() {
|
||||
operations = {
|
||||
positionBuilds: 0,
|
||||
spacingTests: 0,
|
||||
billboardVisits: 0,
|
||||
billboardWrites: 0,
|
||||
};
|
||||
const nowMs = services.now();
|
||||
const taxa = state.drawnParams?.taxa ?? state.taxa;
|
||||
const scene = state.viewer.scene;
|
||||
const horizon = occluder();
|
||||
const densityResult = yield* density.updateWork(
|
||||
state.gridAvailable ? state.gridCells || [] : [],
|
||||
{
|
||||
boxes: state.query?.visibleBoxes ?? state.query?.boxes,
|
||||
isPointVisible: horizon
|
||||
? (anchor) => horizon.isPointVisible(anchor) === true
|
||||
: null,
|
||||
onOperations: (counts) => Object.assign(operations, counts),
|
||||
},
|
||||
);
|
||||
if (densityResult.changed)
|
||||
services.sprites?.restoreSpriteOrder?.(state.viewer);
|
||||
const model = yield* wildlifeIconModelWork({
|
||||
rows: [...state.rows.values()].filter(
|
||||
(row) =>
|
||||
row.stableId === state.selectedId ||
|
||||
isRecentWildlifeSighting(row, nowMs, taxa),
|
||||
),
|
||||
boxes: state.query?.visibleBoxes ?? state.query?.boxes,
|
||||
selectedId: state.selectedId,
|
||||
selectedRow: state.selectedRow,
|
||||
preferredIds: state.ambientIds,
|
||||
onOperations: (counts) => Object.assign(operations, counts),
|
||||
projectRow:
|
||||
typeof services.project === 'function'
|
||||
? (row) => {
|
||||
const anchor = surfaceAnchor(row);
|
||||
const cached = surfaceAnchors.get(row);
|
||||
cached.screen = null;
|
||||
if (horizon && horizon.isPointVisible(anchor) !== true)
|
||||
return null;
|
||||
const screen = services.project(scene, anchor);
|
||||
if (
|
||||
!screen ||
|
||||
screen.x < 0 ||
|
||||
screen.y < 0 ||
|
||||
screen.x >= (scene.canvas?.clientWidth ?? Infinity) ||
|
||||
screen.y >= (scene.canvas?.clientHeight ?? Infinity)
|
||||
)
|
||||
return null;
|
||||
cached.screen = screen;
|
||||
return screen;
|
||||
}
|
||||
: null,
|
||||
});
|
||||
yield 'rank';
|
||||
badgeScreens.clear();
|
||||
for (const row of model.rows) {
|
||||
const screen = surfaceAnchors.get(row)?.screen;
|
||||
if (screen) badgeScreens.set(row.stableId, screen);
|
||||
}
|
||||
state.renderPipelineOperations = operations;
|
||||
state.renderedRows = model.rows;
|
||||
yield* updateBadgeSpacingWork();
|
||||
yield 'rank';
|
||||
state.sightingCount = state.gridAvailable
|
||||
? Math.max(
|
||||
densityResult.sightingCount,
|
||||
model.sightingCount - model.acartiaCount,
|
||||
) + model.acartiaCount
|
||||
: model.sightingCount;
|
||||
const previousRows = state.rowById;
|
||||
state.rowById = new Map(
|
||||
state.renderedRows.map((row) => [row.stableId, row]),
|
||||
);
|
||||
// Panning can bring two visible photo incumbents into one icon bucket.
|
||||
// Keep the single billboard winner, but preserve both card identities and
|
||||
// anchors until selection's front-side/window/height checks release them.
|
||||
const ambientAnchors = new Map();
|
||||
for (const incumbent of state.ambientRows || []) {
|
||||
const row = state.rows.get(incumbent.stableId);
|
||||
if (!row || !isRecentWildlifeSighting(row, nowMs, taxa)) continue;
|
||||
if (state.rowById.has(row.stableId)) continue;
|
||||
const old = previousRows.get(row.stableId);
|
||||
const cached = state.positions.get(row.stableId);
|
||||
ambientAnchors.set(
|
||||
row.stableId,
|
||||
cached && old?.lat === row.lat && old?.lon === row.lon
|
||||
? cached
|
||||
: position(row),
|
||||
);
|
||||
state.rowById.set(row.stableId, row);
|
||||
}
|
||||
function restoreAmbientAnchors() {
|
||||
for (const id of ambientAnchorIds)
|
||||
if (!ambientAnchors.has(id) && !state.pointById.has(id))
|
||||
state.positions.delete(id);
|
||||
for (const [id, anchor] of ambientAnchors)
|
||||
state.positions.set(id, anchor);
|
||||
ambientAnchorIds = new Set(ambientAnchors.keys());
|
||||
}
|
||||
if (state.selectedId && !state.rowById.has(state.selectedId))
|
||||
parts.selection.clear();
|
||||
yield 'billboard-update';
|
||||
const billboardUpdate = yield* billboards.updateWork(state.renderedRows, {
|
||||
onOperations: (counts) => Object.assign(operations, counts),
|
||||
});
|
||||
yield 'overlay-publish';
|
||||
let changed = densityResult.changed;
|
||||
beginBatch();
|
||||
try {
|
||||
restoreAmbientAnchors();
|
||||
changed = stageCells(state.renderedRows) || changed;
|
||||
changed = cull() || changed;
|
||||
if (
|
||||
billboardUpdate.created ||
|
||||
billboardUpdate.removed ||
|
||||
billboardUpdate.writes
|
||||
)
|
||||
changed = true;
|
||||
if (changed) requestRender('render');
|
||||
} finally {
|
||||
endBatch();
|
||||
}
|
||||
services.performanceOperations?.(operations);
|
||||
operations = null;
|
||||
return changed;
|
||||
}
|
||||
|
||||
function refreshSelection() {
|
||||
if (!state.enabled || !billboards) return false;
|
||||
// Selection changes spacing priority without reprojecting the view.
|
||||
updateBadgeSpacing();
|
||||
return cull();
|
||||
}
|
||||
|
||||
function clear() {
|
||||
workQueue.cancel();
|
||||
operations = null;
|
||||
clearCells();
|
||||
density?.clear();
|
||||
billboards?.clear();
|
||||
if (state.points) state.points.show = false;
|
||||
state.pointById.clear();
|
||||
state.positions.clear();
|
||||
state.renderedRows = [];
|
||||
state.rowById.clear();
|
||||
state.sightingCount = 0;
|
||||
ambientAnchorIds.clear();
|
||||
badgeScreens.clear();
|
||||
crowdedBadgeIds.clear();
|
||||
photoCardIds.clear();
|
||||
}
|
||||
|
||||
function destroy() {
|
||||
deactivate();
|
||||
clear();
|
||||
services.sprites?.unregisterSpriteCollection?.(
|
||||
'wildlife-sightings',
|
||||
state.points,
|
||||
);
|
||||
if (state.points) state.viewer?.scene?.primitives?.remove?.(state.points);
|
||||
state.points = null;
|
||||
billboards = null;
|
||||
density?.destroy();
|
||||
density = null;
|
||||
appearances.clear();
|
||||
}
|
||||
|
||||
return {
|
||||
get density() {
|
||||
return density;
|
||||
},
|
||||
get pending() {
|
||||
return workQueue.pending;
|
||||
},
|
||||
init,
|
||||
activate,
|
||||
deactivate,
|
||||
occluder,
|
||||
cull,
|
||||
rebuild,
|
||||
refreshSelection,
|
||||
setPhotoCardVisibility,
|
||||
hasPhotoCard: (id) => photoCardIds.has(id),
|
||||
clear,
|
||||
destroy,
|
||||
requestRender,
|
||||
beginBatch,
|
||||
endBatch,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,544 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import * as Cesium from 'cesium';
|
||||
import { createRendering } from './rendering.js';
|
||||
import { nearFarScalarValueAtDistance } from '../../data/focusDeemphasis.js';
|
||||
import { wildlifeGridCellId } from './gridViewport.js';
|
||||
import {
|
||||
WILDLIFE_GROUND_READY_MAX_CHECKS,
|
||||
WILDLIFE_SCALE_BY_DISTANCE,
|
||||
} from './policy.js';
|
||||
|
||||
const NOW = Date.parse('2026-11-04T18:00:00Z');
|
||||
const base = {
|
||||
stableId: 'synthetic:1',
|
||||
origin: 'inaturalist',
|
||||
lat: 47.6,
|
||||
lon: -122.3,
|
||||
iconic: 'Aves',
|
||||
observedAt: NOW - 60_000,
|
||||
quality: 'research',
|
||||
count: null,
|
||||
obscured: false,
|
||||
cell: null,
|
||||
};
|
||||
|
||||
function event() {
|
||||
const listeners = new Set();
|
||||
return {
|
||||
addEventListener(listener) {
|
||||
listeners.add(listener);
|
||||
return () => listeners.delete(listener);
|
||||
},
|
||||
emit(...args) {
|
||||
for (const listener of [...listeners]) listener(...args);
|
||||
},
|
||||
get size() {
|
||||
return listeners.size;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function harness(rows = [base], extra = {}) {
|
||||
const counts = {
|
||||
collections: 0,
|
||||
created: 0,
|
||||
removed: 0,
|
||||
cleared: 0,
|
||||
writes: [],
|
||||
};
|
||||
const tracked = new Set([
|
||||
'position',
|
||||
'image',
|
||||
'color',
|
||||
'scale',
|
||||
'show',
|
||||
'width',
|
||||
'height',
|
||||
'scaleByDistance',
|
||||
]);
|
||||
class BillboardCollection extends Cesium.BillboardCollection {
|
||||
constructor() {
|
||||
super();
|
||||
counts.collections += 1;
|
||||
}
|
||||
add(options) {
|
||||
counts.created += 1;
|
||||
const point = super.add(options);
|
||||
return new Proxy(point, {
|
||||
get: (target, key) => Reflect.get(target, key, target),
|
||||
set(target, key, value) {
|
||||
if (tracked.has(key)) counts.writes.push(key);
|
||||
return Reflect.set(target, key, value, target);
|
||||
},
|
||||
});
|
||||
}
|
||||
remove(point) {
|
||||
counts.removed += 1;
|
||||
return super.remove(point);
|
||||
}
|
||||
removeAll() {
|
||||
counts.cleared += 1;
|
||||
return super.removeAll();
|
||||
}
|
||||
}
|
||||
class GroundBatch {
|
||||
constructor(options) {
|
||||
Object.assign(this, options);
|
||||
this.ready = false;
|
||||
}
|
||||
destroy() {
|
||||
this.destroyed = true;
|
||||
}
|
||||
isDestroyed() {
|
||||
return this.destroyed === true;
|
||||
}
|
||||
}
|
||||
function primitives() {
|
||||
const values = [];
|
||||
return {
|
||||
values,
|
||||
get length() {
|
||||
return values.length;
|
||||
},
|
||||
get: (i) => values[i],
|
||||
add(primitive) {
|
||||
values.push(primitive);
|
||||
return primitive;
|
||||
},
|
||||
remove(primitive) {
|
||||
const i = values.indexOf(primitive);
|
||||
if (i < 0) return false;
|
||||
values.splice(i, 1);
|
||||
primitive.destroy();
|
||||
return true;
|
||||
},
|
||||
};
|
||||
}
|
||||
const postRender = event();
|
||||
const terrain = event();
|
||||
const tileProgress = event();
|
||||
const scene = {
|
||||
primitives: primitives(),
|
||||
groundPrimitives: primitives(),
|
||||
postRender,
|
||||
terrainProviderChanged: terrain,
|
||||
globe: {
|
||||
terrainProviderChanged: terrain,
|
||||
tileLoadProgressEvent: tileProgress,
|
||||
},
|
||||
};
|
||||
const state = {
|
||||
enabled: true,
|
||||
viewer: { scene, camera: { positionWC: {} } },
|
||||
rows: new Map(rows.map((row) => [row.stableId, row])),
|
||||
renderedRows: [],
|
||||
rowById: new Map(),
|
||||
pointById: new Map(),
|
||||
positions: new Map(),
|
||||
cells: [],
|
||||
staging: null,
|
||||
taxa: 'all',
|
||||
selectedId: null,
|
||||
query: { visibleBoxes: [{ south: -90, west: -180, north: 90, east: 180 }] },
|
||||
band: 'cards',
|
||||
};
|
||||
const renders = [];
|
||||
let visible = true;
|
||||
const registration = new Set();
|
||||
const rendering = createRendering({
|
||||
state,
|
||||
services: {
|
||||
now: () => NOW,
|
||||
cesium: {
|
||||
...Cesium,
|
||||
BillboardCollection,
|
||||
GroundPrimitive: GroundBatch,
|
||||
GroundPolylinePrimitive: GroundBatch,
|
||||
},
|
||||
occluderFactory: () => ({ isPointVisible: () => visible }),
|
||||
render: { governorRequestRender: (reason) => renders.push(reason) },
|
||||
sprites: {
|
||||
registerSpriteCollection: (_id, value) => registration.add(value),
|
||||
unregisterSpriteCollection: (_id, value) => registration.delete(value),
|
||||
},
|
||||
...extra,
|
||||
},
|
||||
parts: {
|
||||
selection: {
|
||||
clear() {
|
||||
state.selectedId = null;
|
||||
},
|
||||
refreshAmbient() {},
|
||||
publishSelected() {},
|
||||
refreshContexts() {},
|
||||
},
|
||||
},
|
||||
});
|
||||
rendering.init();
|
||||
rendering.activate();
|
||||
return {
|
||||
state,
|
||||
scene,
|
||||
rendering,
|
||||
counts,
|
||||
renders,
|
||||
postRender,
|
||||
terrain,
|
||||
tileProgress,
|
||||
registration,
|
||||
visible(value) {
|
||||
visible = value;
|
||||
},
|
||||
rows(next) {
|
||||
state.rows = new Map(next.map((row) => [row.stableId, row]));
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('real Cesium billboard values update in place, and unchanged refreshes write nothing', () => {
|
||||
const second = { ...base, stableId: 'synthetic:2', lon: -120 };
|
||||
const h = harness([base, second]);
|
||||
h.rendering.rebuild();
|
||||
const collection = h.state.points;
|
||||
const incumbent = h.state.pointById.get(base.stableId);
|
||||
assert.equal(h.counts.collections, 1);
|
||||
assert.equal(h.counts.created, 2);
|
||||
assert.equal(incumbent.width * incumbent.scaleByDistance.farValue, 12);
|
||||
assert.deepEqual(
|
||||
incumbent.scaleByDistance,
|
||||
new Cesium.NearFarScalar(...WILDLIFE_SCALE_BY_DISTANCE),
|
||||
);
|
||||
assert.equal(incumbent.color.alpha, 1);
|
||||
h.counts.writes.length = 0;
|
||||
h.renders.length = 0;
|
||||
h.rows([{ ...second }, { ...base }]);
|
||||
assert.equal(h.rendering.rebuild(), false);
|
||||
assert.equal(h.rendering.cull(), false);
|
||||
assert.deepEqual(h.counts.writes, []);
|
||||
assert.deepEqual(h.renders, []);
|
||||
h.rows([{ ...base, lat: base.lat + 0.01 }, second]);
|
||||
assert.equal(h.rendering.rebuild(), true);
|
||||
assert.deepEqual(h.counts.writes, ['position']);
|
||||
assert.equal(h.state.pointById.get(base.stableId), incumbent);
|
||||
assert.equal(h.state.points, collection);
|
||||
h.rows([
|
||||
{ ...base, lat: base.lat + 0.01 },
|
||||
{ ...second, stableId: 'synthetic:3' },
|
||||
]);
|
||||
h.rendering.rebuild();
|
||||
assert.equal(h.counts.created, 3);
|
||||
assert.equal(h.counts.removed, 1);
|
||||
assert.equal(h.counts.cleared, 0);
|
||||
h.rendering.destroy();
|
||||
assert.equal(h.registration.size, 0);
|
||||
assert.equal(h.scene.primitives.length, 0);
|
||||
assert.equal(h.state.pointById.size, 0);
|
||||
assert.equal(h.terrain.size, 0);
|
||||
assert.equal(h.tileProgress.size, 0);
|
||||
});
|
||||
|
||||
test('horizon changes write only changed visibility, with one governor request per batch', () => {
|
||||
const h = harness();
|
||||
h.rendering.rebuild();
|
||||
h.counts.writes.length = 0;
|
||||
h.renders.length = 0;
|
||||
h.visible(false);
|
||||
h.rendering.beginBatch();
|
||||
h.rendering.cull();
|
||||
h.rendering.requestRender('labels');
|
||||
h.rendering.endBatch();
|
||||
assert.deepEqual(h.counts.writes, ['show']);
|
||||
assert.equal(h.renders.length, 1);
|
||||
h.rendering.cull();
|
||||
assert.deepEqual(h.counts.writes, ['show']);
|
||||
assert.equal(h.renders.length, 1);
|
||||
h.rendering.destroy();
|
||||
});
|
||||
|
||||
test('badge pixels stay between 12 and 22 at near, mid and far heights, including selection', () => {
|
||||
const h = harness();
|
||||
h.rendering.rebuild();
|
||||
const wildlife = h.state.pointById.get(base.stableId);
|
||||
for (const selectedId of [null, base.stableId]) {
|
||||
h.state.selectedId = selectedId;
|
||||
h.rendering.refreshSelection();
|
||||
for (const heightM of [
|
||||
0, 1000, 9000, 120_000, 400_000, 1_500_000, 8_000_000, 10_000_000,
|
||||
]) {
|
||||
const pixels =
|
||||
wildlife.width *
|
||||
wildlife.scale *
|
||||
nearFarScalarValueAtDistance(wildlife.scaleByDistance, heightM);
|
||||
assert.ok(
|
||||
pixels >= 12 && pixels <= 22,
|
||||
`${heightM}m, selected=${!!selectedId}: ${pixels}px`,
|
||||
);
|
||||
}
|
||||
}
|
||||
assert.deepEqual(
|
||||
wildlife.color,
|
||||
Cesium.Color.WHITE,
|
||||
'keep the baked white glyph white',
|
||||
);
|
||||
h.rendering.destroy();
|
||||
});
|
||||
|
||||
test('adjacent 28px bucket edges never overlap badges or erase sighting counts', () => {
|
||||
const rows = [27, 29, 56, 84].map((x, i) => ({
|
||||
...base,
|
||||
stableId: `edge:${i}`,
|
||||
lon: base.lon + i * 0.01,
|
||||
x,
|
||||
}));
|
||||
const h = harness(rows, {
|
||||
project: (_scene, anchor) => {
|
||||
const lon = Cesium.Math.toDegrees(
|
||||
Cesium.Cartographic.fromCartesian(anchor).longitude,
|
||||
);
|
||||
return {
|
||||
x: rows.find((row) => Math.abs(row.lon - lon) < 1e-7).x,
|
||||
y: 100,
|
||||
};
|
||||
},
|
||||
});
|
||||
h.rendering.rebuild();
|
||||
assert.equal(h.state.sightingCount, 4);
|
||||
assert.equal(
|
||||
h.state.pointById.size,
|
||||
4,
|
||||
'all occupied buckets retain their identities',
|
||||
);
|
||||
const visible = rows.filter(
|
||||
(row) => h.state.pointById.get(row.stableId).show,
|
||||
);
|
||||
assert.equal(visible.length, 3);
|
||||
for (let i = 0; i < visible.length; i++)
|
||||
for (let j = i + 1; j < visible.length; j++)
|
||||
assert.ok(Math.abs(visible[i].x - visible[j].x) >= 22);
|
||||
h.counts.writes.length = 0;
|
||||
h.renders.length = 0;
|
||||
h.rendering.rebuild();
|
||||
h.rendering.cull();
|
||||
assert.deepEqual(h.counts.writes, []);
|
||||
assert.deepEqual(h.renders, []);
|
||||
h.rendering.destroy();
|
||||
});
|
||||
|
||||
test('only painted photo cards hide their anchored badges, with zero repeated visibility writes', () => {
|
||||
const h = harness();
|
||||
h.rendering.rebuild();
|
||||
const point = h.state.pointById.get(base.stableId);
|
||||
assert.equal(
|
||||
point.show,
|
||||
true,
|
||||
'a requested or loading card does not hide its badge',
|
||||
);
|
||||
h.counts.writes.length = 0;
|
||||
h.renders.length = 0;
|
||||
h.rendering.setPhotoCardVisibility(new Set([`sighting:${base.stableId}`]));
|
||||
assert.equal(point.show, false);
|
||||
assert.deepEqual(h.counts.writes, ['show']);
|
||||
h.rendering.rebuild();
|
||||
h.rendering.cull();
|
||||
h.rendering.setPhotoCardVisibility(new Set([`sighting:${base.stableId}`]));
|
||||
assert.deepEqual(h.counts.writes, ['show']);
|
||||
assert.equal(h.renders.length, 1);
|
||||
h.rendering.setPhotoCardVisibility(new Set());
|
||||
assert.equal(
|
||||
point.show,
|
||||
true,
|
||||
'a card that no longer paints restores its badge',
|
||||
);
|
||||
assert.deepEqual(h.counts.writes, ['show', 'show']);
|
||||
h.rendering.destroy();
|
||||
});
|
||||
|
||||
test('sampled fallback buckets allocate only representatives at every height, with zero idle writes', () => {
|
||||
for (const heightM of [1000, 7_000_000]) {
|
||||
const rows = ['a', 'b', 'c'].map((id, index) => ({
|
||||
...base,
|
||||
stableId: `synthetic:${id}`,
|
||||
lon: base.lon + index * 0.01,
|
||||
}));
|
||||
const screens = new Map(
|
||||
rows.map((row) => [row.lon.toFixed(6), { x: 100, y: 100 }]),
|
||||
);
|
||||
const h = harness(rows, {
|
||||
project: (_scene, anchor) => {
|
||||
const lon = Cesium.Math.toDegrees(
|
||||
Cesium.Cartographic.fromCartesian(anchor).longitude,
|
||||
);
|
||||
return screens.get(lon.toFixed(6));
|
||||
},
|
||||
});
|
||||
h.state.viewer.camera.positionWC = Cesium.Cartesian3.fromDegrees(
|
||||
base.lon,
|
||||
base.lat,
|
||||
heightM,
|
||||
);
|
||||
h.rendering.rebuild();
|
||||
assert.equal(
|
||||
h.state.pointById.size,
|
||||
1,
|
||||
'same bucket reduction near and far',
|
||||
);
|
||||
assert.equal(h.counts.created, 1);
|
||||
screens.set(rows[2].lon.toFixed(6), { x: 200, y: 100 });
|
||||
assert.equal(h.rendering.cull(), false);
|
||||
h.rendering.rebuild(); // moveEnd recomputes buckets, never an idle frame.
|
||||
assert.equal(h.state.pointById.size, 2);
|
||||
assert.equal(h.counts.created, 2);
|
||||
h.counts.writes.length = 0;
|
||||
assert.equal(h.rendering.cull(), false);
|
||||
assert.equal(h.rendering.rebuild(), false);
|
||||
assert.deepEqual(h.counts.writes, []);
|
||||
assert.equal(h.postRender.size, 0);
|
||||
h.rendering.destroy();
|
||||
}
|
||||
});
|
||||
|
||||
test('UTFGrid creates a dedicated unpickable glow and observations alone create badges', () => {
|
||||
let projections = 0;
|
||||
const h = harness([base], {
|
||||
project() {
|
||||
projections++;
|
||||
return { x: 100, y: 100 };
|
||||
},
|
||||
});
|
||||
h.scene.canvas = { clientWidth: 280, clientHeight: 200 };
|
||||
h.state.gridAvailable = true;
|
||||
h.state.gridCells = [1, 50, 2].map((cellCount, index) => ({
|
||||
id: wildlifeGridCellId(base.lat, base.lon + index * 0.01, 16),
|
||||
lat: base.lat,
|
||||
lon: base.lon + index * 0.01,
|
||||
cellCount,
|
||||
}));
|
||||
h.rendering.rebuild();
|
||||
const glow = h.rendering.density.collection;
|
||||
assert.ok(glow);
|
||||
assert.equal(glow.allowPicking, false);
|
||||
assert.equal(glow.length, 3);
|
||||
assert.equal(h.scene.primitives.length, 2);
|
||||
assert.deepEqual([...h.state.pointById.keys()], [base.stableId]);
|
||||
assert.deepEqual(h.state.renderedRows, [base]);
|
||||
assert.equal(h.state.sightingCount, 53);
|
||||
assert.equal(projections, 1, 'only observations require screen projections');
|
||||
assert.equal(h.postRender.size, 0, 'density installs no frame listener');
|
||||
h.state.gridCells = [...h.state.gridCells].reverse();
|
||||
h.counts.writes.length = 0;
|
||||
assert.equal(h.rendering.rebuild(), false);
|
||||
assert.equal(h.rendering.density.collection, glow);
|
||||
assert.deepEqual(h.counts.writes, []);
|
||||
h.rendering.clear();
|
||||
assert.equal(glow.isDestroyed(), true);
|
||||
assert.equal(h.scene.primitives.length, 1);
|
||||
assert.equal(h.state.points.length, 0);
|
||||
h.rendering.destroy();
|
||||
assert.equal(h.scene.primitives.length, 0);
|
||||
});
|
||||
|
||||
test('tile arrival or loss cannot replace a real observation with a grid badge', () => {
|
||||
const h = harness();
|
||||
h.rendering.rebuild();
|
||||
const badge = h.state.pointById.get(base.stableId);
|
||||
h.state.gridAvailable = true;
|
||||
h.state.gridCells = [
|
||||
{
|
||||
id: wildlifeGridCellId(base.lat, base.lon, 2),
|
||||
lat: base.lat,
|
||||
lon: base.lon,
|
||||
cellCount: 10_000,
|
||||
},
|
||||
];
|
||||
h.rendering.rebuild();
|
||||
const glow = h.rendering.density.collection;
|
||||
assert.equal(h.state.sightingCount, 10_000);
|
||||
assert.equal(h.state.pointById.get(base.stableId), badge);
|
||||
h.state.gridAvailable = false;
|
||||
h.rendering.rebuild();
|
||||
assert.equal(h.state.pointById.get(base.stableId), badge);
|
||||
assert.equal(h.state.sightingCount, 1);
|
||||
assert.equal(glow.isDestroyed(), true);
|
||||
h.rendering.destroy();
|
||||
});
|
||||
|
||||
test('a selected observation remains rendered outside the viewport and observation window after a zoom', () => {
|
||||
const selected = { ...base, observedAt: NOW - 49 * 3_600_000 };
|
||||
const h = harness([]);
|
||||
h.state.selectedId = selected.stableId;
|
||||
h.state.selectedRow = selected;
|
||||
h.state.query.visibleBoxes = [{ south: 0, west: 0, north: 1, east: 1 }];
|
||||
h.rendering.rebuild();
|
||||
assert.deepEqual(h.state.renderedRows, [selected]);
|
||||
assert.equal(h.state.rowById.get(selected.stableId), selected);
|
||||
assert.equal(h.state.pointById.has(selected.stableId), true);
|
||||
h.state.band = 'regional';
|
||||
h.state.viewer.camera.positionCartographic = { height: 1_500_000 };
|
||||
h.rendering.rebuild();
|
||||
assert.equal(h.state.selectedId, selected.stableId);
|
||||
assert.equal(h.state.rowById.get(selected.stableId), selected);
|
||||
h.rendering.destroy();
|
||||
});
|
||||
|
||||
test('privacy ground staging has a bounded readiness listener and complete teardown', () => {
|
||||
const h = harness([
|
||||
{
|
||||
...base,
|
||||
obscured: true,
|
||||
cell: { south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
|
||||
},
|
||||
]);
|
||||
h.rendering.rebuild();
|
||||
assert.equal(h.postRender.size, 1);
|
||||
assert.equal(h.scene.groundPrimitives.length, 2);
|
||||
for (let i = 0; i < WILDLIFE_GROUND_READY_MAX_CHECKS; i++)
|
||||
h.postRender.emit();
|
||||
assert.equal(h.postRender.size, 0);
|
||||
assert.equal(h.state.staging, null);
|
||||
assert.equal(h.scene.groundPrimitives.length, 0);
|
||||
h.rendering.destroy();
|
||||
assert.equal(h.postRender.size, 0);
|
||||
});
|
||||
|
||||
test('font readiness swaps images in place without billboard recreation or position work', () => {
|
||||
const listeners = new Set();
|
||||
let ready = false;
|
||||
const badgeSprites = {
|
||||
get: (group) =>
|
||||
`data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg"><circle r="${ready ? 9 : 8}" data-group="${group}"/></svg>`)}`,
|
||||
subscribe(fn) {
|
||||
listeners.add(fn);
|
||||
return () => listeners.delete(fn);
|
||||
},
|
||||
};
|
||||
const rows = [
|
||||
base,
|
||||
{ ...base, stableId: 'synthetic:mammal', iconic: 'Mammalia', lon: -120 },
|
||||
];
|
||||
const h = harness(rows, { badgeSprites });
|
||||
h.rendering.rebuild();
|
||||
const collection = h.state.points;
|
||||
const points = new Map(h.state.pointById);
|
||||
const before = new Map([...points].map(([id, point]) => [id, point.image]));
|
||||
h.counts.writes.length = 0;
|
||||
h.renders.length = 0;
|
||||
ready = true;
|
||||
for (const listener of listeners) listener();
|
||||
assert.equal(h.state.points, collection);
|
||||
assert.equal(h.counts.created, 2);
|
||||
assert.equal(h.counts.removed, 0);
|
||||
assert.equal(h.counts.cleared, 0);
|
||||
assert.deepEqual(h.counts.writes, ['image', 'image']);
|
||||
assert.equal(h.renders.length, 1);
|
||||
for (const [id, point] of points) {
|
||||
assert.equal(h.state.pointById.get(id), point);
|
||||
assert.notEqual(point.image, before.get(id));
|
||||
}
|
||||
h.counts.writes.length = 0;
|
||||
h.rows(rows.map((row) => ({ ...row, lat: row.lat + 0.01 })));
|
||||
h.rendering.rebuild();
|
||||
assert.deepEqual(h.counts.writes, ['position', 'position']);
|
||||
h.rendering.destroy();
|
||||
assert.equal(listeners.size, 0);
|
||||
});
|
||||
@@ -0,0 +1,560 @@
|
||||
import { t } from '../../i18n/index.js';
|
||||
import { wildlifeMeasure } from './performance.js';
|
||||
import { compareWildlifeIds } from './model.js';
|
||||
import { isRecentWildlifeSighting } from './records.js';
|
||||
import {
|
||||
ACARTIA_CREDIT,
|
||||
registerDynamicCredit,
|
||||
} from '../../data/dataCredits.js';
|
||||
import {
|
||||
WILDLIFE_OVERLAY_SOURCE_ID,
|
||||
WILDLIFE_SELECTED_SOURCE_ID,
|
||||
WILDLIFE_LABEL_SOURCE_ID,
|
||||
WILDLIFE_LABEL_SOURCE_OPTIONS,
|
||||
WILDLIFE_OVERLAY_SOURCE_OPTIONS,
|
||||
WILDLIFE_SELECTED_SOURCE_OPTIONS,
|
||||
buildWildlifeThumbnailEntry,
|
||||
buildWildlifeSelectedLabel,
|
||||
buildWildlifeLabelEntry,
|
||||
wildlifeCommonName,
|
||||
wildlifeDisplayName,
|
||||
wildlifeLabelScore,
|
||||
selectWildlifeAmbientRows,
|
||||
} from './cards.js';
|
||||
import {
|
||||
WILDLIFE_CARD_LIMIT,
|
||||
WILDLIFE_CARD_SHOW_MAX_METERS,
|
||||
WILDLIFE_CARD_HIDE_MAX_METERS,
|
||||
WILDLIFE_LABEL_NAME_SEPARATION_PX,
|
||||
WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
|
||||
WILDLIFE_LABEL_LIMIT,
|
||||
} from './policy.js';
|
||||
|
||||
const CONTEXT_LIMIT = 30;
|
||||
|
||||
/** Overlay sources, pinned observation selection and external focus. */
|
||||
export function createSelection({ state, services, parts }) {
|
||||
const overlay = services.overlayHost;
|
||||
const sourceIds = [
|
||||
WILDLIFE_OVERLAY_SOURCE_ID,
|
||||
WILDLIFE_LABEL_SOURCE_ID,
|
||||
WILDLIFE_SELECTED_SOURCE_ID,
|
||||
];
|
||||
const listeners = new Set();
|
||||
// Coordinates are refreshed only by the existing camera/data label pass.
|
||||
const labelScreens = new Map();
|
||||
const ambientSourceOptions = {
|
||||
...WILDLIFE_OVERLAY_SOURCE_OPTIONS,
|
||||
onVisibilityChange: (ids) => parts.rendering.setPhotoCardVisibility?.(ids),
|
||||
};
|
||||
|
||||
function renderBatch(fn) {
|
||||
parts.rendering.beginBatch?.();
|
||||
try {
|
||||
return fn();
|
||||
} finally {
|
||||
parts.rendering.endBatch?.();
|
||||
}
|
||||
}
|
||||
|
||||
function selectionRow() {
|
||||
if (!state.enabled || !state.selectedId) return null;
|
||||
return state.selectedRow || state.rowById.get(state.selectedId) || null;
|
||||
}
|
||||
|
||||
function dispatch(listener, row, metadata) {
|
||||
try {
|
||||
listener(row, metadata);
|
||||
} catch {
|
||||
// A disconnected UI surface must not prevent map selection or teardown.
|
||||
}
|
||||
}
|
||||
|
||||
function notify({ explicitSelection = false } = {}) {
|
||||
const row = selectionRow();
|
||||
const metadata = { explicitSelection: explicitSelection === true };
|
||||
for (const listener of listeners) dispatch(listener, row, metadata);
|
||||
}
|
||||
|
||||
function subscribe(listener) {
|
||||
if (typeof listener !== 'function') return () => {};
|
||||
if (!state.destroyed) listeners.add(listener);
|
||||
dispatch(listener, selectionRow(), { explicitSelection: false });
|
||||
return () => listeners.delete(listener);
|
||||
}
|
||||
|
||||
const cardActions = {
|
||||
select: selectAndFocus,
|
||||
hasRow: (id) => state.enabled && state.rowById.has(id),
|
||||
};
|
||||
|
||||
function publishAmbient() {
|
||||
return wildlifeMeasure('overlay-publish', publishAmbientEntries);
|
||||
}
|
||||
|
||||
function publishAmbientEntries() {
|
||||
if (!state.enabled || !overlay) return;
|
||||
overlay.setEntries(
|
||||
WILDLIFE_OVERLAY_SOURCE_ID,
|
||||
state.ambientRows.map((row) => ({
|
||||
...buildWildlifeThumbnailEntry(row, services.now(), {
|
||||
...cardActions,
|
||||
image: parts.photos.get(row),
|
||||
selected: row.stableId === state.selectedId,
|
||||
}),
|
||||
position: state.positions.get(row.stableId),
|
||||
})),
|
||||
ambientSourceOptions,
|
||||
);
|
||||
parts.rendering.requestRender('photos');
|
||||
}
|
||||
|
||||
function publishSelected() {
|
||||
return wildlifeMeasure('overlay-publish', publishSelectedEntries);
|
||||
}
|
||||
|
||||
function publishSelectedEntries() {
|
||||
if (!state.enabled || !overlay) return;
|
||||
const row = selectionRow();
|
||||
// The selected sighting's painted thumbnail already shows its name.
|
||||
const label =
|
||||
row && !parts.rendering.hasPhotoCard?.(row.stableId)
|
||||
? buildWildlifeSelectedLabel(row)
|
||||
: null;
|
||||
overlay.setEntries(
|
||||
WILDLIFE_SELECTED_SOURCE_ID,
|
||||
label
|
||||
? [
|
||||
{
|
||||
...label,
|
||||
position: state.positions.get(row.stableId),
|
||||
},
|
||||
]
|
||||
: [],
|
||||
WILDLIFE_SELECTED_SOURCE_OPTIONS,
|
||||
);
|
||||
}
|
||||
|
||||
function publishLabels() {
|
||||
return wildlifeMeasure('overlay-publish', publishLabelsEntries);
|
||||
}
|
||||
|
||||
function publishLabelsEntries() {
|
||||
if (!state.enabled || !overlay) return;
|
||||
const names = new Map();
|
||||
const remember = (row) => {
|
||||
const screen = labelScreens.get(row.stableId);
|
||||
if (!screen) return;
|
||||
const name = wildlifeDisplayName(row);
|
||||
if (!names.has(name)) names.set(name, []);
|
||||
names.get(name).push(screen);
|
||||
};
|
||||
// Painted photos win regardless of score. Queued or rejected images do not
|
||||
// suppress neighbors. Selection wins over ambient names using the same cache.
|
||||
for (const row of state.ambientRows)
|
||||
if (parts.rendering.hasPhotoCard?.(row.stableId)) remember(row);
|
||||
const selected = selectionRow();
|
||||
if (
|
||||
selected &&
|
||||
(state.viewer.camera?.positionCartographic?.height ?? 0) <
|
||||
WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS
|
||||
)
|
||||
remember(selected);
|
||||
const entries = [];
|
||||
for (const row of state.labelRows || []) {
|
||||
if (
|
||||
row.stableId === state.selectedId ||
|
||||
parts.rendering.hasPhotoCard?.(row.stableId)
|
||||
)
|
||||
continue;
|
||||
const screen = labelScreens.get(row.stableId);
|
||||
const nearby = names.get(wildlifeDisplayName(row));
|
||||
if (
|
||||
screen &&
|
||||
nearby?.some(
|
||||
(other) =>
|
||||
(screen.x - other.x) ** 2 + (screen.y - other.y) ** 2 <
|
||||
WILDLIFE_LABEL_NAME_SEPARATION_PX ** 2,
|
||||
)
|
||||
)
|
||||
continue;
|
||||
const entry = buildWildlifeLabelEntry(row, {
|
||||
...cardActions,
|
||||
nowMs: services.now(),
|
||||
});
|
||||
if (!entry) continue;
|
||||
entries.push({ ...entry, position: state.positions.get(row.stableId) });
|
||||
remember(row);
|
||||
if (entries.length >= WILDLIFE_LABEL_LIMIT) break;
|
||||
}
|
||||
overlay.setEntries(
|
||||
WILDLIFE_LABEL_SOURCE_ID,
|
||||
entries,
|
||||
WILDLIFE_LABEL_SOURCE_OPTIONS,
|
||||
);
|
||||
parts.rendering.requestRender('labels');
|
||||
}
|
||||
|
||||
function refreshLabels() {
|
||||
if (!state.enabled || !overlay) return;
|
||||
const scene = state.viewer.scene;
|
||||
const horizon = parts.rendering.occluder();
|
||||
const width = scene.canvas?.clientWidth || 0;
|
||||
const height = scene.canvas?.clientHeight || 0;
|
||||
// Rank during camera/data passes; the host handles pixel collisions.
|
||||
const nowMs = services.now();
|
||||
const candidates = [];
|
||||
labelScreens.clear();
|
||||
const rows = new Map(state.renderedRows.map((row) => [row.stableId, row]));
|
||||
for (const row of state.ambientRows) rows.set(row.stableId, row);
|
||||
for (const row of rows.values()) {
|
||||
if (!wildlifeCommonName(row)) continue;
|
||||
const position = state.positions.get(row.stableId);
|
||||
if (!position || (horizon && horizon.isPointVisible(position) !== true))
|
||||
continue;
|
||||
const screen = services.project(scene, position);
|
||||
if (
|
||||
!screen ||
|
||||
screen.x < 0 ||
|
||||
screen.y < 0 ||
|
||||
screen.x > width ||
|
||||
screen.y > height
|
||||
)
|
||||
continue;
|
||||
labelScreens.set(row.stableId, { x: screen.x, y: screen.y });
|
||||
candidates.push(row);
|
||||
}
|
||||
candidates.sort(
|
||||
(a, b) =>
|
||||
wildlifeLabelScore(b, nowMs) - wildlifeLabelScore(a, nowMs) ||
|
||||
compareWildlifeIds(a.stableId, b.stableId),
|
||||
);
|
||||
// Keep ranked candidates so a disappearing photo or cleared selection can
|
||||
// restore suppressed names without another projection pass. Cap after dedup.
|
||||
state.labelRows = candidates;
|
||||
publishLabels();
|
||||
}
|
||||
|
||||
function ambientCandidates(rows) {
|
||||
const scene = state.viewer.scene;
|
||||
const horizon = parts.rendering.occluder();
|
||||
const width = scene.canvas?.clientWidth ?? Infinity;
|
||||
const height = scene.canvas?.clientHeight ?? Infinity;
|
||||
const screens = new Map();
|
||||
const nowMs = services.now();
|
||||
const taxa = state.drawnParams?.taxa ?? state.taxa;
|
||||
const eligible = rows.filter((row) => {
|
||||
if (
|
||||
!row.photo ||
|
||||
row.obscured ||
|
||||
!isRecentWildlifeSighting(row, nowMs, taxa)
|
||||
)
|
||||
return false;
|
||||
const position = state.positions.get(row.stableId);
|
||||
if (!position || (horizon && horizon.isPointVisible(position) !== true))
|
||||
return false;
|
||||
const screen = services.project(scene, position);
|
||||
if (
|
||||
!screen ||
|
||||
screen.x < 0 ||
|
||||
screen.y < 0 ||
|
||||
screen.x > width ||
|
||||
screen.y > height
|
||||
)
|
||||
return false;
|
||||
screens.set(row.stableId, { x: screen.x, y: screen.y });
|
||||
return true;
|
||||
});
|
||||
return { eligible, screens, width, height };
|
||||
}
|
||||
|
||||
/** Snapshot before acquisition replaces its sample. Only currently visible
|
||||
* photos survive; acquisition also checks the observation window/params. */
|
||||
function retainedAmbientRows() {
|
||||
if (!state.enabled) return [];
|
||||
const height =
|
||||
state.viewer?.camera?.positionCartographic?.height ?? Infinity;
|
||||
if (height >= WILDLIFE_CARD_HIDE_MAX_METERS) return [];
|
||||
return ambientCandidates(state.ambientRows).eligible;
|
||||
}
|
||||
|
||||
function refreshAmbient() {
|
||||
if (!state.enabled) return;
|
||||
refreshLabels();
|
||||
const height =
|
||||
state.viewer?.camera?.positionCartographic?.height ?? Infinity;
|
||||
if (state.ambientActive) {
|
||||
if (height >= WILDLIFE_CARD_HIDE_MAX_METERS) state.ambientActive = false;
|
||||
} else if (height <= WILDLIFE_CARD_SHOW_MAX_METERS)
|
||||
state.ambientActive = true;
|
||||
if (!state.ambientActive) {
|
||||
state.ambientRows = [];
|
||||
state.ambientIds = [];
|
||||
parts.photos.setAmbient([]);
|
||||
publishAmbient();
|
||||
return;
|
||||
}
|
||||
// A bucket rebuild may hide an incumbent behind a newly sampled neighbor.
|
||||
// Retain its actual loaded row; rendering gives ambient IDs bucket priority.
|
||||
const byId = new Map(state.renderedRows.map((row) => [row.stableId, row]));
|
||||
for (const row of state.ambientRows) {
|
||||
const current = state.rowById.get(row.stableId);
|
||||
if (current) byId.set(row.stableId, current);
|
||||
}
|
||||
const candidates = ambientCandidates([...byId.values()]);
|
||||
state.ambientRows = selectWildlifeAmbientRows(
|
||||
candidates.eligible,
|
||||
state.ambientIds,
|
||||
services.now(),
|
||||
WILDLIFE_CARD_LIMIT,
|
||||
candidates,
|
||||
);
|
||||
state.ambientIds = state.ambientRows.map((row) => row.stableId);
|
||||
parts.photos.setAmbient(state.ambientRows);
|
||||
publishAmbient();
|
||||
}
|
||||
|
||||
// iNaturalist is static; Acartia enters the attribution popover on first use.
|
||||
function syncCredits() {
|
||||
if (!state.enabled) return;
|
||||
if (state.renderedRows.some((row) => row.origin === 'acartia'))
|
||||
registerDynamicCredit(state.viewer, ACARTIA_CREDIT);
|
||||
}
|
||||
|
||||
function registerContext(row) {
|
||||
if (!services.context?.registerEntityContext) return null;
|
||||
let carrier = state.carriers.get(row.stableId);
|
||||
if (!carrier) {
|
||||
carrier = { show: true };
|
||||
state.carriers.set(row.stableId, carrier);
|
||||
}
|
||||
carrier.__localBaseCartesian = state.positions.get(row.stableId);
|
||||
// A badge yielding to its photo or a neighbor is still a visible sighting.
|
||||
// Context visibility follows the anchor, independently of badge declutter.
|
||||
const horizon = parts.rendering.occluder();
|
||||
carrier.show =
|
||||
!horizon || horizon.isPointVisible(carrier.__localBaseCartesian) === true;
|
||||
const name = row.commonName || row.scientificName || t('Cetacean');
|
||||
// i18n-ignore: provider names and feed-supplied organism names are verbatim
|
||||
const label = `${name} · ${row.origin === 'acartia' ? 'Acartia' : 'iNaturalist'}`;
|
||||
services.context.registerEntityContext(carrier, {
|
||||
id: row.stableId,
|
||||
layerId: 'wildlife-sightings',
|
||||
layerName: t('Wildlife Sightings'),
|
||||
source: row.origin === 'acartia' ? 'Acartia' : 'iNaturalist',
|
||||
label,
|
||||
latitude: row.lat,
|
||||
longitude: row.lon,
|
||||
properties: {
|
||||
quality: row.quality,
|
||||
iconic: row.iconic,
|
||||
obscured: row.obscured,
|
||||
},
|
||||
select: () => selectAndFocus(row.stableId),
|
||||
});
|
||||
return carrier;
|
||||
}
|
||||
|
||||
function refreshContexts() {
|
||||
if (!services.context) return;
|
||||
const rows = state.renderedRows.slice(0, CONTEXT_LIMIT);
|
||||
const selected = selectionRow();
|
||||
if (selected && !rows.includes(selected)) rows.push(selected);
|
||||
const next = new Set(rows.map((row) => row.stableId));
|
||||
try {
|
||||
for (const row of rows) registerContext(row);
|
||||
const store = services.context.getContextStore?.();
|
||||
for (const id of state.contextIds) {
|
||||
if (!next.has(id)) {
|
||||
if (store?.entities?.get(id)?.layerId === 'wildlife-sightings')
|
||||
store.entities.delete(id);
|
||||
state.carriers.delete(id);
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Optional context surfaces must not prevent data or cards rendering.
|
||||
}
|
||||
state.contextIds = next;
|
||||
}
|
||||
|
||||
function select(id, { publishContext = true } = {}) {
|
||||
return renderBatch(() => selectRecord(id, { publishContext }));
|
||||
}
|
||||
|
||||
function selectRecord(id, { publishContext = true } = {}) {
|
||||
if (!state.enabled || !state.rowById.has(id)) return false;
|
||||
const row = state.rowById.get(id);
|
||||
state.selectedId = id;
|
||||
state.selectedRow = row;
|
||||
parts.rendering.refreshSelection();
|
||||
publishAmbient();
|
||||
publishLabels();
|
||||
publishSelected();
|
||||
try {
|
||||
const carrier = registerContext(row);
|
||||
state.contextIds.add(id);
|
||||
if (publishContext && carrier) {
|
||||
state.publishingContext = true;
|
||||
try {
|
||||
services.context?.selectEntityContext?.(carrier);
|
||||
} finally {
|
||||
state.publishingContext = false;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
state.publishingContext = false;
|
||||
}
|
||||
notify({ explicitSelection: true });
|
||||
parts.rendering.requestRender('select');
|
||||
return true;
|
||||
}
|
||||
|
||||
function selectAndFocus(id, options = {}) {
|
||||
const row = state.rowById.get(typeof id === 'string' ? id : id?.stableId);
|
||||
if (!state.enabled || !row) return false;
|
||||
if (!select(row.stableId, options)) return false;
|
||||
services.focus?.requestWorldFocus?.({
|
||||
kind: row.obscured ? 'sighting-area' : 'sighting',
|
||||
id: row.stableId,
|
||||
label: row.commonName || row.scientificName || t('SIGHTING'),
|
||||
position: state.positions.get(row.stableId),
|
||||
});
|
||||
return true;
|
||||
}
|
||||
|
||||
function clear() {
|
||||
return renderBatch(clearRecord);
|
||||
}
|
||||
|
||||
function clearRecord() {
|
||||
const hadSelection = state.selectedId !== null;
|
||||
state.selectedId = null;
|
||||
state.selectedRow = null;
|
||||
try {
|
||||
services.context?.clearSelectedEntityContextForLayer?.(
|
||||
'wildlife-sightings',
|
||||
);
|
||||
} catch {
|
||||
/* optional context host is already gone */
|
||||
}
|
||||
if (state.enabled) {
|
||||
if (hadSelection) publishAmbient();
|
||||
publishSelected();
|
||||
if (hadSelection) publishLabels();
|
||||
if (hadSelection) parts.rendering.requestRender('select');
|
||||
}
|
||||
notify();
|
||||
return hadSelection;
|
||||
}
|
||||
|
||||
function clearAndRebuild() {
|
||||
return renderBatch(() => {
|
||||
const hadSelection = clear();
|
||||
if (hadSelection) parts.rendering.refreshSelection();
|
||||
return hadSelection;
|
||||
});
|
||||
}
|
||||
|
||||
function install() {
|
||||
const onContext = (event) => {
|
||||
if (!state.enabled || state.publishingContext) return;
|
||||
const record =
|
||||
event.detail || services.context?.getSelectedEntityContext?.();
|
||||
if (record?.layerId === 'wildlife-sightings')
|
||||
selectAndFocus(record.id, { publishContext: false });
|
||||
};
|
||||
services.eventTarget?.addEventListener?.('gev:entity-selected', onContext);
|
||||
state.removeContext = () =>
|
||||
services.eventTarget?.removeEventListener?.(
|
||||
'gev:entity-selected',
|
||||
onContext,
|
||||
);
|
||||
if (typeof services.screenSpaceEventHandlerFactory !== 'function') return;
|
||||
state.clickHandler = services.screenSpaceEventHandlerFactory(state.viewer);
|
||||
state.clickHandler.setInputAction((click) => {
|
||||
if (!state.enabled || services.pointer?.isPointerFree?.() === false)
|
||||
return;
|
||||
const hit =
|
||||
overlay?.hitTest?.(click.position?.x, click.position?.y, {
|
||||
sourceId: WILDLIFE_SELECTED_SOURCE_ID,
|
||||
}) ||
|
||||
overlay?.hitTest?.(click.position?.x, click.position?.y, {
|
||||
sourceId: WILDLIFE_OVERLAY_SOURCE_ID,
|
||||
}) ||
|
||||
overlay?.hitTest?.(click.position?.x, click.position?.y, {
|
||||
sourceId: WILDLIFE_LABEL_SOURCE_ID,
|
||||
});
|
||||
if (hit) {
|
||||
hit.entry?.activate?.();
|
||||
return;
|
||||
}
|
||||
const picked = state.viewer.scene.pick(click.position);
|
||||
const id =
|
||||
services.picking?.resolvePickId?.(picked) ??
|
||||
picked?.id ??
|
||||
picked?.primitive?.id;
|
||||
if (
|
||||
typeof id === 'string' &&
|
||||
id.startsWith('wildlife:') &&
|
||||
selectAndFocus(id.slice(9))
|
||||
)
|
||||
return;
|
||||
if (
|
||||
id &&
|
||||
services.picking?.isOwnedByOtherLayer?.('wildlife-sightings', id)
|
||||
)
|
||||
return;
|
||||
clearAndRebuild();
|
||||
}, services.cesium.ScreenSpaceEventType.LEFT_CLICK);
|
||||
}
|
||||
|
||||
function remove() {
|
||||
state.clickHandler?.destroy();
|
||||
state.clickHandler = null;
|
||||
state.removeContext?.();
|
||||
state.removeContext = null;
|
||||
clear();
|
||||
try {
|
||||
services.context?.removeEntityContextsForLayer?.('wildlife-sightings');
|
||||
} catch {
|
||||
/* optional context host is already gone */
|
||||
}
|
||||
state.carriers.clear();
|
||||
state.contextIds.clear();
|
||||
state.ambientIds = [];
|
||||
state.ambientRows = [];
|
||||
state.ambientActive = false;
|
||||
state.labelRows = [];
|
||||
labelScreens.clear();
|
||||
for (const id of sourceIds) {
|
||||
overlay?.clearSource?.(id);
|
||||
overlay?.setVisible?.(id, false);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
selectAndFocus,
|
||||
clear,
|
||||
clearAndRebuild,
|
||||
subscribe,
|
||||
notify,
|
||||
destroy() {
|
||||
listeners.clear();
|
||||
},
|
||||
install,
|
||||
remove,
|
||||
refreshAmbient,
|
||||
retainedAmbientRows,
|
||||
publishAmbient,
|
||||
publishSelected,
|
||||
photoCardsChanged() {
|
||||
renderBatch(() => {
|
||||
publishLabels();
|
||||
publishSelected();
|
||||
});
|
||||
},
|
||||
refreshContexts,
|
||||
syncCredits,
|
||||
sourceIds,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,301 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { createSelection } from './selection.js';
|
||||
|
||||
const row = {
|
||||
stableId: 'inat:123',
|
||||
origin: 'inaturalist',
|
||||
lat: 48.1,
|
||||
lon: 8.2,
|
||||
commonName: 'Synthetic bird',
|
||||
iconic: 'Aves',
|
||||
observedAt: Date.UTC(2026, 10, 4),
|
||||
link: 'https://www.inaturalist.org/observations/123',
|
||||
};
|
||||
|
||||
function fixture(sighting = row) {
|
||||
const position = { x: 300, y: 300, z: 0 };
|
||||
const entries = new Map();
|
||||
const flights = [];
|
||||
const seen = [];
|
||||
const painted = new Set();
|
||||
let hit = null;
|
||||
let projections = 0;
|
||||
let picked = null;
|
||||
let click;
|
||||
const state = {
|
||||
enabled: true,
|
||||
destroyed: false,
|
||||
selectedId: null,
|
||||
selectedRow: null,
|
||||
rowById: new Map([[sighting.stableId, sighting]]),
|
||||
positions: new Map([[sighting.stableId, position]]),
|
||||
renderedRows: [sighting],
|
||||
carriers: new Map(),
|
||||
contextIds: new Set(),
|
||||
ambientIds: [],
|
||||
ambientRows: [],
|
||||
labelRows: [],
|
||||
viewer: {
|
||||
scene: {
|
||||
pick: () => picked,
|
||||
canvas: { clientWidth: 1200, clientHeight: 900 },
|
||||
},
|
||||
camera: { positionCartographic: { height: 30_000 } },
|
||||
},
|
||||
};
|
||||
const selection = createSelection({
|
||||
state,
|
||||
services: {
|
||||
overlayHost: {
|
||||
setEntries: (id, value) => entries.set(id, value),
|
||||
clearSource: (id) => entries.delete(id),
|
||||
setVisible() {},
|
||||
hitTest: (_x, _y, { sourceId }) =>
|
||||
hit?.sourceId === sourceId ? hit : null,
|
||||
},
|
||||
now: () => row.observedAt + 60_000,
|
||||
project: (_scene, anchor) => {
|
||||
projections++;
|
||||
return anchor;
|
||||
},
|
||||
focus: { requestWorldFocus: (request) => flights.push(request) },
|
||||
screenSpaceEventHandlerFactory: () => ({
|
||||
setInputAction: (fn) => (click = fn),
|
||||
destroy() {},
|
||||
}),
|
||||
cesium: { ScreenSpaceEventType: { LEFT_CLICK: 0 } },
|
||||
eventTarget: new EventTarget(),
|
||||
},
|
||||
parts: {
|
||||
rendering: {
|
||||
refreshSelection() {},
|
||||
requestRender() {},
|
||||
occluder: () => null,
|
||||
hasPhotoCard: (id) => painted.has(id),
|
||||
},
|
||||
photos: { get: () => ({ width: 75, height: 75 }), setAmbient() {} },
|
||||
},
|
||||
});
|
||||
selection.subscribe((value, metadata) => seen.push({ value, metadata }));
|
||||
return {
|
||||
state,
|
||||
selection,
|
||||
position,
|
||||
flights,
|
||||
entries,
|
||||
seen,
|
||||
get projections() {
|
||||
return projections;
|
||||
},
|
||||
hit(sourceId, entryId) {
|
||||
const entry = entries
|
||||
.get(sourceId)
|
||||
?.find((entry) => entry.id === entryId);
|
||||
hit = entry ? { sourceId, entryId, entry } : null;
|
||||
},
|
||||
paint(ids) {
|
||||
painted.clear();
|
||||
for (const id of ids) painted.add(id);
|
||||
selection.photoCardsChanged();
|
||||
},
|
||||
click(id = `wildlife:${sighting.stableId}`) {
|
||||
picked = id ? { id } : null;
|
||||
click({ position: { x: 10, y: 20 } });
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('a real sighting click pins its row, opens its label and focuses its true position', () => {
|
||||
const f = fixture();
|
||||
f.selection.install();
|
||||
f.click();
|
||||
assert.equal(f.state.selectedId, row.stableId);
|
||||
assert.equal(f.state.selectedRow, row);
|
||||
assert.equal(f.flights.length, 1);
|
||||
assert.deepEqual(f.flights[0], {
|
||||
kind: 'sighting',
|
||||
id: row.stableId,
|
||||
label: row.commonName,
|
||||
position: f.position,
|
||||
});
|
||||
assert.deepEqual(f.seen.at(-1), {
|
||||
value: row,
|
||||
metadata: { explicitSelection: true },
|
||||
});
|
||||
assert.equal(f.entries.get('wildlife-sightings-selected').length, 1);
|
||||
f.selection.remove();
|
||||
});
|
||||
|
||||
test('selected photo and name cards use the selected lane, select on click and never open links themselves', () => {
|
||||
for (const photo of [
|
||||
null,
|
||||
{
|
||||
square:
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpg',
|
||||
licence: 'cc-by',
|
||||
attribution: 'Synthetic Photographer',
|
||||
},
|
||||
]) {
|
||||
const sighting = { ...row, photo };
|
||||
const f = fixture(sighting);
|
||||
f.selection.install();
|
||||
f.selection.refreshAmbient();
|
||||
const source = photo ? 'wildlife-sightings' : 'wildlife-sightings-labels';
|
||||
const id = photo
|
||||
? 'sighting:inat:123'
|
||||
: 'wildlife-sightings-label:inat:123';
|
||||
f.hit(source, id);
|
||||
f.click();
|
||||
assert.equal(f.flights.length, 1);
|
||||
if (photo) f.paint([row.stableId]);
|
||||
const selectedSource = photo ? source : 'wildlife-sightings-selected';
|
||||
const card = f.entries.get(selectedSource)[0];
|
||||
assert.equal(card.selected, true);
|
||||
assert.equal(card.paintLane, 'selected');
|
||||
assert.ok(
|
||||
!(card.details || []).some((line) => line.includes('↗')),
|
||||
'the anchored photo card owns the single source link',
|
||||
);
|
||||
assert.match(card.accessibilityLabel, /Synthetic bird/);
|
||||
if (photo) {
|
||||
assert.equal(card.variant, 'thumbnail');
|
||||
assert.ok(card.image);
|
||||
assert.deepEqual(f.entries.get('wildlife-sightings-selected'), []);
|
||||
}
|
||||
f.hit(selectedSource, card.id);
|
||||
f.click('other:aircraft');
|
||||
assert.equal(f.flights.length, photo ? 2 : 1);
|
||||
f.selection.clearAndRebuild();
|
||||
if (photo) {
|
||||
const ambient = f.entries.get(source)[0];
|
||||
assert.equal(ambient.selected, undefined);
|
||||
assert.deepEqual(ambient.details, ['© Synthetic Photographer']);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test('nearby duplicate display names yield to painted cards and higher-ranked labels using cached screens', () => {
|
||||
const low = {
|
||||
...row,
|
||||
stableId: 'inat:low',
|
||||
quality: 'research',
|
||||
photo: {
|
||||
square:
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpg',
|
||||
licence: 'cc-by',
|
||||
attribution: 'Synthetic Photographer',
|
||||
},
|
||||
};
|
||||
const high = { ...low, stableId: 'inat:high', favesCount: 50 };
|
||||
const far = { ...row, stableId: 'inat:far' };
|
||||
const different = {
|
||||
...row,
|
||||
stableId: 'inat:different',
|
||||
commonName: 'Other bird',
|
||||
};
|
||||
const f = fixture();
|
||||
f.state.renderedRows = [low, high, far, different];
|
||||
f.state.rowById = new Map(
|
||||
f.state.renderedRows.map((row) => [row.stableId, row]),
|
||||
);
|
||||
f.state.positions = new Map([
|
||||
[low.stableId, { x: 300, y: 300 }],
|
||||
[high.stableId, { x: 379, y: 300 }],
|
||||
[far.stableId, { x: 460, y: 300 }],
|
||||
[different.stableId, { x: 310, y: 300 }],
|
||||
]);
|
||||
const labelIds = () =>
|
||||
f.entries.get('wildlife-sightings-labels').map((entry) => entry.id);
|
||||
f.selection.refreshAmbient();
|
||||
assert.ok(!labelIds().includes('wildlife-sightings-label:inat:low'));
|
||||
assert.ok(labelIds().includes('wildlife-sightings-label:inat:high'));
|
||||
assert.ok(
|
||||
labelIds().includes('wildlife-sightings-label:inat:far'),
|
||||
'81px names survive',
|
||||
);
|
||||
assert.ok(labelIds().includes('wildlife-sightings-label:inat:different'));
|
||||
const projections = f.projections;
|
||||
f.state.ambientRows = [low];
|
||||
f.paint([low.stableId]);
|
||||
assert.ok(
|
||||
!labelIds().includes('wildlife-sightings-label:inat:high'),
|
||||
'a painted lower-score card wins',
|
||||
);
|
||||
assert.equal(
|
||||
f.projections,
|
||||
projections,
|
||||
'paint membership uses the last label pass',
|
||||
);
|
||||
f.paint([]);
|
||||
assert.ok(
|
||||
labelIds().includes('wildlife-sightings-label:inat:high'),
|
||||
'a queued/unpainted card suppresses nothing',
|
||||
);
|
||||
f.selection.selectAndFocus(low.stableId);
|
||||
assert.ok(
|
||||
!labelIds().includes('wildlife-sightings-label:inat:high'),
|
||||
'selected labels outrank ambient names',
|
||||
);
|
||||
assert.equal(
|
||||
f.projections,
|
||||
projections,
|
||||
'selection never projects the population',
|
||||
);
|
||||
f.selection.clearAndRebuild();
|
||||
f.state.positions.set(high.stableId, { x: 600, y: 300 });
|
||||
f.selection.refreshAmbient();
|
||||
assert.ok(
|
||||
labelIds().includes('wildlife-sightings-label:inat:low'),
|
||||
'moveEnd admits separated names',
|
||||
);
|
||||
});
|
||||
|
||||
test('selection remains published while a new sample or camera pass replaces rendered lookup rows', () => {
|
||||
const f = fixture();
|
||||
f.selection.selectAndFocus(row.stableId);
|
||||
f.state.rowById.clear();
|
||||
f.state.renderedRows = [];
|
||||
f.selection.publishSelected();
|
||||
f.selection.notify();
|
||||
assert.equal(f.seen.at(-1).value, row);
|
||||
assert.equal(
|
||||
f.entries.get('wildlife-sightings-selected')[0].position,
|
||||
f.position,
|
||||
);
|
||||
assert.equal(
|
||||
f.flights.length,
|
||||
1,
|
||||
'refresh notifications never start another flight',
|
||||
);
|
||||
f.selection.clearAndRebuild();
|
||||
assert.equal(f.state.selectedId, null);
|
||||
assert.equal(f.state.selectedRow, null);
|
||||
assert.equal(f.seen.at(-1).value, null);
|
||||
assert.deepEqual(f.entries.get('wildlife-sightings-selected'), []);
|
||||
});
|
||||
|
||||
test('an obscured observation focuses only its existing privacy-safe anchor', () => {
|
||||
const obscured = { ...row, obscured: true, lat: 48.1, lon: 8.3 };
|
||||
const f = fixture(obscured);
|
||||
assert.equal(f.selection.selectAndFocus(obscured.stableId), true);
|
||||
assert.equal(f.flights[0].kind, 'sighting-area');
|
||||
assert.equal(f.flights[0].position, f.position);
|
||||
assert.equal(f.state.selectedRow, obscured);
|
||||
});
|
||||
|
||||
test('empty clicks and layer removal release the selected row and its overlay', () => {
|
||||
const f = fixture();
|
||||
f.selection.install();
|
||||
f.click();
|
||||
f.click(null);
|
||||
assert.equal(f.state.selectedRow, null);
|
||||
assert.equal(f.state.selectedId, null);
|
||||
f.click();
|
||||
f.state.enabled = false;
|
||||
f.selection.remove();
|
||||
assert.equal(f.state.selectedRow, null);
|
||||
assert.equal(f.state.selectedId, null);
|
||||
assert.equal(f.seen.at(-1).value, null);
|
||||
assert.equal(f.entries.size, 0);
|
||||
});
|
||||
@@ -0,0 +1,663 @@
|
||||
import { readResponseJsonCapped } from '../../sources/httpBody.js';
|
||||
import { mergeSightings } from './records.js';
|
||||
import { wildlifeMeasure } from './performance.js';
|
||||
import {
|
||||
ACARTIA_GUARD_BOX,
|
||||
TAXA_PRESETS,
|
||||
WILDLIFE_RETRY_AFTER_MAX_SEC,
|
||||
} from './policy.js';
|
||||
import { boxIntersects, retryDelayMs } from './viewport.js';
|
||||
import {
|
||||
WILDLIFE_GRID_MAX_ZOOM,
|
||||
WILDLIFE_GRID_TILE_CAP,
|
||||
wildlifeGridCellId,
|
||||
} from './gridViewport.js';
|
||||
|
||||
// Leave room for projected observations while bounding malformed proxy replies.
|
||||
const SNAPSHOT_MAX_BYTES = 2 * 1024 * 1024;
|
||||
// The proxy owns upstream pacing; observation requests precede these workers.
|
||||
export const WILDLIFE_GRID_CONCURRENCY = 4;
|
||||
export const WILDLIFE_GRID_CACHE_MAX = 400;
|
||||
export const WILDLIFE_GRID_TTL_MS = 15 * 60_000;
|
||||
// Match the proxy's one-hour stale allowance. Keep the original data time so
|
||||
// repeated refresh failures never extend a tile's usable life.
|
||||
const GRID_STALE_MAX_MS = 3_600_000;
|
||||
const HOUR_MS = 3_600_000;
|
||||
|
||||
function validTile(tile) {
|
||||
return (
|
||||
!!tile &&
|
||||
Number.isInteger(tile.z) &&
|
||||
tile.z >= 0 &&
|
||||
tile.z <= WILDLIFE_GRID_MAX_ZOOM &&
|
||||
Number.isInteger(tile.x) &&
|
||||
Number.isInteger(tile.y) &&
|
||||
tile.x >= 0 &&
|
||||
tile.y >= 0 &&
|
||||
tile.x < 2 ** tile.z &&
|
||||
tile.y < 2 ** tile.z
|
||||
);
|
||||
}
|
||||
|
||||
function validProjectedGrid(payload) {
|
||||
return (
|
||||
Number.isFinite(payload?.fetchedAt) &&
|
||||
Number.isSafeInteger(payload.totalResults) &&
|
||||
payload.totalResults >= 0 &&
|
||||
(payload.stale === undefined || typeof payload.stale === 'boolean') &&
|
||||
Array.isArray(payload.cells) &&
|
||||
payload.cells.length <= 4096 &&
|
||||
payload.cells.every(
|
||||
(cell) =>
|
||||
cell &&
|
||||
Object.keys(cell).sort().join(',') === 'cellCount,id,lat,lon' &&
|
||||
/^grid:\d+\/\d+\/\d+:\d+:\d+$/.test(cell.id) &&
|
||||
Number.isSafeInteger(cell.cellCount) &&
|
||||
cell.cellCount > 0 &&
|
||||
Number.isFinite(cell.lat) &&
|
||||
Math.abs(cell.lat) <= 90 &&
|
||||
Number.isFinite(cell.lon) &&
|
||||
Math.abs(cell.lon) <= 180 &&
|
||||
wildlifeGridCellId(
|
||||
cell.lat,
|
||||
cell.lon,
|
||||
Number(cell.id.split(':')[1].split('/')[0]),
|
||||
) === cell.id,
|
||||
) &&
|
||||
new Set(payload.cells.map((cell) => cell.id)).size ===
|
||||
payload.cells.length &&
|
||||
payload.cells.reduce((sum, cell) => sum + cell.cellCount, 0) ===
|
||||
payload.totalResults
|
||||
);
|
||||
}
|
||||
|
||||
function retryAfterSeconds(value, nowMs) {
|
||||
if (typeof value !== 'string' || !value.trim()) return null;
|
||||
const text = value.trim();
|
||||
if (/^\d+(?:\.\d+)?$/.test(text)) {
|
||||
const seconds = Number(text);
|
||||
return Number.isFinite(seconds)
|
||||
? Math.min(WILDLIFE_RETRY_AFTER_MAX_SEC, Math.ceil(seconds))
|
||||
: null;
|
||||
}
|
||||
// Reject malformed numeric values rather than letting Date.parse interpret
|
||||
// them as calendar dates. HTTP dates include a named weekday or month.
|
||||
if (!/[a-z]/i.test(text)) return null;
|
||||
const deadline = Date.parse(text);
|
||||
return Number.isFinite(deadline) && Number.isFinite(nowMs)
|
||||
? Math.min(
|
||||
WILDLIFE_RETRY_AFTER_MAX_SEC,
|
||||
Math.max(0, Math.ceil((deadline - nowMs) / 1000)),
|
||||
)
|
||||
: null;
|
||||
}
|
||||
|
||||
function validProjectedRows(rows, origin) {
|
||||
return (
|
||||
Array.isArray(rows) &&
|
||||
rows.every(
|
||||
(row) =>
|
||||
row &&
|
||||
typeof row.stableId === 'string' &&
|
||||
row.stableId.startsWith(
|
||||
origin === 'inaturalist' ? 'inat:' : 'acartia:',
|
||||
) &&
|
||||
row.origin === origin &&
|
||||
Number.isFinite(row.lat) &&
|
||||
Math.abs(row.lat) <= 90 &&
|
||||
Number.isFinite(row.lon) &&
|
||||
Math.abs(row.lon) <= 180,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/** Return the status a failure reports. The proxy marks upstream failures
|
||||
* with X-Upstream-Status; without it the HTTP status is the signal. */
|
||||
function wildlifeFailureStatus(error) {
|
||||
return (
|
||||
error?.upstreamStatus ||
|
||||
error?.status ||
|
||||
Number(/HTTP (\d{3})/.exec(error?.message || '')?.[1]) ||
|
||||
0
|
||||
);
|
||||
}
|
||||
|
||||
/** Whether a failure asks clients to wait before the next request. */
|
||||
export function wildlifeFailureRetryable(error) {
|
||||
const status = wildlifeFailureStatus(error);
|
||||
return status === 429 || status >= 500;
|
||||
}
|
||||
|
||||
/** Return a Retry-After in milliseconds, capped at one day, or null when
|
||||
* it is missing, negative or not finite. */
|
||||
export function wildlifeRetryAfterMs(seconds) {
|
||||
return Number.isFinite(seconds) && seconds >= 0
|
||||
? Math.min(WILDLIFE_RETRY_AFTER_MAX_SEC, seconds) * 1000
|
||||
: null;
|
||||
}
|
||||
|
||||
/** Return how long a failure asks the layer to wait, or null for none:
|
||||
* 429 and 5xx wait for their Retry-After, else the default backoff after
|
||||
* `previousMs`; other failures may retry on the next view. */
|
||||
export function wildlifeFailureDelayMs(error, previousMs = 0) {
|
||||
if (!error || !wildlifeFailureRetryable(error)) return null;
|
||||
return wildlifeRetryAfterMs(error.retryAfterSec) ?? retryDelayMs(previousMs);
|
||||
}
|
||||
|
||||
/** Flatten failures, expanding a group into every request that failed. */
|
||||
export function wildlifeFailures(errors) {
|
||||
return [errors]
|
||||
.flat()
|
||||
.filter(Boolean)
|
||||
.flatMap((error) =>
|
||||
Array.isArray(error.failures) && error.failures.length
|
||||
? error.failures
|
||||
: [error],
|
||||
);
|
||||
}
|
||||
|
||||
/** Return the failure with the longest effective delay (the first failure
|
||||
* when none waits), carrying every failure so the caller can recompute. */
|
||||
export function preferredWildlifeFailure(errors, previousMs = 0) {
|
||||
const failures = wildlifeFailures(errors);
|
||||
if (!failures.length) return null;
|
||||
let chosen = failures[0];
|
||||
let longest = wildlifeFailureDelayMs(chosen, previousMs) ?? -1;
|
||||
for (const error of failures.slice(1)) {
|
||||
const delay = wildlifeFailureDelayMs(error, previousMs) ?? -1;
|
||||
if (delay > longest) [chosen, longest] = [error, delay];
|
||||
}
|
||||
if (failures.length === 1) return chosen;
|
||||
// Grid errors are shared between consumers of one tile request; describe
|
||||
// the group with a new error rather than mutating any of them.
|
||||
return Object.assign(new Error(chosen.message, { cause: chosen }), {
|
||||
...(chosen.status ? { status: chosen.status } : {}),
|
||||
...(chosen.upstreamStatus ? { upstreamStatus: chosen.upstreamStatus } : {}),
|
||||
...(Number.isFinite(chosen.retryAfterSec)
|
||||
? { retryAfterSec: chosen.retryAfterSec }
|
||||
: {}),
|
||||
failures,
|
||||
});
|
||||
}
|
||||
|
||||
/** Merge occupied cells incrementally; neighboring UTFGrid hit tiles can
|
||||
* report the same geographic cell, so source ids remain the dedupe key. */
|
||||
export function combineWildlifeGridSnapshots(snapshots, error = null) {
|
||||
const cells = [
|
||||
...new Map(
|
||||
snapshots
|
||||
.flatMap((snapshot) => snapshot.cells)
|
||||
.map((cell) => [cell.id, cell]),
|
||||
).values(),
|
||||
];
|
||||
const totalResults = cells.reduce((sum, cell) => sum + cell.cellCount, 0);
|
||||
if (!Number.isSafeInteger(totalResults))
|
||||
throw new Error('Malformed iNaturalist grid response');
|
||||
// A failure's Retry-After counts only when its status asks for a wait.
|
||||
const retryAfter = [
|
||||
...snapshots.map((snapshot) => snapshot.retryAfterSec),
|
||||
...wildlifeFailures(error)
|
||||
.filter(wildlifeFailureRetryable)
|
||||
.map((failure) => failure.retryAfterSec),
|
||||
].filter(Number.isFinite);
|
||||
const stale = snapshots.some((snapshot) => snapshot.stale === true);
|
||||
return {
|
||||
cells,
|
||||
totalResults,
|
||||
fetchedAt: Math.min(...snapshots.map((snapshot) => snapshot.fetchedAt)),
|
||||
stale,
|
||||
...(stale
|
||||
? {
|
||||
upstreamStatus: Math.max(
|
||||
0,
|
||||
...snapshots.map((snapshot) => snapshot.upstreamStatus || 0),
|
||||
),
|
||||
}
|
||||
: {}),
|
||||
...(error ? { error } : {}),
|
||||
...(retryAfter.length ? { retryAfterSec: Math.max(...retryAfter) } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
/** Request both provider proxies when coverage calls for it. API-specific
|
||||
* parameters (Cetacea, photo requirement, observation window) belong to the proxy. */
|
||||
export function createWildlifeSightingsSource({
|
||||
fetchImpl = (...args) => globalThis.fetch(...args),
|
||||
now = () => Date.now(),
|
||||
} = {}) {
|
||||
const gridCache = new Map();
|
||||
const gridInFlight = new Map();
|
||||
async function readProxy(url, provider, signal, { grid = false } = {}) {
|
||||
signal?.throwIfAborted();
|
||||
const response = await fetchImpl(url, { signal });
|
||||
signal?.throwIfAborted();
|
||||
const retryAfterSec = retryAfterSeconds(
|
||||
response.headers?.get?.('Retry-After'),
|
||||
now(),
|
||||
);
|
||||
const upstreamStatus =
|
||||
Number(response.headers?.get?.('X-Upstream-Status')) || 0;
|
||||
if (!response.ok) {
|
||||
await response.body?.cancel?.();
|
||||
signal?.throwIfAborted();
|
||||
const error = new Error(
|
||||
provider === 'iNaturalist' && upstreamStatus === 429
|
||||
? 'iNaturalist rate limited'
|
||||
: `${provider} HTTP ${response.status}`,
|
||||
);
|
||||
error.status = response.status;
|
||||
error.upstreamStatus = upstreamStatus;
|
||||
if (retryAfterSec !== null) error.retryAfterSec = retryAfterSec;
|
||||
throw error;
|
||||
}
|
||||
let payload;
|
||||
try {
|
||||
payload = await readResponseJsonCapped(
|
||||
response,
|
||||
SNAPSHOT_MAX_BYTES,
|
||||
signal,
|
||||
);
|
||||
} catch (error) {
|
||||
signal?.throwIfAborted();
|
||||
throw new Error(`Malformed ${provider} response`, { cause: error });
|
||||
}
|
||||
signal?.throwIfAborted();
|
||||
if (
|
||||
payload &&
|
||||
typeof payload === 'object' &&
|
||||
(payload.stale === true ||
|
||||
response.headers?.get?.('X-Data-Stale') === 'true')
|
||||
) {
|
||||
payload.stale = true;
|
||||
if (retryAfterSec !== null) payload.retryAfterSec = retryAfterSec;
|
||||
payload.upstreamStatus = upstreamStatus;
|
||||
}
|
||||
if (grid) {
|
||||
if (!wildlifeMeasure('tile-decode', () => validProjectedGrid(payload)))
|
||||
throw new Error('Malformed iNaturalist grid response');
|
||||
return payload;
|
||||
}
|
||||
const origin = provider === 'iNaturalist' ? 'inaturalist' : 'acartia';
|
||||
if (
|
||||
!validProjectedRows(payload?.rows, origin) ||
|
||||
(origin === 'inaturalist' &&
|
||||
(!Number.isSafeInteger(payload.totalResults) ||
|
||||
payload.totalResults < 0))
|
||||
) {
|
||||
throw new Error(`Malformed ${provider} response`);
|
||||
}
|
||||
return payload;
|
||||
}
|
||||
|
||||
function readGridTile(key, url, metadata, signal) {
|
||||
signal?.throwIfAborted();
|
||||
let pending = gridInFlight.get(key);
|
||||
if (!pending || pending.controller.signal.aborted) {
|
||||
const controller = new AbortController();
|
||||
pending = { controller, consumers: new Set(), promise: null };
|
||||
const entry = pending;
|
||||
pending.promise = readProxy(url, 'iNaturalist', controller.signal, {
|
||||
grid: true,
|
||||
})
|
||||
.then((value) => {
|
||||
gridCache.delete(key);
|
||||
gridCache.set(key, {
|
||||
value,
|
||||
savedAt: value.stale ? Math.min(now(), value.fetchedAt) : now(),
|
||||
...metadata,
|
||||
});
|
||||
while (gridCache.size > WILDLIFE_GRID_CACHE_MAX)
|
||||
gridCache.delete(gridCache.keys().next().value);
|
||||
return value;
|
||||
})
|
||||
.finally(() => {
|
||||
if (gridInFlight.get(key) === entry) gridInFlight.delete(key);
|
||||
});
|
||||
gridInFlight.set(key, pending);
|
||||
}
|
||||
const consumer = {};
|
||||
pending.consumers.add(consumer);
|
||||
return new Promise((resolve, reject) => {
|
||||
const finish = (aborted = false) => {
|
||||
signal?.removeEventListener('abort', abort);
|
||||
pending.consumers.delete(consumer);
|
||||
if (aborted && !pending.consumers.size) pending.controller.abort();
|
||||
};
|
||||
const abort = () => {
|
||||
finish(true);
|
||||
reject(signal.reason);
|
||||
};
|
||||
signal?.addEventListener('abort', abort, { once: true });
|
||||
pending.promise.then(
|
||||
(value) => {
|
||||
finish();
|
||||
resolve(value);
|
||||
},
|
||||
(error) => {
|
||||
finish();
|
||||
reject(error);
|
||||
},
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
/** Publish cached tiles immediately and refresh their occupied cells. */
|
||||
async function getGridSnapshot({
|
||||
tiles,
|
||||
confirmed = false,
|
||||
taxa = 'all',
|
||||
signal,
|
||||
onTile,
|
||||
} = {}) {
|
||||
signal?.throwIfAborted();
|
||||
if (
|
||||
!Array.isArray(tiles) ||
|
||||
!tiles.length ||
|
||||
tiles.length > WILDLIFE_GRID_TILE_CAP ||
|
||||
!tiles.every(validTile)
|
||||
)
|
||||
throw new TypeError('Wildlife grid requires visible tiles');
|
||||
const preset = TAXA_PRESETS.some((item) => item.value === taxa)
|
||||
? taxa
|
||||
: 'all';
|
||||
const unique = [
|
||||
...new Map(
|
||||
tiles.map((tile) => [`${tile.z}/${tile.x}/${tile.y}`, tile]),
|
||||
).values(),
|
||||
].sort((a, b) => a.z - b.z || a.x - b.x || a.y - b.y);
|
||||
const windowKey = Math.floor(
|
||||
(now() - (preset === 'whales' ? 168 : 48) * HOUR_MS) / HOUR_MS,
|
||||
);
|
||||
const snapshots = new Array(unique.length);
|
||||
const failures = new Array(unique.length);
|
||||
const usable = (entry) => {
|
||||
const age = now() - entry.value.fetchedAt;
|
||||
return age >= 0 && age <= GRID_STALE_MAX_MS;
|
||||
};
|
||||
const touch = (key, entry) => {
|
||||
gridCache.delete(key);
|
||||
gridCache.set(key, entry);
|
||||
};
|
||||
function cachedFallback(tile, tileKey) {
|
||||
let exact = null;
|
||||
const adjacent = [];
|
||||
for (const [key, entry] of gridCache) {
|
||||
if (!usable(entry)) continue;
|
||||
if (key.startsWith(tileKey)) {
|
||||
if (!exact || entry.savedAt > exact.savedAt) exact = entry;
|
||||
} else if (
|
||||
entry.preset === preset &&
|
||||
entry.confirmed === confirmed &&
|
||||
Math.abs(entry.tile.z - tile.z) === 1 &&
|
||||
(entry.tile.z < tile.z
|
||||
? entry.tile.x === Math.floor(tile.x / 2) &&
|
||||
entry.tile.y === Math.floor(tile.y / 2)
|
||||
: Math.floor(entry.tile.x / 2) === tile.x &&
|
||||
Math.floor(entry.tile.y / 2) === tile.y)
|
||||
) {
|
||||
adjacent.push(entry);
|
||||
}
|
||||
}
|
||||
if (exact) return { ...exact.value, stale: true };
|
||||
if (!adjacent.length) return null;
|
||||
// Preserve cached geographic centres and counts while exact tiles load.
|
||||
const newest = [
|
||||
...new Map(
|
||||
adjacent
|
||||
.sort((a, b) => a.savedAt - b.savedAt)
|
||||
.map((entry) => [
|
||||
`${entry.tile.z}/${entry.tile.x}/${entry.tile.y}`,
|
||||
entry,
|
||||
]),
|
||||
).values(),
|
||||
];
|
||||
const parent = newest.find((entry) => entry.tile.z < tile.z);
|
||||
const values = parent
|
||||
? [parent.value]
|
||||
: newest.map((entry) => entry.value);
|
||||
const value = combineWildlifeGridSnapshots(values);
|
||||
value.cells = value.cells.filter((cell) =>
|
||||
wildlifeGridCellId(cell.lat, cell.lon, tile.z)?.startsWith(
|
||||
`grid:${tile.z}/${tile.x}/${tile.y}:`,
|
||||
),
|
||||
);
|
||||
value.totalResults = value.cells.reduce(
|
||||
(sum, cell) => sum + cell.cellCount,
|
||||
0,
|
||||
);
|
||||
return { ...value, stale: true };
|
||||
}
|
||||
function publish(index, value) {
|
||||
signal?.throwIfAborted();
|
||||
snapshots[index] = value;
|
||||
onTile?.(value, { tile: unique[index] });
|
||||
}
|
||||
const requests = [];
|
||||
// Publish all cached coverage before slow misses can occupy the workers.
|
||||
for (let index = 0; index < unique.length; index += 1) {
|
||||
const tile = unique[index];
|
||||
const tileKey = `${tile.z}/${tile.x}/${tile.y}:${preset}:${confirmed ? 'research' : 'all'}:`;
|
||||
const key = `${tileKey}${windowKey}`;
|
||||
const cached = gridCache.get(key);
|
||||
const age = cached ? now() - cached.savedAt : Infinity;
|
||||
if (
|
||||
age >= 0 &&
|
||||
age < WILDLIFE_GRID_TTL_MS &&
|
||||
!cached.value.stale &&
|
||||
usable(cached)
|
||||
) {
|
||||
touch(key, cached);
|
||||
publish(index, cached.value);
|
||||
continue;
|
||||
}
|
||||
const fallback = cachedFallback(tile, tileKey);
|
||||
if (fallback) publish(index, fallback);
|
||||
requests.push({ index, tile, key });
|
||||
}
|
||||
let cursor = 0;
|
||||
async function worker() {
|
||||
while (cursor < requests.length) {
|
||||
signal?.throwIfAborted();
|
||||
const { index, tile, key } = requests[cursor++];
|
||||
const query = new URLSearchParams({
|
||||
z: String(tile.z),
|
||||
x: String(tile.x),
|
||||
y: String(tile.y),
|
||||
taxa: preset,
|
||||
});
|
||||
if (confirmed) query.set('quality', 'research');
|
||||
try {
|
||||
let value = await readGridTile(
|
||||
key,
|
||||
`/api/inaturalist/grid?${query}`,
|
||||
{ tile, preset, confirmed },
|
||||
signal,
|
||||
);
|
||||
signal?.throwIfAborted();
|
||||
publish(index, value);
|
||||
if (value.stale && !value.upstreamStatus) {
|
||||
// A server SWR response paints immediately. Join its existing
|
||||
// refresh so this same view receives the new cells when ready.
|
||||
query.set('refresh', 'wait');
|
||||
value = await readGridTile(
|
||||
key,
|
||||
`/api/inaturalist/grid?${query}`,
|
||||
{ tile, preset, confirmed },
|
||||
signal,
|
||||
);
|
||||
publish(index, value);
|
||||
}
|
||||
} catch (error) {
|
||||
signal?.throwIfAborted();
|
||||
failures[index] = error;
|
||||
// Other tiles can already be cached or in flight. Keep their
|
||||
// progressive coverage even if one upstream request fails.
|
||||
}
|
||||
}
|
||||
}
|
||||
await Promise.all(
|
||||
Array.from(
|
||||
{ length: Math.min(WILDLIFE_GRID_CONCURRENCY, requests.length) },
|
||||
worker,
|
||||
),
|
||||
);
|
||||
signal?.throwIfAborted();
|
||||
const failure = preferredWildlifeFailure(failures);
|
||||
if (!snapshots.some(Boolean) && failure) throw failure;
|
||||
return combineWildlifeGridSnapshots(snapshots.filter(Boolean), failure);
|
||||
}
|
||||
|
||||
/** Merge recent provider rows with source availability and cache age. */
|
||||
async function getSnapshotDetail({
|
||||
signal,
|
||||
box = null,
|
||||
boxes = null,
|
||||
scope = 'view',
|
||||
confirmed = false,
|
||||
taxa = 'all',
|
||||
} = {}) {
|
||||
signal?.throwIfAborted();
|
||||
const preset = TAXA_PRESETS.some((item) => item.value === taxa)
|
||||
? taxa
|
||||
: 'all';
|
||||
const requestBoxes =
|
||||
scope === 'global'
|
||||
? [null]
|
||||
: Array.isArray(boxes)
|
||||
? boxes
|
||||
: box
|
||||
? [box]
|
||||
: [];
|
||||
if (!requestBoxes.length)
|
||||
throw new TypeError('Wildlife sightings require a view box');
|
||||
const useAcartia =
|
||||
scope !== 'global' &&
|
||||
['all', 'Mammalia', 'whales'].includes(preset) &&
|
||||
requestBoxes.some((bounds) => boxIntersects(bounds, ACARTIA_GUARD_BOX));
|
||||
|
||||
// Each box settles independently: one failed antimeridian half must not
|
||||
// discard the other half, and neither may discard a good Acartia reply.
|
||||
const inatRequest = Promise.allSettled(
|
||||
requestBoxes.map((bounds) => {
|
||||
const params = new URLSearchParams({
|
||||
scope: scope === 'global' ? 'global' : 'view',
|
||||
taxa: preset,
|
||||
});
|
||||
if (confirmed) params.set('quality', 'research');
|
||||
if (scope !== 'global') {
|
||||
for (const key of ['south', 'west', 'north', 'east'])
|
||||
params.set(key, String(bounds[key]));
|
||||
}
|
||||
return readProxy(
|
||||
`/api/inaturalist/observations?${params}`,
|
||||
'iNaturalist',
|
||||
signal,
|
||||
);
|
||||
}),
|
||||
);
|
||||
const acartiaRequest = useAcartia
|
||||
? readProxy('/api/acartia/sightings', 'Acartia', signal)
|
||||
: Promise.resolve(null);
|
||||
const [inatResult, acartiaResult] = await Promise.allSettled([
|
||||
inatRequest,
|
||||
acartiaRequest,
|
||||
]);
|
||||
signal?.throwIfAborted();
|
||||
const inatSnapshots = [];
|
||||
const failedBoxes = [];
|
||||
const inatErrors = [];
|
||||
inatResult.value.forEach((result, index) => {
|
||||
if (result.status === 'fulfilled') inatSnapshots.push(result.value);
|
||||
else {
|
||||
failedBoxes.push(requestBoxes[index]);
|
||||
inatErrors.push(result.reason);
|
||||
}
|
||||
});
|
||||
// Keep every failed box; the layer waits for the longest of them.
|
||||
const inatError = preferredWildlifeFailure(inatErrors);
|
||||
// Fail outright only when nothing succeeded; otherwise draw what arrived
|
||||
// and report the failed source in its per-source status.
|
||||
const acartiaError =
|
||||
useAcartia && acartiaResult.status === 'rejected'
|
||||
? acartiaResult.reason
|
||||
: null;
|
||||
if (
|
||||
!inatSnapshots.length &&
|
||||
(!useAcartia || acartiaResult.status !== 'fulfilled')
|
||||
)
|
||||
throw preferredWildlifeFailure([inatError, acartiaError]);
|
||||
const inatRows = inatSnapshots.flatMap((snapshot) => snapshot.rows);
|
||||
const acartiaSnapshot =
|
||||
acartiaResult.status === 'fulfilled' ? acartiaResult.value : null;
|
||||
const acartiaRows = acartiaSnapshot?.rows || [];
|
||||
const rows = mergeSightings(inatRows, acartiaRows, {
|
||||
nowMs: now(),
|
||||
taxa: preset,
|
||||
confirmed,
|
||||
});
|
||||
const inatDates = inatSnapshots
|
||||
.map((snapshot) => snapshot.fetchedAt)
|
||||
.filter(Number.isFinite);
|
||||
const inatFetchedAt = inatDates.length ? Math.min(...inatDates) : null;
|
||||
const inatStale = inatSnapshots.some((snapshot) => snapshot.stale === true);
|
||||
const acartiaStale = acartiaSnapshot?.stale === true;
|
||||
const drawnAcartia = rows.filter((row) => row.origin === 'acartia').length;
|
||||
const dates = [
|
||||
inatFetchedAt,
|
||||
drawnAcartia ? acartiaSnapshot?.fetchedAt : null,
|
||||
].filter(Number.isFinite);
|
||||
const retryAfter = [
|
||||
...inatSnapshots.map((snapshot) => snapshot.retryAfterSec),
|
||||
drawnAcartia ? acartiaSnapshot?.retryAfterSec : null,
|
||||
].filter(Number.isFinite);
|
||||
return {
|
||||
rows,
|
||||
stale: inatStale || (drawnAcartia > 0 && acartiaStale),
|
||||
...(inatStale || acartiaStale
|
||||
? {
|
||||
upstreamStatus: Math.max(
|
||||
0,
|
||||
...inatSnapshots.map((snapshot) => snapshot.upstreamStatus || 0),
|
||||
acartiaSnapshot?.upstreamStatus || 0,
|
||||
),
|
||||
}
|
||||
: {}),
|
||||
fetchedAt: dates.length ? Math.min(...dates) : null,
|
||||
totalResults:
|
||||
inatSnapshots.reduce(
|
||||
(total, snapshot) => total + snapshot.totalResults,
|
||||
0,
|
||||
) + drawnAcartia,
|
||||
scope: scope === 'global' ? 'global' : 'view',
|
||||
partial: inatSnapshots.some((snapshot) => snapshot.partial === true),
|
||||
...(retryAfter.length ? { retryAfterSec: Math.max(...retryAfter) } : {}),
|
||||
sources: {
|
||||
inaturalist: {
|
||||
ok: !inatError,
|
||||
stale: inatStale,
|
||||
fetchedAt: inatFetchedAt,
|
||||
count: rows.filter((row) => row.origin === 'inaturalist').length,
|
||||
...(inatError ? { error: inatError, failedBoxes } : {}),
|
||||
},
|
||||
acartia: {
|
||||
ok: !acartiaError,
|
||||
stale: acartiaStale,
|
||||
fetchedAt: Number.isFinite(acartiaSnapshot?.fetchedAt)
|
||||
? acartiaSnapshot.fetchedAt
|
||||
: null,
|
||||
count: drawnAcartia,
|
||||
...(acartiaError ? { error: acartiaError } : {}),
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
/** Return recent, privacy-projected rows without source status metadata. */
|
||||
async getSnapshot(options = {}) {
|
||||
return (await getSnapshotDetail(options)).rows;
|
||||
},
|
||||
getSnapshotDetail,
|
||||
getGridSnapshot,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,889 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
createWildlifeSightingsSource,
|
||||
WILDLIFE_GRID_TTL_MS,
|
||||
} from './source.js';
|
||||
import { wildlifeGridCellId } from './gridViewport.js';
|
||||
|
||||
const now = Date.UTC(2026, 10, 4, 18);
|
||||
const seattle = { south: 47.5, west: -122.5, north: 47.7, east: -122.2 };
|
||||
const outside = { south: 10, west: 10, north: 12, east: 12 };
|
||||
const inat = {
|
||||
stableId: 'inat:123',
|
||||
origin: 'inaturalist',
|
||||
lat: 47.6,
|
||||
lon: -122.3,
|
||||
observedAt: now - 3_600_000,
|
||||
observedOn: '2026-11-04',
|
||||
};
|
||||
const acartia = {
|
||||
stableId: 'acartia:abc',
|
||||
origin: 'acartia',
|
||||
lat: 48.12,
|
||||
lon: -122.54,
|
||||
observedAt: now - 3_600_000,
|
||||
cetacean: true,
|
||||
quality: 'research',
|
||||
provider: { name: 'Provider', entity: null },
|
||||
};
|
||||
const inatEnvelope = (extra = {}) => ({
|
||||
fetchedAt: now,
|
||||
rows: [inat],
|
||||
scope: 'view',
|
||||
totalResults: 1,
|
||||
...extra,
|
||||
});
|
||||
const acartiaEnvelope = (extra = {}) => ({
|
||||
fetchedAt: now,
|
||||
rows: [acartia],
|
||||
...extra,
|
||||
});
|
||||
|
||||
test('construction performs no acquisition', () => {
|
||||
createWildlifeSightingsSource({
|
||||
fetchImpl: () => assert.fail('construction fetched'),
|
||||
});
|
||||
});
|
||||
|
||||
test('source sends proxy-only scope, box, taxa and confirmed parameters for all presets', async () => {
|
||||
for (const taxa of [
|
||||
'all',
|
||||
'Aves',
|
||||
'Mammalia',
|
||||
'whales',
|
||||
'Insecta',
|
||||
'Plantae',
|
||||
]) {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(new URL(url, 'https://example.test'));
|
||||
return Response.json(inatEnvelope());
|
||||
},
|
||||
});
|
||||
await source.getSnapshotDetail({ box: outside, taxa, confirmed: true });
|
||||
assert.equal(urls.length, 1);
|
||||
assert.equal(urls[0].pathname, '/api/inaturalist/observations');
|
||||
assert.deepEqual(Object.fromEntries(urls[0].searchParams), {
|
||||
scope: 'view',
|
||||
taxa,
|
||||
quality: 'research',
|
||||
south: '10',
|
||||
west: '10',
|
||||
north: '12',
|
||||
east: '12',
|
||||
});
|
||||
// taxon_id, d1 (observed date), photos and quality_grade are upstream
|
||||
// choices owned and tested by the server, never browser query controls.
|
||||
}
|
||||
});
|
||||
|
||||
test('confirmed false omits quality, and global sample omits bbox and Acartia', async () => {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(url);
|
||||
return Response.json(inatEnvelope({ scope: 'global' }));
|
||||
},
|
||||
});
|
||||
const result = await source.getSnapshotDetail({
|
||||
scope: 'global',
|
||||
taxa: 'whales',
|
||||
confirmed: false,
|
||||
box: seattle,
|
||||
});
|
||||
assert.equal(result.scope, 'global');
|
||||
assert.deepEqual(
|
||||
Object.fromEntries(new URL(urls[0], 'https://example.test').searchParams),
|
||||
{ scope: 'global', taxa: 'whales' },
|
||||
);
|
||||
assert.equal(urls.length, 1);
|
||||
});
|
||||
|
||||
test('Acartia loads only inside coverage for the three mammal-inclusive presets', async () => {
|
||||
for (const box of [seattle, outside])
|
||||
for (const taxa of [
|
||||
'all',
|
||||
'Aves',
|
||||
'Mammalia',
|
||||
'whales',
|
||||
'Insecta',
|
||||
'Plantae',
|
||||
]) {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(url);
|
||||
return Response.json(
|
||||
url.startsWith('/api/acartia') ? acartiaEnvelope() : inatEnvelope(),
|
||||
);
|
||||
},
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box, taxa });
|
||||
const expected =
|
||||
box === seattle && ['all', 'Mammalia', 'whales'].includes(taxa);
|
||||
assert.equal(
|
||||
urls.some((url) => url === '/api/acartia/sightings'),
|
||||
expected,
|
||||
);
|
||||
assert.equal(result.rows.length, expected ? 2 : 1);
|
||||
}
|
||||
});
|
||||
|
||||
test('Acartia failure preserves iNat rows with an explicit failed source', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
url.startsWith('/api/acartia')
|
||||
? new Response('', { status: 502 })
|
||||
: Response.json(inatEnvelope()),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box: seattle });
|
||||
assert.deepEqual(result.rows, [inat]);
|
||||
assert.equal(result.sources.acartia.ok, false);
|
||||
assert.equal(result.sources.inaturalist.ok, true);
|
||||
});
|
||||
|
||||
test('iNat failure keeps a successful Acartia result and reports iNat degraded', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
url.startsWith('/api/acartia')
|
||||
? Response.json(acartiaEnvelope())
|
||||
: new Response('', {
|
||||
status: 502,
|
||||
headers: { 'X-Upstream-Status': '503', 'Retry-After': '30' },
|
||||
}),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box: seattle });
|
||||
assert.deepEqual(result.rows, [acartia]);
|
||||
assert.equal(result.totalResults, 1);
|
||||
assert.equal(result.fetchedAt, now);
|
||||
assert.equal(result.sources.acartia.ok, true);
|
||||
assert.equal(result.sources.inaturalist.ok, false);
|
||||
assert.equal(result.sources.inaturalist.count, 0);
|
||||
assert.equal(
|
||||
result.sources.inaturalist.error.message,
|
||||
'iNaturalist HTTP 502',
|
||||
);
|
||||
assert.equal(result.sources.inaturalist.error.retryAfterSec, 30);
|
||||
assert.deepEqual(result.sources.inaturalist.failedBoxes, [seattle]);
|
||||
});
|
||||
|
||||
test('observations reject only when every requested source failed', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
new Response('', { status: url.startsWith('/api/acartia') ? 502 : 503 }),
|
||||
});
|
||||
await assert.rejects(source.getSnapshotDetail({ box: seattle }), {
|
||||
message: 'iNaturalist HTTP 503',
|
||||
});
|
||||
const antimeridian = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async () => new Response('', { status: 503 }),
|
||||
});
|
||||
await assert.rejects(
|
||||
antimeridian.getSnapshotDetail({
|
||||
boxes: [
|
||||
{ south: 10, west: 179, north: 12, east: 180 },
|
||||
{ south: 10, west: -180, north: 12, east: -178 },
|
||||
],
|
||||
}),
|
||||
{ message: 'iNaturalist HTTP 503' },
|
||||
);
|
||||
});
|
||||
|
||||
test('one failed antimeridian half keeps the other half and reports the failed box', async () => {
|
||||
const east = { south: 10, west: 179, north: 12, east: 180 };
|
||||
const west = { south: 10, west: -180, north: 12, east: -178 };
|
||||
const eastRow = { ...inat, stableId: 'inat:east', lat: 11, lon: 179.5 };
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
new URL(url, 'https://example.test').searchParams.get('west') === '179'
|
||||
? Response.json(inatEnvelope({ rows: [eastRow], totalResults: 3 }))
|
||||
: new Response('', { status: 503 }),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ boxes: [east, west] });
|
||||
assert.deepEqual(result.rows, [eastRow]);
|
||||
assert.equal(result.totalResults, 3);
|
||||
assert.equal(result.sources.inaturalist.ok, false);
|
||||
assert.equal(result.sources.inaturalist.count, 1);
|
||||
assert.equal(
|
||||
result.sources.inaturalist.error.message,
|
||||
'iNaturalist HTTP 503',
|
||||
);
|
||||
assert.deepEqual(result.sources.inaturalist.failedBoxes, [west]);
|
||||
});
|
||||
|
||||
test('proxy staleness and original fetch dates pass through with per-source counts', async () => {
|
||||
const fetchedAt = now - 50 * 60_000;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
Response.json(
|
||||
url.startsWith('/api/acartia')
|
||||
? acartiaEnvelope()
|
||||
: inatEnvelope({
|
||||
fetchedAt,
|
||||
stale: true,
|
||||
partial: true,
|
||||
totalResults: 400,
|
||||
}),
|
||||
),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box: seattle });
|
||||
assert.equal(result.stale, true);
|
||||
assert.equal(result.fetchedAt, fetchedAt);
|
||||
assert.equal(result.partial, true);
|
||||
assert.equal(result.totalResults, 401);
|
||||
assert.deepEqual(result.sources.inaturalist, {
|
||||
ok: true,
|
||||
stale: true,
|
||||
fetchedAt,
|
||||
count: 1,
|
||||
});
|
||||
assert.equal(result.sources.acartia.count, 1);
|
||||
});
|
||||
|
||||
test('antimeridian boxes fetch once each and merge duplicate boundary rows', async () => {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(url);
|
||||
return Response.json(inatEnvelope());
|
||||
},
|
||||
});
|
||||
const boxes = [
|
||||
{ south: 10, west: 179, north: 12, east: 180 },
|
||||
{ south: 10, west: -180, north: 12, east: -178 },
|
||||
];
|
||||
const result = await source.getSnapshotDetail({ boxes });
|
||||
assert.equal(urls.length, 2);
|
||||
assert.equal(result.rows.length, 1);
|
||||
assert.equal(result.totalResults, 2);
|
||||
});
|
||||
|
||||
test('iNat non-OK responses carry stable status messages and status values', async () => {
|
||||
for (const status of [429, 502]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () =>
|
||||
new Response('', {
|
||||
status,
|
||||
headers: { 'X-Upstream-Status': String(status) },
|
||||
}),
|
||||
});
|
||||
await assert.rejects(source.getSnapshot({ box: outside }), (error) => {
|
||||
assert.equal(
|
||||
error.message,
|
||||
status === 429 ? 'iNaturalist rate limited' : 'iNaturalist HTTP 502',
|
||||
);
|
||||
assert.equal(error.status, status);
|
||||
return true;
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
test('Retry-After delta seconds and HTTP dates use the injected source clock', async () => {
|
||||
for (const [header, seconds] of [
|
||||
['3600', 3600],
|
||||
[new Date(now + 12 * 3_600_000).toUTCString(), 43_200],
|
||||
[new Date(now - 1000).toUTCString(), 0],
|
||||
['0', 0],
|
||||
['not a deadline', undefined],
|
||||
['-10', undefined],
|
||||
['', undefined],
|
||||
]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async () =>
|
||||
new Response('', {
|
||||
status: 429,
|
||||
headers: { 'Retry-After': header },
|
||||
}),
|
||||
});
|
||||
await assert.rejects(source.getSnapshot({ box: outside }), (error) => {
|
||||
assert.equal(error.status, 429);
|
||||
assert.equal(error.retryAfterSec, seconds, header);
|
||||
return true;
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
test('malformed envelopes and invalid rows reject instead of becoming empty', async () => {
|
||||
for (const payload of [
|
||||
{},
|
||||
{ rows: {} },
|
||||
{ rows: [], totalResults: null },
|
||||
{ rows: [{}], totalResults: 1 },
|
||||
{ results: [], total_results: 0 },
|
||||
]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () => Response.json(payload),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getSnapshot({ box: outside }),
|
||||
/Malformed iNaturalist response/,
|
||||
);
|
||||
}
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () => new Response('{bad'),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getSnapshot({ box: outside }),
|
||||
/Malformed iNaturalist response/,
|
||||
);
|
||||
});
|
||||
|
||||
test('well-formed empty projected snapshot is legitimate and getSnapshot returns only rows', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () =>
|
||||
Response.json(inatEnvelope({ rows: [], totalResults: 0 })),
|
||||
});
|
||||
assert.deepEqual(await source.getSnapshot({ box: outside }), []);
|
||||
});
|
||||
|
||||
test('abort is checked before acquisition and after a late fetch resolves', async () => {
|
||||
const early = new AbortController();
|
||||
early.abort();
|
||||
const idle = createWildlifeSightingsSource({
|
||||
fetchImpl: () => assert.fail('aborted fetch ran'),
|
||||
});
|
||||
await assert.rejects(
|
||||
idle.getSnapshot({ box: outside, signal: early.signal }),
|
||||
{ name: 'AbortError' },
|
||||
);
|
||||
let resolve;
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: () =>
|
||||
new Promise((done) => {
|
||||
resolve = done;
|
||||
}),
|
||||
});
|
||||
const late = new AbortController();
|
||||
const request = source.getSnapshot({ box: outside, signal: late.signal });
|
||||
late.abort();
|
||||
resolve(Response.json(inatEnvelope()));
|
||||
await assert.rejects(request, { name: 'AbortError' });
|
||||
});
|
||||
|
||||
const gridCell = {
|
||||
id: 'grid:2/1/1:1:51',
|
||||
cellCount: 6,
|
||||
lat: 65.94,
|
||||
lon: -18.28125,
|
||||
};
|
||||
const gridEnvelope = (extra = {}) => ({
|
||||
cells: [gridCell],
|
||||
totalResults: 6,
|
||||
fetchedAt: now,
|
||||
...extra,
|
||||
});
|
||||
const gridTile = { z: 2, x: 1, y: 1 };
|
||||
|
||||
test('grid source sends visible XYZ/filter parameters only, dedupes tiles and keeps source untouched', async () => {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url, options) => {
|
||||
urls.push(new URL(url, 'https://example.test'));
|
||||
assert.ok(options.signal instanceof AbortSignal);
|
||||
return Response.json(gridEnvelope());
|
||||
},
|
||||
});
|
||||
const result = await source.getGridSnapshot({
|
||||
tiles: [gridTile, gridTile],
|
||||
confirmed: true,
|
||||
taxa: 'Aves',
|
||||
});
|
||||
assert.equal(urls.length, 1);
|
||||
assert.equal(urls[0].pathname, '/api/inaturalist/grid');
|
||||
assert.deepEqual(Object.fromEntries(urls[0].searchParams), {
|
||||
z: '2',
|
||||
x: '1',
|
||||
y: '1',
|
||||
taxa: 'Aves',
|
||||
quality: 'research',
|
||||
});
|
||||
assert.deepEqual(result, {
|
||||
cells: [gridCell],
|
||||
totalResults: 6,
|
||||
fetchedAt: now,
|
||||
stale: false,
|
||||
});
|
||||
});
|
||||
|
||||
test('grid source caches stable tile/filter/hour keys and combines neighbor edge cells once', async () => {
|
||||
let clock = now;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: async () => {
|
||||
calls += 1;
|
||||
return Response.json(gridEnvelope());
|
||||
},
|
||||
});
|
||||
const options = { tiles: [gridTile, { z: 2, x: 2, y: 1 }] };
|
||||
const result = await source.getGridSnapshot(options);
|
||||
assert.equal(calls, 2);
|
||||
assert.equal(
|
||||
result.cells.length,
|
||||
1,
|
||||
'same geographic cell can bleed into a neighboring hit tile',
|
||||
);
|
||||
assert.equal(result.totalResults, 6);
|
||||
await source.getGridSnapshot({ tiles: [...options.tiles].reverse() });
|
||||
assert.equal(calls, 2, 'ordering does not change stable keys');
|
||||
await source.getGridSnapshot({ ...options, confirmed: true });
|
||||
assert.equal(calls, 4, 'quality changes the key');
|
||||
clock += WILDLIFE_GRID_TTL_MS + 1;
|
||||
await source.getGridSnapshot(options);
|
||||
assert.equal(calls, 6, 'fifteen minute refresh cap');
|
||||
});
|
||||
|
||||
test('grid source preserves stale metadata and rejects invalid projected schema/privacy fields', async () => {
|
||||
const staleSource = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async () =>
|
||||
Response.json(gridEnvelope({ stale: true, fetchedAt: now - 1000 })),
|
||||
});
|
||||
const stale = await staleSource.getGridSnapshot({ tiles: [gridTile] });
|
||||
assert.equal(stale.stale, true);
|
||||
assert.equal(stale.fetchedAt, now - 1000);
|
||||
for (const payload of [
|
||||
{},
|
||||
gridEnvelope({ cells: {} }),
|
||||
gridEnvelope({ totalResults: -1 }),
|
||||
gridEnvelope({ totalResults: 5 }),
|
||||
gridEnvelope({ fetchedAt: null }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, uuid: 'must-not-leave-proxy' }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, iconic: 'Aves' }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, lat: 91 }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, id: 'grid:99/0/0:1:1' }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, id: 'grid:2/1/1:3:51' }] }),
|
||||
gridEnvelope({ cells: [gridCell, gridCell], totalResults: 12 }),
|
||||
]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () => Response.json(payload),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getGridSnapshot({ tiles: [gridTile] }),
|
||||
/Malformed iNaturalist grid response/,
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('grid source validates request bounds before fetching and aborts superseded loads', async () => {
|
||||
const idle = createWildlifeSightingsSource({
|
||||
fetchImpl: () => assert.fail('invalid/aborted grid acquired'),
|
||||
});
|
||||
for (const tiles of [
|
||||
undefined,
|
||||
[],
|
||||
[{ z: 2, x: 4, y: 0 }],
|
||||
[{ z: -1, x: 0, y: 0 }],
|
||||
Array(13).fill(gridTile),
|
||||
]) {
|
||||
await assert.rejects(
|
||||
idle.getGridSnapshot({ tiles }),
|
||||
/requires visible tiles/,
|
||||
);
|
||||
}
|
||||
const early = new AbortController();
|
||||
early.abort();
|
||||
await assert.rejects(
|
||||
idle.getGridSnapshot({ tiles: [gridTile], signal: early.signal }),
|
||||
{ name: 'AbortError' },
|
||||
);
|
||||
let resolve;
|
||||
let passedSignal;
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: (_url, options) => {
|
||||
passedSignal = options.signal;
|
||||
return new Promise((done) => {
|
||||
resolve = done;
|
||||
});
|
||||
},
|
||||
});
|
||||
const late = new AbortController();
|
||||
const loading = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
signal: late.signal,
|
||||
});
|
||||
late.abort();
|
||||
assert.equal(passedSignal.aborted, true);
|
||||
resolve(Response.json(gridEnvelope()));
|
||||
await assert.rejects(loading, { name: 'AbortError' });
|
||||
});
|
||||
|
||||
test('grid worker concurrency is bounded and a failed tile preserves progressive siblings', async () => {
|
||||
const waiting = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: (_url, options) =>
|
||||
new Promise((resolve, reject) => {
|
||||
waiting.push({ resolve, signal: options.signal });
|
||||
options.signal.addEventListener(
|
||||
'abort',
|
||||
() => reject(options.signal.reason),
|
||||
{ once: true },
|
||||
);
|
||||
}),
|
||||
});
|
||||
const tiles = Array.from({ length: 6 }, (_, x) => ({ z: 3, x, y: 0 }));
|
||||
const loading = source.getGridSnapshot({ tiles });
|
||||
assert.equal(waiting.length, 4);
|
||||
waiting[0].resolve(new Response('', { status: 502 }));
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (let i = 1; i < 4; i++) waiting[i].resolve(Response.json(gridEnvelope()));
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (let i = 4; i < waiting.length; i++)
|
||||
waiting[i].resolve(Response.json(gridEnvelope()));
|
||||
const result = await loading;
|
||||
assert.equal(result.error.message, 'iNaturalist HTTP 502');
|
||||
assert.deepEqual(result.cells, [gridCell]);
|
||||
assert.ok(waiting.every((item) => !item.signal.aborted));
|
||||
});
|
||||
|
||||
test('failed grid refresh keeps the tile last good cells across its window-hour key, without extending stale life', async () => {
|
||||
let clock = now + 55 * 60_000;
|
||||
let fail = false;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: async () => {
|
||||
calls++;
|
||||
return fail
|
||||
? new Response('', { status: 502, headers: { 'Retry-After': '40' } })
|
||||
: Response.json(gridEnvelope({ fetchedAt: clock }));
|
||||
},
|
||||
});
|
||||
const good = await source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
taxa: 'whales',
|
||||
});
|
||||
const fetchedAt = clock;
|
||||
fail = true;
|
||||
clock += 300_001;
|
||||
const stale = await source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
taxa: 'whales',
|
||||
});
|
||||
assert.deepEqual(stale.cells, good.cells);
|
||||
assert.equal(stale.totalResults, good.totalResults);
|
||||
assert.equal(stale.stale, true);
|
||||
assert.equal(stale.fetchedAt, fetchedAt);
|
||||
assert.equal(stale.error.message, 'iNaturalist HTTP 502');
|
||||
assert.equal(stale.retryAfterSec, 40);
|
||||
assert.equal(calls, 2);
|
||||
await assert.rejects(
|
||||
source.getGridSnapshot({ tiles: [gridTile], taxa: 'Aves' }),
|
||||
/iNaturalist HTTP 502/,
|
||||
'a different filter cannot borrow the last tile',
|
||||
);
|
||||
clock = fetchedAt + 3_600_001;
|
||||
await assert.rejects(
|
||||
source.getGridSnapshot({ tiles: [gridTile], taxa: 'whales' }),
|
||||
/iNaturalist HTTP 502/,
|
||||
'failed refresh did not renew original data age',
|
||||
);
|
||||
});
|
||||
|
||||
test('a rejected grid request never rejects a parallel observations acquisition', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
url.startsWith('/api/inaturalist/grid?')
|
||||
? new Response('', { status: 502 })
|
||||
: Response.json(inatEnvelope()),
|
||||
});
|
||||
const [grid, observations] = await Promise.allSettled([
|
||||
source.getGridSnapshot({ tiles: [gridTile] }),
|
||||
source.getSnapshotDetail({ box: outside }),
|
||||
]);
|
||||
assert.equal(grid.status, 'rejected');
|
||||
assert.equal(grid.reason.status, 502);
|
||||
assert.equal(observations.status, 'fulfilled');
|
||||
assert.deepEqual(observations.value.rows, [inat]);
|
||||
});
|
||||
|
||||
test('one failed cached tile retains its cells while neighboring tiles refresh successfully', async () => {
|
||||
let clock = now;
|
||||
let refreshing = false;
|
||||
const neighbor = {
|
||||
...gridCell,
|
||||
id: wildlifeGridCellId(30, 20, 2),
|
||||
lat: 30,
|
||||
lon: 20,
|
||||
};
|
||||
const signals = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: async (url, { signal }) => {
|
||||
signals.push(signal);
|
||||
const isFailedTile =
|
||||
new URL(url, 'https://example.test').searchParams.get('x') === '1';
|
||||
if (refreshing && isFailedTile) return new Response('', { status: 502 });
|
||||
const cell = isFailedTile
|
||||
? gridCell
|
||||
: { ...neighbor, cellCount: refreshing ? 10 : 6 };
|
||||
return Response.json({
|
||||
cells: [cell],
|
||||
totalResults: cell.cellCount,
|
||||
fetchedAt: clock,
|
||||
});
|
||||
},
|
||||
});
|
||||
const options = { tiles: [gridTile, { z: 2, x: 2, y: 1 }] };
|
||||
await source.getGridSnapshot(options);
|
||||
refreshing = true;
|
||||
clock += WILDLIFE_GRID_TTL_MS + 1;
|
||||
const result = await source.getGridSnapshot(options);
|
||||
assert.equal(result.cells.length, 2);
|
||||
assert.equal(
|
||||
result.cells.find((cell) => cell.id === gridCell.id).cellCount,
|
||||
6,
|
||||
);
|
||||
assert.equal(
|
||||
result.cells.find((cell) => cell.id === neighbor.id).cellCount,
|
||||
10,
|
||||
);
|
||||
assert.equal(result.totalResults, 16);
|
||||
assert.equal(result.stale, true);
|
||||
assert.equal(result.error.message, 'iNaturalist HTTP 502');
|
||||
assert.ok(signals.every((signal) => !signal.aborted));
|
||||
});
|
||||
|
||||
test('stale successful proxy answers preserve Retry-After for observation and grid retry guidance', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
Response.json(
|
||||
url.startsWith('/api/inaturalist/grid?')
|
||||
? gridEnvelope({ stale: true })
|
||||
: inatEnvelope({ stale: true }),
|
||||
{ headers: { 'X-Data-Stale': 'true', 'Retry-After': '75' } },
|
||||
),
|
||||
});
|
||||
const rows = await source.getSnapshotDetail({ box: outside });
|
||||
const grid = await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
assert.equal(rows.stale, true);
|
||||
assert.equal(rows.retryAfterSec, 75);
|
||||
assert.equal(grid.stale, true);
|
||||
assert.equal(grid.retryAfterSec, 75);
|
||||
});
|
||||
|
||||
test('client stale tiles publish before revalidation finishes and retain the original data date', async () => {
|
||||
let clock = now;
|
||||
let refresh;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: () =>
|
||||
++calls === 1
|
||||
? Promise.resolve(Response.json(gridEnvelope()))
|
||||
: new Promise((resolve) => {
|
||||
refresh = resolve;
|
||||
}),
|
||||
});
|
||||
await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
clock += WILDLIFE_GRID_TTL_MS + 1;
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
onTile: (tile) => paints.push(tile),
|
||||
});
|
||||
assert.equal(
|
||||
paints.length,
|
||||
1,
|
||||
'stale cache is synchronous, before the fetch settles',
|
||||
);
|
||||
assert.equal(paints[0].stale, true);
|
||||
assert.equal(paints[0].fetchedAt, now);
|
||||
refresh(
|
||||
Response.json(
|
||||
gridEnvelope({
|
||||
cells: [{ ...gridCell, cellCount: 9 }],
|
||||
totalResults: 9,
|
||||
fetchedAt: clock,
|
||||
}),
|
||||
),
|
||||
);
|
||||
const result = await pending;
|
||||
assert.equal(paints.length, 2);
|
||||
assert.equal(paints[1].stale, undefined);
|
||||
assert.equal(result.totalResults, 9);
|
||||
});
|
||||
|
||||
test('cached coverage publishes before slow misses earlier in XYZ order fill all workers', async () => {
|
||||
const waiting = [];
|
||||
let cold = false;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: (url) => {
|
||||
const x = Number(
|
||||
new URL(url, 'https://example.test').searchParams.get('x'),
|
||||
);
|
||||
const cell = {
|
||||
id: wildlifeGridCellId(83, x * 45 - 157.5, 3),
|
||||
lat: 83,
|
||||
lon: x * 45 - 157.5,
|
||||
cellCount: 6,
|
||||
};
|
||||
const value = { cells: [cell], totalResults: 6, fetchedAt: now };
|
||||
return cold
|
||||
? new Promise((resolve) =>
|
||||
waiting.push(() => resolve(Response.json(value))),
|
||||
)
|
||||
: Promise.resolve(Response.json(value));
|
||||
},
|
||||
});
|
||||
const tiles = Array.from({ length: 6 }, (_, x) => ({ z: 3, x, y: 0 }));
|
||||
await source.getGridSnapshot({ tiles: tiles.slice(4) });
|
||||
cold = true;
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles,
|
||||
onTile: (value, metadata) => paints.push({ value, metadata }),
|
||||
});
|
||||
assert.deepEqual(
|
||||
paints.map(({ metadata }) => metadata.tile.x),
|
||||
[4, 5],
|
||||
'known cells paint synchronously even though the four earlier misses are unresolved',
|
||||
);
|
||||
assert.equal(waiting.length, 4);
|
||||
for (const finish of waiting) finish();
|
||||
const result = await pending;
|
||||
assert.equal(result.cells.length, 6);
|
||||
assert.equal(result.totalResults, 36);
|
||||
});
|
||||
|
||||
test('an adjacent zoom cache fills the new tile immediately while its exact cells load', async () => {
|
||||
let resolve;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: () =>
|
||||
++calls === 1
|
||||
? Promise.resolve(Response.json(gridEnvelope()))
|
||||
: new Promise((done) => {
|
||||
resolve = done;
|
||||
}),
|
||||
});
|
||||
await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
const parent = { z: 1, x: 0, y: 0 };
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles: [parent],
|
||||
onTile: (value) => paints.push(value),
|
||||
});
|
||||
assert.equal(paints.length, 1);
|
||||
assert.deepEqual(paints[0].cells, [gridCell]);
|
||||
assert.equal(calls, 2, 'the exact zoom still loads in the background');
|
||||
const cell = {
|
||||
...gridCell,
|
||||
id: wildlifeGridCellId(gridCell.lat, gridCell.lon, 1),
|
||||
};
|
||||
resolve(Response.json(gridEnvelope({ cells: [cell] })));
|
||||
await pending;
|
||||
assert.equal(paints.length, 2);
|
||||
assert.deepEqual(paints[1].cells, [cell]);
|
||||
});
|
||||
|
||||
test('concurrent client views share an in-flight tile without one consumer aborting the other', async () => {
|
||||
let resolve;
|
||||
let calls = 0;
|
||||
let signal;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: (_url, options) => {
|
||||
calls++;
|
||||
signal = options.signal;
|
||||
return new Promise((done) => {
|
||||
resolve = done;
|
||||
});
|
||||
},
|
||||
});
|
||||
const first = new AbortController();
|
||||
const one = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
signal: first.signal,
|
||||
});
|
||||
const two = source.getGridSnapshot({ tiles: [gridTile] });
|
||||
first.abort();
|
||||
await assert.rejects(one, { name: 'AbortError' });
|
||||
assert.equal(signal.aborted, false);
|
||||
resolve(Response.json(gridEnvelope()));
|
||||
assert.equal((await two).totalResults, 6);
|
||||
assert.equal(calls, 1);
|
||||
await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
assert.equal(calls, 1);
|
||||
});
|
||||
|
||||
test('local HTTP pacing errors never become iNaturalist rate-limited errors', async () => {
|
||||
for (const status of [429, 503]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () =>
|
||||
new Response('', { status, headers: { 'Retry-After': '30' } }),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getSnapshotDetail({ box: outside }),
|
||||
(error) => {
|
||||
assert.equal(error.upstreamStatus, 0);
|
||||
assert.doesNotMatch(error.message, /rate limited/i);
|
||||
return true;
|
||||
},
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('a server stale-while-revalidate answer joins its refresh and publishes fresh cells in the same view', async () => {
|
||||
const urls = [];
|
||||
let resolve;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: (url) => {
|
||||
urls.push(url);
|
||||
return urls.length === 1
|
||||
? Promise.resolve(
|
||||
Response.json(
|
||||
gridEnvelope({
|
||||
stale: true,
|
||||
fetchedAt: now - WILDLIFE_GRID_TTL_MS - 1,
|
||||
}),
|
||||
),
|
||||
)
|
||||
: new Promise((done) => {
|
||||
resolve = done;
|
||||
});
|
||||
},
|
||||
});
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
onTile: (value) => paints.push(value),
|
||||
});
|
||||
await new Promise((done) => setImmediate(done));
|
||||
assert.equal(paints.length, 1);
|
||||
assert.equal(paints[0].stale, true);
|
||||
assert.equal(
|
||||
new URL(urls[1], 'https://example.test').searchParams.get('refresh'),
|
||||
'wait',
|
||||
);
|
||||
resolve(
|
||||
Response.json(
|
||||
gridEnvelope({
|
||||
cells: [{ ...gridCell, cellCount: 11 }],
|
||||
totalResults: 11,
|
||||
}),
|
||||
),
|
||||
);
|
||||
assert.equal((await pending).totalResults, 11);
|
||||
assert.equal(paints.length, 2);
|
||||
assert.equal(paints[1].stale, undefined);
|
||||
});
|
||||
@@ -0,0 +1,136 @@
|
||||
import { ICONIC_TINTS, WILDLIFE_SPRITE_PX } from './policy.js';
|
||||
|
||||
// Missing taxon symbols use related shapes from Material Symbols Outlined.
|
||||
export const WILDLIFE_BADGE_GLYPHS = Object.freeze({
|
||||
bird: 'raven',
|
||||
mammal: 'pets',
|
||||
reptile: 'egg_alt',
|
||||
amphibian: 'water_drop',
|
||||
fish: 'set_meal',
|
||||
insect: 'bug_report',
|
||||
arachnid: 'pest_control',
|
||||
plant: 'eco',
|
||||
fungus: 'umbrella',
|
||||
other: 'category',
|
||||
unknown: 'question_mark',
|
||||
});
|
||||
export const WILDLIFE_SPRITE_GROUPS = Object.freeze(
|
||||
Object.keys(WILDLIFE_BADGE_GLYPHS),
|
||||
);
|
||||
export const WILDLIFE_SPRITE_ICONIC = Object.freeze({
|
||||
bird: 'Aves',
|
||||
mammal: 'Mammalia',
|
||||
reptile: 'Reptilia',
|
||||
amphibian: 'Amphibia',
|
||||
fish: 'Actinopterygii',
|
||||
insect: 'Insecta',
|
||||
arachnid: 'Arachnida',
|
||||
plant: 'Plantae',
|
||||
fungus: 'Fungi',
|
||||
other: 'Animalia',
|
||||
unknown: 'Unknown',
|
||||
});
|
||||
const ICONIC_GROUPS = Object.freeze(
|
||||
Object.fromEntries(
|
||||
Object.entries(WILDLIFE_SPRITE_ICONIC).map(([group, iconic]) => [
|
||||
iconic,
|
||||
group,
|
||||
]),
|
||||
),
|
||||
);
|
||||
|
||||
/** Resolve a taxon or sprite group to one of the shared badge textures. */
|
||||
export function wildlifeSpriteGroup(groupOrIconic) {
|
||||
if (groupOrIconic === 'Mollusca') return 'other';
|
||||
return Object.hasOwn(WILDLIFE_SPRITE_ICONIC, groupOrIconic)
|
||||
? groupOrIconic
|
||||
: Object.hasOwn(ICONIC_GROUPS, groupOrIconic)
|
||||
? ICONIC_GROUPS[groupOrIconic]
|
||||
: 'unknown';
|
||||
}
|
||||
|
||||
export const WILDLIFE_BADGE_OUTLINE_PX = 1.5;
|
||||
const OUTLINE_COLOR = '#040c10';
|
||||
const FONT = '400 14px "Material Symbols Outlined"';
|
||||
const FONT_GLYPHS = Object.values(WILDLIFE_BADGE_GLYPHS).join(' ');
|
||||
const FALLBACKS = new Map(
|
||||
WILDLIFE_SPRITE_GROUPS.map((group) => [
|
||||
group,
|
||||
`data:image/svg+xml,${encodeURIComponent(
|
||||
`<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 20 20"><circle cx="10" cy="10" r="9.1" fill="${ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]}" stroke="${OUTLINE_COLOR}" stroke-width="${WILDLIFE_BADGE_OUTLINE_PX}"/></svg>`,
|
||||
)}`,
|
||||
]),
|
||||
);
|
||||
|
||||
/** One bounded set of canvas sprites per document, painted only after the
|
||||
* icon font is decoded. Until then the very same billboards use plain badges. */
|
||||
export function createWildlifeSpriteCache({
|
||||
documentRef = globalThis.document,
|
||||
} = {}) {
|
||||
const sprites = new Map();
|
||||
const listeners = new Set();
|
||||
let ready = false;
|
||||
let loading = null;
|
||||
|
||||
function paint(group) {
|
||||
const canvas = documentRef.createElement('canvas');
|
||||
canvas.width = canvas.height = WILDLIFE_SPRITE_PX * 2;
|
||||
const ctx = canvas.getContext('2d');
|
||||
if (!ctx) return FALLBACKS.get(group);
|
||||
ctx.scale(2, 2);
|
||||
ctx.beginPath();
|
||||
ctx.arc(10, 10, 9.1, 0, Math.PI * 2);
|
||||
ctx.fillStyle = ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]];
|
||||
ctx.fill();
|
||||
ctx.lineWidth = WILDLIFE_BADGE_OUTLINE_PX;
|
||||
ctx.strokeStyle = OUTLINE_COLOR;
|
||||
ctx.stroke();
|
||||
ctx.font = FONT;
|
||||
ctx.textAlign = 'center';
|
||||
ctx.textBaseline = 'middle';
|
||||
ctx.fillStyle = '#ffffff';
|
||||
ctx.fillText(WILDLIFE_BADGE_GLYPHS[group], 10, 10, 16);
|
||||
return canvas;
|
||||
}
|
||||
|
||||
function load() {
|
||||
if (loading) return loading;
|
||||
if (!documentRef?.fonts?.load) return Promise.resolve(false);
|
||||
loading = Promise.resolve()
|
||||
.then(() => documentRef.fonts.load(FONT, FONT_GLYPHS))
|
||||
.then((faces) => {
|
||||
if (!faces?.length) return false;
|
||||
// Paint once per group, never once per observation or refresh.
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS)
|
||||
sprites.set(group, paint(group));
|
||||
ready = true;
|
||||
for (const listener of [...listeners]) listener();
|
||||
return true;
|
||||
})
|
||||
.catch(() => false);
|
||||
return loading;
|
||||
}
|
||||
|
||||
return {
|
||||
get(groupOrIconic) {
|
||||
const group = wildlifeSpriteGroup(groupOrIconic);
|
||||
return (ready ? sprites : FALLBACKS).get(group);
|
||||
},
|
||||
load,
|
||||
subscribe(listener) {
|
||||
listeners.add(listener);
|
||||
void load();
|
||||
return () => listeners.delete(listener);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const caches = new WeakMap();
|
||||
let headlessCache;
|
||||
/** Share the bounded sprite cache among layer instances in one document. */
|
||||
export function wildlifeSpriteCache(documentRef = globalThis.document) {
|
||||
if (!documentRef) return (headlessCache ??= createWildlifeSpriteCache());
|
||||
if (!caches.has(documentRef))
|
||||
caches.set(documentRef, createWildlifeSpriteCache({ documentRef }));
|
||||
return caches.get(documentRef);
|
||||
}
|
||||
@@ -0,0 +1,189 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import sharp from 'sharp';
|
||||
import { aircraftIcon } from '../../data/aircraftIcons.js';
|
||||
import { ICONIC_TINTS, WILDLIFE_SPRITE_PX } from './policy.js';
|
||||
import {
|
||||
WILDLIFE_SPRITE_GROUPS,
|
||||
WILDLIFE_SPRITE_ICONIC,
|
||||
WILDLIFE_BADGE_GLYPHS,
|
||||
WILDLIFE_BADGE_OUTLINE_PX,
|
||||
createWildlifeSpriteCache,
|
||||
wildlifeSpriteCache,
|
||||
wildlifeSpriteGroup,
|
||||
} from './sprites.js';
|
||||
|
||||
const sprites = wildlifeSpriteCache();
|
||||
|
||||
test('every taxon group has an explicit Material Symbol and tinted circle fallback', () => {
|
||||
assert.equal(Object.isFrozen(WILDLIFE_BADGE_GLYPHS), true);
|
||||
assert.deepEqual(WILDLIFE_BADGE_GLYPHS, {
|
||||
bird: 'raven',
|
||||
mammal: 'pets',
|
||||
reptile: 'egg_alt',
|
||||
amphibian: 'water_drop',
|
||||
fish: 'set_meal',
|
||||
insect: 'bug_report',
|
||||
arachnid: 'pest_control',
|
||||
plant: 'eco',
|
||||
fungus: 'umbrella',
|
||||
other: 'category',
|
||||
unknown: 'question_mark',
|
||||
});
|
||||
const textures = new Set();
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS) {
|
||||
const texture = sprites.get(group);
|
||||
textures.add(texture);
|
||||
assert.equal(wildlifeSpriteGroup(WILDLIFE_SPRITE_ICONIC[group]), group);
|
||||
assert.equal(sprites.get(WILDLIFE_SPRITE_ICONIC[group]), texture);
|
||||
assert.equal(sprites.get(group), texture);
|
||||
const svg = decodeURIComponent(texture.slice(texture.indexOf(',') + 1));
|
||||
assert.match(svg, /<circle /);
|
||||
assert.ok(
|
||||
svg.includes(`fill="${ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]}"`),
|
||||
);
|
||||
assert.match(svg, /stroke="#040c10"/);
|
||||
assert.match(svg, /stroke-width="1.5"/);
|
||||
assert.doesNotMatch(svg, /<path|<text|<image|href=|<script|<foreignObject/);
|
||||
}
|
||||
assert.equal(textures.size, Object.keys(ICONIC_TINTS).length);
|
||||
});
|
||||
|
||||
test('unknown taxon keys share the slate fallback without allocating textures', () => {
|
||||
for (const value of [
|
||||
undefined,
|
||||
null,
|
||||
'Unknown',
|
||||
'Synthetic kingdom',
|
||||
'__proto__',
|
||||
'constructor',
|
||||
'toString',
|
||||
]) {
|
||||
assert.equal(wildlifeSpriteGroup(value), 'unknown');
|
||||
assert.equal(sprites.get(value), sprites.get('unknown'));
|
||||
}
|
||||
assert.equal(sprites.get('Mollusca'), sprites.get('other'));
|
||||
});
|
||||
|
||||
test('canvas badges wait for the icon font, paint once and notify existing consumers', async () => {
|
||||
let resolveFont;
|
||||
let fontLoads = 0;
|
||||
const canvases = [];
|
||||
const documentRef = {
|
||||
fonts: {
|
||||
load(font, glyphs) {
|
||||
fontLoads += 1;
|
||||
assert.match(font, /Material Symbols Outlined/);
|
||||
for (const glyph of Object.values(WILDLIFE_BADGE_GLYPHS))
|
||||
assert.ok(glyphs.includes(glyph));
|
||||
return new Promise((resolve) => {
|
||||
resolveFont = resolve;
|
||||
});
|
||||
},
|
||||
},
|
||||
createElement(tag) {
|
||||
assert.equal(tag, 'canvas');
|
||||
const commands = [];
|
||||
const ctx = {
|
||||
scale(...args) {
|
||||
commands.push(['scale', ...args]);
|
||||
},
|
||||
beginPath() {},
|
||||
arc(...args) {
|
||||
commands.push(['arc', ...args]);
|
||||
},
|
||||
fill() {
|
||||
commands.push(['fill', this.fillStyle]);
|
||||
},
|
||||
stroke() {
|
||||
commands.push(['stroke', this.strokeStyle, this.lineWidth]);
|
||||
},
|
||||
fillText(...args) {
|
||||
commands.push(['text', this.fillStyle, this.font, ...args]);
|
||||
},
|
||||
};
|
||||
const canvas = { commands, getContext: () => ctx };
|
||||
canvases.push(canvas);
|
||||
return canvas;
|
||||
},
|
||||
};
|
||||
const cache = createWildlifeSpriteCache({ documentRef });
|
||||
const fallback = cache.get('Aves');
|
||||
let notifications = 0;
|
||||
const unsubscribe = cache.subscribe(() => {
|
||||
notifications += 1;
|
||||
});
|
||||
const loading = cache.load();
|
||||
assert.equal(cache.load(), loading);
|
||||
await Promise.resolve();
|
||||
assert.equal(fontLoads, 1);
|
||||
assert.equal(canvases.length, 0, 'no glyph is rasterized in a fallback font');
|
||||
assert.equal(cache.get('Aves'), fallback);
|
||||
resolveFont([{}]);
|
||||
assert.equal(await loading, true);
|
||||
assert.equal(notifications, 1);
|
||||
assert.equal(canvases.length, WILDLIFE_SPRITE_GROUPS.length);
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS) {
|
||||
const canvas = cache.get(group);
|
||||
assert.equal(canvas, cache.get(WILDLIFE_SPRITE_ICONIC[group]));
|
||||
assert.equal(canvas.width, WILDLIFE_SPRITE_PX * 2);
|
||||
assert.equal(canvas.height, WILDLIFE_SPRITE_PX * 2);
|
||||
assert.deepEqual(
|
||||
canvas.commands.find(([op]) => op === 'fill'),
|
||||
['fill', ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]],
|
||||
);
|
||||
assert.deepEqual(
|
||||
canvas.commands.find(([op]) => op === 'stroke'),
|
||||
['stroke', '#040c10', WILDLIFE_BADGE_OUTLINE_PX],
|
||||
);
|
||||
const glyph = canvas.commands.find(([op]) => op === 'text');
|
||||
assert.equal(glyph[1], '#ffffff');
|
||||
assert.match(glyph[2], /Material Symbols Outlined/);
|
||||
assert.equal(glyph[3], WILDLIFE_BADGE_GLYPHS[group]);
|
||||
}
|
||||
await cache.load();
|
||||
assert.equal(canvases.length, WILDLIFE_SPRITE_GROUPS.length);
|
||||
unsubscribe();
|
||||
});
|
||||
|
||||
test('unavailable font keeps plain badges and does not paint a ligature word', async () => {
|
||||
const cache = createWildlifeSpriteCache({
|
||||
documentRef: {
|
||||
fonts: { load: async () => [] },
|
||||
createElement() {
|
||||
assert.fail('no canvas before the icon font is ready');
|
||||
},
|
||||
},
|
||||
});
|
||||
const fallback = cache.get('Aves');
|
||||
assert.equal(await cache.load(), false);
|
||||
assert.equal(cache.get('Aves'), fallback);
|
||||
});
|
||||
|
||||
async function visiblePixels(texture, size) {
|
||||
const svg = texture.includes(';base64,')
|
||||
? Buffer.from(texture.slice(texture.indexOf(',') + 1), 'base64')
|
||||
: Buffer.from(decodeURIComponent(texture.slice(texture.indexOf(',') + 1)));
|
||||
const { data, info } = await sharp(svg)
|
||||
.resize(size, size)
|
||||
.ensureAlpha()
|
||||
.raw()
|
||||
.toBuffer({ resolveWithObject: true });
|
||||
let pixels = 0;
|
||||
for (let i = 0; i < data.length; i += info.channels)
|
||||
if (Math.max(data[i], data[i + 1], data[i + 2]) > 150 && data[i + 3] > 127)
|
||||
pixels += 1;
|
||||
return pixels;
|
||||
}
|
||||
|
||||
test('compact badge fill remains legible at its near and far footprints', async () => {
|
||||
assert.equal(WILDLIFE_SPRITE_PX, 20);
|
||||
for (const size of [12, 16, WILDLIFE_SPRITE_PX, 22]) {
|
||||
const flightPixels = await visiblePixels(aircraftIcon('airliner'), size);
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS)
|
||||
assert.ok(
|
||||
(await visiblePixels(sprites.get(group), size)) >= flightPixels,
|
||||
`${group} at ${size}px`,
|
||||
);
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,83 @@
|
||||
import {
|
||||
WILDLIFE_MAX_VIEW_DEGREES,
|
||||
WILDLIFE_RETRY_MIN_MS,
|
||||
WILDLIFE_RETRY_MAX_MS,
|
||||
} from './policy.js';
|
||||
|
||||
export { snapWildlifeBox } from './bounds.js';
|
||||
|
||||
const degrees = (radians) => (radians * 180) / Math.PI;
|
||||
const cleanDegree = (value) => Math.round(value * 1e8) / 1e8;
|
||||
|
||||
function validBox(box) {
|
||||
return (
|
||||
!!box &&
|
||||
['south', 'west', 'north', 'east'].every((key) =>
|
||||
Number.isFinite(box[key]),
|
||||
) &&
|
||||
box.south >= -90 &&
|
||||
box.north <= 90 &&
|
||||
box.north >= box.south &&
|
||||
box.west >= -180 &&
|
||||
box.west <= 180 &&
|
||||
box.east >= -180 &&
|
||||
box.east <= 180
|
||||
);
|
||||
}
|
||||
|
||||
function longitudeRanges(box) {
|
||||
return box.west <= box.east
|
||||
? [[box.west, box.east]]
|
||||
: [
|
||||
[box.west, 180],
|
||||
[-180, box.east],
|
||||
];
|
||||
}
|
||||
|
||||
/** Test geographic overlap, including boxes that cross the antimeridian. */
|
||||
export function boxIntersects(a, b) {
|
||||
if (!validBox(a) || !validBox(b) || a.south > b.north || a.north < b.south)
|
||||
return false;
|
||||
return longitudeRanges(a).some(([aw, ae]) =>
|
||||
longitudeRanges(b).some(([bw, be]) => aw <= be && ae >= bw),
|
||||
);
|
||||
}
|
||||
|
||||
/** Split a local camera rectangle into noncrossing observation query boxes. */
|
||||
export function wildlifeViewportBoxes(viewer) {
|
||||
const camera = viewer?.camera;
|
||||
if (typeof camera?.computeViewRectangle !== 'function') return null;
|
||||
const rectangle = camera.computeViewRectangle(
|
||||
viewer?.scene?.globe?.ellipsoid,
|
||||
);
|
||||
if (!rectangle) return null;
|
||||
const box = Object.fromEntries(
|
||||
['south', 'west', 'north', 'east'].map((key) => [
|
||||
key,
|
||||
cleanDegree(degrees(rectangle[key])),
|
||||
]),
|
||||
);
|
||||
if (!validBox(box) || box.north <= box.south) return null;
|
||||
const width =
|
||||
box.east >= box.west ? box.east - box.west : 360 - box.west + box.east;
|
||||
if (
|
||||
width <= 0 ||
|
||||
Math.max(box.north - box.south, width) > WILDLIFE_MAX_VIEW_DEGREES
|
||||
)
|
||||
return null;
|
||||
return longitudeRanges(box)
|
||||
.filter(([west, east]) => east > west)
|
||||
.map(([west, east]) => ({
|
||||
south: box.south,
|
||||
west,
|
||||
north: box.north,
|
||||
east,
|
||||
}));
|
||||
}
|
||||
|
||||
/** 30 seconds, doubling to a four-minute ceiling, for local retry guidance. */
|
||||
export function retryDelayMs(previousMs) {
|
||||
return Number.isFinite(previousMs) && previousMs > 0
|
||||
? Math.min(WILDLIFE_RETRY_MAX_MS, previousMs * 2)
|
||||
: WILDLIFE_RETRY_MIN_MS;
|
||||
}
|
||||
@@ -0,0 +1,136 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
wildlifeViewportBoxes,
|
||||
snapWildlifeBox,
|
||||
boxIntersects,
|
||||
retryDelayMs,
|
||||
} from './viewport.js';
|
||||
import { ACARTIA_GUARD_BOX } from './policy.js';
|
||||
import { getWildlifeHeightBand } from './model.js';
|
||||
|
||||
const viewer = ({ south, west, north, east }) => ({
|
||||
camera: {
|
||||
computeViewRectangle: () =>
|
||||
Object.fromEntries(
|
||||
Object.entries({ south, west, north, east }).map(([key, value]) => [
|
||||
key,
|
||||
(value * Math.PI) / 180,
|
||||
]),
|
||||
),
|
||||
},
|
||||
scene: { globe: { ellipsoid: {} } },
|
||||
});
|
||||
|
||||
test('local boxes snap outward to 0.1 degrees; wider views to whole degrees', () => {
|
||||
assert.deepEqual(
|
||||
snapWildlifeBox({
|
||||
south: 47.61,
|
||||
west: -122.35,
|
||||
north: 47.79,
|
||||
east: -122.21,
|
||||
}),
|
||||
{ south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
|
||||
);
|
||||
assert.deepEqual(
|
||||
snapWildlifeBox({ south: 40.1, west: -126.2, north: 46.1, east: -121.1 }),
|
||||
{ south: 40, west: -127, north: 47, east: -121 },
|
||||
);
|
||||
assert.deepEqual(
|
||||
snapWildlifeBox({ south: 47.6, west: -122.4, north: 47.8, east: -122.2 }),
|
||||
{ south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
|
||||
);
|
||||
assert.equal(
|
||||
snapWildlifeBox({ south: -20, west: -30, north: 21, east: 10 }),
|
||||
null,
|
||||
);
|
||||
});
|
||||
|
||||
test('the final snapped span stays within 40 degrees and snapping is idempotent', () => {
|
||||
for (const box of [
|
||||
{ south: 10.2, west: 0, north: 50.1, east: 1 },
|
||||
{ south: 0, west: 10.2, north: 1, east: 50.1 },
|
||||
])
|
||||
assert.equal(snapWildlifeBox(box), null, JSON.stringify(box));
|
||||
for (const box of [
|
||||
{ south: 47.4, west: -122.3, north: 47.6, east: -122.1 },
|
||||
{ south: 10.01, west: -122.3, north: 14.99, east: -117.31 },
|
||||
{ south: 10.01, west: 0, north: 15, east: 5 },
|
||||
{ south: 10.01, west: 0, north: 15.01, east: 5 },
|
||||
{ south: 10, west: 0, north: 50, east: 1 },
|
||||
]) {
|
||||
const snapped = snapWildlifeBox(box);
|
||||
assert.ok(snapped, JSON.stringify(box));
|
||||
assert.deepEqual(snapWildlifeBox(snapped), snapped);
|
||||
}
|
||||
});
|
||||
|
||||
test('intersections handle guard coverage, point boxes and antimeridian', () => {
|
||||
const seattle = { south: 47.5, west: -122.5, north: 47.7, east: -122.2 };
|
||||
assert.equal(boxIntersects(seattle, ACARTIA_GUARD_BOX), true);
|
||||
assert.equal(
|
||||
boxIntersects({ ...seattle, west: 20, east: 21 }, ACARTIA_GUARD_BOX),
|
||||
false,
|
||||
);
|
||||
const dateline = { south: 10, west: 175, north: 20, east: -175 };
|
||||
assert.equal(
|
||||
boxIntersects(dateline, { south: 11, west: 178, north: 12, east: 179 }),
|
||||
true,
|
||||
);
|
||||
assert.equal(
|
||||
boxIntersects(dateline, { south: 11, west: -1, north: 12, east: 1 }),
|
||||
false,
|
||||
);
|
||||
assert.equal(boxIntersects(null, seattle), false);
|
||||
});
|
||||
|
||||
test('viewport rectangles split at 180 degrees and reject overly large or missing views', () => {
|
||||
assert.deepEqual(
|
||||
wildlifeViewportBoxes(
|
||||
viewer({ south: 10, west: 179, north: 12, east: -178 }),
|
||||
),
|
||||
[
|
||||
{ south: 10, west: 179, north: 12, east: 180 },
|
||||
{ south: 10, west: -180, north: 12, east: -178 },
|
||||
],
|
||||
);
|
||||
assert.deepEqual(
|
||||
wildlifeViewportBoxes(
|
||||
viewer({ south: 47, west: -123, north: 48, east: -122 }),
|
||||
),
|
||||
[{ south: 47, west: -123, north: 48, east: -122 }],
|
||||
);
|
||||
assert.equal(
|
||||
wildlifeViewportBoxes(
|
||||
viewer({ south: -21, west: -10, north: 20, east: 10 }),
|
||||
),
|
||||
null,
|
||||
);
|
||||
assert.equal(
|
||||
wildlifeViewportBoxes(
|
||||
viewer({ south: 0, west: 170, north: 10, east: -140 }),
|
||||
),
|
||||
null,
|
||||
);
|
||||
assert.equal(wildlifeViewportBoxes({}), null);
|
||||
});
|
||||
|
||||
test('height bands retain representations across +/-5% and switch beyond +/-10%', () => {
|
||||
assert.equal(getWildlifeHeightBand(3_000_001), 'global');
|
||||
assert.equal(getWildlifeHeightBand(3_000_000), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(3_150_000, 'regional'), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(2_850_000, 'global'), 'global');
|
||||
assert.equal(getWildlifeHeightBand(3_310_000, 'regional'), 'global');
|
||||
assert.equal(getWildlifeHeightBand(2_690_000, 'global'), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(1_600_000), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(1_000_000), 'cells');
|
||||
assert.equal(getWildlifeHeightBand(30_000), 'cards');
|
||||
assert.equal(getWildlifeHeightBand(30_000, 'global'), 'cards');
|
||||
});
|
||||
|
||||
test('retry guidance doubles from 30 seconds to a four-minute ceiling', () => {
|
||||
assert.deepEqual(
|
||||
[undefined, 30_000, 60_000, 120_000, 240_000].map(retryDelayMs),
|
||||
[30_000, 60_000, 120_000, 240_000, 240_000],
|
||||
);
|
||||
});
|
||||
Reference in new issue
Block a user