Merge remote-tracking branch 'upstream/main' into HEAD

This commit is contained in:
Said Turksever committed 2026-11-06 11:54:29 +00:00
commit 0dbbd9047e
402 files changed
+63739 -1868

No files matched your search

+1
View File
@@ -23,6 +23,7 @@ export function createControls({ state: layerState, services, parts, source }) {
attachDataManager(dataManager) {
layerState.dataManager = dataManager;
parts.dependencies.watchAdoptions(dataManager);
},
setParams(params = {}) {
+20
View File
@@ -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,
};
}
+105
View File
@@ -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;
},
};
+1
View File
@@ -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,
+2 -1
View File
@@ -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,
};
}
+38
View File
@@ -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?.();
});
+87
View File
@@ -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 = {
+1
View File
@@ -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(':'))
+26
View File
@@ -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
+594 -22
View File
@@ -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();
}
});
+6
View File
@@ -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,
+17
View File
@@ -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',
+75 -6
View File
@@ -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);
+89
View File
@@ -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([
+96
View File
@@ -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',
};
}
+74
View File
@@ -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'));
});
+37
View File
@@ -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/);
});
+366
View File
@@ -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;
}
+218
View File
@@ -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);
});
+135
View File
@@ -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;
}
+164
View File
@@ -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);
});
+38
View File
@@ -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,
};
}
+119
View File
@@ -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);
});
+88
View File
@@ -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;
},
};
}
+128
View File
@@ -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`,
);
});
+44
View File
@@ -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');
});
+28 -5
View File
@@ -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 };
}
+30
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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,
+51
View File
@@ -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;
+3
View File
@@ -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;
+184
View File
@@ -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)'),
};
},
};
}
+152
View File
@@ -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`,
);
});
+111
View File
@@ -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 };
}
+10
View File
@@ -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
+10
View File
@@ -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');
});
+8
View File
@@ -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)
+47 -13
View File
@@ -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)
+73 -8
View File
@@ -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]. */
+130
View File
@@ -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,
+26
View File
@@ -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;
});
}
});
+6 -1
View File
@@ -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`,
};
}
+28
View File
@@ -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`,
);
});
+12
View File
@@ -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');
});
+2
View File
@@ -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,
};
},
};
+155
View File
@@ -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 };
}
+51
View File
@@ -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;
}
});
+281
View File
@@ -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,
};
}
+627
View File
@@ -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
View File
@@ -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 };
}
+462
View File
@@ -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();
});
+129
View File
@@ -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);
});
+130
View File
@@ -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;
},
});
}
+851
View File
@@ -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,
};
}
+208
View File
@@ -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`,
);
}
},
);
+162
View File
@@ -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
+115
View File
@@ -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();
}
});
+36
View File
@@ -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;
}
+183
View File
@@ -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();
});
+145
View File
@@ -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'),
}),
]);
+341
View File
@@ -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();
},
};
}
+691
View File
@@ -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);
});
+560
View File
@@ -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);
});
+663
View File
@@ -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);
});
+136
View File
@@ -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`,
);
}
});
+83
View File
@@ -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],
);
});