mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
Merge main through #1591 into the renderer seam
Brings in the wildlife sightings layer (#1591, iNaturalist and Acartia sightings). Its badges, density glow and privacy cells draw through the draw port: the badges and the glow are icons sets (iconCollection.js batches point writes into one upsert per task), and the privacy cells are ground-clamped shapes and lines sets swapped whole. The eye, the view rectangle, clicks, projection, ground readiness and frames come from the camera, query, input, globe and frame ports, so the layer, its card and its placement no longer import Cesium. Differences from main: the density glow is drawn as pixel-sized splats (56 px) instead of metre-sized ones with a near fade; the card's pan eases with cubicOut, the contract's nearest ease-out; ground heights are resampled when the globe's load progress settles or its surface changes, rather than on tileset load events. Also fixes two things the last merge left: a double-click that starts on the followed track and ends off it reaches the renderer's own follow again (a press that cannot end a double-click on the track gives its hold back at its release), and the Active Fires heat drapes under the weather imagery, so weather turned on after it stacks above. CURRENT-STATE notes that the 2D and Columbus scene-mode checks are gone.
This commit is contained in:
commit
020a433b51
129 files changed
+22143
-336
No files matched your search
@@ -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,113 @@
|
||||
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)) {
|
||||
// Our last descriptor, rather than what the point now holds,
|
||||
// records whether the appearance has actually changed.
|
||||
if (old?.appearance?.[key] === appearance[key]) continue;
|
||||
point[key] = appearance[key];
|
||||
writes += 1;
|
||||
}
|
||||
result.writes += writes;
|
||||
if (writes) result.updated += 1;
|
||||
}
|
||||
previous.set(id, {
|
||||
lat: row.lat,
|
||||
lon: row.lon,
|
||||
group,
|
||||
appearance,
|
||||
});
|
||||
}
|
||||
for (const [id, point] of pointById) {
|
||||
if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'billboard-update';
|
||||
if (nextIds.has(id)) continue;
|
||||
collection.remove(point);
|
||||
pointById.delete(id);
|
||||
positions.delete(id);
|
||||
previous.delete(id);
|
||||
result.removed += 1;
|
||||
}
|
||||
onOperations?.({ billboardVisits: visits, billboardWrites: result.writes });
|
||||
return result;
|
||||
}
|
||||
|
||||
function clear() {
|
||||
collection.removeAll();
|
||||
pointById.clear();
|
||||
positions.clear();
|
||||
previous.clear();
|
||||
}
|
||||
|
||||
// Font readiness replaces just the cached texture. Never resample anchors,
|
||||
// clear the collection or allocate replacement billboards for this swap.
|
||||
function refreshImages(imageForGroup) {
|
||||
let writes = 0;
|
||||
for (const [id, old] of previous) {
|
||||
const point = pointById.get(id);
|
||||
const image = imageForGroup(old.group);
|
||||
if (!point || old.appearance.image === image) continue;
|
||||
point.image = image;
|
||||
old.appearance = { ...old.appearance, image };
|
||||
writes += 1;
|
||||
}
|
||||
return writes;
|
||||
}
|
||||
|
||||
return { update, updateWork, clear, refreshImages };
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
// Shared by browser viewport queries and the provider's cache-key validation.
|
||||
export const WILDLIFE_MAX_VIEW_DEGREES = 40;
|
||||
|
||||
const cleanDegree = (value) => Math.round(value * 1e8) / 1e8;
|
||||
const spanOf = (box) => Math.max(box.north - box.south, box.east - box.west);
|
||||
|
||||
/** Snap non-crossing boxes outward to one canonical grid. Validate the final
|
||||
* span too: a legal raw box may expand past the supported query size. */
|
||||
export function snapWildlifeBox(box) {
|
||||
if (
|
||||
!box ||
|
||||
!['south', 'west', 'north', 'east'].every((key) =>
|
||||
Number.isFinite(box[key]),
|
||||
) ||
|
||||
box.south < -90 ||
|
||||
box.north > 90 ||
|
||||
box.west < -180 ||
|
||||
box.east > 180 ||
|
||||
box.north <= box.south ||
|
||||
box.east <= box.west ||
|
||||
spanOf(box) > WILDLIFE_MAX_VIEW_DEGREES + 1e-8
|
||||
)
|
||||
return null;
|
||||
let grid = spanOf(box) > 5 ? 1 : 0.1;
|
||||
const snap = () => ({
|
||||
south: Math.max(
|
||||
-90,
|
||||
cleanDegree(Math.floor((box.south + 1e-10) / grid) * grid),
|
||||
),
|
||||
west: Math.max(
|
||||
-180,
|
||||
cleanDegree(Math.floor((box.west + 1e-10) / grid) * grid),
|
||||
),
|
||||
north: Math.min(
|
||||
90,
|
||||
cleanDegree(Math.ceil((box.north - 1e-10) / grid) * grid),
|
||||
),
|
||||
east: Math.min(
|
||||
180,
|
||||
cleanDegree(Math.ceil((box.east - 1e-10) / grid) * grid),
|
||||
),
|
||||
});
|
||||
let snapped = snap();
|
||||
// Crossing the five-degree boundary while snapping must pick the same grid
|
||||
// on the browser and proxy, and on every subsequent snap of this box.
|
||||
if (grid === 0.1 && spanOf(snapped) > 5 + 1e-8) {
|
||||
grid = 1;
|
||||
snapped = snap();
|
||||
}
|
||||
return spanOf(snapped) <= WILDLIFE_MAX_VIEW_DEGREES ? snapped : null;
|
||||
}
|
||||
@@ -0,0 +1,111 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { inaturalistProxy } from '../../../server/providers/inaturalist/observations.js';
|
||||
import { syntheticGrid } from '../../../server/providers/inaturalist/grid.fixture.mjs';
|
||||
import {
|
||||
createWildlifeSightingsSource,
|
||||
WILDLIFE_GRID_TTL_MS,
|
||||
} from './source.js';
|
||||
|
||||
// Exercise both real cache owners through their projected response contract.
|
||||
// Only the HTTP transport and upstream data are synthetic; no socket is needed.
|
||||
test('client and proxy share stale revalidation and publish its fresh result in the same view', async () => {
|
||||
let now = Date.parse('2026-11-04T18:05:00Z');
|
||||
let upstreamCalls = 0;
|
||||
let proxyCalls = 0;
|
||||
let finishRefresh;
|
||||
let handler;
|
||||
inaturalistProxy({
|
||||
now: () => now,
|
||||
cacheDir: null,
|
||||
queueOptions: { intervalMs: 0, windowMs: 0 },
|
||||
warn() {},
|
||||
fetchImpl() {
|
||||
upstreamCalls++;
|
||||
return upstreamCalls === 1
|
||||
? Response.json(syntheticGrid())
|
||||
: new Promise((resolve) => {
|
||||
finishRefresh = resolve;
|
||||
});
|
||||
},
|
||||
}).configureServer({
|
||||
middlewares: {
|
||||
use(_mount, middleware) {
|
||||
handler = middleware;
|
||||
},
|
||||
},
|
||||
});
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
async fetchImpl(url) {
|
||||
proxyCalls++;
|
||||
let status;
|
||||
let headers;
|
||||
let response;
|
||||
await handler(
|
||||
{
|
||||
method: 'GET',
|
||||
url: url.slice('/api/inaturalist'.length),
|
||||
headers: {},
|
||||
socket: { remoteAddress: 'synthetic' },
|
||||
},
|
||||
{
|
||||
writeHead(code, values) {
|
||||
status = code;
|
||||
headers = values;
|
||||
},
|
||||
end(body) {
|
||||
response = new Response(body, { status, headers });
|
||||
},
|
||||
},
|
||||
);
|
||||
return response;
|
||||
},
|
||||
});
|
||||
const options = { tiles: [{ z: 2, x: 1, y: 1 }], taxa: 'Aves' };
|
||||
const first = await source.getGridSnapshot(options);
|
||||
assert.equal(first.cells.length, 2);
|
||||
await source.getGridSnapshot(options);
|
||||
assert.equal(upstreamCalls, 1);
|
||||
assert.equal(proxyCalls, 1, 'client hits do not even call the proxy');
|
||||
now += WILDLIFE_GRID_TTL_MS;
|
||||
const publications = [];
|
||||
let settled = false;
|
||||
const refreshing = source
|
||||
.getGridSnapshot({
|
||||
...options,
|
||||
onTile: (value) => publications.push(value),
|
||||
})
|
||||
.then((value) => {
|
||||
settled = true;
|
||||
return value;
|
||||
});
|
||||
try {
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
assert.equal(settled, false, 'revalidation is still waiting for upstream');
|
||||
assert.equal(
|
||||
publications[0]?.stale,
|
||||
true,
|
||||
'old cells already reached the renderer',
|
||||
);
|
||||
assert.deepEqual(publications[0].cells, first.cells);
|
||||
assert.equal(
|
||||
upstreamCalls,
|
||||
2,
|
||||
'normal stale GET and refresh=wait share one upstream attempt',
|
||||
);
|
||||
finishRefresh(Response.json(syntheticGrid()));
|
||||
const fresh = await refreshing;
|
||||
assert.equal(fresh.stale, false);
|
||||
assert.equal(fresh.fetchedAt, now);
|
||||
assert.equal(publications.at(-1).fetchedAt, now);
|
||||
assert.notEqual(publications.at(-1).stale, true);
|
||||
const before = proxyCalls;
|
||||
await source.getGridSnapshot(options);
|
||||
assert.equal(proxyCalls, before);
|
||||
assert.equal(upstreamCalls, 2);
|
||||
} finally {
|
||||
finishRefresh?.(Response.json(syntheticGrid()));
|
||||
await refreshing;
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,281 @@
|
||||
import { photoCreator } from './photoText.js';
|
||||
import { getLocale, t, translateKnown } from '../../i18n/index.js';
|
||||
import { CCTV_THUMBNAIL_STYLE } from '../../overlays/worldOverlayTokens.js';
|
||||
import { truncateOverlayTitle } from '../../overlays/worldOverlayDraw.js';
|
||||
import { isOpenPhoto } from './records.js';
|
||||
import { compareWildlifeIds, wildlifeIconicGroup } from './model.js';
|
||||
import {
|
||||
ICONIC_TINTS,
|
||||
WILDLIFE_CARD_LIMIT,
|
||||
WILDLIFE_CARD_MIN_SEP_PX,
|
||||
WILDLIFE_CARD_REGION_COLUMNS,
|
||||
WILDLIFE_CARD_REGION_ROWS,
|
||||
WILDLIFE_CARD_ALTITUDE_SCALE,
|
||||
WILDLIFE_CARD_FADE_LOW_METERS,
|
||||
WILDLIFE_CARD_FADE_HIGH_METERS,
|
||||
WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS,
|
||||
WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
|
||||
WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
WILDLIFE_CARD_MAX_DISTANCE_METERS,
|
||||
WILDLIFE_LABEL_LIMIT,
|
||||
} from './policy.js';
|
||||
|
||||
export const WILDLIFE_OVERLAY_SOURCE_ID = 'wildlife-sightings';
|
||||
export const WILDLIFE_LABEL_SOURCE_ID = 'wildlife-sightings-labels';
|
||||
export const WILDLIFE_SELECTED_SOURCE_ID = 'wildlife-sightings-selected';
|
||||
export const WILDLIFE_LABEL_SOURCE_OPTIONS = Object.freeze({
|
||||
cohortLimit: WILDLIFE_LABEL_LIMIT,
|
||||
collisionCapacity: WILDLIFE_LABEL_LIMIT,
|
||||
moving: false,
|
||||
});
|
||||
export const WILDLIFE_OVERLAY_SOURCE_OPTIONS = Object.freeze({
|
||||
cohortLimit: WILDLIFE_CARD_LIMIT,
|
||||
collisionCapacity: WILDLIFE_CARD_LIMIT,
|
||||
moving: false,
|
||||
});
|
||||
export const WILDLIFE_SELECTED_SOURCE_OPTIONS = Object.freeze({
|
||||
cohortLimit: 1,
|
||||
collisionCapacity: 1,
|
||||
moving: false,
|
||||
});
|
||||
|
||||
/** Match cards and labels to the sighting sprite's taxon tint. */
|
||||
export function wildlifeAccent(iconic) {
|
||||
return ICONIC_TINTS[wildlifeIconicGroup(iconic)];
|
||||
}
|
||||
|
||||
/** Importance score for open, non-sensitive iNaturalist photos. Other rows
|
||||
* cannot consume a slot, even if an accidental photo field reaches a caller. */
|
||||
export function ambientScore(row, nowMs) {
|
||||
if (row?.obscured || !isOpenPhoto(row?.photo) || !photoCreator(row.photo))
|
||||
return -Infinity;
|
||||
const nonnegative = (n) => (Number.isFinite(n) ? Math.max(0, n) : 0);
|
||||
const time = Number.isFinite(row.observedAt)
|
||||
? row.observedAt
|
||||
: Date.parse(row.observedOn);
|
||||
const ageH =
|
||||
Number.isFinite(time) && Number.isFinite(nowMs)
|
||||
? Math.max(0, (nowMs - time) / 3_600_000)
|
||||
: Infinity;
|
||||
return (
|
||||
(row.quality === 'research' ? 2 : 0) +
|
||||
(row.threatened ? 1 : 0) +
|
||||
Math.log1p(nonnegative(row.favesCount)) +
|
||||
0.5 * Math.log1p(nonnegative(row.identificationAgreements)) +
|
||||
2 * 0.5 ** (ageH / 12)
|
||||
);
|
||||
}
|
||||
|
||||
/** Named rows without eligible photos rank below eligible photo rows. */
|
||||
export function wildlifeLabelScore(row, nowMs) {
|
||||
const score = ambientScore(row, nowMs);
|
||||
return Number.isFinite(score) ? score : -1;
|
||||
}
|
||||
|
||||
/** Visible incumbents own their slots until they leave the view/window. A new
|
||||
* random sample or a higher-scoring challenger can only fill a free slot. */
|
||||
function rankWildlifeAmbientRows(rows, currentIds, nowMs) {
|
||||
const incumbent = new Map(currentIds.map((id, index) => [id, index]));
|
||||
const scored = rows
|
||||
.map((row) => ({
|
||||
row,
|
||||
score: ambientScore(row, nowMs),
|
||||
current: incumbent.get(row.stableId),
|
||||
}))
|
||||
.filter((item) => Number.isFinite(item.score));
|
||||
scored.sort((a, b) => {
|
||||
if (a.current !== undefined || b.current !== undefined) {
|
||||
if (a.current === undefined) return 1;
|
||||
if (b.current === undefined) return -1;
|
||||
return a.current - b.current;
|
||||
}
|
||||
return (
|
||||
b.score - a.score || compareWildlifeIds(a.row.stableId, b.row.stableId)
|
||||
);
|
||||
});
|
||||
return scored.map((item) => item.row);
|
||||
}
|
||||
|
||||
/** Spread newly admitted cards over screen regions. Once shown, a card stays
|
||||
* even when a pan moves it into another incumbent's region; region quotas only
|
||||
* govern free slots, so a camera movement never replaces a visible photo. */
|
||||
export function selectWildlifeAmbientRows(
|
||||
rows,
|
||||
currentIds = [],
|
||||
nowMs,
|
||||
limit = WILDLIFE_CARD_LIMIT,
|
||||
{ screens = null, width = 0, height = 0 } = {},
|
||||
) {
|
||||
const incumbent = new Set(currentIds);
|
||||
const accepted = [];
|
||||
const regions = new Set();
|
||||
const regionFor = (screen) =>
|
||||
`${Math.min(WILDLIFE_CARD_REGION_COLUMNS - 1, Math.floor((screen.x / width) * WILDLIFE_CARD_REGION_COLUMNS))}:${Math.min(WILDLIFE_CARD_REGION_ROWS - 1, Math.floor((screen.y / height) * WILDLIFE_CARD_REGION_ROWS))}`;
|
||||
for (const row of rankWildlifeAmbientRows(rows, currentIds, nowMs)) {
|
||||
if (accepted.length >= Math.max(0, limit)) break;
|
||||
const screen = screens?.get(row.stableId);
|
||||
const region = screen && width > 0 && height > 0 ? regionFor(screen) : null;
|
||||
if (!incumbent.has(row.stableId)) {
|
||||
if (region !== null && regions.has(region)) continue;
|
||||
if (
|
||||
screen &&
|
||||
accepted.some((other) => {
|
||||
const prior = screens.get(other.stableId);
|
||||
return (
|
||||
prior &&
|
||||
Math.hypot(prior.x - screen.x, prior.y - screen.y) <
|
||||
WILDLIFE_CARD_MIN_SEP_PX
|
||||
);
|
||||
})
|
||||
)
|
||||
continue;
|
||||
}
|
||||
accepted.push(row);
|
||||
if (region !== null) regions.add(region);
|
||||
}
|
||||
return accepted;
|
||||
}
|
||||
|
||||
function nameFor(row) {
|
||||
return translateKnown(row.commonName || row.scientificName) || t('SIGHTING');
|
||||
}
|
||||
|
||||
/** Return a trimmed common name, or null for unnamed observations. */
|
||||
export function wildlifeCommonName(row) {
|
||||
const name = row.commonName;
|
||||
return typeof name === 'string' && name.trim() ? name.trim() : null;
|
||||
}
|
||||
|
||||
/** Full translated display name, shared by titles and screen-space deduping. */
|
||||
export function wildlifeDisplayName(row) {
|
||||
const commonName = wildlifeCommonName(row);
|
||||
const name = commonName ? translateKnown(commonName).trim() : '';
|
||||
return name.replace(/\s+/g, ' ').trim().toLocaleUpperCase(getLocale());
|
||||
}
|
||||
|
||||
function compactName(row) {
|
||||
return truncateOverlayTitle(
|
||||
wildlifeDisplayName(row),
|
||||
WILDLIFE_SELECTED_LABEL_MAX_CHARS,
|
||||
);
|
||||
}
|
||||
|
||||
/** One-line common names for identified observations. The caller adds the
|
||||
* Cartesian anchor after ranking and front-side/screen-space filtering. */
|
||||
export function buildWildlifeLabelEntry(
|
||||
row,
|
||||
{ select, hasRow, nowMs = Date.now() } = {},
|
||||
) {
|
||||
if (!wildlifeCommonName(row)) return null;
|
||||
return {
|
||||
id: `wildlife-sightings-label:${row.stableId}`,
|
||||
variant: 'label',
|
||||
title: compactName(row),
|
||||
accent: wildlifeAccent(row.iconic),
|
||||
priority: wildlifeLabelScore(row, nowMs),
|
||||
collisionGroup: 'ambient-label',
|
||||
// The host checks actual card placements, including sticky/fading cards,
|
||||
// before spending the remaining space on labels in score order.
|
||||
yieldToCollisionGroup: 'ambient-card',
|
||||
stateless: true,
|
||||
paintLane: 'ambient-label',
|
||||
gapPx: 15,
|
||||
verticalOnly: true,
|
||||
placement: 'above',
|
||||
horizonCull: true,
|
||||
edgeFade: 'keyhole',
|
||||
interactive: false,
|
||||
accessibilityLabel: nameFor(row),
|
||||
...selectionAction(row, { select, hasRow }),
|
||||
};
|
||||
}
|
||||
|
||||
function selectionAction(row, { select, hasRow } = {}) {
|
||||
if (typeof select !== 'function') return {};
|
||||
return {
|
||||
interactive: true,
|
||||
accessibilityLabel: t('Show {name} sighting', { name: nameFor(row) }),
|
||||
activate() {
|
||||
if (typeof hasRow === 'function' && !hasRow(row.stableId)) return false;
|
||||
return select(row.stableId) !== false;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** Build an attributed ambient photo; the runtime supplies the decoded image. */
|
||||
export function buildWildlifeThumbnailEntry(
|
||||
row,
|
||||
nowMs,
|
||||
{ image = null, select, hasRow, selected = false } = {},
|
||||
) {
|
||||
const score = ambientScore(row, nowMs);
|
||||
if (!Number.isFinite(score)) return null;
|
||||
return {
|
||||
id: `sighting:${row.stableId}`,
|
||||
variant: 'thumbnail',
|
||||
title: nameFor(row),
|
||||
image,
|
||||
requireImage: true,
|
||||
accent: wildlifeAccent(row.iconic),
|
||||
interactive: false,
|
||||
accessibilityLabel: t('Show {name} sighting', { name: nameFor(row) }),
|
||||
collisionGroup: 'ambient-card',
|
||||
horizonCull: true,
|
||||
edgeFade: 'keyhole',
|
||||
verticalOnly: true,
|
||||
gapPx: 15,
|
||||
thumbnailPadX: CCTV_THUMBNAIL_STYLE.padding,
|
||||
thumbnailPadTop: CCTV_THUMBNAIL_STYLE.padding,
|
||||
thumbnailPadBottom: CCTV_THUMBNAIL_STYLE.padding,
|
||||
thumbnailTitleGap: 2,
|
||||
thumbnailTitleHeight: CCTV_THUMBNAIL_STYLE.titleHeight,
|
||||
thumbnailTitleChars: CCTV_THUMBNAIL_STYLE.titleChars,
|
||||
thumbnailTitleWordBoundary: true,
|
||||
thumbnailBackground: CCTV_THUMBNAIL_STYLE.background,
|
||||
thumbnailTitleColor: CCTV_THUMBNAIL_STYLE.titleColor,
|
||||
thumbnailTitleFont: CCTV_THUMBNAIL_STYLE.titleFont,
|
||||
thumbnailLeaderColor: CCTV_THUMBNAIL_STYLE.leader,
|
||||
thumbnailRuleColor: CCTV_THUMBNAIL_STYLE.rule,
|
||||
thumbnailRuleHeight: CCTV_THUMBNAIL_STYLE.ruleHeight,
|
||||
thumbnailRadius: CCTV_THUMBNAIL_STYLE.radius,
|
||||
...selectionAction(row, { select, hasRow }),
|
||||
// i18n-ignore: the creator is verbatim feed attribution with a copyright mark
|
||||
details: [`© ${photoCreator(row.photo)}`],
|
||||
thumbnailFixedWidth: true,
|
||||
thumbnailFit: 'contain',
|
||||
thumbnailWidth: 96,
|
||||
thumbnailHeight: 72,
|
||||
priority: selected ? Number.MAX_SAFE_INTEGER : score,
|
||||
minAnchorSeparationPx: WILDLIFE_CARD_MIN_SEP_PX,
|
||||
maxDistance: WILDLIFE_CARD_MAX_DISTANCE_METERS,
|
||||
altitudeScale: WILDLIFE_CARD_ALTITUDE_SCALE,
|
||||
altitudeFadeStart: WILDLIFE_CARD_FADE_LOW_METERS,
|
||||
altitudeFadeEnd: WILDLIFE_CARD_FADE_HIGH_METERS,
|
||||
...(selected ? { selected: true, paintLane: 'selected' } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
/** A bounded selected name uses the host's shared selected card treatment. */
|
||||
export function buildWildlifeSelectedLabel(row) {
|
||||
if (!wildlifeCommonName(row)) return null;
|
||||
return {
|
||||
id: `wildlife-sightings-label:${row.stableId}`,
|
||||
variant: 'label',
|
||||
selected: true,
|
||||
protected: true,
|
||||
yieldToCollisionGroup: 'ambient-card',
|
||||
paintLane: 'selected',
|
||||
priority: Number.MAX_SAFE_INTEGER,
|
||||
title: compactName(row),
|
||||
accent: wildlifeAccent(row.iconic),
|
||||
gapPx: 15,
|
||||
verticalOnly: true,
|
||||
placement: 'above',
|
||||
horizonCull: true,
|
||||
edgeFade: 'keyhole',
|
||||
interactive: false,
|
||||
accessibilityLabel: nameFor(row),
|
||||
altitudeFadeStart: WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS,
|
||||
altitudeFadeEnd: WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,629 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { bindWildlifeViewer } from '../../testSupport/wildlifeViewer.mjs';
|
||||
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 } },
|
||||
},
|
||||
};
|
||||
bindWildlifeViewer(state.viewer);
|
||||
const photos = [];
|
||||
const painted = [];
|
||||
const entries = new Map();
|
||||
let cardSourceOptions;
|
||||
const selection = createSelection({
|
||||
state,
|
||||
services: {
|
||||
now: () => now,
|
||||
project: (_scene, position) => position,
|
||||
overlayHost: {
|
||||
setEntries(id, _entries, options) {
|
||||
entries.set(id, _entries);
|
||||
if (id === 'wildlife-sightings') cardSourceOptions = options;
|
||||
},
|
||||
},
|
||||
},
|
||||
parts: {
|
||||
rendering: {
|
||||
occluder: () => null,
|
||||
requestRender() {},
|
||||
setPhotoCardVisibility: (ids) => painted.push([...ids]),
|
||||
},
|
||||
photos: { get: () => null, setAmbient: (rows) => photos.push(rows) },
|
||||
},
|
||||
});
|
||||
return {
|
||||
state,
|
||||
selection,
|
||||
photos,
|
||||
painted,
|
||||
entries,
|
||||
get cardSourceOptions() {
|
||||
return cardSourceOptions;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('label candidates and host priorities use ambientScore before the candidate cap', () => {
|
||||
const rows = Array.from({ length: WILDLIFE_LABEL_LIMIT + 20 }, (_, i) =>
|
||||
row({
|
||||
stableId: `inat:${String(i).padStart(3, '0')}`,
|
||||
commonName: `Synthetic bird ${i}`,
|
||||
favesCount: i,
|
||||
}),
|
||||
);
|
||||
const f = ambientFixture(
|
||||
rows,
|
||||
new Map(
|
||||
rows.map((r, i) => [
|
||||
r.stableId,
|
||||
{ x: 10 + (i % 40) * 28, y: 200 + Math.floor(i / 40) * 28 },
|
||||
]),
|
||||
),
|
||||
);
|
||||
f.selection.refreshAmbient();
|
||||
const entries = f.entries.get('wildlife-sightings-labels');
|
||||
assert.equal(entries.length, WILDLIFE_LABEL_LIMIT);
|
||||
assert.deepEqual(
|
||||
entries.map((entry) => entry.id),
|
||||
rows
|
||||
.slice(20)
|
||||
.reverse()
|
||||
.map((r) => `wildlife-sightings-label:${r.stableId}`),
|
||||
);
|
||||
for (const r of f.state.labelRows)
|
||||
assert.equal(
|
||||
buildWildlifeLabelEntry(r, { nowMs: now }).priority,
|
||||
ambientScore(r, now),
|
||||
);
|
||||
});
|
||||
|
||||
test('ambient source forwards actual painted membership to badge visibility', () => {
|
||||
const r = row();
|
||||
const f = ambientFixture([r], new Map([[r.stableId, { x: 150, y: 150 }]]));
|
||||
f.selection.refreshAmbient();
|
||||
assert.deepEqual(f.painted, [], 'a queued photo is not a painted card');
|
||||
f.cardSourceOptions.onVisibilityChange(new Set([`sighting:${r.stableId}`]));
|
||||
assert.deepEqual(f.painted, [[`sighting:${r.stableId}`]]);
|
||||
f.cardSourceOptions.onVisibilityChange(new Set());
|
||||
assert.deepEqual(f.painted.at(-1), []);
|
||||
});
|
||||
|
||||
test('new ambient cards admit at most one highest-score photo per screen region', () => {
|
||||
const rows = Array.from({ length: 24 }, (_, i) =>
|
||||
row({ stableId: `inat:${i}`, favesCount: i }),
|
||||
);
|
||||
const screens = new Map(
|
||||
rows.map((row, i) => [
|
||||
row.stableId,
|
||||
{
|
||||
x: 150 + (Math.floor(i / 2) % 4) * 300,
|
||||
y: 150 + Math.floor(i / 8) * 300,
|
||||
},
|
||||
]),
|
||||
);
|
||||
const f = ambientFixture(rows, screens);
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 12);
|
||||
assert.ok(
|
||||
f.state.ambientRows.every(
|
||||
(row) => Number(row.stableId.split(':')[1]) % 2 === 1,
|
||||
),
|
||||
);
|
||||
assert.equal(
|
||||
new Set(
|
||||
f.state.ambientRows.map((row) => {
|
||||
const p = screens.get(row.stableId);
|
||||
return `${Math.floor(p.x / 300)}:${Math.floor(p.y / 300)}`;
|
||||
}),
|
||||
).size,
|
||||
12,
|
||||
);
|
||||
});
|
||||
|
||||
test('pans retain every on-screen photo and refreshes only fill free slots', () => {
|
||||
const a = row({ stableId: 'inat:a' });
|
||||
const b = row({ stableId: 'inat:b' });
|
||||
const c = row({ stableId: 'inat:c', favesCount: 1000 });
|
||||
const screens = new Map([
|
||||
[a.stableId, { x: 150, y: 150 }],
|
||||
[b.stableId, { x: 450, y: 150 }],
|
||||
[c.stableId, { x: 170, y: 150 }],
|
||||
]);
|
||||
const f = ambientFixture([a, b], screens);
|
||||
f.selection.refreshAmbient();
|
||||
const initial = f.state.ambientIds.slice();
|
||||
// This pan moves the two incumbents into one region. Neither may be evicted.
|
||||
f.state.positions.set(b.stableId, { x: 200, y: 160 });
|
||||
f.selection.refreshAmbient();
|
||||
assert.deepEqual(f.state.ambientIds, initial);
|
||||
f.state.rowById.set(c.stableId, c);
|
||||
f.state.positions.set(c.stableId, screens.get(c.stableId));
|
||||
// A new random sample can omit both incumbent rows from the rendered batch.
|
||||
f.state.renderedRows = [c];
|
||||
f.selection.refreshAmbient();
|
||||
assert.deepEqual(f.state.ambientIds, initial);
|
||||
assert.deepEqual(
|
||||
new Set(f.selection.retainedAmbientRows().map((row) => row.stableId)),
|
||||
new Set(initial),
|
||||
);
|
||||
f.state.positions.set(a.stableId, { x: -1, y: 150 });
|
||||
assert.deepEqual(
|
||||
f.selection.retainedAmbientRows().map((row) => row.stableId),
|
||||
[b.stableId],
|
||||
);
|
||||
});
|
||||
|
||||
test('ambient show/hide thresholds have hysteresis without small-zoom toggles', () => {
|
||||
const a = row();
|
||||
const f = ambientFixture([a], new Map([[a.stableId, { x: 150, y: 150 }]]));
|
||||
const height = f.state.viewer.camera.positionCartographic;
|
||||
height.height = WILDLIFE_CARD_SHOW_MAX_METERS - 1;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 1);
|
||||
for (const altitude of [110_001, 119_999, 120_001, 124_999, 110_001]) {
|
||||
height.height = altitude;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 1);
|
||||
}
|
||||
height.height = WILDLIFE_CARD_HIDE_MAX_METERS;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 0);
|
||||
height.height = WILDLIFE_CARD_HIDE_MAX_METERS - 1;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 0);
|
||||
height.height = WILDLIFE_CARD_SHOW_MAX_METERS;
|
||||
f.selection.refreshAmbient();
|
||||
assert.equal(f.state.ambientRows.length, 1);
|
||||
});
|
||||
+250
@@ -0,0 +1,250 @@
|
||||
import { t, formatNumber, translateKnown } from '../../i18n/index.js';
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
import { translateFeedError } from '../../ui/statusText.js';
|
||||
import { wildlifeIconicGroup } from './model.js';
|
||||
import { formatAge } from './photoText.js';
|
||||
import { wildlifeEyeHeight } from './view.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 &&
|
||||
wildlifeEyeHeight(state.viewer) > WILDLIFE_GRID_HEIGHT_METERS
|
||||
) {
|
||||
// i18n-ignore: feed-state protocol value
|
||||
stats.status = 'zoom-in';
|
||||
stats.statusMessage = msg('Zoom in for local sightings');
|
||||
} else if (!state.error && state.lastUpdate && !count) {
|
||||
// i18n-ignore: feed-state protocol value
|
||||
stats.status = 'empty';
|
||||
stats.statusMessage = msg('No recent sightings in view');
|
||||
}
|
||||
if (state.retryAt > services.now())
|
||||
stats.retryInSec = Math.ceil((state.retryAt - services.now()) / 1000);
|
||||
return stats;
|
||||
},
|
||||
};
|
||||
return { methods, notify };
|
||||
}
|
||||
@@ -0,0 +1,485 @@
|
||||
import { fromDegrees } from '../../geo/ellipsoid.js';
|
||||
import { drawOf, findCamera } from '../../render/rendererOf.js';
|
||||
import { spriteDrawOrder } from '../../data/spriteOrder.js';
|
||||
import { createWildlifeIconCollection } from './iconCollection.js';
|
||||
import {
|
||||
WILDLIFE_GRID_SAMPLE_SPACING_PX,
|
||||
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;
|
||||
// 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;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* A splat's drawn width, CSS pixels: the kernel spans
|
||||
* `WILDLIFE_DENSITY_OVERLAP` grid cells, and the grid is chosen so a cell
|
||||
* is about `WILDLIFE_GRID_SAMPLE_SPACING_PX` wide on screen.
|
||||
*/
|
||||
export const WILDLIFE_DENSITY_SPLAT_PX =
|
||||
WILDLIFE_DENSITY_OVERLAP * WILDLIFE_GRID_SAMPLE_SPACING_PX;
|
||||
|
||||
let glowSets = 0;
|
||||
|
||||
/**
|
||||
* The splats as an unpickable icons draw set under every sprite layer:
|
||||
* each splat a pixel-sized radial kernel drawn over depth. Positions are
|
||||
* ECEF metres, colours `[r, g, b, a]` in 0..1.
|
||||
*/
|
||||
function createGlowIcons(viewer, { image }) {
|
||||
const set = drawOf(viewer).icons({
|
||||
id: `wildlife-sightings:${++glowSets}:density`,
|
||||
pickable: false,
|
||||
drawOrder: spriteDrawOrder('cctv') - 1,
|
||||
});
|
||||
const points = createWildlifeIconCollection(set);
|
||||
let ids = 0;
|
||||
return {
|
||||
add({ position, color }) {
|
||||
return points.add({
|
||||
id: `density:${++ids}`,
|
||||
position,
|
||||
image,
|
||||
size: [WILDLIFE_DENSITY_SPLAT_PX, WILDLIFE_DENSITY_SPLAT_PX],
|
||||
color,
|
||||
disableDepthTest: Number.POSITIVE_INFINITY,
|
||||
pickable: false,
|
||||
});
|
||||
},
|
||||
setPosition(point, position) {
|
||||
point.position = position;
|
||||
},
|
||||
setColor(point, color) {
|
||||
point.color = color;
|
||||
},
|
||||
remove(point) {
|
||||
points.remove(point);
|
||||
},
|
||||
get length() {
|
||||
return points.length;
|
||||
},
|
||||
flush: () => points.flush(),
|
||||
destroy() {
|
||||
// Drops the batched writes too, so none reaches the disposed set.
|
||||
points.dispose();
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** The WGS84 polar radius, the inscribed sphere the horizon test fits in. */
|
||||
const MINIMUM_RADIUS = 6_356_752.314245;
|
||||
|
||||
/** Own noninteractive, world-sized glow splats, arrival fades and style changes. */
|
||||
export function createWildlifeDensity({
|
||||
viewer,
|
||||
createGlow = createGlowIcons,
|
||||
positionForCell = (cell) => 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;
|
||||
/** Send the splats' batched writes, then ask for the frame that shows them. */
|
||||
const render = (reason) => {
|
||||
collection?.flush();
|
||||
requestRender(reason);
|
||||
};
|
||||
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 });
|
||||
|
||||
function color(entry) {
|
||||
const mix = (i) => tint.low[i] + (tint.high[i] - tint.low[i]) * entry.rank;
|
||||
return [
|
||||
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';
|
||||
collection.setColor(entry.point, color(entry));
|
||||
}
|
||||
}
|
||||
|
||||
function setStyle(style) {
|
||||
const next = tintForStyle(style);
|
||||
if (next === tint) return;
|
||||
tint = next;
|
||||
if (entries.size)
|
||||
styleQueue.start(styleWork(), () => render('density-style'));
|
||||
}
|
||||
|
||||
function onStyle(event) {
|
||||
if (!cockpitVision) setStyle(event?.detail?.style);
|
||||
}
|
||||
|
||||
function onVision(event) {
|
||||
cockpitVision = event?.detail?.cockpit === true;
|
||||
setStyle(event?.detail?.style);
|
||||
}
|
||||
|
||||
/** The splat collection, made on first use. */
|
||||
function ensureCollection() {
|
||||
if (collection) return collection;
|
||||
collection = createGlow(viewer, { image: DENSITY_IMAGE });
|
||||
if (!listening) {
|
||||
tint = tintForStyle(documentRef?.documentElement?.dataset?.gevStyle);
|
||||
eventTarget?.addEventListener?.('gev:style-change', onStyle);
|
||||
eventTarget?.addEventListener?.('gev:vision-change', onVision);
|
||||
listening = true;
|
||||
}
|
||||
return collection;
|
||||
}
|
||||
|
||||
function* fadeWork() {
|
||||
let visits = 0;
|
||||
for (const entry of fading) {
|
||||
if (visits++ % WILDLIFE_WORK_UNIT === 0) yield 'density-fade';
|
||||
entry.fade++;
|
||||
collection.setColor(entry.point, 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(), () => {
|
||||
render('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 pose = findCamera(viewer)?.pose();
|
||||
const height = pose?.height ?? 0;
|
||||
const opacity = Math.max(
|
||||
0,
|
||||
Math.min(
|
||||
1,
|
||||
(ALTITUDE_FADE_END - height) /
|
||||
(ALTITUDE_FADE_END - ALTITUDE_FADE_START),
|
||||
),
|
||||
);
|
||||
const insideHorizon = horizonTest(pose?.position, MINIMUM_RADIUS);
|
||||
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,
|
||||
color: color(entry),
|
||||
});
|
||||
entries.set(data.id, entry);
|
||||
fading.add(entry);
|
||||
operations.densityCreated++;
|
||||
changed = true;
|
||||
} else {
|
||||
entry.seen = token;
|
||||
if (entry.data.position !== data.position) {
|
||||
collection.setPosition(entry.point, data.position);
|
||||
operations.densityWrites++;
|
||||
changed = true;
|
||||
}
|
||||
if (entry.rank !== rank || entry.opacity !== opacity) {
|
||||
entry.rank = rank;
|
||||
entry.opacity = opacity;
|
||||
collection.setColor(entry.point, 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) render('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) {
|
||||
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)),
|
||||
/** Send the glow's batched writes to its set now. */
|
||||
flush: () => collection?.flush?.(),
|
||||
clear,
|
||||
destroy() {
|
||||
clear();
|
||||
destroyed = true;
|
||||
},
|
||||
get collection() {
|
||||
return collection;
|
||||
},
|
||||
get size() {
|
||||
return entries.size;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,530 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { fromDegrees, toLonLatH } from '../../geo/ellipsoid.js';
|
||||
import { horizonFrom } from '../../geo/horizon.js';
|
||||
import { wildlifeGridCellBounds } from './gridViewport.js';
|
||||
import {
|
||||
createWildlifeDensity,
|
||||
wildlifeDensityIntensity,
|
||||
wildlifeDensityRanks,
|
||||
wildlifeDensityKernel,
|
||||
WILDLIFE_DENSITY_MAX_ALPHA,
|
||||
WILDLIFE_DENSITY_OVERLAP,
|
||||
WILDLIFE_DENSITY_SPLAT_PX,
|
||||
} from './density.js';
|
||||
import { bindFakeCesiumCamera } from '../../testSupport/fakeCameraPort.mjs';
|
||||
import { fakeDrawPort } from '../../testSupport/fakeDrawPort.mjs';
|
||||
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 = { positionCartographic: { height: 0 } },
|
||||
} = {}) {
|
||||
const counts = { positions: 0, writes: 0, created: 0, updates: 0 };
|
||||
const draw = fakeDrawPort();
|
||||
const viewer = { camera, scene: {} };
|
||||
bindFakeCesiumCamera(viewer, { draw });
|
||||
const glowSets = () =>
|
||||
[...draw.sets.values()].filter(
|
||||
(record) => !record.disposed && record.spec.id.endsWith(':density'),
|
||||
);
|
||||
// Each splat reads its item live, by id, with its colour by channel.
|
||||
const views = new Map();
|
||||
const view = (record, id) => {
|
||||
if (!views.has(id))
|
||||
views.set(
|
||||
id,
|
||||
new Proxy(
|
||||
{},
|
||||
{
|
||||
get(_target, key) {
|
||||
const item = glowSets()[0]?.items.get(id);
|
||||
if (key === 'color') {
|
||||
const [red, green, blue, alpha] = item.color;
|
||||
return { red, green, blue, alpha };
|
||||
}
|
||||
return item?.[key];
|
||||
},
|
||||
},
|
||||
),
|
||||
);
|
||||
return views.get(id);
|
||||
};
|
||||
const glow = () => {
|
||||
const record = glowSets()[0];
|
||||
if (!record) return null;
|
||||
const ids = [...record.items.keys()];
|
||||
return {
|
||||
spec: record.spec,
|
||||
length: ids.length,
|
||||
get: (index) => view(record, ids[index]),
|
||||
};
|
||||
};
|
||||
// The draw port's writes to the glow, every batch counted once.
|
||||
Object.defineProperty(counts, 'writes', {
|
||||
get: () =>
|
||||
[...draw.sets.values()]
|
||||
.filter((record) => record.spec.id.endsWith(':density'))
|
||||
.reduce((sum, record) => sum + record.writes, 0),
|
||||
});
|
||||
const primitives = {
|
||||
get length() {
|
||||
return glowSets().length;
|
||||
},
|
||||
};
|
||||
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({
|
||||
viewer,
|
||||
positionForCell(row) {
|
||||
counts.positions++;
|
||||
return 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,
|
||||
glow,
|
||||
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 is a pixel-sized splat drawn over depth at its cell', () => {
|
||||
const h = harness();
|
||||
const rows = [cell(0, 4), cell(1, 9)];
|
||||
h.density.update(rows);
|
||||
const collection = h.glow();
|
||||
assert.equal(collection.length, 2);
|
||||
for (let i = 0; i < collection.length; i++) {
|
||||
const point = collection.get(i);
|
||||
assert.deepEqual(point.size, [
|
||||
WILDLIFE_DENSITY_SPLAT_PX,
|
||||
WILDLIFE_DENSITY_SPLAT_PX,
|
||||
]);
|
||||
assert.equal(point.disableDepthTest, Infinity);
|
||||
assert.ok(Math.abs(toLonLatH(point.pos).lon - rows[i].lon) < 1e-9);
|
||||
}
|
||||
h.density.destroy();
|
||||
});
|
||||
|
||||
test('occupied grid counts produce unlabelled glow icons that never enter 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.glow();
|
||||
assert.equal(collection.spec.pickable, false);
|
||||
assert.equal(
|
||||
collection.spec.blend,
|
||||
undefined,
|
||||
'the default blend, so translucent glow writes no depth over badges',
|
||||
);
|
||||
assert.equal(collection.length, 3);
|
||||
const first = collection.get(0);
|
||||
assert.equal(first.pickable, false, 'density has no pick payload');
|
||||
assert.doesNotMatch(first.id, /wildlife:/, 'nor a sighting identity');
|
||||
assert.match(decodeURIComponent(first.image), /radialGradient/);
|
||||
assert.doesNotMatch(decodeURIComponent(first.image), /text|badge|raven/);
|
||||
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.glow().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.glow().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.glow().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: fromDegrees(0, 0, 5_000_000),
|
||||
positionCartographic: { height: 5_000_000 },
|
||||
};
|
||||
const h = harness({ camera });
|
||||
const occluder = horizonFrom(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(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.glow().get(0);
|
||||
const fullAlpha = point.color.alpha;
|
||||
camera.positionCartographic.height = 5_500_000;
|
||||
h.density.update(cells);
|
||||
assert.equal(h.glow().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.glow().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.glow().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 glow set, coordinates, timers and listeners', () => {
|
||||
const h = harness();
|
||||
const row = cell(0);
|
||||
h.density.update([row]);
|
||||
assert.equal(h.timers.size, 1);
|
||||
h.fadeStep();
|
||||
h.density.clear();
|
||||
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('destroy mid-update drops the glow writes still batched', async () => {
|
||||
const h = harness();
|
||||
const work = h.density.updateWork([cell(0), cell(1)]);
|
||||
while (!h.primitives.length && !work.next().done);
|
||||
assert.equal(h.primitives.length, 1, 'a splat is batched, not yet sent');
|
||||
h.density.destroy();
|
||||
// A batched write reaching the disposed set would throw here.
|
||||
await Promise.resolve();
|
||||
await Promise.resolve();
|
||||
assert.equal(h.primitives.length, 0);
|
||||
});
|
||||
|
||||
test('dense six-tile updates have a deterministic linear operation budget and no warmed writes/projections', (t) => {
|
||||
const h = harness();
|
||||
const cells = [];
|
||||
for (let x = 1; x < 3; x++)
|
||||
for (let y = 1; y < 4; y++)
|
||||
for (let row = 1; row < 64; row += 2)
|
||||
for (let column = 1; column < 64; column += 2) {
|
||||
const id = `grid:3/${x}/${y}:${row}:${column}`;
|
||||
const box = wildlifeGridCellBounds(id);
|
||||
cells.push({
|
||||
id,
|
||||
lat: (box.south + box.north) / 2,
|
||||
lon: (box.west + box.east) / 2,
|
||||
cellCount: row * 64 + column,
|
||||
});
|
||||
}
|
||||
let operations;
|
||||
h.density.update(cells, {
|
||||
onOperations: (value) => {
|
||||
operations = value;
|
||||
},
|
||||
});
|
||||
h.settle();
|
||||
assert.equal(operations.densityVisits, 6144);
|
||||
assert.equal(operations.densityMetadataBuilds, 6144);
|
||||
assert.equal(operations.densityPositionBuilds, 6144);
|
||||
assert.equal(operations.densityCreated, 6144);
|
||||
const positions = h.counts.positions;
|
||||
const writes = h.counts.writes;
|
||||
let units = 0;
|
||||
const work = h.density.updateWork(cells, {
|
||||
onOperations: (value) => {
|
||||
operations = value;
|
||||
},
|
||||
});
|
||||
while (!work.next().done) units++;
|
||||
assert.deepEqual(operations, {
|
||||
densityVisits: 6144,
|
||||
densityRetirementVisits: 6144,
|
||||
densityMetadataBuilds: 0,
|
||||
densityPositionBuilds: 0,
|
||||
densityWrites: 0,
|
||||
densityCreated: 0,
|
||||
densityRemoved: 0,
|
||||
});
|
||||
assert.equal(units, Math.ceil(6144 / WILDLIFE_WORK_UNIT) * 2);
|
||||
assert.equal(h.counts.positions, positions);
|
||||
assert.equal(h.counts.writes, writes);
|
||||
t.diagnostic(
|
||||
`6,144 occupied cells: ${units} bounded units, 12,288 linear visits, zero warmed metadata/Cartesian builds, projections or billboard writes`,
|
||||
);
|
||||
h.density.destroy();
|
||||
});
|
||||
@@ -0,0 +1,129 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { VOICE_OFF_LAYERS } from '../../voice/layerManifest.js';
|
||||
import { ANALYST_LAYERS } from '../../data/analystEngine.js';
|
||||
|
||||
const read = (path) =>
|
||||
readFileSync(new URL(`../../../${path}`, import.meta.url), 'utf8');
|
||||
const current = read('docs/CURRENT-STATE.md');
|
||||
const start = current.indexOf('## Wildlife Sightings —');
|
||||
const section = current
|
||||
.slice(start, current.indexOf('\n## ', start + 1))
|
||||
.replace(/\s+/g, ' ');
|
||||
|
||||
test('Wildlife docs name the permanent token, voice policy and coverage limits', () => {
|
||||
const token = JSON.parse(
|
||||
read('src/data/layerStateTokenReservations.json'),
|
||||
).find(([id]) => id === 'wildlife-sightings')?.[1];
|
||||
assert.ok(token);
|
||||
assert.match(section, new RegExp(`share-link token \`${token}\``));
|
||||
assert.match(section, /Voice is off for this layer for now/);
|
||||
assert.ok(Object.hasOwn(VOICE_OFF_LAYERS, 'wildlife-sightings'));
|
||||
assert.ok(!Object.hasOwn(ANALYST_LAYERS, 'wildlife-sightings'));
|
||||
assert.match(section, /not a census/i);
|
||||
assert.match(section, /Salish Sea/);
|
||||
assert.match(section, /0\.01°/);
|
||||
assert.match(section, /private records are excluded/);
|
||||
});
|
||||
|
||||
test('Wildlife documentation defines recency by observation time and compact ambient credit', () => {
|
||||
assert.match(section, /observation time/i);
|
||||
assert.match(section, /\bd1\b/);
|
||||
assert.match(section, /48 h/);
|
||||
assert.match(section, /96 px/);
|
||||
assert.match(section, /creator name/i);
|
||||
assert.match(section, /110\/125 km/);
|
||||
assert.match(section, /120 km/);
|
||||
assert.match(section, /random sample/);
|
||||
assert.match(section, /bounded frame cache/);
|
||||
assert.match(read('DATA_SOURCES.md'), /observation time/i);
|
||||
});
|
||||
|
||||
test('Wildlife docs describe direct photo selection and text-only privacy rows', () => {
|
||||
assert.match(section, /compact anchored\s+photo card/);
|
||||
assert.match(section, /object-fit: contain/);
|
||||
assert.match(section, /preserving zoom/);
|
||||
assert.match(section, /compact observed\s+age/);
|
||||
assert.match(section, /Obscured sightings also stay\s+text-only/);
|
||||
assert.match(section, /Acartia stays text-only/);
|
||||
assert.match(section, /closes the card and clears selection/);
|
||||
assert.match(
|
||||
section,
|
||||
/shell teardown also removes its host and subscription/,
|
||||
);
|
||||
assert.doesNotMatch(
|
||||
section,
|
||||
/opens\s+the \*\*Sighting\*\* panel|Clicking the panel photo/,
|
||||
);
|
||||
});
|
||||
|
||||
test('Wildlife docs record queue failure isolation and the complete badge mapping', () => {
|
||||
assert.match(section, /recovered queue tail/);
|
||||
assert.match(section, /ordinary grid failures/);
|
||||
assert.match(section, /DEGRADED/);
|
||||
assert.match(section, /1.5 px dark outline/);
|
||||
for (const glyph of [
|
||||
'raven',
|
||||
'pets',
|
||||
'egg_alt',
|
||||
'water_drop',
|
||||
'set_meal',
|
||||
'bug_report',
|
||||
'pest_control',
|
||||
'eco',
|
||||
'umbrella',
|
||||
'category',
|
||||
'question_mark',
|
||||
])
|
||||
assert.ok(section.includes('`' + glyph + '`'), glyph);
|
||||
});
|
||||
|
||||
test('Wildlife docs separate density from real observation icons and define persistent selection', () => {
|
||||
assert.match(section, /dedicated, nonpickable billboard/);
|
||||
assert.match(section, /view-relative density ramp/);
|
||||
assert.match(section, /four logical cell widths/);
|
||||
assert.match(
|
||||
section,
|
||||
/Only real sampled observation rows produce taxon badges/,
|
||||
);
|
||||
assert.match(
|
||||
section,
|
||||
/Grid tiles publish even while the independent observation/,
|
||||
);
|
||||
assert.match(section, /until explicit\s+deselection or layer disable/);
|
||||
assert.match(
|
||||
section,
|
||||
/releases\s+the glow collection, texture atlas, timers, queues and style listeners/,
|
||||
);
|
||||
assert.doesNotMatch(section, /grid badge|Clicking a grid cell/);
|
||||
});
|
||||
|
||||
test('Wildlife docs describe one source link, name declutter and globe glow limits', () => {
|
||||
assert.match(section, /selected chrome and paint lane/);
|
||||
assert.match(section, /single source link/);
|
||||
assert.match(section, /80 screen pixels/);
|
||||
assert.match(section, /word boundary/);
|
||||
assert.match(section, /3,000 km/);
|
||||
assert.match(section, /8,000 km/);
|
||||
assert.match(section, /5% radius margin/);
|
||||
assert.match(section, /add no per-frame work/);
|
||||
});
|
||||
|
||||
test('Wildlife docs cite the documented UTFGrid endpoint and the Acartia key request', () => {
|
||||
for (const path of [
|
||||
'docs/KNOWN-ISSUES.md',
|
||||
'DATA_SOURCES.md',
|
||||
'docs/CURRENT-STATE.md',
|
||||
]) {
|
||||
const text = read(path);
|
||||
assert.doesNotMatch(text, /undocumented (iNaturalist|UTFGrid) endpoint/i);
|
||||
assert.doesNotMatch(text, /grid \(undocumented/i);
|
||||
}
|
||||
for (const path of ['docs/KNOWN-ISSUES.md', 'DATA_SOURCES.md'])
|
||||
assert.match(read(path), /Grid Tiles UTFGrid/);
|
||||
assert.match(
|
||||
read('DATA_SOURCES.md'),
|
||||
/create an account and generate an API key/,
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,179 @@
|
||||
// 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.
|
||||
* `rectangle` is the camera's view rectangle in degrees (the camera port's
|
||||
* `viewRectangle()`), or null.
|
||||
*/
|
||||
export function wildlifeGridViewportBoxes(rectangle) {
|
||||
if (!rectangle) return [];
|
||||
return normalizedBoxes([
|
||||
Object.fromEntries(
|
||||
['south', 'west', 'north', 'east'].map((key) => [
|
||||
key,
|
||||
Math.round(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,137 @@
|
||||
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', () => {
|
||||
// The camera port's view rectangle, in degrees.
|
||||
const boxes = wildlifeGridViewportBoxes({
|
||||
south: -80,
|
||||
west: 120,
|
||||
north: 80,
|
||||
east: -120,
|
||||
});
|
||||
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(null), []);
|
||||
});
|
||||
|
||||
test('logical cell ids and bounds share geographic coverage and wrap antimeridian', () => {
|
||||
const id = wildlifeGridCellId(65.94004866768753, -18.28125, 2);
|
||||
assert.equal(id, 'grid:2/1/1:1:51');
|
||||
const bounds = wildlifeGridCellBounds(id);
|
||||
assert.equal(bounds.west, -19.6875);
|
||||
assert.equal(bounds.east, -16.875);
|
||||
assert.ok(bounds.south < 65.94 && bounds.north > 65.94);
|
||||
assert.equal(
|
||||
wildlifeGridCellId(
|
||||
(bounds.south + bounds.north) / 2,
|
||||
(bounds.west + bounds.east) / 2,
|
||||
2,
|
||||
),
|
||||
id,
|
||||
);
|
||||
assert.equal(wildlifeGridCellId(0, 180, 2), wildlifeGridCellId(0, -180, 2));
|
||||
for (const invalid of [
|
||||
'bad',
|
||||
'grid:23/0/0:1:1',
|
||||
'grid:2/4/0:1:1',
|
||||
'grid:2/0/0:64:1',
|
||||
])
|
||||
assert.equal(wildlifeGridCellBounds(invalid), null);
|
||||
});
|
||||
@@ -0,0 +1,123 @@
|
||||
/**
|
||||
* @module layers/wildlifeSightings/iconCollection
|
||||
* @description The sighting badges' icons draw set behind the small
|
||||
* collection shape the billboard model (`billboardModel.js`) reconciles:
|
||||
* `add` hands back a point whose property writes (`position`, `image`,
|
||||
* `show` and the appearance) are batched and sent to the set as one upsert
|
||||
* per task, and `remove`/`removeAll` take items off it. A point's `id` is
|
||||
* its item id, so a pick on a badge names it.
|
||||
*/
|
||||
|
||||
/** Item fields a point carries as they are (its appearance). */
|
||||
const PASSED = [
|
||||
'size',
|
||||
'color',
|
||||
'scale',
|
||||
'scaleByDistance',
|
||||
'disableDepthTest',
|
||||
'pickable',
|
||||
];
|
||||
|
||||
/**
|
||||
* @param {import('../../render/contract/draw').DrawSet<import('../../render/contract/draw').IconItem>} set
|
||||
* @param {{schedule?: (flush: () => void) => void}} [options] - How the
|
||||
* batched writes are flushed (a microtask by default).
|
||||
*/
|
||||
export function createWildlifeIconCollection(
|
||||
set,
|
||||
{ schedule = queueMicrotask } = {},
|
||||
) {
|
||||
/** @type {Map<string, object>} Points by item id. */
|
||||
const points = new Map();
|
||||
/** @type {Set<object>} Points written since the last flush. */
|
||||
const dirty = new Set();
|
||||
let scheduled = false;
|
||||
const canvasKeys = new WeakMap();
|
||||
let canvasCount = 0;
|
||||
|
||||
/** A sprite as the contract names it: a URL, or a canvas with its key. */
|
||||
function imageRef(image) {
|
||||
if (typeof image === 'string' || !image) return image;
|
||||
if (!canvasKeys.has(image))
|
||||
canvasKeys.set(image, `wildlife-sprite:${++canvasCount}`);
|
||||
return { canvas: image, key: canvasKeys.get(image) };
|
||||
}
|
||||
|
||||
function itemOf(point) {
|
||||
const item = {
|
||||
id: point.id,
|
||||
pos: point.position,
|
||||
image: imageRef(point.image),
|
||||
show: point.show !== false,
|
||||
};
|
||||
for (const key of PASSED)
|
||||
if (point[key] !== undefined) item[key] = point[key];
|
||||
return item;
|
||||
}
|
||||
|
||||
function flush() {
|
||||
scheduled = false;
|
||||
if (!dirty.size) return;
|
||||
const items = [];
|
||||
for (const point of dirty)
|
||||
if (points.get(point.id) === point) items.push(itemOf(point));
|
||||
dirty.clear();
|
||||
if (items.length) set.upsert(items);
|
||||
}
|
||||
|
||||
function touch(point) {
|
||||
dirty.add(point);
|
||||
if (scheduled) return;
|
||||
scheduled = true;
|
||||
schedule(flush);
|
||||
}
|
||||
|
||||
return {
|
||||
/** Add a point (`id`, `position`, `image` and its appearance). */
|
||||
add(options) {
|
||||
const point = new Proxy(
|
||||
{ show: true, ...options },
|
||||
{
|
||||
set(target, key, value) {
|
||||
if (target[key] === value) return true;
|
||||
target[key] = value;
|
||||
touch(point);
|
||||
return true;
|
||||
},
|
||||
},
|
||||
);
|
||||
points.set(point.id, point);
|
||||
touch(point);
|
||||
return point;
|
||||
},
|
||||
remove(point) {
|
||||
if (points.get(point?.id) !== point) return false;
|
||||
points.delete(point.id);
|
||||
dirty.delete(point);
|
||||
set.remove([point.id]);
|
||||
return true;
|
||||
},
|
||||
removeAll() {
|
||||
points.clear();
|
||||
dirty.clear();
|
||||
set.clear();
|
||||
},
|
||||
/** Take the set off the renderer. */
|
||||
dispose() {
|
||||
points.clear();
|
||||
dirty.clear();
|
||||
set.dispose();
|
||||
},
|
||||
/** Send the batched writes now. */
|
||||
flush,
|
||||
get show() {
|
||||
return set.show;
|
||||
},
|
||||
set show(value) {
|
||||
set.show = value;
|
||||
},
|
||||
get length() {
|
||||
return points.size;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
import { horizonFrom } from '../../geo/horizon.js';
|
||||
import { inputFor } from '../../input/dispatcher.js';
|
||||
import { findQuery } from '../../render/rendererOf.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,
|
||||
input = (viewer) => inputFor(viewer),
|
||||
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,
|
||||
project = (viewer, position) => findQuery(viewer)?.project(position) ?? null,
|
||||
occluderFactory = horizonFrom,
|
||||
} = {}) {
|
||||
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: [],
|
||||
cellSets: 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,
|
||||
input,
|
||||
picking,
|
||||
pointer,
|
||||
sprites,
|
||||
badgeSprites,
|
||||
render,
|
||||
context,
|
||||
focus,
|
||||
groundFloor,
|
||||
now,
|
||||
setTimer,
|
||||
clearTimer,
|
||||
requestIdleCallback,
|
||||
cancelIdleCallback,
|
||||
eventTarget,
|
||||
project,
|
||||
occluderFactory,
|
||||
};
|
||||
const owner = { state, services, parts };
|
||||
parts.photos = createPhotoSlots({
|
||||
imageFactory,
|
||||
now,
|
||||
setTimer,
|
||||
clearTimer,
|
||||
onChange() {
|
||||
if (!state.enabled) return;
|
||||
parts.selection.publishAmbient();
|
||||
},
|
||||
});
|
||||
parts.rendering = createRendering(owner);
|
||||
parts.selection = createSelection(owner);
|
||||
parts.controls = createControls(owner);
|
||||
parts.lifecycle = createLifecycle(owner);
|
||||
return Object.assign({}, parts.controls.methods, parts.lifecycle.methods, {
|
||||
selectSighting: parts.selection.selectAndFocus,
|
||||
clearSightingSelection: parts.selection.clearAndRebuild,
|
||||
subscribeSelection: parts.selection.subscribe,
|
||||
/** Return the current surface anchor for a retained observation. */
|
||||
getSightingPosition(id) {
|
||||
return state.positions.get(id) || null;
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,843 @@
|
||||
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 { canvasOf, findCamera } from '../../render/rendererOf.js';
|
||||
import { wildlifeEyeHeight, wildlifeViewRectangle } from './view.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 = wildlifeEyeHeight(state.viewer);
|
||||
state.band = getWildlifeHeightBand(height ?? Infinity, state.band);
|
||||
const rectangle = wildlifeViewRectangle(state.viewer);
|
||||
const boxes =
|
||||
state.band === 'global'
|
||||
? null
|
||||
: wildlifeViewportBoxes(rectangle)?.map((box) => snapWildlifeBox(box));
|
||||
const visibleBoxes = wildlifeGridViewportBoxes(rectangle);
|
||||
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 = canvasOf(state.viewer);
|
||||
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 draw sets and listeners 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 = findCamera(state.viewer)?.on('moveEnd', () => {
|
||||
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;
|
||||
// The badges' set keeps its place among the sprite layers by its draw
|
||||
// order (`spriteDrawOrder`), whichever layer was turned on first.
|
||||
return true;
|
||||
},
|
||||
/** Refresh observations and density independently for the current filters. */
|
||||
async update(_viewer, { signal } = {}) {
|
||||
if (
|
||||
!state.enabled ||
|
||||
!state.points ||
|
||||
state.destroyed ||
|
||||
signal?.aborted
|
||||
) {
|
||||
if (!state.request) clearPending();
|
||||
return false;
|
||||
}
|
||||
if (initialCameraDeadline && services.now() < initialCameraDeadline)
|
||||
await settleInitialCamera(signal);
|
||||
initialCameraDeadline = 0;
|
||||
if (!state.enabled || state.destroyed || signal?.aborted) return false;
|
||||
const query = currentQuery();
|
||||
state.query = query;
|
||||
if (!query || pageHidden()) {
|
||||
clearPending();
|
||||
return true;
|
||||
}
|
||||
if (services.now() < state.retryAt) {
|
||||
if (state.pendingParams && state.cameraTimer == null) scheduleRefresh();
|
||||
return true;
|
||||
}
|
||||
if (
|
||||
requestQueryKey === query.key &&
|
||||
state.request &&
|
||||
!state.request.signal.aborted
|
||||
)
|
||||
return true;
|
||||
state.request?.abort();
|
||||
const request = new AbortController();
|
||||
const requestLifetime = lifetimeEpoch;
|
||||
// One acquisition publishes several times (tiles, rows, final grid).
|
||||
// Each derives its default backoff from the backoff before it started.
|
||||
const previousFailures = state.failures || 0;
|
||||
const supersededResult = () =>
|
||||
state.enabled &&
|
||||
!state.destroyed &&
|
||||
lifetimeEpoch === requestLifetime &&
|
||||
!signal?.aborted;
|
||||
state.request = request;
|
||||
requestQueryKey = query.key;
|
||||
const onAbort = () => request.abort(signal.reason);
|
||||
signal?.addEventListener?.('abort', onAbort, { once: true });
|
||||
const params = { confirmed: state.confirmed, taxa: state.taxa };
|
||||
state.loading = true;
|
||||
if (!state.pendingParams) {
|
||||
const drawn = state.drawnParams || { confirmed: false, taxa: null };
|
||||
const keys = ['confirmed', 'taxa'].filter(
|
||||
(key) => params[key] !== drawn[key],
|
||||
);
|
||||
if (keys.length) state.pendingParams = { ...params, keys };
|
||||
}
|
||||
parts.controls.notify();
|
||||
let received = false;
|
||||
let gridPending = false;
|
||||
let acceptedSnapshot = null;
|
||||
let gridRequest = null;
|
||||
let gridResult = null;
|
||||
const tileSnapshots = new Map();
|
||||
const gridParams = state.gridParams || state.drawnParams;
|
||||
const retainedGrid =
|
||||
params.taxa === gridParams?.taxa &&
|
||||
params.confirmed === gridParams?.confirmed
|
||||
? state.gridCells || []
|
||||
: [];
|
||||
function aggregateTiles(complete = false) {
|
||||
if (!tileSnapshots.size) return undefined;
|
||||
const grid = combineWildlifeGridSnapshots([...tileSnapshots.values()]);
|
||||
if (!complete && retainedGrid.length) {
|
||||
const zoom = query.tiles[0]?.z;
|
||||
const covered = new Set(tileSnapshots.keys());
|
||||
const retained = retainedGrid.filter(
|
||||
(cell) =>
|
||||
!covered.has(
|
||||
wildlifeGridCellId(cell.lat, cell.lon, zoom)?.split(':')[1],
|
||||
),
|
||||
);
|
||||
return combineWildlifeGridSnapshots([
|
||||
{ ...grid, cells: [...retained, ...grid.cells] },
|
||||
]);
|
||||
}
|
||||
return grid;
|
||||
}
|
||||
function completedGrid(value) {
|
||||
if (!value) return value;
|
||||
const aggregate = aggregateTiles(!value.error);
|
||||
return aggregate
|
||||
? combineWildlifeGridSnapshots([aggregate, value], value.error)
|
||||
: value;
|
||||
}
|
||||
function publish(grid, gridError = null, replaceRows = false) {
|
||||
applyAccepted({
|
||||
snapshot: acceptedSnapshot,
|
||||
grid,
|
||||
gridError,
|
||||
replaceRows,
|
||||
query,
|
||||
params,
|
||||
request,
|
||||
signal,
|
||||
epoch: requestLifetime,
|
||||
previousFailures,
|
||||
});
|
||||
}
|
||||
function finishTiles() {
|
||||
signal?.removeEventListener?.('abort', onAbort);
|
||||
if (state.request === request) {
|
||||
state.request = null;
|
||||
requestQueryKey = null;
|
||||
state.loading = false;
|
||||
if (request.signal.aborted && state.cameraTimer == null)
|
||||
clearPending();
|
||||
parts.controls.notify();
|
||||
}
|
||||
}
|
||||
function continueTiles() {
|
||||
if (!gridRequest || gridResult) return;
|
||||
gridPending = true;
|
||||
void gridRequest
|
||||
.then((result) => {
|
||||
if (
|
||||
acceptedSnapshot &&
|
||||
!request.signal.aborted &&
|
||||
state.request === request &&
|
||||
state.enabled
|
||||
)
|
||||
publish(result?.value, result?.error || result?.value?.error);
|
||||
})
|
||||
.finally(finishTiles);
|
||||
}
|
||||
try {
|
||||
const options = {
|
||||
signal: request.signal,
|
||||
boxes: query.boxes,
|
||||
box: query.boxes?.[0] || null,
|
||||
scope: query.scope,
|
||||
...params,
|
||||
};
|
||||
// Observation requests enter the shared proxy queue first. A slow tile
|
||||
// never holds the manager's initial enable or the first observations.
|
||||
const observationRequest =
|
||||
typeof services.source.getSnapshotDetail === 'function'
|
||||
? services.source.getSnapshotDetail(options)
|
||||
: Promise.resolve(services.source.getSnapshot(options)).then(
|
||||
(rows) => ({ rows, stale: false, fetchedAt: services.now() }),
|
||||
);
|
||||
const hasGrid =
|
||||
typeof services.source.getGridSnapshot === 'function' &&
|
||||
query.tiles.length;
|
||||
gridRequest = hasGrid
|
||||
? services.source
|
||||
.getGridSnapshot({
|
||||
signal: request.signal,
|
||||
tiles: query.tiles,
|
||||
...params,
|
||||
onTile(value, { tile }) {
|
||||
if (request.signal.aborted || state.request !== request)
|
||||
return;
|
||||
tileSnapshots.set(`${tile.z}/${tile.x}/${tile.y}`, value);
|
||||
publish(aggregateTiles());
|
||||
},
|
||||
})
|
||||
.then(
|
||||
(value) => {
|
||||
gridResult = { value: completedGrid(value) };
|
||||
if (!acceptedSnapshot)
|
||||
publish(gridResult.value, value?.error);
|
||||
return gridResult;
|
||||
},
|
||||
(error) => (gridResult = { error }),
|
||||
)
|
||||
: null;
|
||||
const snapshot = await observationRequest;
|
||||
if (
|
||||
request.signal.aborted ||
|
||||
state.request !== request ||
|
||||
!state.enabled
|
||||
)
|
||||
return supersededResult();
|
||||
if (!Array.isArray(snapshot?.rows))
|
||||
throw new Error('Malformed iNaturalist response');
|
||||
received = true;
|
||||
acceptedSnapshot = snapshot;
|
||||
publish(
|
||||
gridResult?.value || aggregateTiles(),
|
||||
gridResult?.error || gridResult?.value?.error,
|
||||
true,
|
||||
);
|
||||
if (hasGrid && !gridResult) {
|
||||
continueTiles();
|
||||
} else if (gridResult && !gridResult.value && gridResult.error) {
|
||||
// Observation rows remain visible when the first tile set fails.
|
||||
publish(undefined, gridResult.error);
|
||||
}
|
||||
return true;
|
||||
} catch (error) {
|
||||
if (
|
||||
request.signal.aborted ||
|
||||
state.request !== request ||
|
||||
!state.enabled
|
||||
)
|
||||
return supersededResult();
|
||||
if (received) throw error;
|
||||
// Observation failures must not cancel independent density tiles.
|
||||
continueTiles();
|
||||
state.stale = false;
|
||||
state.error =
|
||||
preferredWildlifeFailure(error, previousFailures)?.message ||
|
||||
msg('Wildlife sightings source unavailable');
|
||||
failParams(params);
|
||||
state.lastQueryKey = null;
|
||||
requestQueryKey = null;
|
||||
applyRetry(error, null, previousFailures);
|
||||
console.warn('[Data:WildlifeSightings] Update failed:', state.error);
|
||||
return true;
|
||||
} finally {
|
||||
if (!gridPending) finishTiles();
|
||||
}
|
||||
},
|
||||
/** Stop acquisition and release visible resources while retaining filters. */
|
||||
disable,
|
||||
/** Release requests, subscriptions, caches and scene resources. */
|
||||
destroy() {
|
||||
if (state.destroyed) return;
|
||||
disable();
|
||||
state.destroyed = true;
|
||||
parts.selection.destroy();
|
||||
parts.photos.destroy();
|
||||
parts.rendering.destroy();
|
||||
state.rows.clear();
|
||||
state.lastUpdate = null;
|
||||
state.error = null;
|
||||
state.stale = false;
|
||||
state.drawnParams = null;
|
||||
state.gridParams = null;
|
||||
state.pendingParams = null;
|
||||
state.failedParams = null;
|
||||
state.controlsListener = null;
|
||||
state.manager = null;
|
||||
state.viewer = null;
|
||||
},
|
||||
};
|
||||
return {
|
||||
methods,
|
||||
scheduleRefresh,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,208 @@
|
||||
import {
|
||||
WILDLIFE_HEIGHT_BANDS,
|
||||
WILDLIFE_HEIGHT_HYSTERESIS,
|
||||
WILDLIFE_RENDER_LIMIT,
|
||||
WILDLIFE_VIEW_PADDING,
|
||||
} from './policy.js';
|
||||
import { WILDLIFE_GRID_TARGET_SPACING_PX } from './gridViewport.js';
|
||||
import { drainWildlifeWork, WILDLIFE_WORK_UNIT } from './performance.js';
|
||||
|
||||
const BAND_ORDER = Object.freeze(['cards', 'cells', 'regional', 'global']);
|
||||
const BAND_THRESHOLDS = Object.freeze([
|
||||
WILDLIFE_HEIGHT_BANDS.cards,
|
||||
WILDLIFE_HEIGHT_BANDS.cells,
|
||||
WILDLIFE_HEIGHT_BANDS.global,
|
||||
]);
|
||||
|
||||
/** A previous band is retained until a boundary is crossed by ten percent. */
|
||||
export function getWildlifeHeightBand(heightM, previous) {
|
||||
const height = Number.isFinite(heightM) ? Math.max(0, heightM) : 0;
|
||||
let index = BAND_ORDER.indexOf(previous);
|
||||
if (index < 0)
|
||||
return BAND_ORDER[
|
||||
BAND_THRESHOLDS.filter((boundary) => height > boundary).length
|
||||
];
|
||||
while (
|
||||
index < BAND_ORDER.length - 1 &&
|
||||
height > BAND_THRESHOLDS[index] * (1 + WILDLIFE_HEIGHT_HYSTERESIS)
|
||||
)
|
||||
index += 1;
|
||||
while (
|
||||
index > 0 &&
|
||||
height < BAND_THRESHOLDS[index - 1] * (1 - WILDLIFE_HEIGHT_HYSTERESIS)
|
||||
)
|
||||
index -= 1;
|
||||
return BAND_ORDER[index];
|
||||
}
|
||||
|
||||
/** Share the legend's animal grouping and unknown fallback with sprites. */
|
||||
export function wildlifeIconicGroup(iconic) {
|
||||
if (iconic === 'Mollusca' || iconic === 'Animalia') return 'Animalia';
|
||||
return [
|
||||
'Aves',
|
||||
'Mammalia',
|
||||
'Reptilia',
|
||||
'Amphibia',
|
||||
'Actinopterygii',
|
||||
'Insecta',
|
||||
'Arachnida',
|
||||
'Plantae',
|
||||
'Fungi',
|
||||
].includes(iconic)
|
||||
? iconic
|
||||
: 'Unknown';
|
||||
}
|
||||
|
||||
function validIconPosition(row) {
|
||||
return (
|
||||
Number.isFinite(row?.lat) &&
|
||||
Math.abs(row.lat) <= 90 &&
|
||||
Number.isFinite(row?.lon) &&
|
||||
Math.abs(row.lon) <= 180
|
||||
);
|
||||
}
|
||||
|
||||
/** Compare provider IDs consistently across locales. */
|
||||
export function compareWildlifeIds(a, b) {
|
||||
return a < b ? -1 : a > b ? 1 : 0;
|
||||
}
|
||||
|
||||
/** Prefer a selected/identified recent contact when a population exceeds its
|
||||
* cap. Density is never converted into a larger billboard. */
|
||||
export function wildlifeIconRelevance(row, selectedId = null) {
|
||||
return (
|
||||
(row.stableId === selectedId ? 1e15 : 0) +
|
||||
(row.commonName ? 1e13 : 0) +
|
||||
(row.quality === 'research' ? 1e12 : 0) +
|
||||
(Number.isFinite(row.observedAt) ? row.observedAt / 1000 : 0)
|
||||
);
|
||||
}
|
||||
|
||||
/** Real observations alone compete for 28px screen buckets. Density is an
|
||||
* independent visual and can never supply or suppress a sighting's identity.
|
||||
* A selected observation keeps its slot even outside the new camera view. */
|
||||
export function buildWildlifeIconModel(options = {}) {
|
||||
return drainWildlifeWork(wildlifeIconModelWork(options));
|
||||
}
|
||||
|
||||
/** Yield bounded units while selecting real observations for screen buckets. */
|
||||
export function* wildlifeIconModelWork({
|
||||
rows = [],
|
||||
boxes = null,
|
||||
selectedId = null,
|
||||
selectedRow = null,
|
||||
preferredIds = [],
|
||||
limit = WILDLIFE_RENDER_LIMIT,
|
||||
projectRow = null,
|
||||
onOperations = null,
|
||||
} = {}) {
|
||||
const operations = {
|
||||
observationVisits: 0,
|
||||
projections: 0,
|
||||
rankComparisons: 0,
|
||||
};
|
||||
const preferred = new Set(preferredIds);
|
||||
const seen = new Set();
|
||||
const buckets = new Map();
|
||||
let sightingCount = 0;
|
||||
let acartiaCount = 0;
|
||||
const score = (row) =>
|
||||
wildlifeIconRelevance(row, selectedId) +
|
||||
(preferred.has(row.stableId) ? 1e14 : 0);
|
||||
const candidates =
|
||||
selectedRow && !rows.includes(selectedRow) ? [...rows, selectedRow] : rows;
|
||||
yield 'bucket';
|
||||
for (const row of candidates) {
|
||||
if (
|
||||
operations.observationVisits &&
|
||||
operations.observationVisits % WILDLIFE_WORK_UNIT === 0
|
||||
)
|
||||
yield 'bucket';
|
||||
operations.observationVisits++;
|
||||
if (
|
||||
typeof row?.stableId !== 'string' ||
|
||||
!row.stableId.length ||
|
||||
!validIconPosition(row) ||
|
||||
seen.has(row.stableId)
|
||||
)
|
||||
continue;
|
||||
seen.add(row.stableId);
|
||||
const selected = row.stableId === selectedId;
|
||||
const inView = rowInWildlifeBoxes(row, boxes, 0);
|
||||
if (!selected && !inView) continue;
|
||||
let key = row.stableId;
|
||||
let visible = inView;
|
||||
if (typeof projectRow === 'function') {
|
||||
operations.projections++;
|
||||
const screen = projectRow(row);
|
||||
visible &&=
|
||||
!!screen && Number.isFinite(screen.x) && Number.isFinite(screen.y);
|
||||
if (!visible && !selected) continue;
|
||||
if (visible) {
|
||||
const x = Math.floor(screen.x / WILDLIFE_GRID_TARGET_SPACING_PX);
|
||||
const y = Math.floor(screen.y / WILDLIFE_GRID_TARGET_SPACING_PX);
|
||||
key =
|
||||
Math.abs(x) < 1048576 && Math.abs(y) < 1048576
|
||||
? x * 2097152 + y
|
||||
: `${x}:${y}`;
|
||||
}
|
||||
}
|
||||
if (visible) {
|
||||
sightingCount++;
|
||||
if (row.origin === 'acartia') acartiaCount++;
|
||||
}
|
||||
const incumbent = buckets.get(key);
|
||||
if (
|
||||
!incumbent ||
|
||||
score(row) > score(incumbent) ||
|
||||
(score(row) === score(incumbent) && row.stableId < incumbent.stableId)
|
||||
)
|
||||
buckets.set(key, row);
|
||||
}
|
||||
yield 'rank';
|
||||
const population = [...buckets.values()];
|
||||
const cap = Math.max(selectedId ? 1 : 0, Math.floor(limit));
|
||||
const saturated = population.length > cap;
|
||||
if (saturated)
|
||||
population.sort((a, b) => {
|
||||
operations.rankComparisons++;
|
||||
return score(b) - score(a) || compareWildlifeIds(a.stableId, b.stableId);
|
||||
});
|
||||
onOperations?.(operations);
|
||||
return {
|
||||
rows: saturated ? population.slice(0, cap) : population,
|
||||
saturated,
|
||||
totalPoints: population.length,
|
||||
sightingCount,
|
||||
acartiaCount,
|
||||
};
|
||||
}
|
||||
|
||||
/** Test the padded view in degrees, including across the antimeridian. Null
|
||||
* boxes are the global sample, whose rows all remain candidates. */
|
||||
export function rowInWildlifeBoxes(
|
||||
row,
|
||||
boxes,
|
||||
padding = WILDLIFE_VIEW_PADDING,
|
||||
) {
|
||||
if (!Number.isFinite(row?.lat) || !Number.isFinite(row?.lon)) return false;
|
||||
if (!Array.isArray(boxes)) return true;
|
||||
for (const box of boxes) {
|
||||
const latPad = (box.north - box.south) * padding;
|
||||
const width =
|
||||
box.east >= box.west ? box.east - box.west : 360 - box.west + box.east;
|
||||
const lonPad = width * padding;
|
||||
if (
|
||||
row.lat < Math.max(-90, box.south - latPad) ||
|
||||
row.lat > Math.min(90, box.north + latPad)
|
||||
)
|
||||
continue;
|
||||
const relative = row.lon - box.west;
|
||||
if (relative >= -lonPad && relative <= width + lonPad) return true;
|
||||
if (relative + 360 >= -lonPad && relative + 360 <= width + lonPad)
|
||||
return true;
|
||||
if (relative - 360 >= -lonPad && relative - 360 <= width + lonPad)
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { performance } from 'node:perf_hooks';
|
||||
import test from 'node:test';
|
||||
import { perfBudgetTestOptions } from '../../../scripts/run-perf-tests.mjs';
|
||||
import {
|
||||
harness,
|
||||
syntheticRows,
|
||||
changePositions,
|
||||
WILDLIFE_BENCHMARK_REFRESHES,
|
||||
} from '../../testSupport/wildlifeBillboardModel.mjs';
|
||||
|
||||
// Pure model and incremental reconciliation, measured after warmup.
|
||||
// The 2,000-contact allowance is a fraction of one 60Hz frame; the 5,000 cap
|
||||
// gets a proportional allowance. No renderer, network or real sightings run.
|
||||
const WILDLIFE_MODEL_UPDATE_BUDGET_MS = Object.freeze({
|
||||
500: 4,
|
||||
2000: 8,
|
||||
5000: 20,
|
||||
});
|
||||
test(
|
||||
'500 / 2,000 / 5,000 icon model updates stay within their named timing budgets',
|
||||
perfBudgetTestOptions(),
|
||||
(t) => {
|
||||
// Warm the same pure hot paths before recording CPU time.
|
||||
const warm = harness();
|
||||
let warmRows = syntheticRows(2000);
|
||||
warm.apply(warmRows);
|
||||
for (let i = 0; i < 25; i++) {
|
||||
warmRows = changePositions(warmRows, i);
|
||||
warm.apply(warmRows);
|
||||
}
|
||||
for (const n of [500, 2000, 5000]) {
|
||||
const h = harness();
|
||||
let rows = syntheticRows(n);
|
||||
const start = performance.now();
|
||||
const initial = h.apply(rows);
|
||||
const initialMs = performance.now() - start;
|
||||
assert.equal(initial.created, n);
|
||||
const durations = [];
|
||||
for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
|
||||
rows = changePositions(rows, refresh);
|
||||
const before = performance.now();
|
||||
const update = h.apply(rows);
|
||||
durations.push(performance.now() - before);
|
||||
assert.deepEqual(update, {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: n / 10,
|
||||
writes: n / 10,
|
||||
});
|
||||
}
|
||||
const meanMs =
|
||||
durations.reduce((sum, value) => sum + value, 0) / durations.length;
|
||||
const maxMs = Math.max(...durations);
|
||||
assert.ok(
|
||||
maxMs <= WILDLIFE_MODEL_UPDATE_BUDGET_MS[n],
|
||||
`${n}: ${maxMs.toFixed(3)}ms update exceeds ${WILDLIFE_MODEL_UPDATE_BUDGET_MS[n]}ms`,
|
||||
);
|
||||
const before = { ...h.counters };
|
||||
assert.deepEqual(h.apply([...rows].reverse()), {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: 0,
|
||||
writes: 0,
|
||||
});
|
||||
assert.deepEqual(
|
||||
h.counters,
|
||||
before,
|
||||
'unchanged content performs zero billboard writes or allocations',
|
||||
);
|
||||
t.diagnostic(
|
||||
`N=${n}; initial=${initialMs.toFixed(3)}ms; incremental10% mean=${meanMs.toFixed(3)}ms, max=${maxMs.toFixed(3)}ms; budget=${WILDLIFE_MODEL_UPDATE_BUDGET_MS[n]}ms; unchanged writes=0`,
|
||||
);
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,162 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
wildlifeIconicGroup,
|
||||
rowInWildlifeBoxes,
|
||||
buildWildlifeIconModel,
|
||||
} from './model.js';
|
||||
import { ICONIC_TINTS, ICONIC_LEGEND_ORDER, TAXA_PRESETS } from './policy.js';
|
||||
|
||||
const row = {
|
||||
stableId: 'inat:1',
|
||||
lat: 47.6,
|
||||
lon: -122.3,
|
||||
cell: null,
|
||||
iconic: 'Aves',
|
||||
quality: 'research',
|
||||
count: null,
|
||||
obscured: false,
|
||||
};
|
||||
|
||||
test('unknown groups are slate and molluscs fold into other animals', () => {
|
||||
assert.equal(wildlifeIconicGroup('Mollusca'), 'Animalia');
|
||||
for (const iconic of ['Unknown', 'Protozoa', 'Chromista', undefined])
|
||||
assert.equal(wildlifeIconicGroup(iconic), 'Unknown');
|
||||
assert.equal(ICONIC_TINTS.Unknown, '#9aa7b3');
|
||||
assert.equal(ICONIC_LEGEND_ORDER.at(-1), 'Unknown');
|
||||
assert.equal(ICONIC_LEGEND_ORDER.length, 11);
|
||||
assert.equal(TAXA_PRESETS.length, 6);
|
||||
assert.equal(TAXA_PRESETS.filter((item) => item.label === 'ALL').length, 1);
|
||||
assert.equal(Object.isFrozen(ICONIC_TINTS), true);
|
||||
assert.equal(Object.isFrozen(TAXA_PRESETS[0]), true);
|
||||
});
|
||||
|
||||
test('view filtering includes padding and both sides of the antimeridian', () => {
|
||||
const boxes = [{ south: 47, west: -123, north: 48, east: -122 }];
|
||||
assert.equal(rowInWildlifeBoxes(row, boxes), true);
|
||||
assert.equal(rowInWildlifeBoxes({ ...row, lat: 48.2 }, boxes), true);
|
||||
assert.equal(rowInWildlifeBoxes({ ...row, lat: 48.4 }, boxes), false);
|
||||
assert.equal(
|
||||
rowInWildlifeBoxes({ ...row, lat: 10.5, lon: -179.9 }, [
|
||||
{ south: 10, west: 179, north: 11, east: 180 },
|
||||
]),
|
||||
true,
|
||||
);
|
||||
assert.equal(rowInWildlifeBoxes(row, null), true);
|
||||
assert.equal(rowInWildlifeBoxes(row, []), false);
|
||||
});
|
||||
|
||||
test('grid cells never enter the observation icon model', () => {
|
||||
const cells = [
|
||||
{ id: 'grid:2/0/0:1:1', lat: 47.6, lon: -122.3, cellCount: 999 },
|
||||
];
|
||||
assert.deepEqual(buildWildlifeIconModel({ rows: cells }).rows, []);
|
||||
assert.deepEqual(buildWildlifeIconModel({ rows: [...cells, row] }).rows, [
|
||||
row,
|
||||
]);
|
||||
});
|
||||
|
||||
test('screen buckets retain incumbent photos at their real sighting positions', () => {
|
||||
const incumbent = {
|
||||
...row,
|
||||
commonName: 'Incumbent',
|
||||
photo: { square: 'synthetic.jpg' },
|
||||
};
|
||||
const challenger = {
|
||||
...row,
|
||||
stableId: 'inat:2',
|
||||
commonName: 'Challenger',
|
||||
observedAt: Date.UTC(2026, 10, 4),
|
||||
};
|
||||
const distant = { ...row, stableId: 'inat:3', lon: row.lon + 1 };
|
||||
const model = buildWildlifeIconModel({
|
||||
rows: [challenger, incumbent, distant],
|
||||
preferredIds: [incumbent.stableId],
|
||||
projectRow: (item) => ({ x: (item.lon - row.lon) * 28 + 14, y: 14 }),
|
||||
});
|
||||
assert.deepEqual(model.rows, [incumbent, distant]);
|
||||
assert.equal(model.sightingCount, 3);
|
||||
assert.equal(model.rows[0].photo, incumbent.photo);
|
||||
});
|
||||
|
||||
test('visible observation counts precede per-area and global caps', () => {
|
||||
const rows = Array.from({ length: 6000 }, (_, i) => ({
|
||||
...row,
|
||||
stableId: `inat:${i}`,
|
||||
lon: -160 + i * 0.01,
|
||||
}));
|
||||
let projections = 0;
|
||||
const model = buildWildlifeIconModel({
|
||||
rows,
|
||||
projectRow(item) {
|
||||
projections++;
|
||||
return { x: (item.lon + 160) * 5600 + 14, y: 14 };
|
||||
},
|
||||
});
|
||||
assert.equal(projections, 6000);
|
||||
assert.equal(model.rows.length, 5000);
|
||||
assert.equal(model.totalPoints, 6000);
|
||||
assert.equal(model.saturated, true);
|
||||
assert.equal(model.sightingCount, 6000);
|
||||
});
|
||||
|
||||
test('selected observations win their bucket and survive a sample, viewport and projection change', () => {
|
||||
const selected = { ...row, commonName: 'Selected sighting' };
|
||||
const challenger = {
|
||||
...row,
|
||||
stableId: 'inat:2',
|
||||
commonName: 'Newer',
|
||||
observedAt: Date.UTC(2026, 10, 4),
|
||||
};
|
||||
const input = {
|
||||
selectedId: row.stableId,
|
||||
selectedRow: selected,
|
||||
rows: [challenger],
|
||||
limit: 1,
|
||||
};
|
||||
assert.deepEqual(
|
||||
buildWildlifeIconModel({ ...input, projectRow: () => ({ x: 14, y: 14 }) })
|
||||
.rows,
|
||||
[selected],
|
||||
);
|
||||
const offscreen = buildWildlifeIconModel({
|
||||
...input,
|
||||
boxes: [{ south: 0, west: 0, north: 1, east: 1 }],
|
||||
projectRow: () => null,
|
||||
});
|
||||
assert.deepEqual(offscreen.rows, [selected]);
|
||||
assert.equal(
|
||||
offscreen.sightingCount,
|
||||
0,
|
||||
'an offscreen pin is not a visible observation',
|
||||
);
|
||||
});
|
||||
|
||||
test('observation reduction is stable under input order, selected priority and visible filtering', () => {
|
||||
const named = { ...row, stableId: 'inat:2', commonName: 'Known bird' };
|
||||
const outside = { ...row, stableId: 'inat:3', lat: 0 };
|
||||
const input = {
|
||||
boxes: [{ south: 47, west: -123, north: 48, east: -122 }],
|
||||
limit: 1,
|
||||
};
|
||||
const model = buildWildlifeIconModel({
|
||||
...input,
|
||||
rows: [row, named, outside],
|
||||
});
|
||||
assert.equal(model.saturated, true);
|
||||
assert.equal(model.totalPoints, 2);
|
||||
assert.equal(model.sightingCount, 2);
|
||||
assert.deepEqual(model.rows, [named]);
|
||||
assert.deepEqual(
|
||||
buildWildlifeIconModel({ ...input, rows: [outside, named, row] }),
|
||||
model,
|
||||
);
|
||||
assert.deepEqual(
|
||||
buildWildlifeIconModel({
|
||||
...input,
|
||||
rows: [named, row],
|
||||
selectedId: row.stableId,
|
||||
}).rows,
|
||||
[row],
|
||||
);
|
||||
});
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,115 @@
|
||||
/** Camera work runs on moveEnd/data arrival only. Measures remain observable
|
||||
* through PerformanceObserver while clearing entries prevents a long session
|
||||
* accumulating one timing record for every pan and streamed tile. */
|
||||
export const WILDLIFE_MOVE_END_BUDGET_MS = 4;
|
||||
const measureSpans = new Map();
|
||||
|
||||
function measureSpan(stage) {
|
||||
let span = measureSpans.get(stage);
|
||||
if (!span) {
|
||||
span = { name: `wildlife-sightings:${stage}`, depth: 0, frames: [] };
|
||||
measureSpans.set(stage, span);
|
||||
}
|
||||
const depth = span.depth++;
|
||||
if (!span.frames[depth]) {
|
||||
const start = `${span.name}:start:${depth}`;
|
||||
span.frames[depth] = { start, options: { start } };
|
||||
}
|
||||
return span;
|
||||
}
|
||||
|
||||
/** Measure a render phase without accumulating performance entries. */
|
||||
export function wildlifeMeasure(stage, work) {
|
||||
const clock = globalThis.performance;
|
||||
if (typeof clock?.mark !== 'function' || typeof clock?.measure !== 'function')
|
||||
return work();
|
||||
// Reuse names/options; nesting depth distinguishes simultaneous spans.
|
||||
const span = measureSpan(stage);
|
||||
const frame = span.frames[span.depth - 1];
|
||||
clock.mark(frame.start);
|
||||
try {
|
||||
return work();
|
||||
} finally {
|
||||
clock.measure(span.name, frame.options);
|
||||
clock.clearMarks?.(frame.start);
|
||||
clock.clearMeasures?.(span.name);
|
||||
span.depth--;
|
||||
}
|
||||
}
|
||||
|
||||
// A unit is at most 128 cells/billboards. The one-millisecond target leaves
|
||||
// room for the last unit, draw-set writes and the overlay host within 4ms.
|
||||
export const WILDLIFE_WORK_UNIT = 128;
|
||||
const WILDLIFE_WORK_SLICE_MS = 1;
|
||||
export const WILDLIFE_SYNC_CELL_LIMIT = 256;
|
||||
|
||||
function wildlifeWorkStep(work, stage = 'bucket') {
|
||||
return wildlifeMeasure(stage, () => work.next());
|
||||
}
|
||||
|
||||
/** Run bounded work synchronously for a small population. */
|
||||
export function drainWildlifeWork(work) {
|
||||
let stage = 'bucket';
|
||||
for (;;) {
|
||||
const step = wildlifeWorkStep(work, stage);
|
||||
if (step.done) return step.value;
|
||||
stage = step.value || stage;
|
||||
}
|
||||
}
|
||||
|
||||
/** A cancellable idle queue, never a frame listener. Superseding a camera view
|
||||
* drops unrun work. No network or requestAnimationFrame enters this queue. */
|
||||
export function createWildlifeWorkQueue({
|
||||
requestIdle = globalThis.requestIdleCallback?.bind(globalThis),
|
||||
cancelIdle = globalThis.cancelIdleCallback?.bind(globalThis),
|
||||
now = () => performance.now(),
|
||||
onSlice = () => {},
|
||||
} = {}) {
|
||||
let active = null;
|
||||
function cancel() {
|
||||
if (!active) return;
|
||||
const old = active;
|
||||
active = null;
|
||||
if (requestIdle) cancelIdle?.(old.handle);
|
||||
else clearTimeout(old.handle);
|
||||
old.work.return?.();
|
||||
}
|
||||
function start(work, complete) {
|
||||
cancel();
|
||||
const job = { work, handle: null, stage: 'bucket' };
|
||||
active = job;
|
||||
function schedule() {
|
||||
job.handle = requestIdle
|
||||
? requestIdle(run, { timeout: 32 })
|
||||
: setTimeout(run, 0);
|
||||
}
|
||||
function run() {
|
||||
if (active !== job) return;
|
||||
const began = now();
|
||||
let units = 0;
|
||||
let result;
|
||||
wildlifeMeasure('moveEnd:slice', () => {
|
||||
do {
|
||||
result = wildlifeWorkStep(work, job.stage);
|
||||
units++;
|
||||
if (result.done) {
|
||||
active = null;
|
||||
complete(result.value);
|
||||
break;
|
||||
}
|
||||
job.stage = result.value || job.stage;
|
||||
} while (units < 8 && now() - began < WILDLIFE_WORK_SLICE_MS);
|
||||
});
|
||||
onSlice({ startTimeMs: began, durationMs: now() - began, units });
|
||||
if (!result.done && active === job) schedule();
|
||||
}
|
||||
schedule();
|
||||
}
|
||||
return {
|
||||
start,
|
||||
cancel,
|
||||
get pending() {
|
||||
return active !== null;
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,299 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import {
|
||||
harness,
|
||||
syntheticRows,
|
||||
changePositions,
|
||||
WILDLIFE_BENCHMARK_REFRESHES,
|
||||
} from '../../testSupport/wildlifeBillboardModel.mjs';
|
||||
|
||||
test('500 / 2,000 / 5,000 contacts write only position deltas and do no work for unchanged input', () => {
|
||||
for (const n of [500, 2000, 5000]) {
|
||||
const h = harness();
|
||||
let rows = syntheticRows(n);
|
||||
assert.equal(h.apply(rows).created, n);
|
||||
const retained = h.pointById.get(rows[1].stableId);
|
||||
for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
|
||||
rows = changePositions(rows, refresh);
|
||||
assert.deepEqual(h.apply(rows), {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: n / 10,
|
||||
writes: n / 10,
|
||||
});
|
||||
assert.equal(h.pointById.get(rows[1].stableId), retained);
|
||||
}
|
||||
assert.equal(h.counters.created, n);
|
||||
assert.equal(h.counters.destroyed, 0);
|
||||
const before = { ...h.counters };
|
||||
assert.deepEqual(h.apply([...rows].reverse()), {
|
||||
created: 0,
|
||||
removed: 0,
|
||||
updated: 0,
|
||||
writes: 0,
|
||||
});
|
||||
assert.deepEqual(
|
||||
h.counters,
|
||||
before,
|
||||
'unchanged content writes and allocates nothing',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('ten 10% membership refreshes allocate and remove exactly their delta', (t) => {
|
||||
const n = 2000;
|
||||
const h = harness();
|
||||
let rows = syntheticRows(n);
|
||||
h.apply(rows);
|
||||
const retainedId = rows[1].stableId;
|
||||
const retained = h.pointById.get(retainedId);
|
||||
for (let refresh = 0; refresh < WILDLIFE_BENCHMARK_REFRESHES; refresh++) {
|
||||
rows = rows.map((row, i) =>
|
||||
i % 10 === 0 ? { ...row, stableId: `replacement:${refresh}:${i}` } : row,
|
||||
);
|
||||
assert.deepEqual(h.apply(rows), {
|
||||
created: n / 10,
|
||||
removed: n / 10,
|
||||
updated: 0,
|
||||
writes: (n / 10) * 5,
|
||||
});
|
||||
assert.equal(h.pointById.get(retainedId), retained);
|
||||
assert.equal(h.points.size, n);
|
||||
}
|
||||
assert.equal(h.counters.created, n + (n / 10) * WILDLIFE_BENCHMARK_REFRESHES);
|
||||
assert.equal(h.counters.destroyed, (n / 10) * WILDLIFE_BENCHMARK_REFRESHES);
|
||||
t.diagnostic(
|
||||
`N=${n}, 10 refreshes: initial creates=${n}, delta creates=2000, delta removes=2000, retained billboard identity unchanged`,
|
||||
);
|
||||
});
|
||||
|
||||
test('count, grade and name edits produce no billboard writes or resampling', () => {
|
||||
const h = harness();
|
||||
const rows = syntheticRows(500);
|
||||
h.model.update(rows);
|
||||
const before = { ...h.counters };
|
||||
assert.deepEqual(
|
||||
h.model.update(
|
||||
rows.map((row) => ({
|
||||
...row,
|
||||
count: 1000,
|
||||
quality: 'needs_id',
|
||||
commonName: 'Synthetic name',
|
||||
})),
|
||||
),
|
||||
{ created: 0, removed: 0, updated: 0, writes: 0 },
|
||||
);
|
||||
assert.deepEqual(h.counters, before);
|
||||
});
|
||||
|
||||
import { PerformanceObserver } from 'node:perf_hooks';
|
||||
import {
|
||||
denseContinentalRendering,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
DENSE_CONTINENT_ROWS,
|
||||
} from './renderPerformanceFixtures.mjs';
|
||||
import {
|
||||
WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
WILDLIFE_WORK_UNIT,
|
||||
createWildlifeWorkQueue,
|
||||
} from './performance.js';
|
||||
|
||||
test('dense continental moveEnd has a deterministic linear operation budget and reuses decoded metadata/coordinates', () => {
|
||||
const h = denseContinentalRendering();
|
||||
try {
|
||||
assert.equal(
|
||||
h.moveEnd(),
|
||||
'pending',
|
||||
'dense work must yield before blocking camera input',
|
||||
);
|
||||
assert.equal(
|
||||
h.metrics.projections,
|
||||
0,
|
||||
'moveEnd enqueues work without processing a tile',
|
||||
);
|
||||
const cold = h.flush();
|
||||
assert.ok(
|
||||
cold.glowPrimitives > 4000 &&
|
||||
cold.billboards > 50 &&
|
||||
cold.billboards <= DENSE_CONTINENT_ROWS,
|
||||
'benchmark exercises a dense glow with only real sampled sighting badges',
|
||||
);
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.densityVisits,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
);
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.densityMetadataBuilds,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
);
|
||||
assert.ok(cold.slices.length > 1);
|
||||
for (let move = 1; move <= 4; move++) {
|
||||
h.moveEnd(move * 3);
|
||||
const result = h.flush();
|
||||
const ops = h.state.renderPipelineOperations;
|
||||
assert.equal(ops.densityVisits, DENSE_CONTINENT_CELLS);
|
||||
assert.equal(ops.observationVisits, DENSE_CONTINENT_ROWS);
|
||||
assert.equal(ops.densityMetadataBuilds, 0);
|
||||
assert.equal(ops.densityWrites, 0);
|
||||
assert.equal(ops.densityPositionBuilds, 0);
|
||||
assert.ok(ops.densityRetirementVisits <= DENSE_CONTINENT_CELLS);
|
||||
assert.equal(ops.densityCreated, 0);
|
||||
assert.equal(ops.densityRemoved, 0);
|
||||
assert.equal(
|
||||
result.cartesianBuilds,
|
||||
0,
|
||||
'no repeated longitude/latitude trig per camera pass',
|
||||
);
|
||||
assert.ok(ops.projections <= DENSE_CONTINENT_ROWS);
|
||||
assert.ok(result.projections <= DENSE_CONTINENT_ROWS + 150);
|
||||
assert.ok(
|
||||
ops.billboardVisits <= result.billboards * 3 + WILDLIFE_WORK_UNIT,
|
||||
);
|
||||
assert.equal(
|
||||
ops.rankComparisons,
|
||||
0,
|
||||
'continental buckets never sort the source population',
|
||||
);
|
||||
assert.ok(ops.spacingTests <= result.billboards * 9);
|
||||
assert.ok(result.slices.length <= 144);
|
||||
assert.ok(result.slices.every((slice) => slice.units <= 8));
|
||||
assert.equal(
|
||||
result.publications,
|
||||
3,
|
||||
'publish overlays once after the accepted view is ready',
|
||||
);
|
||||
}
|
||||
h.moveEnd(12);
|
||||
h.flush();
|
||||
assert.equal(h.state.renderPipelineOperations.billboardWrites, 0);
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.billboardVisits,
|
||||
h.state.renderedRows.length * 2,
|
||||
'the delta owner scans each row and retained billboard once',
|
||||
);
|
||||
} finally {
|
||||
h.destroy();
|
||||
}
|
||||
});
|
||||
|
||||
test('superseded dense camera work is dropped and idle callbacks are removed at teardown', () => {
|
||||
const h = denseContinentalRendering();
|
||||
assert.equal(h.moveEnd(0), 'pending');
|
||||
assert.equal(h.moveEnd(12), 'pending');
|
||||
const result = h.flush();
|
||||
assert.equal(
|
||||
h.state.renderPipelineOperations.densityVisits,
|
||||
DENSE_CONTINENT_CELLS,
|
||||
);
|
||||
assert.equal(result.publications, 3);
|
||||
assert.equal(h.moveEnd(24), 'pending');
|
||||
h.destroy();
|
||||
assert.equal(h.flush().slices.length, 0);
|
||||
});
|
||||
|
||||
test('performance marks cover each render phase and leave no accumulated entries', async () => {
|
||||
const observed = [];
|
||||
const observer = new PerformanceObserver((list) =>
|
||||
observed.push(...list.getEntries()),
|
||||
);
|
||||
observer.observe({ entryTypes: ['measure'] });
|
||||
const h = denseContinentalRendering();
|
||||
try {
|
||||
h.moveEnd();
|
||||
h.flush();
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (const phase of [
|
||||
'density',
|
||||
'bucket',
|
||||
'rank',
|
||||
'billboard-update',
|
||||
'overlay-publish',
|
||||
'moveEnd:slice',
|
||||
])
|
||||
assert.ok(
|
||||
observed.some((entry) => entry.name === `wildlife-sightings:${phase}`),
|
||||
phase,
|
||||
);
|
||||
assert.deepEqual(
|
||||
performance
|
||||
.getEntriesByType('mark')
|
||||
.filter((entry) => entry.name.startsWith('wildlife-sightings:')),
|
||||
[],
|
||||
);
|
||||
assert.deepEqual(
|
||||
performance
|
||||
.getEntriesByType('measure')
|
||||
.filter((entry) => entry.name.startsWith('wildlife-sightings:')),
|
||||
[],
|
||||
);
|
||||
assert.equal(WILDLIFE_MOVE_END_BUDGET_MS, 4);
|
||||
} finally {
|
||||
observer.disconnect();
|
||||
h.destroy();
|
||||
}
|
||||
});
|
||||
|
||||
test('idle work has a fixed unit ceiling even when the clock does not advance', () => {
|
||||
const callbacks = new Map();
|
||||
let id = 0;
|
||||
let slices = 0;
|
||||
let done = false;
|
||||
const queue = createWildlifeWorkQueue({
|
||||
requestIdle(fn) {
|
||||
callbacks.set(++id, fn);
|
||||
return id;
|
||||
},
|
||||
cancelIdle(handle) {
|
||||
callbacks.delete(handle);
|
||||
},
|
||||
now: () => 0,
|
||||
onSlice({ units }) {
|
||||
assert.ok(units <= 8);
|
||||
slices++;
|
||||
},
|
||||
});
|
||||
function* work() {
|
||||
for (let i = 0; i < 20; i++) yield 'bucket';
|
||||
return 42;
|
||||
}
|
||||
queue.start(work(), (result) => {
|
||||
assert.equal(result, 42);
|
||||
done = true;
|
||||
});
|
||||
assert.equal(done, false);
|
||||
while (callbacks.size) {
|
||||
const [handle, fn] = callbacks.entries().next().value;
|
||||
callbacks.delete(handle);
|
||||
fn();
|
||||
}
|
||||
assert.equal(done, true);
|
||||
assert.equal(slices, 3);
|
||||
assert.equal(queue.pending, false);
|
||||
});
|
||||
|
||||
test('returning to a previous camera after partially applying a billboard delta still reconciles the collection', (t) => {
|
||||
// Slices end after eight units or 1 ms. A clock that advances 2 ms per read
|
||||
// makes every slice one unit, so the half-applied delta is observable.
|
||||
let clock = 0;
|
||||
t.mock.method(performance, 'now', () => (clock += 2));
|
||||
const h = denseContinentalRendering();
|
||||
try {
|
||||
h.moveEnd(0);
|
||||
h.flush();
|
||||
const originalIds = [...h.state.pointById.keys()].sort();
|
||||
const membership = () => [...h.state.pointById.keys()].sort();
|
||||
h.moveEnd(12);
|
||||
// Advance just until real billboard mutations begin, then supersede the
|
||||
// partially applied view by returning to the original camera.
|
||||
for (let i = 0; i < 5000; i++) {
|
||||
h.flush(1);
|
||||
if (JSON.stringify(membership()) !== JSON.stringify(originalIds)) break;
|
||||
}
|
||||
assert.notDeepEqual(membership(), originalIds);
|
||||
h.moveEnd(0);
|
||||
h.flush();
|
||||
assert.deepEqual(membership(), originalIds);
|
||||
} finally {
|
||||
h.destroy();
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,36 @@
|
||||
import { t } from '../../i18n/index.js';
|
||||
|
||||
/** Compact card ages in translated minutes, hours or days. */
|
||||
export function formatAge(deltaMs) {
|
||||
if (!Number.isFinite(deltaMs) || deltaMs < 0) return null;
|
||||
const hours = Math.floor(deltaMs / 3_600_000);
|
||||
if (hours < 1)
|
||||
return t('{count}m', {
|
||||
context: 'age',
|
||||
count: Math.max(1, Math.floor(deltaMs / 60_000)),
|
||||
});
|
||||
if (hours < 24) return t('{count}h', { context: 'age', count: hours });
|
||||
return t('{count}d', { context: 'age', count: Math.floor(hours / 24) });
|
||||
}
|
||||
|
||||
/** Use the creator portion of the supplied attribution, never a guessed
|
||||
* observer/login. iNaturalist appends rights and licence text after it. */
|
||||
export function photoCreator(photo) {
|
||||
if (typeof photo?.attribution !== 'string') return null;
|
||||
const creator = photo.attribution
|
||||
.replace(/^\s*(?:\(c\)|©|copyright)\s*/i, '')
|
||||
.replace(/,\s*(?:some|no|all)\s+rights\s+reserved\b.*$/i, '')
|
||||
.replace(
|
||||
/(?:,\s*|\s*\()(?:CC[\s-]+BY(?:[\s-]+(?:NC|SA|ND))*|CC0|public\s+domain)(?:\s+\d(?:\.\d)?)?\)?\s*$/i,
|
||||
'',
|
||||
)
|
||||
.trim();
|
||||
if (
|
||||
!creator ||
|
||||
/^(?:(?:some|no|all)\s+rights\s+reserved\b|CC(?:0|[\s-]+BY)\b)/i.test(
|
||||
creator,
|
||||
)
|
||||
)
|
||||
return null;
|
||||
return creator;
|
||||
}
|
||||
@@ -0,0 +1,183 @@
|
||||
import { ambientScore } from './cards.js';
|
||||
import { compareWildlifeIds } from './model.js';
|
||||
import { WILDLIFE_PHOTO_FETCH, WILDLIFE_PHOTO_CACHE_MAX } from './policy.js';
|
||||
|
||||
/** Own decoded ambient images and their cancellable, ranked queue. */
|
||||
export function createPhotoSlots({
|
||||
imageFactory = () => new Image(),
|
||||
now = () => Date.now(),
|
||||
setTimer = (fn, delay) => setTimeout(fn, delay),
|
||||
clearTimer = (timer) => clearTimeout(timer),
|
||||
onChange = null,
|
||||
} = {}) {
|
||||
const slots = new Map();
|
||||
let queue = [];
|
||||
let timer = null;
|
||||
let destroyed = false;
|
||||
let liveKeys = new Set();
|
||||
let cohortKey = null;
|
||||
|
||||
function notify() {
|
||||
if (!destroyed) onChange?.();
|
||||
}
|
||||
|
||||
function release(slot) {
|
||||
slot.cancelled = true;
|
||||
if (!slot.image) return;
|
||||
slot.image.onload = null;
|
||||
slot.image.onerror = null;
|
||||
// Detaching listeners alone would leave pending network and decoded data.
|
||||
slot.image.src = '';
|
||||
}
|
||||
|
||||
function prune() {
|
||||
if (slots.size <= WILDLIFE_PHOTO_CACHE_MAX) return;
|
||||
const ranked = [...slots].sort(([a, slotA], [b, slotB]) => {
|
||||
const keepA = liveKeys.has(a);
|
||||
const keepB = liveKeys.has(b);
|
||||
const frameA = slotA.displayed;
|
||||
const frameB = slotB.displayed;
|
||||
// Decoded photographs that have actually been painted outrank unseen
|
||||
// prefetches. Preserve their Image objects for a flash-free return pan.
|
||||
return Number(keepA) - Number(keepB) || Number(frameA) - Number(frameB);
|
||||
});
|
||||
for (const [key, slot] of ranked) {
|
||||
if (slots.size <= WILDLIFE_PHOTO_CACHE_MAX) break;
|
||||
release(slot);
|
||||
slots.delete(key);
|
||||
}
|
||||
}
|
||||
|
||||
function ensure(row) {
|
||||
const url = row?.photo?.square;
|
||||
if (!url) return null;
|
||||
const key = row.stableId;
|
||||
let slot = slots.get(key);
|
||||
if (slot && slot.url !== url) {
|
||||
release(slot);
|
||||
slots.delete(key);
|
||||
slot = null;
|
||||
}
|
||||
if (!slot) {
|
||||
slot = {
|
||||
key,
|
||||
url,
|
||||
image: null,
|
||||
state: 'queued',
|
||||
cancelled: false,
|
||||
displayed: false,
|
||||
};
|
||||
} else slots.delete(key);
|
||||
slots.set(key, slot);
|
||||
return slot;
|
||||
}
|
||||
|
||||
function launch(slot) {
|
||||
if (
|
||||
destroyed ||
|
||||
slot.cancelled ||
|
||||
slots.get(slot.key) !== slot ||
|
||||
slot.state !== 'queued'
|
||||
)
|
||||
return;
|
||||
slot.state = 'loading';
|
||||
let image;
|
||||
try {
|
||||
image = imageFactory();
|
||||
slot.image = image;
|
||||
// Deliberately non-CORS: the overlay canvas is display-only and is
|
||||
// never read back. Viewport capture reads the separate Cesium canvas.
|
||||
image.onload = () => {
|
||||
if (destroyed || slot.cancelled || slots.get(slot.key) !== slot) return;
|
||||
slot.state = 'ready';
|
||||
image.onload = null;
|
||||
image.onerror = null;
|
||||
notify();
|
||||
};
|
||||
image.onerror = () => {
|
||||
if (destroyed || slot.cancelled || slots.get(slot.key) !== slot) return;
|
||||
slot.state = 'error';
|
||||
image.onload = null;
|
||||
image.onerror = null;
|
||||
notify();
|
||||
};
|
||||
image.src = slot.url;
|
||||
} catch {
|
||||
slot.state = 'error';
|
||||
notify();
|
||||
}
|
||||
}
|
||||
|
||||
function pace() {
|
||||
timer = null;
|
||||
if (destroyed) return;
|
||||
while (queue.length) {
|
||||
const slot = queue.shift();
|
||||
if (slot.cancelled || slots.get(slot.key) !== slot) continue;
|
||||
launch(slot);
|
||||
break;
|
||||
}
|
||||
if (queue.length) timer = setTimer(pace, WILDLIFE_PHOTO_FETCH.intervalMs);
|
||||
}
|
||||
|
||||
function setAmbient(rows) {
|
||||
if (destroyed) return;
|
||||
const ranked = [...rows].sort(
|
||||
(a, b) =>
|
||||
ambientScore(b, now()) - ambientScore(a, now()) ||
|
||||
compareWildlifeIds(a.stableId, b.stableId),
|
||||
);
|
||||
const nextKey = JSON.stringify(
|
||||
ranked.map((row) => [row.stableId, row.photo?.square]),
|
||||
);
|
||||
// A same-cohort refresh must not turn the paced tail into another burst.
|
||||
if (cohortKey === nextKey) return;
|
||||
cohortKey = nextKey;
|
||||
clearTimer(timer);
|
||||
timer = null;
|
||||
liveKeys = new Set(ranked.map((row) => row.stableId));
|
||||
queue = ranked.map(ensure).filter(Boolean);
|
||||
prune();
|
||||
queue = queue.filter(
|
||||
(slot) => slots.get(slot.key) === slot && slot.state === 'queued',
|
||||
);
|
||||
for (
|
||||
let index = 0;
|
||||
index < WILDLIFE_PHOTO_FETCH.burst && queue.length;
|
||||
index++
|
||||
)
|
||||
launch(queue.shift());
|
||||
if (queue.length) timer = setTimer(pace, WILDLIFE_PHOTO_FETCH.intervalMs);
|
||||
}
|
||||
|
||||
function get(row) {
|
||||
const key = row?.stableId;
|
||||
const slot = slots.get(key);
|
||||
if (!slot || slot.state !== 'ready') return null;
|
||||
slot.displayed = true;
|
||||
slots.delete(key);
|
||||
slots.set(key, slot);
|
||||
return slot.image;
|
||||
}
|
||||
|
||||
function clear() {
|
||||
clearTimer(timer);
|
||||
timer = null;
|
||||
queue = [];
|
||||
for (const slot of slots.values()) release(slot);
|
||||
slots.clear();
|
||||
liveKeys.clear();
|
||||
cohortKey = null;
|
||||
}
|
||||
|
||||
return {
|
||||
setAmbient,
|
||||
get,
|
||||
clear,
|
||||
destroy() {
|
||||
destroyed = true;
|
||||
clear();
|
||||
},
|
||||
diagnostics: () => ({ slots: slots.size, queued: queue.length }),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,147 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { createPhotoSlots } from './photos.js';
|
||||
|
||||
function clock() {
|
||||
let time = 0;
|
||||
let next = 0;
|
||||
const timers = new Map();
|
||||
return {
|
||||
now: () => time,
|
||||
setTimer(fn, delay) {
|
||||
const id = ++next;
|
||||
timers.set(id, { fn, at: time + delay });
|
||||
return id;
|
||||
},
|
||||
clearTimer(id) {
|
||||
timers.delete(id);
|
||||
},
|
||||
tick(ms) {
|
||||
const until = time + ms;
|
||||
while (true) {
|
||||
const pending = [...timers].sort((a, b) => a[1].at - b[1].at)[0];
|
||||
if (!pending || pending[1].at > until) break;
|
||||
time = pending[1].at;
|
||||
timers.delete(pending[0]);
|
||||
pending[1].fn();
|
||||
}
|
||||
time = until;
|
||||
},
|
||||
count: () => timers.size,
|
||||
};
|
||||
}
|
||||
|
||||
const row = (index) => ({
|
||||
stableId: `inat:${index}`,
|
||||
quality: 'research',
|
||||
observedAt: 0,
|
||||
favesCount: 100 - index,
|
||||
identificationAgreements: 0,
|
||||
photo: {
|
||||
square: `https://inaturalist-open-data.s3.amazonaws.com/photos/${index}/square.jpg`,
|
||||
medium: `https://inaturalist-open-data.s3.amazonaws.com/photos/${index}/medium.jpg`,
|
||||
licence: 'cc-by',
|
||||
attribution: '(c) Synthetic Photographer',
|
||||
},
|
||||
});
|
||||
|
||||
function harness() {
|
||||
const time = clock();
|
||||
const launches = [];
|
||||
const images = [];
|
||||
let changes = 0;
|
||||
const slots = createPhotoSlots({
|
||||
...time,
|
||||
onChange: () => changes++,
|
||||
imageFactory: () => {
|
||||
const image = {
|
||||
set src(url) {
|
||||
this.url = url;
|
||||
if (url) launches.push({ at: time.now(), url });
|
||||
},
|
||||
};
|
||||
images.push(image);
|
||||
return image;
|
||||
},
|
||||
});
|
||||
return { slots, time, images, launches, changes: () => changes };
|
||||
}
|
||||
|
||||
test('24 photos start in rank order: eight immediately, then one per 250 ms', () => {
|
||||
const h = harness();
|
||||
const rows = Array.from({ length: 24 }, (_, index) => row(index + 1));
|
||||
h.slots.setAmbient([...rows].reverse());
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(249);
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(1);
|
||||
assert.equal(h.launches.length, 9);
|
||||
h.time.tick(3750);
|
||||
assert.equal(h.launches.length, 24);
|
||||
assert.deepEqual(
|
||||
h.launches.map(({ url }) => Number(url.match(/photos\/(\d+)/)[1])),
|
||||
rows.map((_, index) => index + 1),
|
||||
);
|
||||
assert.deepEqual(
|
||||
h.launches.slice(8).map(({ at }) => at),
|
||||
Array.from({ length: 16 }, (_, i) => (i + 1) * 250),
|
||||
);
|
||||
h.slots.destroy();
|
||||
});
|
||||
|
||||
test('same-cohort refresh keeps the ambient queue pacing without restarting its burst', () => {
|
||||
const h = harness();
|
||||
const rows = Array.from({ length: 24 }, (_, i) => row(i + 1));
|
||||
h.slots.setAmbient(rows);
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(100);
|
||||
h.slots.setAmbient(rows);
|
||||
assert.equal(h.launches.length, 8);
|
||||
h.time.tick(150);
|
||||
assert.equal(h.launches.length, 9);
|
||||
assert.ok(h.launches.every(({ url }) => /square.jpg$/.test(url)));
|
||||
h.slots.destroy();
|
||||
});
|
||||
|
||||
test('images settle through slots, are pruned to 96, and late loads cannot publish after clear', () => {
|
||||
const h = harness();
|
||||
h.slots.setAmbient([row(1)]);
|
||||
const loaded = h.images[0];
|
||||
loaded.onload();
|
||||
assert.equal(h.slots.get(row(1)), loaded);
|
||||
assert.equal(h.changes(), 1);
|
||||
for (let index = 2; index <= 130; index++) h.slots.setAmbient([row(index)]);
|
||||
assert.equal(h.slots.diagnostics().slots, 96);
|
||||
const last = h.images.at(-1);
|
||||
const late = last.onload;
|
||||
h.slots.clear();
|
||||
late();
|
||||
assert.equal(h.changes(), 1);
|
||||
assert.equal(h.slots.diagnostics().slots, 0);
|
||||
assert.equal(h.time.count(), 0);
|
||||
assert.ok(h.images.every((image) => image.url === ''));
|
||||
});
|
||||
|
||||
test('returning cards reuse their decoded frame after a pan or height-band hide', () => {
|
||||
const h = harness();
|
||||
const first = row(1);
|
||||
h.slots.setAmbient([first]);
|
||||
const frame = h.images[0];
|
||||
frame.onload();
|
||||
assert.equal(h.slots.get(first), frame);
|
||||
h.slots.setAmbient([]);
|
||||
h.slots.setAmbient([row(2)]);
|
||||
h.images[1].onload();
|
||||
for (let index = 3; index < 105; index++) h.slots.setAmbient([row(index)]);
|
||||
h.slots.setAmbient([first]);
|
||||
assert.equal(
|
||||
h.slots.get(first),
|
||||
frame,
|
||||
'the returning image is already ready, with no empty frame',
|
||||
);
|
||||
assert.equal(
|
||||
h.launches.filter(({ url }) => url.includes('/photos/1/')).length,
|
||||
1,
|
||||
);
|
||||
h.slots.destroy();
|
||||
});
|
||||
@@ -0,0 +1,142 @@
|
||||
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;
|
||||
|
||||
// Camera-height thresholds use +/-10% hysteresis to keep representations still
|
||||
// while a camera settles near a boundary.
|
||||
export const WILDLIFE_HEIGHT_HYSTERESIS = 0.1;
|
||||
export const WILDLIFE_HEIGHT_BANDS = Object.freeze({
|
||||
global: 3_000_000,
|
||||
cells: 1_500_000,
|
||||
cards: 400_000,
|
||||
});
|
||||
export const WILDLIFE_MAX_ROWS = 2_000;
|
||||
export const WILDLIFE_CARD_LIMIT = 24;
|
||||
export const WILDLIFE_CARD_MIN_SEP_PX = 112;
|
||||
export const WILDLIFE_CARD_REGION_COLUMNS = 4;
|
||||
export const WILDLIFE_CARD_REGION_ROWS = 3;
|
||||
export const WILDLIFE_PHOTO_CACHE_MAX = 96;
|
||||
|
||||
// Static S3 thumbnails do not spend the API quota.
|
||||
export const WILDLIFE_PHOTO_FETCH = Object.freeze({
|
||||
burst: 8,
|
||||
intervalMs: 250,
|
||||
});
|
||||
|
||||
export const WILDLIFE_DEBOUNCE_MS = 600;
|
||||
export { WILDLIFE_MAX_VIEW_DEGREES } from './bounds.js';
|
||||
export const WILDLIFE_VIEW_PADDING = 0.3;
|
||||
export const WILDLIFE_RETRY_MIN_MS = 30_000;
|
||||
export const WILDLIFE_RETRY_MAX_MS = 240_000;
|
||||
// Cap a Retry-After so one reply can never stall refresh forever. The proxy's
|
||||
// daily-budget reply waits until the next UTC midnight, so allow one day.
|
||||
export const WILDLIFE_RETRY_AFTER_MAX_SEC = 86_400;
|
||||
|
||||
// Faster polling would reread the proxy's five-minute cache.
|
||||
export const WILDLIFE_UPDATE_INTERVAL_MS = 5 * 60_000;
|
||||
|
||||
export const WILDLIFE_CARD_SCALE_FULL_METERS = 20_000;
|
||||
export const WILDLIFE_CARD_SCALE_MID_METERS = 120_000;
|
||||
export const WILDLIFE_CARD_SCALE_END_METERS = 125_000;
|
||||
// Separate entry and exit thresholds prevent churn during small zooms.
|
||||
export const WILDLIFE_CARD_SHOW_MAX_METERS = 110_000;
|
||||
export const WILDLIFE_CARD_HIDE_MAX_METERS = 125_000;
|
||||
export const WILDLIFE_CARD_FADE_LOW_METERS = 70_000;
|
||||
export const WILDLIFE_CARD_FADE_HIGH_METERS = 125_000;
|
||||
export const WILDLIFE_SELECTED_LABEL_MAX_CHARS = 40;
|
||||
export const WILDLIFE_SELECTED_LABEL_FADE_LOW_METERS = 250_000;
|
||||
export const WILDLIFE_SELECTED_LABEL_FADE_HIGH_METERS = 400_000;
|
||||
export const WILDLIFE_CARD_MAX_DISTANCE_METERS = 600_000;
|
||||
export const WILDLIFE_CARD_ALTITUDE_SCALE = Object.freeze({
|
||||
fullEnd: WILDLIFE_CARD_SCALE_FULL_METERS,
|
||||
midEnd: WILDLIFE_CARD_SCALE_MID_METERS,
|
||||
end: WILDLIFE_CARD_SCALE_END_METERS,
|
||||
midValue: 0.9,
|
||||
endValue: 0.85,
|
||||
smoothToMid: true,
|
||||
});
|
||||
|
||||
export { ACARTIA_GUARD_BOX } from './acartiaTaxa.js';
|
||||
export const WILDLIFE_CONFIRMED_CHIP_ID = 'quality-confirmed';
|
||||
|
||||
export const TAXA_PRESETS = Object.freeze([
|
||||
Object.freeze({
|
||||
value: 'all',
|
||||
id: 'taxa-all',
|
||||
label: msg('ALL'),
|
||||
title: msg('Show all taxa'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Aves',
|
||||
id: 'taxa-birds',
|
||||
label: msg('BIRDS'),
|
||||
title: msg('Show only birds'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Mammalia',
|
||||
id: 'taxa-mammals',
|
||||
label: msg('MAMMALS'),
|
||||
title: msg('Show only mammals'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'whales',
|
||||
id: 'taxa-whales',
|
||||
label: msg('WHALES'),
|
||||
title: msg('Show only whales and dolphins (7 days)'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Insecta',
|
||||
id: 'taxa-insects',
|
||||
label: msg('INSECTS'),
|
||||
title: msg('Show only insects'),
|
||||
}),
|
||||
Object.freeze({
|
||||
value: 'Plantae',
|
||||
id: 'taxa-plants',
|
||||
label: msg('PLANTS'),
|
||||
title: msg('Show only plants'),
|
||||
}),
|
||||
]);
|
||||
@@ -0,0 +1,341 @@
|
||||
// The server imports this module. Keep the projection independent of Cesium,
|
||||
// DOM and the translation catalog, and never copy an upstream record wholesale.
|
||||
import { msg } from '../../i18n/marker.js';
|
||||
import { acartiaSpeciesGroup, inAcartiaCoverage } from './acartiaTaxa.js';
|
||||
|
||||
const OPEN_PHOTO_LICENCES = Object.freeze([
|
||||
'cc0',
|
||||
'cc-by',
|
||||
'cc-by-sa',
|
||||
'cc-by-nc',
|
||||
'cc-by-nc-sa',
|
||||
]);
|
||||
|
||||
const DAY_MS = 86_400_000;
|
||||
const ACARTIA_MAX_AGE_MS = 8 * DAY_MS;
|
||||
const OBSERVATION_FUTURE_TOLERANCE_MS = 10 * 60_000;
|
||||
// A JavaScript $ can match before a final newline; require the true end too.
|
||||
const INAT_PHOTO =
|
||||
/^https:\/\/inaturalist-open-data\.s3\.amazonaws\.com\/photos\/\d+\/square\.(jpe?g|png)$(?![\s\S])/i;
|
||||
const INAT_OBSERVATION =
|
||||
/^https:\/\/www\.inaturalist\.org\/observations\/\d+$(?![\s\S])/;
|
||||
|
||||
/** Accept only canonical iNaturalist observation pages, without URL suffixes. */
|
||||
function inatObservationUri(value) {
|
||||
return typeof value === 'string' && INAT_OBSERVATION.test(value)
|
||||
? value
|
||||
: null;
|
||||
}
|
||||
|
||||
function cleanText(value, maxLength) {
|
||||
if (typeof value !== 'string') return null;
|
||||
const text = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim();
|
||||
return text ? text.slice(0, maxLength) : null;
|
||||
}
|
||||
|
||||
function numberOrNull(value) {
|
||||
if (typeof value !== 'number' && typeof value !== 'string') return null;
|
||||
if (typeof value === 'string' && !value.trim()) return null;
|
||||
const number = Number(value);
|
||||
return Number.isFinite(number) ? number : null;
|
||||
}
|
||||
|
||||
function validPosition(lat, lon) {
|
||||
return (
|
||||
Number.isFinite(lat) &&
|
||||
Math.abs(lat) <= 90 &&
|
||||
Number.isFinite(lon) &&
|
||||
Math.abs(lon) <= 180
|
||||
);
|
||||
}
|
||||
|
||||
function dateOnly(value) {
|
||||
if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
|
||||
return null;
|
||||
const time = Date.parse(value);
|
||||
return Number.isFinite(time) &&
|
||||
new Date(time).toISOString().slice(0, 10) === value
|
||||
? value
|
||||
: null;
|
||||
}
|
||||
|
||||
/** Date-only records cannot prove a time within a partly expired cutoff day.
|
||||
* Use its start conservatively, including for privacy-preserving cached cells. */
|
||||
function withinObservationWindow(observedAt, observedOn, nowMs, windowMs) {
|
||||
const time = Number.isFinite(observedAt)
|
||||
? observedAt
|
||||
: dateOnly(observedOn)
|
||||
? Date.parse(`${observedOn}T00:00:00Z`)
|
||||
: NaN;
|
||||
return (
|
||||
Number.isFinite(time) &&
|
||||
Number.isFinite(nowMs) &&
|
||||
Number.isFinite(windowMs) &&
|
||||
windowMs >= 0 &&
|
||||
time >= nowMs - windowMs &&
|
||||
time <= nowMs + OBSERVATION_FUTURE_TOLERANCE_MS
|
||||
);
|
||||
}
|
||||
|
||||
/** Apply the displayed observation window to projected and retained LRU rows. */
|
||||
export function isRecentWildlifeSighting(row, nowMs, taxa = 'all') {
|
||||
return withinObservationWindow(
|
||||
row?.observedAt,
|
||||
row?.observedOn,
|
||||
nowMs,
|
||||
(taxa === 'whales' ? 7 : 2) * DAY_MS,
|
||||
);
|
||||
}
|
||||
|
||||
/** Strictly parse the two documented Acartia forms. A timezone-free SQL-style
|
||||
* value is UTC; ISO timestamps must carry a timezone rather than using the host's. */
|
||||
export function parseAcartiaTime(value) {
|
||||
if (typeof value !== 'string') return null;
|
||||
const text = value.trim();
|
||||
const sql = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(text);
|
||||
const iso =
|
||||
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/i.test(
|
||||
text,
|
||||
);
|
||||
if (!sql && !iso) return null;
|
||||
const day = dateOnly(text.slice(0, 10));
|
||||
if (!day) return null;
|
||||
const [hour, minute, second] = text.slice(11, 19).split(':').map(Number);
|
||||
if (hour > 23 || minute > 59 || second > 59) return null;
|
||||
const time = Date.parse(sql ? `${text.replace(' ', 'T')}Z` : text);
|
||||
return Number.isFinite(time) ? time : null;
|
||||
}
|
||||
|
||||
function coarsen(value, precision = 2) {
|
||||
const scale = 10 ** precision;
|
||||
return Math.round(value * scale) / scale;
|
||||
}
|
||||
|
||||
/** Public iNaturalist obscuration is a 0.2-degree cell aligned to zero. The
|
||||
* rounding removes floating-point noise, including at negative longitudes. */
|
||||
export function obscuredCell(lat, lon) {
|
||||
if (!validPosition(lat, lon)) return null;
|
||||
const south = Math.min(89.8, Math.floor(lat * 5) / 5);
|
||||
const west = Math.min(179.8, Math.floor(lon * 5) / 5);
|
||||
return {
|
||||
south: coarsen(south, 1),
|
||||
north: coarsen(south + 0.2, 1),
|
||||
west: coarsen(west, 1),
|
||||
east: coarsen(west + 0.2, 1),
|
||||
};
|
||||
}
|
||||
|
||||
/** Only the documented open-data square URL can be transformed to a display size. */
|
||||
export function inatPhotoUrl(url, size = 'square') {
|
||||
if (typeof url !== 'string' || !INAT_PHOTO.test(url)) return null;
|
||||
if (size !== 'square' && size !== 'medium') return null;
|
||||
return size === 'square' ? url : url.replace(/\/square\./i, `/${size}.`);
|
||||
}
|
||||
|
||||
/** Accept either the first upstream photo or the explicitly projected photo. */
|
||||
export function isOpenPhoto(photo) {
|
||||
if (!photo || typeof photo !== 'object') return false;
|
||||
const licence = photo.license_code ?? photo.licence;
|
||||
return (
|
||||
OPEN_PHOTO_LICENCES.includes(licence) &&
|
||||
inatPhotoUrl(photo.url ?? photo.square) !== null &&
|
||||
cleanText(photo.attribution, 160) !== null
|
||||
);
|
||||
}
|
||||
|
||||
/** Licence codes remain provider data; the all-rights-reserved fallback is
|
||||
* marked for translation when cards display it. */
|
||||
export function inatLicenceLabel(code) {
|
||||
switch (code) {
|
||||
case 'cc0':
|
||||
return 'CC0';
|
||||
case 'cc-by':
|
||||
return 'CC BY';
|
||||
case 'cc-by-sa':
|
||||
return 'CC BY-SA';
|
||||
case 'cc-by-nc':
|
||||
return 'CC BY-NC';
|
||||
case 'cc-by-nc-sa':
|
||||
return 'CC BY-NC-SA';
|
||||
case 'cc-by-nd':
|
||||
return 'CC BY-ND';
|
||||
case 'cc-by-nc-nd':
|
||||
return 'CC BY-NC-ND';
|
||||
default:
|
||||
return msg('All rights reserved');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Project API-v1 observation results (the results ARRAY, not the response
|
||||
* envelope). Malformed rows are skipped; only a non-array rejects a snapshot.
|
||||
*/
|
||||
export function normalizeInatObservations(
|
||||
payload,
|
||||
{ nowMs, windowMs = 2 * DAY_MS } = {},
|
||||
) {
|
||||
if (!Array.isArray(payload)) return null;
|
||||
const rows = [];
|
||||
const ids = new Set();
|
||||
for (const raw of payload) {
|
||||
if (!raw || !Number.isSafeInteger(raw.id) || raw.id <= 0) continue;
|
||||
if (raw.geoprivacy === 'private' || raw.taxon_geoprivacy === 'private')
|
||||
continue;
|
||||
if (raw.quality_grade !== 'research' && raw.quality_grade !== 'needs_id')
|
||||
continue;
|
||||
const stableId = `inat:${raw.id}`;
|
||||
if (ids.has(stableId)) continue;
|
||||
let lon = raw.geojson?.coordinates?.[0];
|
||||
let lat = raw.geojson?.coordinates?.[1];
|
||||
if (!validPosition(lat, lon) && typeof raw.location === 'string') {
|
||||
const parts = raw.location.split(',');
|
||||
if (parts.length === 2) [lat, lon] = parts.map(numberOrNull);
|
||||
}
|
||||
if (!validPosition(lat, lon)) continue;
|
||||
const obscured =
|
||||
raw.obscured === true ||
|
||||
raw.geoprivacy === 'obscured' ||
|
||||
raw.taxon_geoprivacy === 'obscured';
|
||||
const cell = obscured ? obscuredCell(lat, lon) : null;
|
||||
const time = parseAcartiaTime(raw.time_observed_at);
|
||||
const observedOn =
|
||||
dateOnly(raw.observed_on) ||
|
||||
(time !== null ? new Date(time).toISOString().slice(0, 10) : null);
|
||||
// The v1 d1 parameter is a DATE filter, so its first day over-fetches the
|
||||
// exact rolling window. Filter before hiding an obscured record's time.
|
||||
if (
|
||||
Number.isFinite(nowMs) &&
|
||||
!withinObservationWindow(time, observedOn, nowMs, windowMs)
|
||||
)
|
||||
continue;
|
||||
const photo = Array.isArray(raw.photos) ? raw.photos[0] : null;
|
||||
const taxon = raw.taxon;
|
||||
const faves = numberOrNull(raw.faves_count);
|
||||
const agreements = numberOrNull(raw.num_identification_agreements);
|
||||
ids.add(stableId);
|
||||
rows.push({
|
||||
stableId,
|
||||
origin: 'inaturalist',
|
||||
lat: cell ? coarsen((cell.south + cell.north) / 2, 1) : lat,
|
||||
lon: cell ? coarsen((cell.west + cell.east) / 2, 1) : lon,
|
||||
obscured,
|
||||
cell,
|
||||
observedAt: obscured ? null : time,
|
||||
observedOn,
|
||||
quality: raw.quality_grade,
|
||||
commonName: cleanText(taxon?.preferred_common_name, 100),
|
||||
scientificName: cleanText(taxon?.name, 100),
|
||||
iconic: cleanText(taxon?.iconic_taxon_name, 40) || 'Unknown',
|
||||
threatened: taxon?.threatened === true,
|
||||
provider: null,
|
||||
link:
|
||||
inatObservationUri(raw.uri) ||
|
||||
`https://www.inaturalist.org/observations/${raw.id}`,
|
||||
photo: isOpenPhoto(photo)
|
||||
? {
|
||||
square: inatPhotoUrl(photo.url),
|
||||
licence: photo.license_code,
|
||||
attribution: cleanText(photo.attribution, 160),
|
||||
}
|
||||
: null,
|
||||
// These public aggregate counters are used only for ambient photo rank.
|
||||
favesCount: faves !== null && faves >= 0 ? Math.floor(faves) : 0,
|
||||
identificationAgreements:
|
||||
agreements !== null && agreements >= 0 ? Math.floor(agreements) : 0,
|
||||
});
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
// Acartia has no documented per-sighting page, and photo_url is supplied by the
|
||||
// contributor. The source link is therefore always the Acartia site itself.
|
||||
export const ACARTIA_SITE = 'https://acartia.io/';
|
||||
|
||||
/** Acartia documents flat rows only. Name and entity are text fields; unknown
|
||||
* shapes are skipped rather than guessing nested provider data. */
|
||||
export function normalizeAcartiaSightings(payload, nowMs) {
|
||||
if (!Array.isArray(payload)) return null;
|
||||
const rows = [];
|
||||
const ids = new Set();
|
||||
for (const raw of payload) {
|
||||
const id =
|
||||
typeof raw?.entry_id === 'string'
|
||||
? cleanText(raw.entry_id, 120)
|
||||
: Number.isFinite(raw?.entry_id)
|
||||
? String(raw.entry_id)
|
||||
: null;
|
||||
if (!id) continue;
|
||||
const stableId = `acartia:${id}`;
|
||||
if (ids.has(stableId)) continue;
|
||||
const lat = numberOrNull(raw.latitude);
|
||||
const lon = numberOrNull(raw.longitude);
|
||||
const observedAt = parseAcartiaTime(raw.created);
|
||||
const name = cleanText(raw.data_source_name, 60);
|
||||
const species = cleanText(raw.type, 100);
|
||||
// Validate the original field: truncating a long, ambiguous name could
|
||||
// otherwise turn a prefix such as "Orca ... or seal" into a valid species.
|
||||
const speciesGroup = acartiaSpeciesGroup(raw.type);
|
||||
if (
|
||||
!validPosition(lat, lon) ||
|
||||
!inAcartiaCoverage(lat, lon) ||
|
||||
!name ||
|
||||
!speciesGroup ||
|
||||
observedAt === null ||
|
||||
!Number.isFinite(nowMs) ||
|
||||
nowMs - observedAt > ACARTIA_MAX_AGE_MS ||
|
||||
observedAt - nowMs > OBSERVATION_FUTURE_TOLERANCE_MS
|
||||
)
|
||||
continue;
|
||||
ids.add(stableId);
|
||||
rows.push({
|
||||
stableId,
|
||||
origin: 'acartia',
|
||||
lat: coarsen(lat),
|
||||
lon: coarsen(lon),
|
||||
obscured: false,
|
||||
cell: null,
|
||||
observedAt,
|
||||
observedOn: new Date(observedAt).toISOString().slice(0, 10),
|
||||
quality:
|
||||
raw.trusted === true || raw.trusted === 1 || raw.trusted === 'true'
|
||||
? 'research'
|
||||
: 'needs_id',
|
||||
commonName: species,
|
||||
scientificName: null,
|
||||
iconic: 'Mammalia',
|
||||
cetacean: speciesGroup === 'cetacean',
|
||||
threatened: false,
|
||||
provider: { name, entity: cleanText(raw.data_source_entity, 60) },
|
||||
link: ACARTIA_SITE,
|
||||
photo: null,
|
||||
favesCount: 0,
|
||||
identificationAgreements: 0,
|
||||
});
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
/** Recheck observation age on projected snapshots, including stale cache rows. */
|
||||
export function mergeSightings(
|
||||
inatRows,
|
||||
acartiaRows,
|
||||
{ nowMs, taxa = 'all', confirmed = false } = {},
|
||||
) {
|
||||
const byId = new Map();
|
||||
for (const row of Array.isArray(inatRows) ? inatRows : []) {
|
||||
if (isRecentWildlifeSighting(row, nowMs, taxa)) byId.set(row.stableId, row);
|
||||
}
|
||||
for (const row of Array.isArray(acartiaRows) ? acartiaRows : []) {
|
||||
if (
|
||||
!inAcartiaCoverage(row.lat, row.lon) ||
|
||||
!isRecentWildlifeSighting(row, nowMs, taxa)
|
||||
)
|
||||
continue;
|
||||
if (confirmed && row.quality !== 'research') continue;
|
||||
if (/inaturalist/i.test(row.provider?.name || '')) continue;
|
||||
if (!['all', 'Mammalia', 'whales'].includes(taxa)) continue;
|
||||
if (taxa === 'whales' && row.cetacean !== true) continue;
|
||||
byId.set(row.stableId, row);
|
||||
}
|
||||
return [...byId.values()];
|
||||
}
|
||||
@@ -0,0 +1,546 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
normalizeInatObservations,
|
||||
normalizeAcartiaSightings,
|
||||
parseAcartiaTime,
|
||||
inatPhotoUrl,
|
||||
isOpenPhoto,
|
||||
obscuredCell,
|
||||
inatLicenceLabel,
|
||||
mergeSightings,
|
||||
isRecentWildlifeSighting,
|
||||
} from './records.js';
|
||||
|
||||
const now = Date.UTC(2026, 10, 4, 18);
|
||||
const hour = 3_600_000;
|
||||
const photo = {
|
||||
url: 'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpeg',
|
||||
license_code: 'cc-by-nc',
|
||||
attribution: '(c) Synthetic Photographer, some rights reserved',
|
||||
};
|
||||
const observation = (overrides = {}) => ({
|
||||
id: 123,
|
||||
uri: 'https://www.inaturalist.org/observations/123',
|
||||
geojson: { coordinates: [-122.351, 47.613] },
|
||||
positional_accuracy: 12,
|
||||
public_positional_accuracy: 12,
|
||||
obscured: false,
|
||||
geoprivacy: null,
|
||||
taxon_geoprivacy: null,
|
||||
time_observed_at: '2026-11-04T16:00:00Z',
|
||||
observed_on: '2026-11-04',
|
||||
created_at: '2026-11-04T17:00:00Z',
|
||||
quality_grade: 'research',
|
||||
license_code: 'cc-by-nc',
|
||||
faves_count: 6,
|
||||
num_identification_agreements: 3,
|
||||
taxon: {
|
||||
name: 'Calypte anna',
|
||||
preferred_common_name: "Anna's Hummingbird",
|
||||
iconic_taxon_name: 'Aves',
|
||||
threatened: false,
|
||||
},
|
||||
photos: [photo],
|
||||
user: { login: 'SHOULD_NEVER_ESCAPE' },
|
||||
...overrides,
|
||||
});
|
||||
const sighting = (overrides = {}) => ({
|
||||
entry_id: 'abc',
|
||||
latitude: 48.12345,
|
||||
longitude: -122.54321,
|
||||
created: '2026-11-04 16:00:00',
|
||||
type: 'Orca',
|
||||
no_sighted: '5',
|
||||
photo_url: 'https://provider.example/photo.jpg',
|
||||
data_source_name: 'Synthetic Network',
|
||||
data_source_entity: 'Whale Alert',
|
||||
trusted: true,
|
||||
data_source_comments: 'PRIVATE PHONE AND NAME',
|
||||
...overrides,
|
||||
});
|
||||
|
||||
test('normalizers reject only non-array snapshots and dedupe validated ids', () => {
|
||||
for (const input of [null, {}, { results: [] }, '']) {
|
||||
assert.equal(normalizeInatObservations(input), null);
|
||||
assert.equal(normalizeAcartiaSightings(input, now), null);
|
||||
}
|
||||
assert.deepEqual(normalizeInatObservations([]), []);
|
||||
assert.equal(
|
||||
normalizeInatObservations([null, observation(), observation()]).length,
|
||||
1,
|
||||
);
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([null, sighting(), sighting()], now).length,
|
||||
1,
|
||||
);
|
||||
});
|
||||
|
||||
test('iNaturalist projection retains only the listed display fields and aggregate photo rank', () => {
|
||||
const [row] = normalizeInatObservations([observation()]);
|
||||
assert.equal(row.stableId, 'inat:123');
|
||||
assert.equal(row.favesCount, 6);
|
||||
assert.equal(row.identificationAgreements, 3);
|
||||
assert.equal(row.photo.attribution, photo.attribution);
|
||||
assert.equal(row.observedAt, now - 2 * hour);
|
||||
for (const key of [
|
||||
'user',
|
||||
'login',
|
||||
'public_positional_accuracy',
|
||||
'geojson',
|
||||
'created_at',
|
||||
])
|
||||
assert.equal(key in row, false);
|
||||
assert.doesNotMatch(JSON.stringify(row), /SHOULD_NEVER_ESCAPE/);
|
||||
});
|
||||
|
||||
test('observation links accept only canonical source pages and fall back to the id', () => {
|
||||
for (const uri of [
|
||||
undefined,
|
||||
'https://www.inaturalist.org/observations/123\n',
|
||||
'https://www.inaturalist.org/observations/123?redirect=elsewhere',
|
||||
'http://www.inaturalist.org/observations/123',
|
||||
'https://www.inaturalist.org.evil.example/observations/123',
|
||||
]) {
|
||||
const [row] = normalizeInatObservations([observation({ uri })]);
|
||||
assert.equal(
|
||||
row.link,
|
||||
observation().uri,
|
||||
'the existing detail card keeps its canonical fallback',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('wildlife package entries construct without acquiring data or a DOM', async () => {
|
||||
const api = await import('gods-eye-view/layers/wildlife-sightings');
|
||||
const sources =
|
||||
await import('gods-eye-view/layers/wildlife-sightings/source');
|
||||
const layer = api.createWildlifeSightingsLayer({
|
||||
source: sources.createWildlifeSightingsSource({
|
||||
fetchImpl() {
|
||||
assert.fail('construction must not acquire');
|
||||
},
|
||||
}),
|
||||
});
|
||||
assert.equal(layer.id, 'wildlife-sightings');
|
||||
layer.destroy();
|
||||
});
|
||||
|
||||
test('only allow-listed photo licences with square open-data hosts and attribution render', () => {
|
||||
for (const license_code of [
|
||||
'cc0',
|
||||
'cc-by',
|
||||
'cc-by-sa',
|
||||
'cc-by-nc',
|
||||
'cc-by-nc-sa',
|
||||
]) {
|
||||
assert.equal(isOpenPhoto({ ...photo, license_code }), true);
|
||||
assert.ok(
|
||||
normalizeInatObservations([
|
||||
observation({ photos: [{ ...photo, license_code }] }),
|
||||
])[0].photo,
|
||||
);
|
||||
}
|
||||
for (const badPhoto of [
|
||||
{ ...photo, license_code: null },
|
||||
{ ...photo, license_code: 'cc-by-nd' },
|
||||
{ ...photo, license_code: 'cc-by-nc-nd' },
|
||||
{ ...photo, license_code: 'all rights reserved' },
|
||||
{ ...photo, url: 'https://static.inaturalist.org/photos/123/square.jpg' },
|
||||
{ ...photo, url: `${photo.url}?size=square` },
|
||||
{ ...photo, url: photo.url.replace('https:', 'http:') },
|
||||
{ ...photo, attribution: '' },
|
||||
{ ...photo, url: photo.url.replace('/square.', '/medium.') },
|
||||
]) {
|
||||
assert.equal(isOpenPhoto(badPhoto), false);
|
||||
assert.equal(
|
||||
normalizeInatObservations([observation({ photos: [badPhoto] })])[0].photo,
|
||||
null,
|
||||
);
|
||||
}
|
||||
assert.equal(
|
||||
inatPhotoUrl(photo.url, 'medium'),
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/medium.jpeg',
|
||||
);
|
||||
for (const extension of ['jpg', 'jpeg', 'PNG']) {
|
||||
const square = photo.url.replace('square.jpeg', `square.${extension}`);
|
||||
assert.equal(
|
||||
inatPhotoUrl(square, 'medium'),
|
||||
square.replace('/square.', '/medium.'),
|
||||
);
|
||||
}
|
||||
for (const invalid of [
|
||||
null,
|
||||
new URL(photo.url),
|
||||
photo.url.replace('https:', 'http:'),
|
||||
photo.url.replace('amazonaws.com', 'amazonaws.com.evil.example'),
|
||||
photo.url.replace('https://', 'https://user:secret@'),
|
||||
photo.url.replace('https://', 'https://evil.example@'),
|
||||
photo.url.replace('/photos/', '/other/photos/'),
|
||||
photo.url.replace('/123/', '/abc/'),
|
||||
photo.url.replace('/square.', '/medium.'),
|
||||
photo.url.replace('/square.', '/large.'),
|
||||
photo.url.replace('.jpeg', '.webp'),
|
||||
`${photo.url}?size=large`,
|
||||
`${photo.url}#large`,
|
||||
`${photo.url}\n`,
|
||||
]) {
|
||||
assert.equal(inatPhotoUrl(invalid, 'medium'), null, String(invalid));
|
||||
}
|
||||
for (const invalidSize of [
|
||||
'original',
|
||||
'small',
|
||||
'large',
|
||||
'Medium',
|
||||
'../medium',
|
||||
'medium?query=1',
|
||||
null,
|
||||
]) {
|
||||
assert.equal(inatPhotoUrl(photo.url, invalidSize), null);
|
||||
}
|
||||
assert.equal(inatLicenceLabel('cc-by-nc-sa'), 'CC BY-NC-SA');
|
||||
assert.equal(inatLicenceLabel(null), 'All rights reserved');
|
||||
});
|
||||
|
||||
test('photo attribution is trimmed, control-free and bounded', () => {
|
||||
const attribution = ` Photo\u0000\n${'A'.repeat(200)} `;
|
||||
const [row] = normalizeInatObservations([
|
||||
observation({ photos: [{ ...photo, attribution }] }),
|
||||
]);
|
||||
assert.equal(row.photo.attribution.length, 160);
|
||||
assert.match(row.photo.attribution, /^PhotoA/);
|
||||
assert.doesNotMatch(row.photo.attribution, /[\u0000-\u001f]/);
|
||||
});
|
||||
|
||||
test('obscured rows reveal only cell centres and date, without accuracy', () => {
|
||||
assert.deepEqual(obscuredCell(47.613, -122.351), {
|
||||
south: 47.6,
|
||||
north: 47.8,
|
||||
west: -122.4,
|
||||
east: -122.2,
|
||||
});
|
||||
for (const hiding of [
|
||||
{ obscured: true },
|
||||
{ geoprivacy: 'obscured' },
|
||||
{ taxon_geoprivacy: 'obscured' },
|
||||
]) {
|
||||
const [row] = normalizeInatObservations([observation(hiding)]);
|
||||
assert.equal(row.obscured, true);
|
||||
assert.equal(row.lat, 47.7);
|
||||
assert.equal(row.lon, -122.3);
|
||||
assert.equal('accuracyM' in row, false);
|
||||
assert.equal(row.observedAt, null);
|
||||
assert.equal(row.observedOn, '2026-11-04');
|
||||
assert.doesNotMatch(JSON.stringify(row), /47\.613|-122\.351|16:00/);
|
||||
}
|
||||
assert.deepEqual(obscuredCell(90, 180), {
|
||||
south: 89.8,
|
||||
north: 90,
|
||||
west: 179.8,
|
||||
east: 180,
|
||||
});
|
||||
});
|
||||
|
||||
test('private, casual, invalid coordinates and invalid ids are skipped', () => {
|
||||
const invalid = [
|
||||
observation({ geoprivacy: 'private' }),
|
||||
observation({ taxon_geoprivacy: 'private' }),
|
||||
observation({ quality_grade: 'casual' }),
|
||||
observation({ id: -1 }),
|
||||
observation({ id: 1.5 }),
|
||||
observation({ geojson: { coordinates: [181, 47] } }),
|
||||
observation({ geojson: null }),
|
||||
];
|
||||
assert.deepEqual(normalizeInatObservations(invalid), []);
|
||||
const [fallback] = normalizeInatObservations([
|
||||
observation({
|
||||
geojson: null,
|
||||
location: '47.613,-122.351',
|
||||
uri: 'https://bad.example',
|
||||
}),
|
||||
]);
|
||||
assert.equal(fallback.lat, 47.613);
|
||||
assert.equal(fallback.link, 'https://www.inaturalist.org/observations/123');
|
||||
assert.deepEqual(
|
||||
normalizeInatObservations([observation({ geojson: null, location: ',0' })]),
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('Acartia accepts only the two stated UTC timestamp formats', () => {
|
||||
assert.equal(parseAcartiaTime('2026-11-04 16:00:00'), now - 2 * hour);
|
||||
assert.equal(parseAcartiaTime('2026-11-04T16:00:00Z'), now - 2 * hour);
|
||||
assert.equal(parseAcartiaTime('2026-11-04T18:00:00+02:00'), now - 2 * hour);
|
||||
for (const value of [
|
||||
'2026-11-04T16:00:00',
|
||||
'11/04/2026',
|
||||
'2026-02-30 12:00:00',
|
||||
'2026-11-04 25:00:00',
|
||||
123,
|
||||
null,
|
||||
])
|
||||
assert.equal(parseAcartiaTime(value), null);
|
||||
});
|
||||
|
||||
test('Acartia coarsens before returning data, keeps provider, and never reads comments', () => {
|
||||
const raw = sighting();
|
||||
Object.defineProperty(raw, 'data_source_comments', {
|
||||
get() {
|
||||
assert.fail('comments read');
|
||||
},
|
||||
});
|
||||
const [row] = normalizeAcartiaSightings([raw], now);
|
||||
assert.equal(row.lat, 48.12);
|
||||
assert.equal(row.lon, -122.54);
|
||||
assert.deepEqual(row.provider, {
|
||||
name: 'Synthetic Network',
|
||||
entity: 'Whale Alert',
|
||||
});
|
||||
assert.equal(row.quality, 'research');
|
||||
assert.equal(row.photo, null);
|
||||
assert.doesNotMatch(
|
||||
JSON.stringify(row),
|
||||
/data_source_comments|PRIVATE|48\.12345|-122\.54321/,
|
||||
);
|
||||
});
|
||||
|
||||
test('Acartia requires flat provider text, handles trust, and sanitizes type', () => {
|
||||
for (const provider of ['', null, {}, { name: 'Invented nested shape' }]) {
|
||||
assert.deepEqual(
|
||||
normalizeAcartiaSightings(
|
||||
[sighting({ data_source_name: provider })],
|
||||
now,
|
||||
),
|
||||
[],
|
||||
);
|
||||
}
|
||||
for (const trusted of [true, 1, 'true'])
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting({ trusted })], now)[0].quality,
|
||||
'research',
|
||||
);
|
||||
for (const trusted of [false, 0, 'false', '1'])
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting({ trusted })], now)[0].quality,
|
||||
'needs_id',
|
||||
);
|
||||
assert.deepEqual(
|
||||
normalizeAcartiaSightings([sighting({ type: ' \u0000 ' })], now),
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('Acartia rejects invalid times/positions and its link is always the Acartia site', () => {
|
||||
for (const overrides of [
|
||||
{ created: new Date(now - 8 * 24 * hour - 1).toISOString() },
|
||||
{ created: new Date(now + 10 * 60_000 + 1).toISOString() },
|
||||
{ created: 'not a timestamp' },
|
||||
{ latitude: 91 },
|
||||
{ longitude: -181 },
|
||||
{ entry_id: '' },
|
||||
])
|
||||
assert.deepEqual(normalizeAcartiaSightings([sighting(overrides)], now), []);
|
||||
for (const photo_url of [
|
||||
// A contributor-supplied URL is never labelled as the Acartia source.
|
||||
'https://provider.example/photo.jpg',
|
||||
'https://phishing.example/acartia.io/login',
|
||||
'https://acartia.io.attacker.example/',
|
||||
'http://provider.example/p.jpg',
|
||||
'https://user:[email protected]/p.jpg',
|
||||
'javascript:bad()',
|
||||
'https://' + 'x'.repeat(501),
|
||||
null,
|
||||
]) {
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting({ photo_url })], now)[0].link,
|
||||
'https://acartia.io/',
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('merge applies Acartia windows, trust, preset and iNat dedupe', () => {
|
||||
const inat = normalizeInatObservations([observation()]);
|
||||
const rows = normalizeAcartiaSightings(
|
||||
[
|
||||
sighting(),
|
||||
sighting({
|
||||
entry_id: 'old',
|
||||
created: new Date(now - 3 * 24 * hour).toISOString(),
|
||||
}),
|
||||
sighting({ entry_id: 'untrusted', trusted: false }),
|
||||
sighting({
|
||||
entry_id: 'inat',
|
||||
data_source_name: 'iNaturalist observations',
|
||||
}),
|
||||
],
|
||||
now,
|
||||
);
|
||||
const ids = (options) =>
|
||||
mergeSightings(inat, rows, { nowMs: now, ...options }).map(
|
||||
(row) => row.stableId,
|
||||
);
|
||||
assert.deepEqual(ids({}), ['inat:123', 'acartia:abc', 'acartia:untrusted']);
|
||||
assert.deepEqual(ids({ confirmed: true }), ['inat:123', 'acartia:abc']);
|
||||
assert.ok(ids({ taxa: 'whales' }).includes('acartia:old'));
|
||||
assert.deepEqual(ids({ taxa: 'Aves' }), ['inat:123']);
|
||||
});
|
||||
|
||||
test('iNaturalist recency uses observation time and the exact preset window', () => {
|
||||
const raw = [
|
||||
observation({
|
||||
id: 1,
|
||||
time_observed_at: '2010-11-04T16:00:00Z',
|
||||
observed_on: '2010-11-04',
|
||||
created_at: new Date(now).toISOString(),
|
||||
}),
|
||||
observation({
|
||||
id: 2,
|
||||
time_observed_at: new Date(now - 48 * hour - 1).toISOString(),
|
||||
observed_on: '2026-11-02',
|
||||
}),
|
||||
observation({
|
||||
id: 3,
|
||||
time_observed_at: new Date(now - 48 * hour).toISOString(),
|
||||
observed_on: '2026-11-02',
|
||||
created_at: '2026-10-01T00:00:00Z',
|
||||
}),
|
||||
observation({
|
||||
id: 4,
|
||||
time_observed_at: new Date(now - 3 * 24 * hour).toISOString(),
|
||||
observed_on: '2026-11-01',
|
||||
}),
|
||||
];
|
||||
const ids = (rows) => rows.map((row) => row.stableId);
|
||||
assert.deepEqual(ids(normalizeInatObservations(raw, { nowMs: now })), [
|
||||
'inat:3',
|
||||
]);
|
||||
assert.deepEqual(
|
||||
ids(
|
||||
normalizeInatObservations(raw, { nowMs: now, windowMs: 7 * 24 * hour }),
|
||||
),
|
||||
['inat:2', 'inat:3', 'inat:4'],
|
||||
);
|
||||
// Recheck cached/projected rows as the clock moves between server refreshes.
|
||||
assert.deepEqual(
|
||||
ids(mergeSightings(normalizeInatObservations(raw), [], { nowMs: now })),
|
||||
['inat:3'],
|
||||
);
|
||||
assert.deepEqual(
|
||||
mergeSightings(normalizeInatObservations([raw[2]]), [], { nowMs: now + 1 }),
|
||||
[],
|
||||
);
|
||||
});
|
||||
|
||||
test('date-only and obscured iNaturalist recency never includes a partly expired date', () => {
|
||||
const rows = normalizeInatObservations(
|
||||
[
|
||||
observation({ id: 1, time_observed_at: null, observed_on: '2026-11-02' }),
|
||||
observation({ id: 2, time_observed_at: null, observed_on: '2026-11-03' }),
|
||||
observation({ id: 3, time_observed_at: null, observed_on: null }),
|
||||
observation({
|
||||
id: 4,
|
||||
obscured: true,
|
||||
time_observed_at: '2010-11-04T16:00:00Z',
|
||||
observed_on: '2010-11-04',
|
||||
}),
|
||||
],
|
||||
{ nowMs: now },
|
||||
);
|
||||
assert.deepEqual(
|
||||
rows.map((row) => row.stableId),
|
||||
['inat:2'],
|
||||
);
|
||||
});
|
||||
|
||||
test('retained sightings use the same exact, date-only and preset recency limits', () => {
|
||||
const boundary = { observedAt: now - 48 * hour };
|
||||
assert.equal(isRecentWildlifeSighting(boundary, now), true);
|
||||
assert.equal(isRecentWildlifeSighting(boundary, now + 1), false);
|
||||
assert.equal(isRecentWildlifeSighting(boundary, now + 1, 'whales'), true);
|
||||
const whaleBoundary = { observedAt: now - 7 * 24 * hour };
|
||||
assert.equal(isRecentWildlifeSighting(whaleBoundary, now, 'whales'), true);
|
||||
assert.equal(
|
||||
isRecentWildlifeSighting(whaleBoundary, now + 1, 'whales'),
|
||||
false,
|
||||
);
|
||||
assert.equal(isRecentWildlifeSighting(whaleBoundary, now, 'Mammalia'), false);
|
||||
for (const [observedOn, expected] of [
|
||||
['2026-11-02', false],
|
||||
['2026-11-03', true],
|
||||
['2026-11-04', true],
|
||||
]) {
|
||||
assert.equal(
|
||||
isRecentWildlifeSighting({ observedAt: null, observedOn }, now),
|
||||
expected,
|
||||
);
|
||||
}
|
||||
assert.equal(
|
||||
isRecentWildlifeSighting({ observedOn: '2026-11-03' }, now + 24 * hour),
|
||||
false,
|
||||
);
|
||||
for (const row of [
|
||||
null,
|
||||
{},
|
||||
{ observedOn: '2010-11-04' },
|
||||
{ observedOn: 'invalid' },
|
||||
]) {
|
||||
assert.equal(isRecentWildlifeSighting(row, now), false);
|
||||
}
|
||||
assert.equal(isRecentWildlifeSighting(boundary, NaN), false);
|
||||
});
|
||||
|
||||
test('Acartia validates the documented type field before applying the WHALES preset', () => {
|
||||
const rows = normalizeAcartiaSightings(
|
||||
[
|
||||
sighting({ entry_id: 'orca', type: 'Orca' }),
|
||||
sighting({ entry_id: 'scientific', type: 'Phocoena phocoena' }),
|
||||
sighting({ entry_id: 'seal', type: 'Harbor seal' }),
|
||||
sighting({
|
||||
entry_id: 'unidentified',
|
||||
type: 'Unidentified marine mammal',
|
||||
}),
|
||||
sighting({ entry_id: 'unknown-whale', type: 'Unidentified whale' }),
|
||||
sighting({ entry_id: 'unknown', type: 'Unknown' }),
|
||||
sighting({ entry_id: 'empty', type: '' }),
|
||||
sighting({ entry_id: 'fish', type: 'Whale shark' }),
|
||||
sighting({ entry_id: 'text', type: 'Maybe an Orca or a seal' }),
|
||||
sighting({ entry_id: 'prefix', type: `Orca${' '.repeat(120)}or a seal` }),
|
||||
sighting({ entry_id: 'invented-shape', type: { species: 'Orca' } }),
|
||||
],
|
||||
now,
|
||||
);
|
||||
const ids = (taxa) =>
|
||||
mergeSightings([], rows, { nowMs: now, taxa }).map((row) => row.stableId);
|
||||
assert.deepEqual(ids('whales'), ['acartia:orca', 'acartia:scientific']);
|
||||
const mammals = [
|
||||
'acartia:orca',
|
||||
'acartia:scientific',
|
||||
'acartia:seal',
|
||||
'acartia:unidentified',
|
||||
'acartia:unknown-whale',
|
||||
];
|
||||
assert.deepEqual(ids('all'), mammals);
|
||||
assert.deepEqual(ids('Mammalia'), mammals);
|
||||
assert.deepEqual(ids('Aves'), []);
|
||||
});
|
||||
|
||||
test('Acartia rejects out-of-coverage rows before rounding or caching', () => {
|
||||
for (const position of [
|
||||
{ latitude: 45.49999 },
|
||||
{ latitude: 50.50001 },
|
||||
{ longitude: -126.00001 },
|
||||
{ longitude: -120.99999 },
|
||||
{ latitude: 37.8, longitude: -122.4 },
|
||||
]) {
|
||||
assert.deepEqual(normalizeAcartiaSightings([sighting(position)], now), []);
|
||||
}
|
||||
for (const position of [
|
||||
{ latitude: 45.5, longitude: -126 },
|
||||
{ latitude: 50.5, longitude: -121 },
|
||||
]) {
|
||||
assert.equal(
|
||||
normalizeAcartiaSightings([sighting(position)], now).length,
|
||||
1,
|
||||
);
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,166 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { performance, PerformanceObserver } from 'node:perf_hooks';
|
||||
import test from 'node:test';
|
||||
import { perfBudgetTestOptions } from '../../../scripts/run-perf-tests.mjs';
|
||||
import { denseContinentalRendering } from './renderPerformanceFixtures.mjs';
|
||||
import { WILDLIFE_MOVE_END_BUDGET_MS } from './performance.js';
|
||||
|
||||
const median = (values) =>
|
||||
[...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
|
||||
const percentile95 = (values) =>
|
||||
[...values].sort((a, b) => a - b)[Math.floor(values.length * 0.95)];
|
||||
|
||||
// A GC pause is outside the layer's CPU work. Keep raw wall times in the
|
||||
// diagnostic and subtract only directly observed, overlapping GC intervals
|
||||
// for the strict CPU budget; never hide a slow layer phase as an outlier.
|
||||
function activeMs(slice, collections) {
|
||||
const start = slice.startTimeMs;
|
||||
const end = start + slice.durationMs;
|
||||
return (
|
||||
slice.durationMs -
|
||||
collections.reduce(
|
||||
(sum, gc) =>
|
||||
sum +
|
||||
Math.max(
|
||||
0,
|
||||
Math.min(end, gc.startTime + gc.duration) -
|
||||
Math.max(start, gc.startTime),
|
||||
),
|
||||
0,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
test(
|
||||
'dense continental production moveEnd pipeline yields every 4ms, including cold tiles and real Cesium billboard updates',
|
||||
perfBudgetTestOptions(),
|
||||
async (t) => {
|
||||
// Settle CPU-triggered runtime startup before creating the cold layer;
|
||||
// cells, coordinates and billboard collections remain unwarmed.
|
||||
const calibrationStart = performance.now();
|
||||
let calibrationChecksum = 0;
|
||||
for (;;) {
|
||||
const cpu = process.threadCpuUsage();
|
||||
if (cpu.user + cpu.system >= 1_100_000) break;
|
||||
for (let i = 0; i < 65536; i++)
|
||||
calibrationChecksum =
|
||||
(calibrationChecksum + i) ^ (calibrationChecksum >>> 16);
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
}
|
||||
const runtimeSettleMs = performance.now() - calibrationStart;
|
||||
const collections = [];
|
||||
const phases = [];
|
||||
const observer = new PerformanceObserver((list) => {
|
||||
for (const entry of list.getEntries())
|
||||
(entry.entryType === 'gc' ? collections : phases).push(entry);
|
||||
});
|
||||
observer.observe({ entryTypes: ['gc', 'measure'] });
|
||||
const h = denseContinentalRendering();
|
||||
const runs = [];
|
||||
try {
|
||||
for (let i = 0; i < 65; i++) {
|
||||
const start = performance.now();
|
||||
assert.equal(h.moveEnd((i % 4) * 3), 'pending');
|
||||
const enqueueMs = performance.now() - start;
|
||||
const result = h.flush();
|
||||
runs.push({
|
||||
startTimeMs: start,
|
||||
endTimeMs: performance.now(),
|
||||
enqueueMs,
|
||||
...result,
|
||||
});
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
}
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (const entry of observer.takeRecords())
|
||||
(entry.entryType === 'gc' ? collections : phases).push(entry);
|
||||
const warm = runs.slice(25);
|
||||
const allSlices = runs.flatMap((run) => run.slices);
|
||||
const warmSlices = warm.flatMap((run) => run.slices);
|
||||
const activeSlices = allSlices.map((slice) =>
|
||||
activeMs(slice, collections),
|
||||
);
|
||||
const warmTotal = warm.map((run) =>
|
||||
run.slices.reduce(
|
||||
(sum, slice) => sum + activeMs(slice, collections),
|
||||
run.enqueueMs,
|
||||
),
|
||||
);
|
||||
const enqueueMax = Math.max(...runs.map((run) => run.enqueueMs));
|
||||
const coldMax = Math.max(
|
||||
...runs[0].slices.map((slice) => activeMs(slice, collections)),
|
||||
);
|
||||
const sliceMax = Math.max(...activeSlices);
|
||||
if (sliceMax > WILDLIFE_MOVE_END_BUDGET_MS) {
|
||||
const slow = allSlices[activeSlices.indexOf(sliceMax)];
|
||||
const entries = phases
|
||||
.filter(
|
||||
(entry) =>
|
||||
entry.entryType === 'measure' &&
|
||||
entry.name !== 'wildlife-sightings:moveEnd:slice' &&
|
||||
entry.startTime >= slow.startTimeMs &&
|
||||
entry.startTime < slow.startTimeMs + slow.durationMs,
|
||||
)
|
||||
.map((entry) => ({
|
||||
phase: entry.name,
|
||||
durationMs: entry.duration,
|
||||
activeMs: activeMs(
|
||||
{ startTimeMs: entry.startTime, durationMs: entry.duration },
|
||||
collections,
|
||||
),
|
||||
}));
|
||||
t.diagnostic(
|
||||
`Slow slice ${JSON.stringify({ slice: slow, phases: entries, gc: collections.map((entry) => ({ start: entry.startTime, duration: entry.duration })), now: performance.now(), uptimeMs: process.uptime() * 1000 })}`,
|
||||
);
|
||||
}
|
||||
assert.ok(
|
||||
enqueueMax <= WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
`moveEnd enqueue ${enqueueMax.toFixed(3)}ms`,
|
||||
);
|
||||
assert.ok(
|
||||
sliceMax <= WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
`longest layer CPU slice ${sliceMax.toFixed(3)}ms exceeds 4ms`,
|
||||
);
|
||||
assert.ok(
|
||||
median(warmTotal) <= WILDLIFE_MOVE_END_BUDGET_MS,
|
||||
`median full moveEnd CPU ${median(warmTotal).toFixed(3)}ms exceeds 4ms`,
|
||||
);
|
||||
assert.equal(warm.at(-1).cartesianBuilds, 0);
|
||||
const phaseMeans = Object.fromEntries(
|
||||
[
|
||||
'density',
|
||||
'bucket',
|
||||
'rank',
|
||||
'billboard-update',
|
||||
'overlay-publish',
|
||||
].map((name) => {
|
||||
const duration = phases
|
||||
.filter(
|
||||
(entry) =>
|
||||
entry.name === `wildlife-sightings:${name}` &&
|
||||
entry.startTime >= warm[0].startTimeMs,
|
||||
)
|
||||
.reduce(
|
||||
(sum, entry) =>
|
||||
sum +
|
||||
activeMs(
|
||||
{
|
||||
startTimeMs: entry.startTime,
|
||||
durationMs: entry.duration,
|
||||
},
|
||||
collections,
|
||||
),
|
||||
0,
|
||||
);
|
||||
return [name, (duration / warm.length).toFixed(3)];
|
||||
}),
|
||||
);
|
||||
t.diagnostic(
|
||||
`6,144 cells + 500 observations, ${runs.at(-1).glowPrimitives} glow splats + ${runs.at(-1).billboards} real icons; moveEnd enqueue max=${enqueueMax.toFixed(3)}ms; cold max CPU slice=${coldMax.toFixed(3)}ms; all max CPU slice=${sliceMax.toFixed(3)}ms; warm total CPU median=${median(warmTotal).toFixed(3)}ms; warm slice p95=${percentile95(warmSlices.map((slice) => activeMs(slice, collections))).toFixed(3)}ms; raw wall slice max=${Math.max(...allSlices.map((slice) => slice.durationMs)).toFixed(3)}ms; observed GC pauses=${collections.length}; repeated Cartesian builds=0; CPU startup calibration=${runtimeSettleMs.toFixed(0)}ms, checksum=${calibrationChecksum} (cold fixture created afterward); warm phase mean ms=${JSON.stringify(phaseMeans)}`,
|
||||
);
|
||||
} finally {
|
||||
h.destroy();
|
||||
observer.disconnect();
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,177 @@
|
||||
import { fromDegrees } from '../../geo/ellipsoid.js';
|
||||
import { createRendering } from './rendering.js';
|
||||
import { bindWildlifeViewer } from '../../testSupport/wildlifeViewer.mjs';
|
||||
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 ECEF anchors and badges on a
|
||||
* fake draw port. Only the renderer 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 scene = { canvas: { clientWidth: 1440, clientHeight: 900 } };
|
||||
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: [],
|
||||
cellSets: 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(),
|
||||
};
|
||||
bindWildlifeViewer(state.viewer);
|
||||
// The local east and north axes at 42 N, 90 W.
|
||||
const lon = (-90 * Math.PI) / 180;
|
||||
const lat = (42 * Math.PI) / 180;
|
||||
const east = { x: -Math.sin(lon), y: Math.cos(lon), z: 0 };
|
||||
const north = {
|
||||
x: -Math.sin(lat) * Math.cos(lon),
|
||||
y: -Math.sin(lat) * Math.sin(lon),
|
||||
z: Math.cos(lat),
|
||||
};
|
||||
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);
|
||||
},
|
||||
fromDegrees(...args) {
|
||||
metrics.cartesianBuilds++;
|
||||
return fromDegrees(...args);
|
||||
},
|
||||
project(_scene, anchor) {
|
||||
metrics.projections++;
|
||||
return {
|
||||
x:
|
||||
720 +
|
||||
(anchor.x * east.x + anchor.y * east.y + anchor.z * east.z) / 8000 +
|
||||
pan,
|
||||
y:
|
||||
450 -
|
||||
(anchor.x * north.x + anchor.y * north.y + anchor.z * north.z) / 8000,
|
||||
};
|
||||
},
|
||||
occluderFactory: () => ({ isPointVisible: () => true }),
|
||||
badgeSprites: {
|
||||
get: (group) => `data:image/svg+xml,${group}`,
|
||||
subscribe: () => () => {},
|
||||
},
|
||||
render: { governorRequestRender() {} },
|
||||
overlayHost: {
|
||||
setEntries() {
|
||||
metrics.publications++;
|
||||
},
|
||||
},
|
||||
performanceOperations: onOperations,
|
||||
};
|
||||
parts.rendering = createRendering({ state, services, parts });
|
||||
parts.photos = { get: () => null, setAmbient() {} };
|
||||
parts.selection = createSelection({ state, services, parts });
|
||||
parts.rendering.init();
|
||||
return {
|
||||
state,
|
||||
metrics,
|
||||
moveEnd(offset = 0) {
|
||||
pan = offset;
|
||||
metrics.projections = metrics.publications = metrics.cartesianBuilds = 0;
|
||||
slices.length = 0;
|
||||
const result = parts.rendering.rebuild();
|
||||
if (result !== 'pending') {
|
||||
parts.selection.refreshAmbient();
|
||||
parts.selection.publishSelected();
|
||||
parts.selection.refreshContexts();
|
||||
}
|
||||
return result;
|
||||
},
|
||||
flush(maxSlices = Infinity) {
|
||||
let count = 0;
|
||||
while (idle.size && count++ < maxSlices) {
|
||||
const [id, fn] = idle.entries().next().value;
|
||||
idle.delete(id);
|
||||
const threadStart = process.threadCpuUsage();
|
||||
fn({ timeRemaining: () => 8, didTimeout: false });
|
||||
const threadUsed = process.threadCpuUsage(threadStart);
|
||||
if (slices.length)
|
||||
slices.at(-1).threadCpuMs =
|
||||
(threadUsed.user + threadUsed.system) / 1000;
|
||||
}
|
||||
return {
|
||||
...metrics,
|
||||
billboards: state.renderedRows.length,
|
||||
glowPrimitives: parts.rendering.density?.size ?? 0,
|
||||
slices: [...slices],
|
||||
};
|
||||
},
|
||||
destroy() {
|
||||
parts.rendering.destroy();
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,616 @@
|
||||
import { wildlifeAccent } from './cards.js';
|
||||
import {
|
||||
wildlifeIconModelWork,
|
||||
wildlifeIconRelevance,
|
||||
compareWildlifeIds,
|
||||
} from './model.js';
|
||||
import { createWildlifeBillboardModel } from './billboardModel.js';
|
||||
import { createWildlifeDensity } from './density.js';
|
||||
import { createWildlifeIconCollection } from './iconCollection.js';
|
||||
import { fromDegrees } from '../../geo/ellipsoid.js';
|
||||
import { cssColor } from '../../render/color.js';
|
||||
import {
|
||||
canvasOf,
|
||||
drawOf,
|
||||
findCamera,
|
||||
findGlobe,
|
||||
} from '../../render/rendererOf.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_SPRITE_PX,
|
||||
} from './policy.js';
|
||||
|
||||
/** Live layer instances, for set ids unique among a renderer's sets. */
|
||||
let instances = 0;
|
||||
|
||||
/** A rebuilt anchor that lands where the old one was. */
|
||||
function sameAnchor(a, b) {
|
||||
return !!a && !!b && a.x === b.x && a.y === b.y && a.z === b.z;
|
||||
}
|
||||
|
||||
/** Own sighting billboards, density glow and batched privacy cells. */
|
||||
export function createRendering({ state, services, parts }) {
|
||||
const spriteDrawOrder =
|
||||
services.sprites?.spriteDrawOrder?.('wildlife-sightings') ?? 0;
|
||||
const badgeSprites = services.badgeSprites ?? wildlifeSpriteCache();
|
||||
// How anchors are built from degrees (a test may count the builds).
|
||||
const anchorAt = services.fromDegrees ?? fromDegrees;
|
||||
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 = anchorAt(row.lon, row.lat);
|
||||
surfaceAnchors.set(row, { lat: row.lat, lon: row.lon, anchor });
|
||||
if (operations) operations.positionBuilds++;
|
||||
return anchor;
|
||||
}
|
||||
const requestRender = (reason) => {
|
||||
// Every write is followed by a render request: send the sets what was
|
||||
// written before the frame is asked for.
|
||||
state.points?.flush();
|
||||
density?.flush();
|
||||
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 = [];
|
||||
|
||||
// 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
|
||||
? anchorAt(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 eye = state.viewer ? findCamera(state.viewer)?.pose().position : null;
|
||||
return eye ? services.occluderFactory?.(eye) : 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 (sameAnchor(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 deactivate() {
|
||||
workQueue.cancel();
|
||||
operations = null;
|
||||
for (const remove of surfaceRemovers.splice(0)) remove?.();
|
||||
}
|
||||
|
||||
function activate() {
|
||||
deactivate();
|
||||
if (!state.enabled || !state.viewer) return;
|
||||
const refreshBadgeImages = () => {
|
||||
if (!state.enabled) return;
|
||||
appearances.clear();
|
||||
if (billboards?.refreshImages((group) => badgeSprites.get(group)))
|
||||
requestRender('font-ready');
|
||||
};
|
||||
surfaceRemovers.push(badgeSprites.subscribe(refreshBadgeImages));
|
||||
refreshBadgeImages();
|
||||
// Anchors follow the ground: resample once terrain or the base tiles in
|
||||
// view finish loading, and when what heights answer against changes
|
||||
// (terrain, the shown tilesets).
|
||||
const globe = findGlobe(state.viewer);
|
||||
let surface = globe?.surfaceVersion?.();
|
||||
// Loaded until the port says otherwise.
|
||||
let pending = { tilesPending: 0, terrainPending: 0 };
|
||||
const off = globe?.on?.('progress', (progress) => {
|
||||
const version = globe.surfaceVersion?.();
|
||||
const surfaceChanged = version !== surface;
|
||||
surface = version;
|
||||
const loaded =
|
||||
(progress.terrainPending === 0 && pending.terrainPending !== 0) ||
|
||||
(progress.tilesPending === 0 && pending.tilesPending !== 0);
|
||||
pending = progress;
|
||||
if (surfaceChanged || loaded) resampleAnchors();
|
||||
});
|
||||
if (typeof off === 'function') surfaceRemovers.push(off);
|
||||
services.eventTarget?.addEventListener?.(
|
||||
'gev:map-stack-changed',
|
||||
resampleAnchors,
|
||||
);
|
||||
surfaceRemovers.push(() =>
|
||||
services.eventTarget?.removeEventListener?.(
|
||||
'gev:map-stack-changed',
|
||||
resampleAnchors,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
function clearCells() {
|
||||
state.cells = [];
|
||||
cellsSignature = null;
|
||||
if (!state.cellSets) return;
|
||||
state.cellSets.fills.clear();
|
||||
state.cellSets.outlines.clear();
|
||||
}
|
||||
|
||||
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;
|
||||
if (!unique.size) {
|
||||
clearCells();
|
||||
cellsSignature = signature;
|
||||
return true;
|
||||
}
|
||||
cellsSignature = signature;
|
||||
const fills = [];
|
||||
const outlines = [];
|
||||
let index = 0;
|
||||
for (const row of unique.values()) {
|
||||
const { south, west, north, east } = row.cell;
|
||||
const tint = cssColor(wildlifeAccent(row.iconic)) ?? [1, 1, 1, 1];
|
||||
const id = `cell:${index++}`;
|
||||
fills.push({
|
||||
id,
|
||||
geometry: { kind: 'rectangle', rect: { west, south, east, north } },
|
||||
fill: [tint[0], tint[1], tint[2], 0.25],
|
||||
height: 'clampGround',
|
||||
pickable: false,
|
||||
});
|
||||
outlines.push({
|
||||
id,
|
||||
positions: [
|
||||
[west, south],
|
||||
[east, south],
|
||||
[east, north],
|
||||
[west, north],
|
||||
[west, south],
|
||||
].map(([lon, lat]) => fromDegrees(lon, lat)),
|
||||
widthPx: 2,
|
||||
mode: 'draped',
|
||||
style: { kind: 'solid', color: [tint[0], tint[1], tint[2], 0.8] },
|
||||
pickable: false,
|
||||
});
|
||||
}
|
||||
// Each set swaps its whole contents at once, so the previous privacy
|
||||
// cells go as the new ones arrive.
|
||||
state.cellSets.fills.set(fills);
|
||||
state.cellSets.outlines.set(outlines);
|
||||
state.cells = fills;
|
||||
requestRender('render');
|
||||
return true;
|
||||
}
|
||||
|
||||
function init() {
|
||||
density = createWildlifeDensity({
|
||||
viewer: state.viewer,
|
||||
positionForCell: surfaceAnchor,
|
||||
requestRender,
|
||||
setTimer: services.setTimer,
|
||||
clearTimer: services.clearTimer,
|
||||
requestIdle: services.requestIdleCallback,
|
||||
cancelIdle: services.cancelIdleCallback,
|
||||
eventTarget: services.eventTarget,
|
||||
});
|
||||
const draw = drawOf(state.viewer);
|
||||
const prefix = `wildlife-sightings:${++instances}`;
|
||||
state.cellSets = {
|
||||
fills: draw.shapes({ id: `${prefix}:cells`, clampTo: 'both' }),
|
||||
outlines: draw.lines({ id: `${prefix}:cell-outlines`, clampTo: 'both' }),
|
||||
};
|
||||
state.points = createWildlifeIconCollection(
|
||||
draw.icons({ id: `${prefix}:badges`, drawOrder: spriteDrawOrder }),
|
||||
);
|
||||
state.points.show = false;
|
||||
const [near, nearValue, far, farValue] = WILDLIFE_SCALE_BY_DISTANCE;
|
||||
const distanceScale = { near, nearValue, far, farValue };
|
||||
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),
|
||||
size: [WILDLIFE_SPRITE_PX, WILDLIFE_SPRITE_PX],
|
||||
// The sprite includes its tint and white glyph. Multiplication
|
||||
// by a taxon colour would tint the glyph as well.
|
||||
color: [1, 1, 1, 1],
|
||||
scale: 1,
|
||||
scaleByDistance: distanceScale,
|
||||
disableDepthTest: 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 canvas = canvasOf(state.viewer);
|
||||
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),
|
||||
},
|
||||
);
|
||||
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(state.viewer, anchor);
|
||||
if (
|
||||
!screen ||
|
||||
screen.x < 0 ||
|
||||
screen.y < 0 ||
|
||||
screen.x >= (canvas?.clientWidth ?? Infinity) ||
|
||||
screen.y >= (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();
|
||||
state.points?.dispose();
|
||||
state.points = null;
|
||||
state.cellSets?.fills.dispose();
|
||||
state.cellSets?.outlines.dispose();
|
||||
state.cellSets = 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,524 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { createRendering } from './rendering.js';
|
||||
import { nearFarScalarValueAtDistance } from '../../data/focusDeemphasis.js';
|
||||
import { wildlifeGridCellId } from './gridViewport.js';
|
||||
import { bindWildlifeViewer } from '../../testSupport/wildlifeViewer.mjs';
|
||||
import { fromDegrees, toLonLatH } from '../../geo/ellipsoid.js';
|
||||
import { 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 = {}) {
|
||||
// Counts read after the badges' batched writes reach their set.
|
||||
const tally = { created: 0, removed: 0, cleared: 0, writes: [] };
|
||||
const flushed = (key) => () => {
|
||||
state.points?.flush();
|
||||
return tally[key];
|
||||
};
|
||||
const counts = {
|
||||
collections: 0,
|
||||
get created() {
|
||||
return flushed('created')();
|
||||
},
|
||||
get removed() {
|
||||
return flushed('removed')();
|
||||
},
|
||||
get cleared() {
|
||||
return flushed('cleared')();
|
||||
},
|
||||
get writes() {
|
||||
return flushed('writes')();
|
||||
},
|
||||
};
|
||||
// What a badge's item changes, by the billboard property names it had.
|
||||
const tracked = {
|
||||
pos: 'position',
|
||||
image: 'image',
|
||||
color: 'color',
|
||||
scale: 'scale',
|
||||
show: 'show',
|
||||
size: 'width',
|
||||
scaleByDistance: 'scaleByDistance',
|
||||
};
|
||||
const postRender = event();
|
||||
const terrain = event();
|
||||
const tileProgress = event();
|
||||
const scene = {
|
||||
postRender,
|
||||
globe: {
|
||||
terrainProviderChanged: terrain,
|
||||
tileLoadProgressEvent: tileProgress,
|
||||
},
|
||||
};
|
||||
const viewer = {
|
||||
scene,
|
||||
camera: { positionWC: {}, positionCartographic: { height: 0 } },
|
||||
};
|
||||
const ports = bindWildlifeViewer(viewer);
|
||||
// Count the badges set's item writes as billboard writes were counted.
|
||||
const icons = ports.draw.icons;
|
||||
ports.draw.icons = (spec) => {
|
||||
const set = icons(spec);
|
||||
if (!spec.id.endsWith(':badges')) return set;
|
||||
counts.collections += 1;
|
||||
const record = ports.draw.sets.get(spec.id);
|
||||
const upsert = set.upsert;
|
||||
set.upsert = (items) => {
|
||||
for (const item of items) {
|
||||
const old = record.items.get(item.id);
|
||||
if (!old) {
|
||||
tally.created += 1;
|
||||
continue;
|
||||
}
|
||||
for (const [key, name] of Object.entries(tracked))
|
||||
if (JSON.stringify(old[key]) !== JSON.stringify(item[key]))
|
||||
tally.writes.push(name);
|
||||
}
|
||||
upsert(items);
|
||||
};
|
||||
const remove = set.remove;
|
||||
set.remove = (ids) => {
|
||||
tally.removed += ids.length;
|
||||
remove(ids);
|
||||
};
|
||||
const clear = set.clear;
|
||||
set.clear = () => {
|
||||
tally.cleared += 1;
|
||||
clear();
|
||||
};
|
||||
return set;
|
||||
};
|
||||
const state = {
|
||||
enabled: true,
|
||||
viewer,
|
||||
rows: new Map(rows.map((row) => [row.stableId, row])),
|
||||
renderedRows: [],
|
||||
rowById: new Map(),
|
||||
pointById: new Map(),
|
||||
positions: new Map(),
|
||||
cells: [],
|
||||
cellSets: null,
|
||||
taxa: 'all',
|
||||
selectedId: null,
|
||||
query: { visibleBoxes: [{ south: -90, west: -180, north: 90, east: 180 }] },
|
||||
band: 'cards',
|
||||
};
|
||||
const renders = [];
|
||||
let visible = true;
|
||||
const rendering = createRendering({
|
||||
state,
|
||||
services: {
|
||||
now: () => NOW,
|
||||
occluderFactory: () => ({ isPointVisible: () => visible }),
|
||||
render: { governorRequestRender: (reason) => renders.push(reason) },
|
||||
sprites: { spriteDrawOrder: () => -9 },
|
||||
...extra,
|
||||
},
|
||||
parts: {
|
||||
selection: {
|
||||
clear() {
|
||||
state.selectedId = null;
|
||||
},
|
||||
refreshAmbient() {},
|
||||
publishSelected() {},
|
||||
refreshContexts() {},
|
||||
},
|
||||
},
|
||||
});
|
||||
rendering.init();
|
||||
rendering.activate();
|
||||
return {
|
||||
state,
|
||||
scene,
|
||||
ports,
|
||||
sets: () => ports.sets(),
|
||||
rendering,
|
||||
counts,
|
||||
renders,
|
||||
postRender,
|
||||
terrain,
|
||||
tileProgress,
|
||||
visible(value) {
|
||||
visible = value;
|
||||
},
|
||||
rows(next) {
|
||||
state.rows = new Map(next.map((row) => [row.stableId, row]));
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('badge 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.size[0] * incumbent.scaleByDistance.farValue, 12);
|
||||
const [near, nearValue, far, farValue] = WILDLIFE_SCALE_BY_DISTANCE;
|
||||
assert.deepEqual(incumbent.scaleByDistance, {
|
||||
near,
|
||||
nearValue,
|
||||
far,
|
||||
farValue,
|
||||
});
|
||||
assert.equal(incumbent.color[3], 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.deepEqual(Object.values(h.sets()).filter(Boolean), []);
|
||||
assert.equal(h.ports.progressListeners(), 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.size[0] *
|
||||
wildlife.scale *
|
||||
nearFarScalarValueAtDistance(wildlife.scaleByDistance, heightM);
|
||||
assert.ok(
|
||||
pixels >= 12 && pixels <= 22,
|
||||
`${heightM}m, selected=${!!selectedId}: ${pixels}px`,
|
||||
);
|
||||
}
|
||||
}
|
||||
assert.deepEqual(
|
||||
wildlife.color,
|
||||
[1, 1, 1, 1],
|
||||
'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 = toLonLatH(anchor).lon;
|
||||
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 = toLonLatH(anchor).lon;
|
||||
return screens.get(lon.toFixed(6));
|
||||
},
|
||||
});
|
||||
h.state.viewer.camera.positionWC = fromDegrees(base.lon, base.lat, heightM);
|
||||
h.state.viewer.camera.positionCartographic = { height: 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();
|
||||
h.rendering.density.flush();
|
||||
const glow = h.sets().glow;
|
||||
assert.ok(glow);
|
||||
assert.equal(glow.spec.pickable, false);
|
||||
assert.equal(glow.items.size, 3);
|
||||
assert.ok(h.sets().badges);
|
||||
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.sets().glow, glow);
|
||||
assert.deepEqual(h.counts.writes, []);
|
||||
h.rendering.clear();
|
||||
assert.equal(glow.disposed, true);
|
||||
assert.ok(h.sets().badges);
|
||||
assert.equal(h.state.points.length, 0);
|
||||
h.rendering.destroy();
|
||||
assert.equal(h.sets().badges, undefined);
|
||||
});
|
||||
|
||||
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();
|
||||
h.rendering.density.flush();
|
||||
const glow = h.sets().glow;
|
||||
assert.ok(glow);
|
||||
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.disposed, 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 cells draw as ground fills and outlines with no frame listener, and teardown disposes them', () => {
|
||||
const h = harness([
|
||||
{
|
||||
...base,
|
||||
obscured: true,
|
||||
cell: { south: 47.6, west: -122.4, north: 47.8, east: -122.2 },
|
||||
},
|
||||
]);
|
||||
h.rendering.rebuild();
|
||||
const { cells, outlines } = h.sets();
|
||||
assert.equal(cells.items.size, 1);
|
||||
assert.equal(outlines.items.size, 1);
|
||||
assert.equal(cells.spec.clampTo, 'both');
|
||||
assert.equal(outlines.spec.clampTo, 'both');
|
||||
assert.equal(h.postRender.size, 0);
|
||||
h.rendering.destroy();
|
||||
assert.equal(cells.disposed, true);
|
||||
assert.equal(outlines.disposed, true);
|
||||
assert.equal(h.postRender.size, 0);
|
||||
});
|
||||
|
||||
test('font readiness swaps images in place without billboard recreation or position work', () => {
|
||||
const listeners = new Set();
|
||||
let ready = false;
|
||||
const badgeSprites = {
|
||||
get: (group) =>
|
||||
`data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg"><circle r="${ready ? 9 : 8}" data-group="${group}"/></svg>`)}`,
|
||||
subscribe(fn) {
|
||||
listeners.add(fn);
|
||||
return () => listeners.delete(fn);
|
||||
},
|
||||
};
|
||||
const rows = [
|
||||
base,
|
||||
{ ...base, stableId: 'synthetic:mammal', iconic: 'Mammalia', lon: -120 },
|
||||
];
|
||||
const h = harness(rows, { badgeSprites });
|
||||
h.rendering.rebuild();
|
||||
const collection = h.state.points;
|
||||
const points = new Map(h.state.pointById);
|
||||
const before = new Map([...points].map(([id, point]) => [id, point.image]));
|
||||
h.counts.writes.length = 0;
|
||||
h.renders.length = 0;
|
||||
ready = true;
|
||||
for (const listener of listeners) listener();
|
||||
assert.equal(h.state.points, collection);
|
||||
assert.equal(h.counts.created, 2);
|
||||
assert.equal(h.counts.removed, 0);
|
||||
assert.equal(h.counts.cleared, 0);
|
||||
assert.deepEqual(h.counts.writes, ['image', 'image']);
|
||||
assert.equal(h.renders.length, 1);
|
||||
for (const [id, point] of points) {
|
||||
assert.equal(h.state.pointById.get(id), point);
|
||||
assert.notEqual(point.image, before.get(id));
|
||||
}
|
||||
h.counts.writes.length = 0;
|
||||
h.rows(rows.map((row) => ({ ...row, lat: row.lat + 0.01 })));
|
||||
h.rendering.rebuild();
|
||||
assert.deepEqual(h.counts.writes, ['position', 'position']);
|
||||
h.rendering.destroy();
|
||||
assert.equal(listeners.size, 0);
|
||||
});
|
||||
@@ -0,0 +1,564 @@
|
||||
import { t } from '../../i18n/index.js';
|
||||
import { wildlifeMeasure } from './performance.js';
|
||||
import { compareWildlifeIds } from './model.js';
|
||||
import { isRecentWildlifeSighting } from './records.js';
|
||||
import { canvasOf } from '../../render/rendererOf.js';
|
||||
import { wildlifeEyeHeight } from './view.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 &&
|
||||
(wildlifeEyeHeight(state.viewer) ?? 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 canvas = canvasOf(state.viewer);
|
||||
const horizon = parts.rendering.occluder();
|
||||
const width = canvas?.clientWidth || 0;
|
||||
const height = 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(state.viewer, 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 canvas = canvasOf(state.viewer);
|
||||
const horizon = parts.rendering.occluder();
|
||||
const width = canvas?.clientWidth ?? Infinity;
|
||||
const height = 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(state.viewer, 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 = wildlifeEyeHeight(state.viewer) ?? Infinity;
|
||||
if (height >= WILDLIFE_CARD_HIDE_MAX_METERS) return [];
|
||||
return ambientCandidates(state.ambientRows).eligible;
|
||||
}
|
||||
|
||||
function refreshAmbient() {
|
||||
if (!state.enabled) return;
|
||||
refreshLabels();
|
||||
const height = wildlifeEyeHeight(state.viewer) ?? 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,
|
||||
);
|
||||
// A viewer with no renderer input bound takes no clicks.
|
||||
let input = null;
|
||||
try {
|
||||
input = services.input?.(state.viewer) ?? null;
|
||||
} catch {
|
||||
input = null;
|
||||
}
|
||||
if (!input) return;
|
||||
state.clickHandler = input.onClick((click) => {
|
||||
if (!state.enabled || services.pointer?.isPointerFree?.() === false)
|
||||
return;
|
||||
const at = click.screenPosition;
|
||||
const hit =
|
||||
overlay?.hitTest?.(at?.x, at?.y, {
|
||||
sourceId: WILDLIFE_SELECTED_SOURCE_ID,
|
||||
}) ||
|
||||
overlay?.hitTest?.(at?.x, at?.y, {
|
||||
sourceId: WILDLIFE_OVERLAY_SOURCE_ID,
|
||||
}) ||
|
||||
overlay?.hitTest?.(at?.x, at?.y, {
|
||||
sourceId: WILDLIFE_LABEL_SOURCE_ID,
|
||||
});
|
||||
if (hit) {
|
||||
hit.entry?.activate?.();
|
||||
return;
|
||||
}
|
||||
// A sighting icon's item id is its pick id, `wildlife:<stableId>`.
|
||||
const id = click.id;
|
||||
if (
|
||||
typeof id === 'string' &&
|
||||
id.startsWith('wildlife:') &&
|
||||
selectAndFocus(id.slice(9))
|
||||
)
|
||||
return;
|
||||
if (
|
||||
id &&
|
||||
services.picking?.isOwnedByOtherLayer?.('wildlife-sightings', id)
|
||||
)
|
||||
return;
|
||||
clearAndRebuild();
|
||||
});
|
||||
}
|
||||
|
||||
function remove() {
|
||||
state.clickHandler?.();
|
||||
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,300 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import test from 'node:test';
|
||||
import { createSelection } from './selection.js';
|
||||
import { bindWildlifeViewer } from '../../testSupport/wildlifeViewer.mjs';
|
||||
|
||||
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 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: { canvas: { clientWidth: 1200, clientHeight: 900 } },
|
||||
camera: { positionCartographic: { height: 30_000 } },
|
||||
},
|
||||
};
|
||||
bindWildlifeViewer(state.viewer);
|
||||
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) },
|
||||
input: () => ({
|
||||
onClick(fn) {
|
||||
click = fn;
|
||||
return () => (click = null);
|
||||
},
|
||||
}),
|
||||
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}`) {
|
||||
// The input dispatcher hands the pick's registry-resolved id.
|
||||
click({ screenPosition: { x: 10, y: 20 }, id: id ?? undefined });
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
test('a real sighting click pins its row, opens its label and focuses its true position', () => {
|
||||
const f = fixture();
|
||||
f.selection.install();
|
||||
f.click();
|
||||
assert.equal(f.state.selectedId, row.stableId);
|
||||
assert.equal(f.state.selectedRow, row);
|
||||
assert.equal(f.flights.length, 1);
|
||||
assert.deepEqual(f.flights[0], {
|
||||
kind: 'sighting',
|
||||
id: row.stableId,
|
||||
label: row.commonName,
|
||||
position: f.position,
|
||||
});
|
||||
assert.deepEqual(f.seen.at(-1), {
|
||||
value: row,
|
||||
metadata: { explicitSelection: true },
|
||||
});
|
||||
assert.equal(f.entries.get('wildlife-sightings-selected').length, 1);
|
||||
f.selection.remove();
|
||||
});
|
||||
|
||||
test('selected photo and name cards use the selected lane, select on click and never open links themselves', () => {
|
||||
for (const photo of [
|
||||
null,
|
||||
{
|
||||
square:
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpg',
|
||||
licence: 'cc-by',
|
||||
attribution: 'Synthetic Photographer',
|
||||
},
|
||||
]) {
|
||||
const sighting = { ...row, photo };
|
||||
const f = fixture(sighting);
|
||||
f.selection.install();
|
||||
f.selection.refreshAmbient();
|
||||
const source = photo ? 'wildlife-sightings' : 'wildlife-sightings-labels';
|
||||
const id = photo
|
||||
? 'sighting:inat:123'
|
||||
: 'wildlife-sightings-label:inat:123';
|
||||
f.hit(source, id);
|
||||
f.click();
|
||||
assert.equal(f.flights.length, 1);
|
||||
if (photo) f.paint([row.stableId]);
|
||||
const selectedSource = photo ? source : 'wildlife-sightings-selected';
|
||||
const card = f.entries.get(selectedSource)[0];
|
||||
assert.equal(card.selected, true);
|
||||
assert.equal(card.paintLane, 'selected');
|
||||
assert.ok(
|
||||
!(card.details || []).some((line) => line.includes('↗')),
|
||||
'the anchored photo card owns the single source link',
|
||||
);
|
||||
assert.match(card.accessibilityLabel, /Synthetic bird/);
|
||||
if (photo) {
|
||||
assert.equal(card.variant, 'thumbnail');
|
||||
assert.ok(card.image);
|
||||
assert.deepEqual(f.entries.get('wildlife-sightings-selected'), []);
|
||||
}
|
||||
f.hit(selectedSource, card.id);
|
||||
f.click('other:aircraft');
|
||||
assert.equal(f.flights.length, photo ? 2 : 1);
|
||||
f.selection.clearAndRebuild();
|
||||
if (photo) {
|
||||
const ambient = f.entries.get(source)[0];
|
||||
assert.equal(ambient.selected, undefined);
|
||||
assert.deepEqual(ambient.details, ['© Synthetic Photographer']);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test('nearby duplicate display names yield to painted cards and higher-ranked labels using cached screens', () => {
|
||||
const low = {
|
||||
...row,
|
||||
stableId: 'inat:low',
|
||||
quality: 'research',
|
||||
photo: {
|
||||
square:
|
||||
'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpg',
|
||||
licence: 'cc-by',
|
||||
attribution: 'Synthetic Photographer',
|
||||
},
|
||||
};
|
||||
const high = { ...low, stableId: 'inat:high', favesCount: 50 };
|
||||
const far = { ...row, stableId: 'inat:far' };
|
||||
const different = {
|
||||
...row,
|
||||
stableId: 'inat:different',
|
||||
commonName: 'Other bird',
|
||||
};
|
||||
const f = fixture();
|
||||
f.state.renderedRows = [low, high, far, different];
|
||||
f.state.rowById = new Map(
|
||||
f.state.renderedRows.map((row) => [row.stableId, row]),
|
||||
);
|
||||
f.state.positions = new Map([
|
||||
[low.stableId, { x: 300, y: 300 }],
|
||||
[high.stableId, { x: 379, y: 300 }],
|
||||
[far.stableId, { x: 460, y: 300 }],
|
||||
[different.stableId, { x: 310, y: 300 }],
|
||||
]);
|
||||
const labelIds = () =>
|
||||
f.entries.get('wildlife-sightings-labels').map((entry) => entry.id);
|
||||
f.selection.refreshAmbient();
|
||||
assert.ok(!labelIds().includes('wildlife-sightings-label:inat:low'));
|
||||
assert.ok(labelIds().includes('wildlife-sightings-label:inat:high'));
|
||||
assert.ok(
|
||||
labelIds().includes('wildlife-sightings-label:inat:far'),
|
||||
'81px names survive',
|
||||
);
|
||||
assert.ok(labelIds().includes('wildlife-sightings-label:inat:different'));
|
||||
const projections = f.projections;
|
||||
f.state.ambientRows = [low];
|
||||
f.paint([low.stableId]);
|
||||
assert.ok(
|
||||
!labelIds().includes('wildlife-sightings-label:inat:high'),
|
||||
'a painted lower-score card wins',
|
||||
);
|
||||
assert.equal(
|
||||
f.projections,
|
||||
projections,
|
||||
'paint membership uses the last label pass',
|
||||
);
|
||||
f.paint([]);
|
||||
assert.ok(
|
||||
labelIds().includes('wildlife-sightings-label:inat:high'),
|
||||
'a queued/unpainted card suppresses nothing',
|
||||
);
|
||||
f.selection.selectAndFocus(low.stableId);
|
||||
assert.ok(
|
||||
!labelIds().includes('wildlife-sightings-label:inat:high'),
|
||||
'selected labels outrank ambient names',
|
||||
);
|
||||
assert.equal(
|
||||
f.projections,
|
||||
projections,
|
||||
'selection never projects the population',
|
||||
);
|
||||
f.selection.clearAndRebuild();
|
||||
f.state.positions.set(high.stableId, { x: 600, y: 300 });
|
||||
f.selection.refreshAmbient();
|
||||
assert.ok(
|
||||
labelIds().includes('wildlife-sightings-label:inat:low'),
|
||||
'moveEnd admits separated names',
|
||||
);
|
||||
});
|
||||
|
||||
test('selection remains published while a new sample or camera pass replaces rendered lookup rows', () => {
|
||||
const f = fixture();
|
||||
f.selection.selectAndFocus(row.stableId);
|
||||
f.state.rowById.clear();
|
||||
f.state.renderedRows = [];
|
||||
f.selection.publishSelected();
|
||||
f.selection.notify();
|
||||
assert.equal(f.seen.at(-1).value, row);
|
||||
assert.equal(
|
||||
f.entries.get('wildlife-sightings-selected')[0].position,
|
||||
f.position,
|
||||
);
|
||||
assert.equal(
|
||||
f.flights.length,
|
||||
1,
|
||||
'refresh notifications never start another flight',
|
||||
);
|
||||
f.selection.clearAndRebuild();
|
||||
assert.equal(f.state.selectedId, null);
|
||||
assert.equal(f.state.selectedRow, null);
|
||||
assert.equal(f.seen.at(-1).value, null);
|
||||
assert.deepEqual(f.entries.get('wildlife-sightings-selected'), []);
|
||||
});
|
||||
|
||||
test('an obscured observation focuses only its existing privacy-safe anchor', () => {
|
||||
const obscured = { ...row, obscured: true, lat: 48.1, lon: 8.3 };
|
||||
const f = fixture(obscured);
|
||||
assert.equal(f.selection.selectAndFocus(obscured.stableId), true);
|
||||
assert.equal(f.flights[0].kind, 'sighting-area');
|
||||
assert.equal(f.flights[0].position, f.position);
|
||||
assert.equal(f.state.selectedRow, obscured);
|
||||
});
|
||||
|
||||
test('empty clicks and layer removal release the selected row and its overlay', () => {
|
||||
const f = fixture();
|
||||
f.selection.install();
|
||||
f.click();
|
||||
f.click(null);
|
||||
assert.equal(f.state.selectedRow, null);
|
||||
assert.equal(f.state.selectedId, null);
|
||||
f.click();
|
||||
f.state.enabled = false;
|
||||
f.selection.remove();
|
||||
assert.equal(f.state.selectedRow, null);
|
||||
assert.equal(f.state.selectedId, null);
|
||||
assert.equal(f.seen.at(-1).value, null);
|
||||
assert.equal(f.entries.size, 0);
|
||||
});
|
||||
@@ -0,0 +1,663 @@
|
||||
import { readResponseJsonCapped } from '../../sources/httpBody.js';
|
||||
import { mergeSightings } from './records.js';
|
||||
import { wildlifeMeasure } from './performance.js';
|
||||
import {
|
||||
ACARTIA_GUARD_BOX,
|
||||
TAXA_PRESETS,
|
||||
WILDLIFE_RETRY_AFTER_MAX_SEC,
|
||||
} from './policy.js';
|
||||
import { boxIntersects, retryDelayMs } from './viewport.js';
|
||||
import {
|
||||
WILDLIFE_GRID_MAX_ZOOM,
|
||||
WILDLIFE_GRID_TILE_CAP,
|
||||
wildlifeGridCellId,
|
||||
} from './gridViewport.js';
|
||||
|
||||
// Leave room for projected observations while bounding malformed proxy replies.
|
||||
const SNAPSHOT_MAX_BYTES = 2 * 1024 * 1024;
|
||||
// The proxy owns upstream pacing; observation requests precede these workers.
|
||||
export const WILDLIFE_GRID_CONCURRENCY = 4;
|
||||
export const WILDLIFE_GRID_CACHE_MAX = 400;
|
||||
export const WILDLIFE_GRID_TTL_MS = 15 * 60_000;
|
||||
// Match the proxy's one-hour stale allowance. Keep the original data time so
|
||||
// repeated refresh failures never extend a tile's usable life.
|
||||
const GRID_STALE_MAX_MS = 3_600_000;
|
||||
const HOUR_MS = 3_600_000;
|
||||
|
||||
function validTile(tile) {
|
||||
return (
|
||||
!!tile &&
|
||||
Number.isInteger(tile.z) &&
|
||||
tile.z >= 0 &&
|
||||
tile.z <= WILDLIFE_GRID_MAX_ZOOM &&
|
||||
Number.isInteger(tile.x) &&
|
||||
Number.isInteger(tile.y) &&
|
||||
tile.x >= 0 &&
|
||||
tile.y >= 0 &&
|
||||
tile.x < 2 ** tile.z &&
|
||||
tile.y < 2 ** tile.z
|
||||
);
|
||||
}
|
||||
|
||||
function validProjectedGrid(payload) {
|
||||
return (
|
||||
Number.isFinite(payload?.fetchedAt) &&
|
||||
Number.isSafeInteger(payload.totalResults) &&
|
||||
payload.totalResults >= 0 &&
|
||||
(payload.stale === undefined || typeof payload.stale === 'boolean') &&
|
||||
Array.isArray(payload.cells) &&
|
||||
payload.cells.length <= 4096 &&
|
||||
payload.cells.every(
|
||||
(cell) =>
|
||||
cell &&
|
||||
Object.keys(cell).sort().join(',') === 'cellCount,id,lat,lon' &&
|
||||
/^grid:\d+\/\d+\/\d+:\d+:\d+$/.test(cell.id) &&
|
||||
Number.isSafeInteger(cell.cellCount) &&
|
||||
cell.cellCount > 0 &&
|
||||
Number.isFinite(cell.lat) &&
|
||||
Math.abs(cell.lat) <= 90 &&
|
||||
Number.isFinite(cell.lon) &&
|
||||
Math.abs(cell.lon) <= 180 &&
|
||||
wildlifeGridCellId(
|
||||
cell.lat,
|
||||
cell.lon,
|
||||
Number(cell.id.split(':')[1].split('/')[0]),
|
||||
) === cell.id,
|
||||
) &&
|
||||
new Set(payload.cells.map((cell) => cell.id)).size ===
|
||||
payload.cells.length &&
|
||||
payload.cells.reduce((sum, cell) => sum + cell.cellCount, 0) ===
|
||||
payload.totalResults
|
||||
);
|
||||
}
|
||||
|
||||
function retryAfterSeconds(value, nowMs) {
|
||||
if (typeof value !== 'string' || !value.trim()) return null;
|
||||
const text = value.trim();
|
||||
if (/^\d+(?:\.\d+)?$/.test(text)) {
|
||||
const seconds = Number(text);
|
||||
return Number.isFinite(seconds)
|
||||
? Math.min(WILDLIFE_RETRY_AFTER_MAX_SEC, Math.ceil(seconds))
|
||||
: null;
|
||||
}
|
||||
// Reject malformed numeric values rather than letting Date.parse interpret
|
||||
// them as calendar dates. HTTP dates include a named weekday or month.
|
||||
if (!/[a-z]/i.test(text)) return null;
|
||||
const deadline = Date.parse(text);
|
||||
return Number.isFinite(deadline) && Number.isFinite(nowMs)
|
||||
? Math.min(
|
||||
WILDLIFE_RETRY_AFTER_MAX_SEC,
|
||||
Math.max(0, Math.ceil((deadline - nowMs) / 1000)),
|
||||
)
|
||||
: null;
|
||||
}
|
||||
|
||||
function validProjectedRows(rows, origin) {
|
||||
return (
|
||||
Array.isArray(rows) &&
|
||||
rows.every(
|
||||
(row) =>
|
||||
row &&
|
||||
typeof row.stableId === 'string' &&
|
||||
row.stableId.startsWith(
|
||||
origin === 'inaturalist' ? 'inat:' : 'acartia:',
|
||||
) &&
|
||||
row.origin === origin &&
|
||||
Number.isFinite(row.lat) &&
|
||||
Math.abs(row.lat) <= 90 &&
|
||||
Number.isFinite(row.lon) &&
|
||||
Math.abs(row.lon) <= 180,
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/** Return the status a failure reports. The proxy marks upstream failures
|
||||
* with X-Upstream-Status; without it the HTTP status is the signal. */
|
||||
function wildlifeFailureStatus(error) {
|
||||
return (
|
||||
error?.upstreamStatus ||
|
||||
error?.status ||
|
||||
Number(/HTTP (\d{3})/.exec(error?.message || '')?.[1]) ||
|
||||
0
|
||||
);
|
||||
}
|
||||
|
||||
/** Whether a failure asks clients to wait before the next request. */
|
||||
export function wildlifeFailureRetryable(error) {
|
||||
const status = wildlifeFailureStatus(error);
|
||||
return status === 429 || status >= 500;
|
||||
}
|
||||
|
||||
/** Return a Retry-After in milliseconds, capped at one day, or null when
|
||||
* it is missing, negative or not finite. */
|
||||
export function wildlifeRetryAfterMs(seconds) {
|
||||
return Number.isFinite(seconds) && seconds >= 0
|
||||
? Math.min(WILDLIFE_RETRY_AFTER_MAX_SEC, seconds) * 1000
|
||||
: null;
|
||||
}
|
||||
|
||||
/** Return how long a failure asks the layer to wait, or null for none:
|
||||
* 429 and 5xx wait for their Retry-After, else the default backoff after
|
||||
* `previousMs`; other failures may retry on the next view. */
|
||||
export function wildlifeFailureDelayMs(error, previousMs = 0) {
|
||||
if (!error || !wildlifeFailureRetryable(error)) return null;
|
||||
return wildlifeRetryAfterMs(error.retryAfterSec) ?? retryDelayMs(previousMs);
|
||||
}
|
||||
|
||||
/** Flatten failures, expanding a group into every request that failed. */
|
||||
export function wildlifeFailures(errors) {
|
||||
return [errors]
|
||||
.flat()
|
||||
.filter(Boolean)
|
||||
.flatMap((error) =>
|
||||
Array.isArray(error.failures) && error.failures.length
|
||||
? error.failures
|
||||
: [error],
|
||||
);
|
||||
}
|
||||
|
||||
/** Return the failure with the longest effective delay (the first failure
|
||||
* when none waits), carrying every failure so the caller can recompute. */
|
||||
export function preferredWildlifeFailure(errors, previousMs = 0) {
|
||||
const failures = wildlifeFailures(errors);
|
||||
if (!failures.length) return null;
|
||||
let chosen = failures[0];
|
||||
let longest = wildlifeFailureDelayMs(chosen, previousMs) ?? -1;
|
||||
for (const error of failures.slice(1)) {
|
||||
const delay = wildlifeFailureDelayMs(error, previousMs) ?? -1;
|
||||
if (delay > longest) [chosen, longest] = [error, delay];
|
||||
}
|
||||
if (failures.length === 1) return chosen;
|
||||
// Grid errors are shared between consumers of one tile request; describe
|
||||
// the group with a new error rather than mutating any of them.
|
||||
return Object.assign(new Error(chosen.message, { cause: chosen }), {
|
||||
...(chosen.status ? { status: chosen.status } : {}),
|
||||
...(chosen.upstreamStatus ? { upstreamStatus: chosen.upstreamStatus } : {}),
|
||||
...(Number.isFinite(chosen.retryAfterSec)
|
||||
? { retryAfterSec: chosen.retryAfterSec }
|
||||
: {}),
|
||||
failures,
|
||||
});
|
||||
}
|
||||
|
||||
/** Merge occupied cells incrementally; neighboring UTFGrid hit tiles can
|
||||
* report the same geographic cell, so source ids remain the dedupe key. */
|
||||
export function combineWildlifeGridSnapshots(snapshots, error = null) {
|
||||
const cells = [
|
||||
...new Map(
|
||||
snapshots
|
||||
.flatMap((snapshot) => snapshot.cells)
|
||||
.map((cell) => [cell.id, cell]),
|
||||
).values(),
|
||||
];
|
||||
const totalResults = cells.reduce((sum, cell) => sum + cell.cellCount, 0);
|
||||
if (!Number.isSafeInteger(totalResults))
|
||||
throw new Error('Malformed iNaturalist grid response');
|
||||
// A failure's Retry-After counts only when its status asks for a wait.
|
||||
const retryAfter = [
|
||||
...snapshots.map((snapshot) => snapshot.retryAfterSec),
|
||||
...wildlifeFailures(error)
|
||||
.filter(wildlifeFailureRetryable)
|
||||
.map((failure) => failure.retryAfterSec),
|
||||
].filter(Number.isFinite);
|
||||
const stale = snapshots.some((snapshot) => snapshot.stale === true);
|
||||
return {
|
||||
cells,
|
||||
totalResults,
|
||||
fetchedAt: Math.min(...snapshots.map((snapshot) => snapshot.fetchedAt)),
|
||||
stale,
|
||||
...(stale
|
||||
? {
|
||||
upstreamStatus: Math.max(
|
||||
0,
|
||||
...snapshots.map((snapshot) => snapshot.upstreamStatus || 0),
|
||||
),
|
||||
}
|
||||
: {}),
|
||||
...(error ? { error } : {}),
|
||||
...(retryAfter.length ? { retryAfterSec: Math.max(...retryAfter) } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
/** Request both provider proxies when coverage calls for it. API-specific
|
||||
* parameters (Cetacea, photo requirement, observation window) belong to the proxy. */
|
||||
export function createWildlifeSightingsSource({
|
||||
fetchImpl = (...args) => globalThis.fetch(...args),
|
||||
now = () => Date.now(),
|
||||
} = {}) {
|
||||
const gridCache = new Map();
|
||||
const gridInFlight = new Map();
|
||||
async function readProxy(url, provider, signal, { grid = false } = {}) {
|
||||
signal?.throwIfAborted();
|
||||
const response = await fetchImpl(url, { signal });
|
||||
signal?.throwIfAborted();
|
||||
const retryAfterSec = retryAfterSeconds(
|
||||
response.headers?.get?.('Retry-After'),
|
||||
now(),
|
||||
);
|
||||
const upstreamStatus =
|
||||
Number(response.headers?.get?.('X-Upstream-Status')) || 0;
|
||||
if (!response.ok) {
|
||||
await response.body?.cancel?.();
|
||||
signal?.throwIfAborted();
|
||||
const error = new Error(
|
||||
provider === 'iNaturalist' && upstreamStatus === 429
|
||||
? 'iNaturalist rate limited'
|
||||
: `${provider} HTTP ${response.status}`,
|
||||
);
|
||||
error.status = response.status;
|
||||
error.upstreamStatus = upstreamStatus;
|
||||
if (retryAfterSec !== null) error.retryAfterSec = retryAfterSec;
|
||||
throw error;
|
||||
}
|
||||
let payload;
|
||||
try {
|
||||
payload = await readResponseJsonCapped(
|
||||
response,
|
||||
SNAPSHOT_MAX_BYTES,
|
||||
signal,
|
||||
);
|
||||
} catch (error) {
|
||||
signal?.throwIfAborted();
|
||||
throw new Error(`Malformed ${provider} response`, { cause: error });
|
||||
}
|
||||
signal?.throwIfAborted();
|
||||
if (
|
||||
payload &&
|
||||
typeof payload === 'object' &&
|
||||
(payload.stale === true ||
|
||||
response.headers?.get?.('X-Data-Stale') === 'true')
|
||||
) {
|
||||
payload.stale = true;
|
||||
if (retryAfterSec !== null) payload.retryAfterSec = retryAfterSec;
|
||||
payload.upstreamStatus = upstreamStatus;
|
||||
}
|
||||
if (grid) {
|
||||
if (!wildlifeMeasure('tile-decode', () => validProjectedGrid(payload)))
|
||||
throw new Error('Malformed iNaturalist grid response');
|
||||
return payload;
|
||||
}
|
||||
const origin = provider === 'iNaturalist' ? 'inaturalist' : 'acartia';
|
||||
if (
|
||||
!validProjectedRows(payload?.rows, origin) ||
|
||||
(origin === 'inaturalist' &&
|
||||
(!Number.isSafeInteger(payload.totalResults) ||
|
||||
payload.totalResults < 0))
|
||||
) {
|
||||
throw new Error(`Malformed ${provider} response`);
|
||||
}
|
||||
return payload;
|
||||
}
|
||||
|
||||
function readGridTile(key, url, metadata, signal) {
|
||||
signal?.throwIfAborted();
|
||||
let pending = gridInFlight.get(key);
|
||||
if (!pending || pending.controller.signal.aborted) {
|
||||
const controller = new AbortController();
|
||||
pending = { controller, consumers: new Set(), promise: null };
|
||||
const entry = pending;
|
||||
pending.promise = readProxy(url, 'iNaturalist', controller.signal, {
|
||||
grid: true,
|
||||
})
|
||||
.then((value) => {
|
||||
gridCache.delete(key);
|
||||
gridCache.set(key, {
|
||||
value,
|
||||
savedAt: value.stale ? Math.min(now(), value.fetchedAt) : now(),
|
||||
...metadata,
|
||||
});
|
||||
while (gridCache.size > WILDLIFE_GRID_CACHE_MAX)
|
||||
gridCache.delete(gridCache.keys().next().value);
|
||||
return value;
|
||||
})
|
||||
.finally(() => {
|
||||
if (gridInFlight.get(key) === entry) gridInFlight.delete(key);
|
||||
});
|
||||
gridInFlight.set(key, pending);
|
||||
}
|
||||
const consumer = {};
|
||||
pending.consumers.add(consumer);
|
||||
return new Promise((resolve, reject) => {
|
||||
const finish = (aborted = false) => {
|
||||
signal?.removeEventListener('abort', abort);
|
||||
pending.consumers.delete(consumer);
|
||||
if (aborted && !pending.consumers.size) pending.controller.abort();
|
||||
};
|
||||
const abort = () => {
|
||||
finish(true);
|
||||
reject(signal.reason);
|
||||
};
|
||||
signal?.addEventListener('abort', abort, { once: true });
|
||||
pending.promise.then(
|
||||
(value) => {
|
||||
finish();
|
||||
resolve(value);
|
||||
},
|
||||
(error) => {
|
||||
finish();
|
||||
reject(error);
|
||||
},
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
/** Publish cached tiles immediately and refresh their occupied cells. */
|
||||
async function getGridSnapshot({
|
||||
tiles,
|
||||
confirmed = false,
|
||||
taxa = 'all',
|
||||
signal,
|
||||
onTile,
|
||||
} = {}) {
|
||||
signal?.throwIfAborted();
|
||||
if (
|
||||
!Array.isArray(tiles) ||
|
||||
!tiles.length ||
|
||||
tiles.length > WILDLIFE_GRID_TILE_CAP ||
|
||||
!tiles.every(validTile)
|
||||
)
|
||||
throw new TypeError('Wildlife grid requires visible tiles');
|
||||
const preset = TAXA_PRESETS.some((item) => item.value === taxa)
|
||||
? taxa
|
||||
: 'all';
|
||||
const unique = [
|
||||
...new Map(
|
||||
tiles.map((tile) => [`${tile.z}/${tile.x}/${tile.y}`, tile]),
|
||||
).values(),
|
||||
].sort((a, b) => a.z - b.z || a.x - b.x || a.y - b.y);
|
||||
const windowKey = Math.floor(
|
||||
(now() - (preset === 'whales' ? 168 : 48) * HOUR_MS) / HOUR_MS,
|
||||
);
|
||||
const snapshots = new Array(unique.length);
|
||||
const failures = new Array(unique.length);
|
||||
const usable = (entry) => {
|
||||
const age = now() - entry.value.fetchedAt;
|
||||
return age >= 0 && age <= GRID_STALE_MAX_MS;
|
||||
};
|
||||
const touch = (key, entry) => {
|
||||
gridCache.delete(key);
|
||||
gridCache.set(key, entry);
|
||||
};
|
||||
function cachedFallback(tile, tileKey) {
|
||||
let exact = null;
|
||||
const adjacent = [];
|
||||
for (const [key, entry] of gridCache) {
|
||||
if (!usable(entry)) continue;
|
||||
if (key.startsWith(tileKey)) {
|
||||
if (!exact || entry.savedAt > exact.savedAt) exact = entry;
|
||||
} else if (
|
||||
entry.preset === preset &&
|
||||
entry.confirmed === confirmed &&
|
||||
Math.abs(entry.tile.z - tile.z) === 1 &&
|
||||
(entry.tile.z < tile.z
|
||||
? entry.tile.x === Math.floor(tile.x / 2) &&
|
||||
entry.tile.y === Math.floor(tile.y / 2)
|
||||
: Math.floor(entry.tile.x / 2) === tile.x &&
|
||||
Math.floor(entry.tile.y / 2) === tile.y)
|
||||
) {
|
||||
adjacent.push(entry);
|
||||
}
|
||||
}
|
||||
if (exact) return { ...exact.value, stale: true };
|
||||
if (!adjacent.length) return null;
|
||||
// Preserve cached geographic centres and counts while exact tiles load.
|
||||
const newest = [
|
||||
...new Map(
|
||||
adjacent
|
||||
.sort((a, b) => a.savedAt - b.savedAt)
|
||||
.map((entry) => [
|
||||
`${entry.tile.z}/${entry.tile.x}/${entry.tile.y}`,
|
||||
entry,
|
||||
]),
|
||||
).values(),
|
||||
];
|
||||
const parent = newest.find((entry) => entry.tile.z < tile.z);
|
||||
const values = parent
|
||||
? [parent.value]
|
||||
: newest.map((entry) => entry.value);
|
||||
const value = combineWildlifeGridSnapshots(values);
|
||||
value.cells = value.cells.filter((cell) =>
|
||||
wildlifeGridCellId(cell.lat, cell.lon, tile.z)?.startsWith(
|
||||
`grid:${tile.z}/${tile.x}/${tile.y}:`,
|
||||
),
|
||||
);
|
||||
value.totalResults = value.cells.reduce(
|
||||
(sum, cell) => sum + cell.cellCount,
|
||||
0,
|
||||
);
|
||||
return { ...value, stale: true };
|
||||
}
|
||||
function publish(index, value) {
|
||||
signal?.throwIfAborted();
|
||||
snapshots[index] = value;
|
||||
onTile?.(value, { tile: unique[index] });
|
||||
}
|
||||
const requests = [];
|
||||
// Publish all cached coverage before slow misses can occupy the workers.
|
||||
for (let index = 0; index < unique.length; index += 1) {
|
||||
const tile = unique[index];
|
||||
const tileKey = `${tile.z}/${tile.x}/${tile.y}:${preset}:${confirmed ? 'research' : 'all'}:`;
|
||||
const key = `${tileKey}${windowKey}`;
|
||||
const cached = gridCache.get(key);
|
||||
const age = cached ? now() - cached.savedAt : Infinity;
|
||||
if (
|
||||
age >= 0 &&
|
||||
age < WILDLIFE_GRID_TTL_MS &&
|
||||
!cached.value.stale &&
|
||||
usable(cached)
|
||||
) {
|
||||
touch(key, cached);
|
||||
publish(index, cached.value);
|
||||
continue;
|
||||
}
|
||||
const fallback = cachedFallback(tile, tileKey);
|
||||
if (fallback) publish(index, fallback);
|
||||
requests.push({ index, tile, key });
|
||||
}
|
||||
let cursor = 0;
|
||||
async function worker() {
|
||||
while (cursor < requests.length) {
|
||||
signal?.throwIfAborted();
|
||||
const { index, tile, key } = requests[cursor++];
|
||||
const query = new URLSearchParams({
|
||||
z: String(tile.z),
|
||||
x: String(tile.x),
|
||||
y: String(tile.y),
|
||||
taxa: preset,
|
||||
});
|
||||
if (confirmed) query.set('quality', 'research');
|
||||
try {
|
||||
let value = await readGridTile(
|
||||
key,
|
||||
`/api/inaturalist/grid?${query}`,
|
||||
{ tile, preset, confirmed },
|
||||
signal,
|
||||
);
|
||||
signal?.throwIfAborted();
|
||||
publish(index, value);
|
||||
if (value.stale && !value.upstreamStatus) {
|
||||
// A server SWR response paints immediately. Join its existing
|
||||
// refresh so this same view receives the new cells when ready.
|
||||
query.set('refresh', 'wait');
|
||||
value = await readGridTile(
|
||||
key,
|
||||
`/api/inaturalist/grid?${query}`,
|
||||
{ tile, preset, confirmed },
|
||||
signal,
|
||||
);
|
||||
publish(index, value);
|
||||
}
|
||||
} catch (error) {
|
||||
signal?.throwIfAborted();
|
||||
failures[index] = error;
|
||||
// Other tiles can already be cached or in flight. Keep their
|
||||
// progressive coverage even if one upstream request fails.
|
||||
}
|
||||
}
|
||||
}
|
||||
await Promise.all(
|
||||
Array.from(
|
||||
{ length: Math.min(WILDLIFE_GRID_CONCURRENCY, requests.length) },
|
||||
worker,
|
||||
),
|
||||
);
|
||||
signal?.throwIfAborted();
|
||||
const failure = preferredWildlifeFailure(failures);
|
||||
if (!snapshots.some(Boolean) && failure) throw failure;
|
||||
return combineWildlifeGridSnapshots(snapshots.filter(Boolean), failure);
|
||||
}
|
||||
|
||||
/** Merge recent provider rows with source availability and cache age. */
|
||||
async function getSnapshotDetail({
|
||||
signal,
|
||||
box = null,
|
||||
boxes = null,
|
||||
scope = 'view',
|
||||
confirmed = false,
|
||||
taxa = 'all',
|
||||
} = {}) {
|
||||
signal?.throwIfAborted();
|
||||
const preset = TAXA_PRESETS.some((item) => item.value === taxa)
|
||||
? taxa
|
||||
: 'all';
|
||||
const requestBoxes =
|
||||
scope === 'global'
|
||||
? [null]
|
||||
: Array.isArray(boxes)
|
||||
? boxes
|
||||
: box
|
||||
? [box]
|
||||
: [];
|
||||
if (!requestBoxes.length)
|
||||
throw new TypeError('Wildlife sightings require a view box');
|
||||
const useAcartia =
|
||||
scope !== 'global' &&
|
||||
['all', 'Mammalia', 'whales'].includes(preset) &&
|
||||
requestBoxes.some((bounds) => boxIntersects(bounds, ACARTIA_GUARD_BOX));
|
||||
|
||||
// Each box settles independently: one failed antimeridian half must not
|
||||
// discard the other half, and neither may discard a good Acartia reply.
|
||||
const inatRequest = Promise.allSettled(
|
||||
requestBoxes.map((bounds) => {
|
||||
const params = new URLSearchParams({
|
||||
scope: scope === 'global' ? 'global' : 'view',
|
||||
taxa: preset,
|
||||
});
|
||||
if (confirmed) params.set('quality', 'research');
|
||||
if (scope !== 'global') {
|
||||
for (const key of ['south', 'west', 'north', 'east'])
|
||||
params.set(key, String(bounds[key]));
|
||||
}
|
||||
return readProxy(
|
||||
`/api/inaturalist/observations?${params}`,
|
||||
'iNaturalist',
|
||||
signal,
|
||||
);
|
||||
}),
|
||||
);
|
||||
const acartiaRequest = useAcartia
|
||||
? readProxy('/api/acartia/sightings', 'Acartia', signal)
|
||||
: Promise.resolve(null);
|
||||
const [inatResult, acartiaResult] = await Promise.allSettled([
|
||||
inatRequest,
|
||||
acartiaRequest,
|
||||
]);
|
||||
signal?.throwIfAborted();
|
||||
const inatSnapshots = [];
|
||||
const failedBoxes = [];
|
||||
const inatErrors = [];
|
||||
inatResult.value.forEach((result, index) => {
|
||||
if (result.status === 'fulfilled') inatSnapshots.push(result.value);
|
||||
else {
|
||||
failedBoxes.push(requestBoxes[index]);
|
||||
inatErrors.push(result.reason);
|
||||
}
|
||||
});
|
||||
// Keep every failed box; the layer waits for the longest of them.
|
||||
const inatError = preferredWildlifeFailure(inatErrors);
|
||||
// Fail outright only when nothing succeeded; otherwise draw what arrived
|
||||
// and report the failed source in its per-source status.
|
||||
const acartiaError =
|
||||
useAcartia && acartiaResult.status === 'rejected'
|
||||
? acartiaResult.reason
|
||||
: null;
|
||||
if (
|
||||
!inatSnapshots.length &&
|
||||
(!useAcartia || acartiaResult.status !== 'fulfilled')
|
||||
)
|
||||
throw preferredWildlifeFailure([inatError, acartiaError]);
|
||||
const inatRows = inatSnapshots.flatMap((snapshot) => snapshot.rows);
|
||||
const acartiaSnapshot =
|
||||
acartiaResult.status === 'fulfilled' ? acartiaResult.value : null;
|
||||
const acartiaRows = acartiaSnapshot?.rows || [];
|
||||
const rows = mergeSightings(inatRows, acartiaRows, {
|
||||
nowMs: now(),
|
||||
taxa: preset,
|
||||
confirmed,
|
||||
});
|
||||
const inatDates = inatSnapshots
|
||||
.map((snapshot) => snapshot.fetchedAt)
|
||||
.filter(Number.isFinite);
|
||||
const inatFetchedAt = inatDates.length ? Math.min(...inatDates) : null;
|
||||
const inatStale = inatSnapshots.some((snapshot) => snapshot.stale === true);
|
||||
const acartiaStale = acartiaSnapshot?.stale === true;
|
||||
const drawnAcartia = rows.filter((row) => row.origin === 'acartia').length;
|
||||
const dates = [
|
||||
inatFetchedAt,
|
||||
drawnAcartia ? acartiaSnapshot?.fetchedAt : null,
|
||||
].filter(Number.isFinite);
|
||||
const retryAfter = [
|
||||
...inatSnapshots.map((snapshot) => snapshot.retryAfterSec),
|
||||
drawnAcartia ? acartiaSnapshot?.retryAfterSec : null,
|
||||
].filter(Number.isFinite);
|
||||
return {
|
||||
rows,
|
||||
stale: inatStale || (drawnAcartia > 0 && acartiaStale),
|
||||
...(inatStale || acartiaStale
|
||||
? {
|
||||
upstreamStatus: Math.max(
|
||||
0,
|
||||
...inatSnapshots.map((snapshot) => snapshot.upstreamStatus || 0),
|
||||
acartiaSnapshot?.upstreamStatus || 0,
|
||||
),
|
||||
}
|
||||
: {}),
|
||||
fetchedAt: dates.length ? Math.min(...dates) : null,
|
||||
totalResults:
|
||||
inatSnapshots.reduce(
|
||||
(total, snapshot) => total + snapshot.totalResults,
|
||||
0,
|
||||
) + drawnAcartia,
|
||||
scope: scope === 'global' ? 'global' : 'view',
|
||||
partial: inatSnapshots.some((snapshot) => snapshot.partial === true),
|
||||
...(retryAfter.length ? { retryAfterSec: Math.max(...retryAfter) } : {}),
|
||||
sources: {
|
||||
inaturalist: {
|
||||
ok: !inatError,
|
||||
stale: inatStale,
|
||||
fetchedAt: inatFetchedAt,
|
||||
count: rows.filter((row) => row.origin === 'inaturalist').length,
|
||||
...(inatError ? { error: inatError, failedBoxes } : {}),
|
||||
},
|
||||
acartia: {
|
||||
ok: !acartiaError,
|
||||
stale: acartiaStale,
|
||||
fetchedAt: Number.isFinite(acartiaSnapshot?.fetchedAt)
|
||||
? acartiaSnapshot.fetchedAt
|
||||
: null,
|
||||
count: drawnAcartia,
|
||||
...(acartiaError ? { error: acartiaError } : {}),
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
/** Return recent, privacy-projected rows without source status metadata. */
|
||||
async getSnapshot(options = {}) {
|
||||
return (await getSnapshotDetail(options)).rows;
|
||||
},
|
||||
getSnapshotDetail,
|
||||
getGridSnapshot,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,889 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
createWildlifeSightingsSource,
|
||||
WILDLIFE_GRID_TTL_MS,
|
||||
} from './source.js';
|
||||
import { wildlifeGridCellId } from './gridViewport.js';
|
||||
|
||||
const now = Date.UTC(2026, 10, 4, 18);
|
||||
const seattle = { south: 47.5, west: -122.5, north: 47.7, east: -122.2 };
|
||||
const outside = { south: 10, west: 10, north: 12, east: 12 };
|
||||
const inat = {
|
||||
stableId: 'inat:123',
|
||||
origin: 'inaturalist',
|
||||
lat: 47.6,
|
||||
lon: -122.3,
|
||||
observedAt: now - 3_600_000,
|
||||
observedOn: '2026-11-04',
|
||||
};
|
||||
const acartia = {
|
||||
stableId: 'acartia:abc',
|
||||
origin: 'acartia',
|
||||
lat: 48.12,
|
||||
lon: -122.54,
|
||||
observedAt: now - 3_600_000,
|
||||
cetacean: true,
|
||||
quality: 'research',
|
||||
provider: { name: 'Provider', entity: null },
|
||||
};
|
||||
const inatEnvelope = (extra = {}) => ({
|
||||
fetchedAt: now,
|
||||
rows: [inat],
|
||||
scope: 'view',
|
||||
totalResults: 1,
|
||||
...extra,
|
||||
});
|
||||
const acartiaEnvelope = (extra = {}) => ({
|
||||
fetchedAt: now,
|
||||
rows: [acartia],
|
||||
...extra,
|
||||
});
|
||||
|
||||
test('construction performs no acquisition', () => {
|
||||
createWildlifeSightingsSource({
|
||||
fetchImpl: () => assert.fail('construction fetched'),
|
||||
});
|
||||
});
|
||||
|
||||
test('source sends proxy-only scope, box, taxa and confirmed parameters for all presets', async () => {
|
||||
for (const taxa of [
|
||||
'all',
|
||||
'Aves',
|
||||
'Mammalia',
|
||||
'whales',
|
||||
'Insecta',
|
||||
'Plantae',
|
||||
]) {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(new URL(url, 'https://example.test'));
|
||||
return Response.json(inatEnvelope());
|
||||
},
|
||||
});
|
||||
await source.getSnapshotDetail({ box: outside, taxa, confirmed: true });
|
||||
assert.equal(urls.length, 1);
|
||||
assert.equal(urls[0].pathname, '/api/inaturalist/observations');
|
||||
assert.deepEqual(Object.fromEntries(urls[0].searchParams), {
|
||||
scope: 'view',
|
||||
taxa,
|
||||
quality: 'research',
|
||||
south: '10',
|
||||
west: '10',
|
||||
north: '12',
|
||||
east: '12',
|
||||
});
|
||||
// taxon_id, d1 (observed date), photos and quality_grade are upstream
|
||||
// choices owned and tested by the server, never browser query controls.
|
||||
}
|
||||
});
|
||||
|
||||
test('confirmed false omits quality, and global sample omits bbox and Acartia', async () => {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(url);
|
||||
return Response.json(inatEnvelope({ scope: 'global' }));
|
||||
},
|
||||
});
|
||||
const result = await source.getSnapshotDetail({
|
||||
scope: 'global',
|
||||
taxa: 'whales',
|
||||
confirmed: false,
|
||||
box: seattle,
|
||||
});
|
||||
assert.equal(result.scope, 'global');
|
||||
assert.deepEqual(
|
||||
Object.fromEntries(new URL(urls[0], 'https://example.test').searchParams),
|
||||
{ scope: 'global', taxa: 'whales' },
|
||||
);
|
||||
assert.equal(urls.length, 1);
|
||||
});
|
||||
|
||||
test('Acartia loads only inside coverage for the three mammal-inclusive presets', async () => {
|
||||
for (const box of [seattle, outside])
|
||||
for (const taxa of [
|
||||
'all',
|
||||
'Aves',
|
||||
'Mammalia',
|
||||
'whales',
|
||||
'Insecta',
|
||||
'Plantae',
|
||||
]) {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(url);
|
||||
return Response.json(
|
||||
url.startsWith('/api/acartia') ? acartiaEnvelope() : inatEnvelope(),
|
||||
);
|
||||
},
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box, taxa });
|
||||
const expected =
|
||||
box === seattle && ['all', 'Mammalia', 'whales'].includes(taxa);
|
||||
assert.equal(
|
||||
urls.some((url) => url === '/api/acartia/sightings'),
|
||||
expected,
|
||||
);
|
||||
assert.equal(result.rows.length, expected ? 2 : 1);
|
||||
}
|
||||
});
|
||||
|
||||
test('Acartia failure preserves iNat rows with an explicit failed source', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
url.startsWith('/api/acartia')
|
||||
? new Response('', { status: 502 })
|
||||
: Response.json(inatEnvelope()),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box: seattle });
|
||||
assert.deepEqual(result.rows, [inat]);
|
||||
assert.equal(result.sources.acartia.ok, false);
|
||||
assert.equal(result.sources.inaturalist.ok, true);
|
||||
});
|
||||
|
||||
test('iNat failure keeps a successful Acartia result and reports iNat degraded', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
url.startsWith('/api/acartia')
|
||||
? Response.json(acartiaEnvelope())
|
||||
: new Response('', {
|
||||
status: 502,
|
||||
headers: { 'X-Upstream-Status': '503', 'Retry-After': '30' },
|
||||
}),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box: seattle });
|
||||
assert.deepEqual(result.rows, [acartia]);
|
||||
assert.equal(result.totalResults, 1);
|
||||
assert.equal(result.fetchedAt, now);
|
||||
assert.equal(result.sources.acartia.ok, true);
|
||||
assert.equal(result.sources.inaturalist.ok, false);
|
||||
assert.equal(result.sources.inaturalist.count, 0);
|
||||
assert.equal(
|
||||
result.sources.inaturalist.error.message,
|
||||
'iNaturalist HTTP 502',
|
||||
);
|
||||
assert.equal(result.sources.inaturalist.error.retryAfterSec, 30);
|
||||
assert.deepEqual(result.sources.inaturalist.failedBoxes, [seattle]);
|
||||
});
|
||||
|
||||
test('observations reject only when every requested source failed', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
new Response('', { status: url.startsWith('/api/acartia') ? 502 : 503 }),
|
||||
});
|
||||
await assert.rejects(source.getSnapshotDetail({ box: seattle }), {
|
||||
message: 'iNaturalist HTTP 503',
|
||||
});
|
||||
const antimeridian = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async () => new Response('', { status: 503 }),
|
||||
});
|
||||
await assert.rejects(
|
||||
antimeridian.getSnapshotDetail({
|
||||
boxes: [
|
||||
{ south: 10, west: 179, north: 12, east: 180 },
|
||||
{ south: 10, west: -180, north: 12, east: -178 },
|
||||
],
|
||||
}),
|
||||
{ message: 'iNaturalist HTTP 503' },
|
||||
);
|
||||
});
|
||||
|
||||
test('one failed antimeridian half keeps the other half and reports the failed box', async () => {
|
||||
const east = { south: 10, west: 179, north: 12, east: 180 };
|
||||
const west = { south: 10, west: -180, north: 12, east: -178 };
|
||||
const eastRow = { ...inat, stableId: 'inat:east', lat: 11, lon: 179.5 };
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
new URL(url, 'https://example.test').searchParams.get('west') === '179'
|
||||
? Response.json(inatEnvelope({ rows: [eastRow], totalResults: 3 }))
|
||||
: new Response('', { status: 503 }),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ boxes: [east, west] });
|
||||
assert.deepEqual(result.rows, [eastRow]);
|
||||
assert.equal(result.totalResults, 3);
|
||||
assert.equal(result.sources.inaturalist.ok, false);
|
||||
assert.equal(result.sources.inaturalist.count, 1);
|
||||
assert.equal(
|
||||
result.sources.inaturalist.error.message,
|
||||
'iNaturalist HTTP 503',
|
||||
);
|
||||
assert.deepEqual(result.sources.inaturalist.failedBoxes, [west]);
|
||||
});
|
||||
|
||||
test('proxy staleness and original fetch dates pass through with per-source counts', async () => {
|
||||
const fetchedAt = now - 50 * 60_000;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
Response.json(
|
||||
url.startsWith('/api/acartia')
|
||||
? acartiaEnvelope()
|
||||
: inatEnvelope({
|
||||
fetchedAt,
|
||||
stale: true,
|
||||
partial: true,
|
||||
totalResults: 400,
|
||||
}),
|
||||
),
|
||||
});
|
||||
const result = await source.getSnapshotDetail({ box: seattle });
|
||||
assert.equal(result.stale, true);
|
||||
assert.equal(result.fetchedAt, fetchedAt);
|
||||
assert.equal(result.partial, true);
|
||||
assert.equal(result.totalResults, 401);
|
||||
assert.deepEqual(result.sources.inaturalist, {
|
||||
ok: true,
|
||||
stale: true,
|
||||
fetchedAt,
|
||||
count: 1,
|
||||
});
|
||||
assert.equal(result.sources.acartia.count, 1);
|
||||
});
|
||||
|
||||
test('antimeridian boxes fetch once each and merge duplicate boundary rows', async () => {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) => {
|
||||
urls.push(url);
|
||||
return Response.json(inatEnvelope());
|
||||
},
|
||||
});
|
||||
const boxes = [
|
||||
{ south: 10, west: 179, north: 12, east: 180 },
|
||||
{ south: 10, west: -180, north: 12, east: -178 },
|
||||
];
|
||||
const result = await source.getSnapshotDetail({ boxes });
|
||||
assert.equal(urls.length, 2);
|
||||
assert.equal(result.rows.length, 1);
|
||||
assert.equal(result.totalResults, 2);
|
||||
});
|
||||
|
||||
test('iNat non-OK responses carry stable status messages and status values', async () => {
|
||||
for (const status of [429, 502]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () =>
|
||||
new Response('', {
|
||||
status,
|
||||
headers: { 'X-Upstream-Status': String(status) },
|
||||
}),
|
||||
});
|
||||
await assert.rejects(source.getSnapshot({ box: outside }), (error) => {
|
||||
assert.equal(
|
||||
error.message,
|
||||
status === 429 ? 'iNaturalist rate limited' : 'iNaturalist HTTP 502',
|
||||
);
|
||||
assert.equal(error.status, status);
|
||||
return true;
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
test('Retry-After delta seconds and HTTP dates use the injected source clock', async () => {
|
||||
for (const [header, seconds] of [
|
||||
['3600', 3600],
|
||||
[new Date(now + 12 * 3_600_000).toUTCString(), 43_200],
|
||||
[new Date(now - 1000).toUTCString(), 0],
|
||||
['0', 0],
|
||||
['not a deadline', undefined],
|
||||
['-10', undefined],
|
||||
['', undefined],
|
||||
]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async () =>
|
||||
new Response('', {
|
||||
status: 429,
|
||||
headers: { 'Retry-After': header },
|
||||
}),
|
||||
});
|
||||
await assert.rejects(source.getSnapshot({ box: outside }), (error) => {
|
||||
assert.equal(error.status, 429);
|
||||
assert.equal(error.retryAfterSec, seconds, header);
|
||||
return true;
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
test('malformed envelopes and invalid rows reject instead of becoming empty', async () => {
|
||||
for (const payload of [
|
||||
{},
|
||||
{ rows: {} },
|
||||
{ rows: [], totalResults: null },
|
||||
{ rows: [{}], totalResults: 1 },
|
||||
{ results: [], total_results: 0 },
|
||||
]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () => Response.json(payload),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getSnapshot({ box: outside }),
|
||||
/Malformed iNaturalist response/,
|
||||
);
|
||||
}
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () => new Response('{bad'),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getSnapshot({ box: outside }),
|
||||
/Malformed iNaturalist response/,
|
||||
);
|
||||
});
|
||||
|
||||
test('well-formed empty projected snapshot is legitimate and getSnapshot returns only rows', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () =>
|
||||
Response.json(inatEnvelope({ rows: [], totalResults: 0 })),
|
||||
});
|
||||
assert.deepEqual(await source.getSnapshot({ box: outside }), []);
|
||||
});
|
||||
|
||||
test('abort is checked before acquisition and after a late fetch resolves', async () => {
|
||||
const early = new AbortController();
|
||||
early.abort();
|
||||
const idle = createWildlifeSightingsSource({
|
||||
fetchImpl: () => assert.fail('aborted fetch ran'),
|
||||
});
|
||||
await assert.rejects(
|
||||
idle.getSnapshot({ box: outside, signal: early.signal }),
|
||||
{ name: 'AbortError' },
|
||||
);
|
||||
let resolve;
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: () =>
|
||||
new Promise((done) => {
|
||||
resolve = done;
|
||||
}),
|
||||
});
|
||||
const late = new AbortController();
|
||||
const request = source.getSnapshot({ box: outside, signal: late.signal });
|
||||
late.abort();
|
||||
resolve(Response.json(inatEnvelope()));
|
||||
await assert.rejects(request, { name: 'AbortError' });
|
||||
});
|
||||
|
||||
const gridCell = {
|
||||
id: 'grid:2/1/1:1:51',
|
||||
cellCount: 6,
|
||||
lat: 65.94,
|
||||
lon: -18.28125,
|
||||
};
|
||||
const gridEnvelope = (extra = {}) => ({
|
||||
cells: [gridCell],
|
||||
totalResults: 6,
|
||||
fetchedAt: now,
|
||||
...extra,
|
||||
});
|
||||
const gridTile = { z: 2, x: 1, y: 1 };
|
||||
|
||||
test('grid source sends visible XYZ/filter parameters only, dedupes tiles and keeps source untouched', async () => {
|
||||
const urls = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url, options) => {
|
||||
urls.push(new URL(url, 'https://example.test'));
|
||||
assert.ok(options.signal instanceof AbortSignal);
|
||||
return Response.json(gridEnvelope());
|
||||
},
|
||||
});
|
||||
const result = await source.getGridSnapshot({
|
||||
tiles: [gridTile, gridTile],
|
||||
confirmed: true,
|
||||
taxa: 'Aves',
|
||||
});
|
||||
assert.equal(urls.length, 1);
|
||||
assert.equal(urls[0].pathname, '/api/inaturalist/grid');
|
||||
assert.deepEqual(Object.fromEntries(urls[0].searchParams), {
|
||||
z: '2',
|
||||
x: '1',
|
||||
y: '1',
|
||||
taxa: 'Aves',
|
||||
quality: 'research',
|
||||
});
|
||||
assert.deepEqual(result, {
|
||||
cells: [gridCell],
|
||||
totalResults: 6,
|
||||
fetchedAt: now,
|
||||
stale: false,
|
||||
});
|
||||
});
|
||||
|
||||
test('grid source caches stable tile/filter/hour keys and combines neighbor edge cells once', async () => {
|
||||
let clock = now;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: async () => {
|
||||
calls += 1;
|
||||
return Response.json(gridEnvelope());
|
||||
},
|
||||
});
|
||||
const options = { tiles: [gridTile, { z: 2, x: 2, y: 1 }] };
|
||||
const result = await source.getGridSnapshot(options);
|
||||
assert.equal(calls, 2);
|
||||
assert.equal(
|
||||
result.cells.length,
|
||||
1,
|
||||
'same geographic cell can bleed into a neighboring hit tile',
|
||||
);
|
||||
assert.equal(result.totalResults, 6);
|
||||
await source.getGridSnapshot({ tiles: [...options.tiles].reverse() });
|
||||
assert.equal(calls, 2, 'ordering does not change stable keys');
|
||||
await source.getGridSnapshot({ ...options, confirmed: true });
|
||||
assert.equal(calls, 4, 'quality changes the key');
|
||||
clock += WILDLIFE_GRID_TTL_MS + 1;
|
||||
await source.getGridSnapshot(options);
|
||||
assert.equal(calls, 6, 'fifteen minute refresh cap');
|
||||
});
|
||||
|
||||
test('grid source preserves stale metadata and rejects invalid projected schema/privacy fields', async () => {
|
||||
const staleSource = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async () =>
|
||||
Response.json(gridEnvelope({ stale: true, fetchedAt: now - 1000 })),
|
||||
});
|
||||
const stale = await staleSource.getGridSnapshot({ tiles: [gridTile] });
|
||||
assert.equal(stale.stale, true);
|
||||
assert.equal(stale.fetchedAt, now - 1000);
|
||||
for (const payload of [
|
||||
{},
|
||||
gridEnvelope({ cells: {} }),
|
||||
gridEnvelope({ totalResults: -1 }),
|
||||
gridEnvelope({ totalResults: 5 }),
|
||||
gridEnvelope({ fetchedAt: null }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, uuid: 'must-not-leave-proxy' }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, iconic: 'Aves' }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, lat: 91 }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, id: 'grid:99/0/0:1:1' }] }),
|
||||
gridEnvelope({ cells: [{ ...gridCell, id: 'grid:2/1/1:3:51' }] }),
|
||||
gridEnvelope({ cells: [gridCell, gridCell], totalResults: 12 }),
|
||||
]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () => Response.json(payload),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getGridSnapshot({ tiles: [gridTile] }),
|
||||
/Malformed iNaturalist grid response/,
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('grid source validates request bounds before fetching and aborts superseded loads', async () => {
|
||||
const idle = createWildlifeSightingsSource({
|
||||
fetchImpl: () => assert.fail('invalid/aborted grid acquired'),
|
||||
});
|
||||
for (const tiles of [
|
||||
undefined,
|
||||
[],
|
||||
[{ z: 2, x: 4, y: 0 }],
|
||||
[{ z: -1, x: 0, y: 0 }],
|
||||
Array(13).fill(gridTile),
|
||||
]) {
|
||||
await assert.rejects(
|
||||
idle.getGridSnapshot({ tiles }),
|
||||
/requires visible tiles/,
|
||||
);
|
||||
}
|
||||
const early = new AbortController();
|
||||
early.abort();
|
||||
await assert.rejects(
|
||||
idle.getGridSnapshot({ tiles: [gridTile], signal: early.signal }),
|
||||
{ name: 'AbortError' },
|
||||
);
|
||||
let resolve;
|
||||
let passedSignal;
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: (_url, options) => {
|
||||
passedSignal = options.signal;
|
||||
return new Promise((done) => {
|
||||
resolve = done;
|
||||
});
|
||||
},
|
||||
});
|
||||
const late = new AbortController();
|
||||
const loading = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
signal: late.signal,
|
||||
});
|
||||
late.abort();
|
||||
assert.equal(passedSignal.aborted, true);
|
||||
resolve(Response.json(gridEnvelope()));
|
||||
await assert.rejects(loading, { name: 'AbortError' });
|
||||
});
|
||||
|
||||
test('grid worker concurrency is bounded and a failed tile preserves progressive siblings', async () => {
|
||||
const waiting = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: (_url, options) =>
|
||||
new Promise((resolve, reject) => {
|
||||
waiting.push({ resolve, signal: options.signal });
|
||||
options.signal.addEventListener(
|
||||
'abort',
|
||||
() => reject(options.signal.reason),
|
||||
{ once: true },
|
||||
);
|
||||
}),
|
||||
});
|
||||
const tiles = Array.from({ length: 6 }, (_, x) => ({ z: 3, x, y: 0 }));
|
||||
const loading = source.getGridSnapshot({ tiles });
|
||||
assert.equal(waiting.length, 4);
|
||||
waiting[0].resolve(new Response('', { status: 502 }));
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (let i = 1; i < 4; i++) waiting[i].resolve(Response.json(gridEnvelope()));
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
for (let i = 4; i < waiting.length; i++)
|
||||
waiting[i].resolve(Response.json(gridEnvelope()));
|
||||
const result = await loading;
|
||||
assert.equal(result.error.message, 'iNaturalist HTTP 502');
|
||||
assert.deepEqual(result.cells, [gridCell]);
|
||||
assert.ok(waiting.every((item) => !item.signal.aborted));
|
||||
});
|
||||
|
||||
test('failed grid refresh keeps the tile last good cells across its window-hour key, without extending stale life', async () => {
|
||||
let clock = now + 55 * 60_000;
|
||||
let fail = false;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: async () => {
|
||||
calls++;
|
||||
return fail
|
||||
? new Response('', { status: 502, headers: { 'Retry-After': '40' } })
|
||||
: Response.json(gridEnvelope({ fetchedAt: clock }));
|
||||
},
|
||||
});
|
||||
const good = await source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
taxa: 'whales',
|
||||
});
|
||||
const fetchedAt = clock;
|
||||
fail = true;
|
||||
clock += 300_001;
|
||||
const stale = await source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
taxa: 'whales',
|
||||
});
|
||||
assert.deepEqual(stale.cells, good.cells);
|
||||
assert.equal(stale.totalResults, good.totalResults);
|
||||
assert.equal(stale.stale, true);
|
||||
assert.equal(stale.fetchedAt, fetchedAt);
|
||||
assert.equal(stale.error.message, 'iNaturalist HTTP 502');
|
||||
assert.equal(stale.retryAfterSec, 40);
|
||||
assert.equal(calls, 2);
|
||||
await assert.rejects(
|
||||
source.getGridSnapshot({ tiles: [gridTile], taxa: 'Aves' }),
|
||||
/iNaturalist HTTP 502/,
|
||||
'a different filter cannot borrow the last tile',
|
||||
);
|
||||
clock = fetchedAt + 3_600_001;
|
||||
await assert.rejects(
|
||||
source.getGridSnapshot({ tiles: [gridTile], taxa: 'whales' }),
|
||||
/iNaturalist HTTP 502/,
|
||||
'failed refresh did not renew original data age',
|
||||
);
|
||||
});
|
||||
|
||||
test('a rejected grid request never rejects a parallel observations acquisition', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
url.startsWith('/api/inaturalist/grid?')
|
||||
? new Response('', { status: 502 })
|
||||
: Response.json(inatEnvelope()),
|
||||
});
|
||||
const [grid, observations] = await Promise.allSettled([
|
||||
source.getGridSnapshot({ tiles: [gridTile] }),
|
||||
source.getSnapshotDetail({ box: outside }),
|
||||
]);
|
||||
assert.equal(grid.status, 'rejected');
|
||||
assert.equal(grid.reason.status, 502);
|
||||
assert.equal(observations.status, 'fulfilled');
|
||||
assert.deepEqual(observations.value.rows, [inat]);
|
||||
});
|
||||
|
||||
test('one failed cached tile retains its cells while neighboring tiles refresh successfully', async () => {
|
||||
let clock = now;
|
||||
let refreshing = false;
|
||||
const neighbor = {
|
||||
...gridCell,
|
||||
id: wildlifeGridCellId(30, 20, 2),
|
||||
lat: 30,
|
||||
lon: 20,
|
||||
};
|
||||
const signals = [];
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: async (url, { signal }) => {
|
||||
signals.push(signal);
|
||||
const isFailedTile =
|
||||
new URL(url, 'https://example.test').searchParams.get('x') === '1';
|
||||
if (refreshing && isFailedTile) return new Response('', { status: 502 });
|
||||
const cell = isFailedTile
|
||||
? gridCell
|
||||
: { ...neighbor, cellCount: refreshing ? 10 : 6 };
|
||||
return Response.json({
|
||||
cells: [cell],
|
||||
totalResults: cell.cellCount,
|
||||
fetchedAt: clock,
|
||||
});
|
||||
},
|
||||
});
|
||||
const options = { tiles: [gridTile, { z: 2, x: 2, y: 1 }] };
|
||||
await source.getGridSnapshot(options);
|
||||
refreshing = true;
|
||||
clock += WILDLIFE_GRID_TTL_MS + 1;
|
||||
const result = await source.getGridSnapshot(options);
|
||||
assert.equal(result.cells.length, 2);
|
||||
assert.equal(
|
||||
result.cells.find((cell) => cell.id === gridCell.id).cellCount,
|
||||
6,
|
||||
);
|
||||
assert.equal(
|
||||
result.cells.find((cell) => cell.id === neighbor.id).cellCount,
|
||||
10,
|
||||
);
|
||||
assert.equal(result.totalResults, 16);
|
||||
assert.equal(result.stale, true);
|
||||
assert.equal(result.error.message, 'iNaturalist HTTP 502');
|
||||
assert.ok(signals.every((signal) => !signal.aborted));
|
||||
});
|
||||
|
||||
test('stale successful proxy answers preserve Retry-After for observation and grid retry guidance', async () => {
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: async (url) =>
|
||||
Response.json(
|
||||
url.startsWith('/api/inaturalist/grid?')
|
||||
? gridEnvelope({ stale: true })
|
||||
: inatEnvelope({ stale: true }),
|
||||
{ headers: { 'X-Data-Stale': 'true', 'Retry-After': '75' } },
|
||||
),
|
||||
});
|
||||
const rows = await source.getSnapshotDetail({ box: outside });
|
||||
const grid = await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
assert.equal(rows.stale, true);
|
||||
assert.equal(rows.retryAfterSec, 75);
|
||||
assert.equal(grid.stale, true);
|
||||
assert.equal(grid.retryAfterSec, 75);
|
||||
});
|
||||
|
||||
test('client stale tiles publish before revalidation finishes and retain the original data date', async () => {
|
||||
let clock = now;
|
||||
let refresh;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => clock,
|
||||
fetchImpl: () =>
|
||||
++calls === 1
|
||||
? Promise.resolve(Response.json(gridEnvelope()))
|
||||
: new Promise((resolve) => {
|
||||
refresh = resolve;
|
||||
}),
|
||||
});
|
||||
await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
clock += WILDLIFE_GRID_TTL_MS + 1;
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
onTile: (tile) => paints.push(tile),
|
||||
});
|
||||
assert.equal(
|
||||
paints.length,
|
||||
1,
|
||||
'stale cache is synchronous, before the fetch settles',
|
||||
);
|
||||
assert.equal(paints[0].stale, true);
|
||||
assert.equal(paints[0].fetchedAt, now);
|
||||
refresh(
|
||||
Response.json(
|
||||
gridEnvelope({
|
||||
cells: [{ ...gridCell, cellCount: 9 }],
|
||||
totalResults: 9,
|
||||
fetchedAt: clock,
|
||||
}),
|
||||
),
|
||||
);
|
||||
const result = await pending;
|
||||
assert.equal(paints.length, 2);
|
||||
assert.equal(paints[1].stale, undefined);
|
||||
assert.equal(result.totalResults, 9);
|
||||
});
|
||||
|
||||
test('cached coverage publishes before slow misses earlier in XYZ order fill all workers', async () => {
|
||||
const waiting = [];
|
||||
let cold = false;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: (url) => {
|
||||
const x = Number(
|
||||
new URL(url, 'https://example.test').searchParams.get('x'),
|
||||
);
|
||||
const cell = {
|
||||
id: wildlifeGridCellId(83, x * 45 - 157.5, 3),
|
||||
lat: 83,
|
||||
lon: x * 45 - 157.5,
|
||||
cellCount: 6,
|
||||
};
|
||||
const value = { cells: [cell], totalResults: 6, fetchedAt: now };
|
||||
return cold
|
||||
? new Promise((resolve) =>
|
||||
waiting.push(() => resolve(Response.json(value))),
|
||||
)
|
||||
: Promise.resolve(Response.json(value));
|
||||
},
|
||||
});
|
||||
const tiles = Array.from({ length: 6 }, (_, x) => ({ z: 3, x, y: 0 }));
|
||||
await source.getGridSnapshot({ tiles: tiles.slice(4) });
|
||||
cold = true;
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles,
|
||||
onTile: (value, metadata) => paints.push({ value, metadata }),
|
||||
});
|
||||
assert.deepEqual(
|
||||
paints.map(({ metadata }) => metadata.tile.x),
|
||||
[4, 5],
|
||||
'known cells paint synchronously even though the four earlier misses are unresolved',
|
||||
);
|
||||
assert.equal(waiting.length, 4);
|
||||
for (const finish of waiting) finish();
|
||||
const result = await pending;
|
||||
assert.equal(result.cells.length, 6);
|
||||
assert.equal(result.totalResults, 36);
|
||||
});
|
||||
|
||||
test('an adjacent zoom cache fills the new tile immediately while its exact cells load', async () => {
|
||||
let resolve;
|
||||
let calls = 0;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: () =>
|
||||
++calls === 1
|
||||
? Promise.resolve(Response.json(gridEnvelope()))
|
||||
: new Promise((done) => {
|
||||
resolve = done;
|
||||
}),
|
||||
});
|
||||
await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
const parent = { z: 1, x: 0, y: 0 };
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles: [parent],
|
||||
onTile: (value) => paints.push(value),
|
||||
});
|
||||
assert.equal(paints.length, 1);
|
||||
assert.deepEqual(paints[0].cells, [gridCell]);
|
||||
assert.equal(calls, 2, 'the exact zoom still loads in the background');
|
||||
const cell = {
|
||||
...gridCell,
|
||||
id: wildlifeGridCellId(gridCell.lat, gridCell.lon, 1),
|
||||
};
|
||||
resolve(Response.json(gridEnvelope({ cells: [cell] })));
|
||||
await pending;
|
||||
assert.equal(paints.length, 2);
|
||||
assert.deepEqual(paints[1].cells, [cell]);
|
||||
});
|
||||
|
||||
test('concurrent client views share an in-flight tile without one consumer aborting the other', async () => {
|
||||
let resolve;
|
||||
let calls = 0;
|
||||
let signal;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: (_url, options) => {
|
||||
calls++;
|
||||
signal = options.signal;
|
||||
return new Promise((done) => {
|
||||
resolve = done;
|
||||
});
|
||||
},
|
||||
});
|
||||
const first = new AbortController();
|
||||
const one = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
signal: first.signal,
|
||||
});
|
||||
const two = source.getGridSnapshot({ tiles: [gridTile] });
|
||||
first.abort();
|
||||
await assert.rejects(one, { name: 'AbortError' });
|
||||
assert.equal(signal.aborted, false);
|
||||
resolve(Response.json(gridEnvelope()));
|
||||
assert.equal((await two).totalResults, 6);
|
||||
assert.equal(calls, 1);
|
||||
await source.getGridSnapshot({ tiles: [gridTile] });
|
||||
assert.equal(calls, 1);
|
||||
});
|
||||
|
||||
test('local HTTP pacing errors never become iNaturalist rate-limited errors', async () => {
|
||||
for (const status of [429, 503]) {
|
||||
const source = createWildlifeSightingsSource({
|
||||
fetchImpl: async () =>
|
||||
new Response('', { status, headers: { 'Retry-After': '30' } }),
|
||||
});
|
||||
await assert.rejects(
|
||||
source.getSnapshotDetail({ box: outside }),
|
||||
(error) => {
|
||||
assert.equal(error.upstreamStatus, 0);
|
||||
assert.doesNotMatch(error.message, /rate limited/i);
|
||||
return true;
|
||||
},
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('a server stale-while-revalidate answer joins its refresh and publishes fresh cells in the same view', async () => {
|
||||
const urls = [];
|
||||
let resolve;
|
||||
const source = createWildlifeSightingsSource({
|
||||
now: () => now,
|
||||
fetchImpl: (url) => {
|
||||
urls.push(url);
|
||||
return urls.length === 1
|
||||
? Promise.resolve(
|
||||
Response.json(
|
||||
gridEnvelope({
|
||||
stale: true,
|
||||
fetchedAt: now - WILDLIFE_GRID_TTL_MS - 1,
|
||||
}),
|
||||
),
|
||||
)
|
||||
: new Promise((done) => {
|
||||
resolve = done;
|
||||
});
|
||||
},
|
||||
});
|
||||
const paints = [];
|
||||
const pending = source.getGridSnapshot({
|
||||
tiles: [gridTile],
|
||||
onTile: (value) => paints.push(value),
|
||||
});
|
||||
await new Promise((done) => setImmediate(done));
|
||||
assert.equal(paints.length, 1);
|
||||
assert.equal(paints[0].stale, true);
|
||||
assert.equal(
|
||||
new URL(urls[1], 'https://example.test').searchParams.get('refresh'),
|
||||
'wait',
|
||||
);
|
||||
resolve(
|
||||
Response.json(
|
||||
gridEnvelope({
|
||||
cells: [{ ...gridCell, cellCount: 11 }],
|
||||
totalResults: 11,
|
||||
}),
|
||||
),
|
||||
);
|
||||
assert.equal((await pending).totalResults, 11);
|
||||
assert.equal(paints.length, 2);
|
||||
assert.equal(paints[1].stale, undefined);
|
||||
});
|
||||
@@ -0,0 +1,136 @@
|
||||
import { ICONIC_TINTS, WILDLIFE_SPRITE_PX } from './policy.js';
|
||||
|
||||
// Missing taxon symbols use related shapes from Material Symbols Outlined.
|
||||
export const WILDLIFE_BADGE_GLYPHS = Object.freeze({
|
||||
bird: 'raven',
|
||||
mammal: 'pets',
|
||||
reptile: 'egg_alt',
|
||||
amphibian: 'water_drop',
|
||||
fish: 'set_meal',
|
||||
insect: 'bug_report',
|
||||
arachnid: 'pest_control',
|
||||
plant: 'eco',
|
||||
fungus: 'umbrella',
|
||||
other: 'category',
|
||||
unknown: 'question_mark',
|
||||
});
|
||||
export const WILDLIFE_SPRITE_GROUPS = Object.freeze(
|
||||
Object.keys(WILDLIFE_BADGE_GLYPHS),
|
||||
);
|
||||
export const WILDLIFE_SPRITE_ICONIC = Object.freeze({
|
||||
bird: 'Aves',
|
||||
mammal: 'Mammalia',
|
||||
reptile: 'Reptilia',
|
||||
amphibian: 'Amphibia',
|
||||
fish: 'Actinopterygii',
|
||||
insect: 'Insecta',
|
||||
arachnid: 'Arachnida',
|
||||
plant: 'Plantae',
|
||||
fungus: 'Fungi',
|
||||
other: 'Animalia',
|
||||
unknown: 'Unknown',
|
||||
});
|
||||
const ICONIC_GROUPS = Object.freeze(
|
||||
Object.fromEntries(
|
||||
Object.entries(WILDLIFE_SPRITE_ICONIC).map(([group, iconic]) => [
|
||||
iconic,
|
||||
group,
|
||||
]),
|
||||
),
|
||||
);
|
||||
|
||||
/** Resolve a taxon or sprite group to one of the shared badge textures. */
|
||||
export function wildlifeSpriteGroup(groupOrIconic) {
|
||||
if (groupOrIconic === 'Mollusca') return 'other';
|
||||
return Object.hasOwn(WILDLIFE_SPRITE_ICONIC, groupOrIconic)
|
||||
? groupOrIconic
|
||||
: Object.hasOwn(ICONIC_GROUPS, groupOrIconic)
|
||||
? ICONIC_GROUPS[groupOrIconic]
|
||||
: 'unknown';
|
||||
}
|
||||
|
||||
export const WILDLIFE_BADGE_OUTLINE_PX = 1.5;
|
||||
const OUTLINE_COLOR = '#040c10';
|
||||
const FONT = '400 14px "Material Symbols Outlined"';
|
||||
const FONT_GLYPHS = Object.values(WILDLIFE_BADGE_GLYPHS).join(' ');
|
||||
const FALLBACKS = new Map(
|
||||
WILDLIFE_SPRITE_GROUPS.map((group) => [
|
||||
group,
|
||||
`data:image/svg+xml,${encodeURIComponent(
|
||||
`<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 20 20"><circle cx="10" cy="10" r="9.1" fill="${ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]}" stroke="${OUTLINE_COLOR}" stroke-width="${WILDLIFE_BADGE_OUTLINE_PX}"/></svg>`,
|
||||
)}`,
|
||||
]),
|
||||
);
|
||||
|
||||
/** One bounded set of canvas sprites per document, painted only after the
|
||||
* icon font is decoded. Until then the very same billboards use plain badges. */
|
||||
export function createWildlifeSpriteCache({
|
||||
documentRef = globalThis.document,
|
||||
} = {}) {
|
||||
const sprites = new Map();
|
||||
const listeners = new Set();
|
||||
let ready = false;
|
||||
let loading = null;
|
||||
|
||||
function paint(group) {
|
||||
const canvas = documentRef.createElement('canvas');
|
||||
canvas.width = canvas.height = WILDLIFE_SPRITE_PX * 2;
|
||||
const ctx = canvas.getContext('2d');
|
||||
if (!ctx) return FALLBACKS.get(group);
|
||||
ctx.scale(2, 2);
|
||||
ctx.beginPath();
|
||||
ctx.arc(10, 10, 9.1, 0, Math.PI * 2);
|
||||
ctx.fillStyle = ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]];
|
||||
ctx.fill();
|
||||
ctx.lineWidth = WILDLIFE_BADGE_OUTLINE_PX;
|
||||
ctx.strokeStyle = OUTLINE_COLOR;
|
||||
ctx.stroke();
|
||||
ctx.font = FONT;
|
||||
ctx.textAlign = 'center';
|
||||
ctx.textBaseline = 'middle';
|
||||
ctx.fillStyle = '#ffffff';
|
||||
ctx.fillText(WILDLIFE_BADGE_GLYPHS[group], 10, 10, 16);
|
||||
return canvas;
|
||||
}
|
||||
|
||||
function load() {
|
||||
if (loading) return loading;
|
||||
if (!documentRef?.fonts?.load) return Promise.resolve(false);
|
||||
loading = Promise.resolve()
|
||||
.then(() => documentRef.fonts.load(FONT, FONT_GLYPHS))
|
||||
.then((faces) => {
|
||||
if (!faces?.length) return false;
|
||||
// Paint once per group, never once per observation or refresh.
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS)
|
||||
sprites.set(group, paint(group));
|
||||
ready = true;
|
||||
for (const listener of [...listeners]) listener();
|
||||
return true;
|
||||
})
|
||||
.catch(() => false);
|
||||
return loading;
|
||||
}
|
||||
|
||||
return {
|
||||
get(groupOrIconic) {
|
||||
const group = wildlifeSpriteGroup(groupOrIconic);
|
||||
return (ready ? sprites : FALLBACKS).get(group);
|
||||
},
|
||||
load,
|
||||
subscribe(listener) {
|
||||
listeners.add(listener);
|
||||
void load();
|
||||
return () => listeners.delete(listener);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const caches = new WeakMap();
|
||||
let headlessCache;
|
||||
/** Share the bounded sprite cache among layer instances in one document. */
|
||||
export function wildlifeSpriteCache(documentRef = globalThis.document) {
|
||||
if (!documentRef) return (headlessCache ??= createWildlifeSpriteCache());
|
||||
if (!caches.has(documentRef))
|
||||
caches.set(documentRef, createWildlifeSpriteCache({ documentRef }));
|
||||
return caches.get(documentRef);
|
||||
}
|
||||
@@ -0,0 +1,189 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import sharp from 'sharp';
|
||||
import { aircraftIcon } from '../../data/aircraftIcons.js';
|
||||
import { ICONIC_TINTS, WILDLIFE_SPRITE_PX } from './policy.js';
|
||||
import {
|
||||
WILDLIFE_SPRITE_GROUPS,
|
||||
WILDLIFE_SPRITE_ICONIC,
|
||||
WILDLIFE_BADGE_GLYPHS,
|
||||
WILDLIFE_BADGE_OUTLINE_PX,
|
||||
createWildlifeSpriteCache,
|
||||
wildlifeSpriteCache,
|
||||
wildlifeSpriteGroup,
|
||||
} from './sprites.js';
|
||||
|
||||
const sprites = wildlifeSpriteCache();
|
||||
|
||||
test('every taxon group has an explicit Material Symbol and tinted circle fallback', () => {
|
||||
assert.equal(Object.isFrozen(WILDLIFE_BADGE_GLYPHS), true);
|
||||
assert.deepEqual(WILDLIFE_BADGE_GLYPHS, {
|
||||
bird: 'raven',
|
||||
mammal: 'pets',
|
||||
reptile: 'egg_alt',
|
||||
amphibian: 'water_drop',
|
||||
fish: 'set_meal',
|
||||
insect: 'bug_report',
|
||||
arachnid: 'pest_control',
|
||||
plant: 'eco',
|
||||
fungus: 'umbrella',
|
||||
other: 'category',
|
||||
unknown: 'question_mark',
|
||||
});
|
||||
const textures = new Set();
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS) {
|
||||
const texture = sprites.get(group);
|
||||
textures.add(texture);
|
||||
assert.equal(wildlifeSpriteGroup(WILDLIFE_SPRITE_ICONIC[group]), group);
|
||||
assert.equal(sprites.get(WILDLIFE_SPRITE_ICONIC[group]), texture);
|
||||
assert.equal(sprites.get(group), texture);
|
||||
const svg = decodeURIComponent(texture.slice(texture.indexOf(',') + 1));
|
||||
assert.match(svg, /<circle /);
|
||||
assert.ok(
|
||||
svg.includes(`fill="${ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]}"`),
|
||||
);
|
||||
assert.match(svg, /stroke="#040c10"/);
|
||||
assert.match(svg, /stroke-width="1.5"/);
|
||||
assert.doesNotMatch(svg, /<path|<text|<image|href=|<script|<foreignObject/);
|
||||
}
|
||||
assert.equal(textures.size, Object.keys(ICONIC_TINTS).length);
|
||||
});
|
||||
|
||||
test('unknown taxon keys share the slate fallback without allocating textures', () => {
|
||||
for (const value of [
|
||||
undefined,
|
||||
null,
|
||||
'Unknown',
|
||||
'Synthetic kingdom',
|
||||
'__proto__',
|
||||
'constructor',
|
||||
'toString',
|
||||
]) {
|
||||
assert.equal(wildlifeSpriteGroup(value), 'unknown');
|
||||
assert.equal(sprites.get(value), sprites.get('unknown'));
|
||||
}
|
||||
assert.equal(sprites.get('Mollusca'), sprites.get('other'));
|
||||
});
|
||||
|
||||
test('canvas badges wait for the icon font, paint once and notify existing consumers', async () => {
|
||||
let resolveFont;
|
||||
let fontLoads = 0;
|
||||
const canvases = [];
|
||||
const documentRef = {
|
||||
fonts: {
|
||||
load(font, glyphs) {
|
||||
fontLoads += 1;
|
||||
assert.match(font, /Material Symbols Outlined/);
|
||||
for (const glyph of Object.values(WILDLIFE_BADGE_GLYPHS))
|
||||
assert.ok(glyphs.includes(glyph));
|
||||
return new Promise((resolve) => {
|
||||
resolveFont = resolve;
|
||||
});
|
||||
},
|
||||
},
|
||||
createElement(tag) {
|
||||
assert.equal(tag, 'canvas');
|
||||
const commands = [];
|
||||
const ctx = {
|
||||
scale(...args) {
|
||||
commands.push(['scale', ...args]);
|
||||
},
|
||||
beginPath() {},
|
||||
arc(...args) {
|
||||
commands.push(['arc', ...args]);
|
||||
},
|
||||
fill() {
|
||||
commands.push(['fill', this.fillStyle]);
|
||||
},
|
||||
stroke() {
|
||||
commands.push(['stroke', this.strokeStyle, this.lineWidth]);
|
||||
},
|
||||
fillText(...args) {
|
||||
commands.push(['text', this.fillStyle, this.font, ...args]);
|
||||
},
|
||||
};
|
||||
const canvas = { commands, getContext: () => ctx };
|
||||
canvases.push(canvas);
|
||||
return canvas;
|
||||
},
|
||||
};
|
||||
const cache = createWildlifeSpriteCache({ documentRef });
|
||||
const fallback = cache.get('Aves');
|
||||
let notifications = 0;
|
||||
const unsubscribe = cache.subscribe(() => {
|
||||
notifications += 1;
|
||||
});
|
||||
const loading = cache.load();
|
||||
assert.equal(cache.load(), loading);
|
||||
await Promise.resolve();
|
||||
assert.equal(fontLoads, 1);
|
||||
assert.equal(canvases.length, 0, 'no glyph is rasterized in a fallback font');
|
||||
assert.equal(cache.get('Aves'), fallback);
|
||||
resolveFont([{}]);
|
||||
assert.equal(await loading, true);
|
||||
assert.equal(notifications, 1);
|
||||
assert.equal(canvases.length, WILDLIFE_SPRITE_GROUPS.length);
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS) {
|
||||
const canvas = cache.get(group);
|
||||
assert.equal(canvas, cache.get(WILDLIFE_SPRITE_ICONIC[group]));
|
||||
assert.equal(canvas.width, WILDLIFE_SPRITE_PX * 2);
|
||||
assert.equal(canvas.height, WILDLIFE_SPRITE_PX * 2);
|
||||
assert.deepEqual(
|
||||
canvas.commands.find(([op]) => op === 'fill'),
|
||||
['fill', ICONIC_TINTS[WILDLIFE_SPRITE_ICONIC[group]]],
|
||||
);
|
||||
assert.deepEqual(
|
||||
canvas.commands.find(([op]) => op === 'stroke'),
|
||||
['stroke', '#040c10', WILDLIFE_BADGE_OUTLINE_PX],
|
||||
);
|
||||
const glyph = canvas.commands.find(([op]) => op === 'text');
|
||||
assert.equal(glyph[1], '#ffffff');
|
||||
assert.match(glyph[2], /Material Symbols Outlined/);
|
||||
assert.equal(glyph[3], WILDLIFE_BADGE_GLYPHS[group]);
|
||||
}
|
||||
await cache.load();
|
||||
assert.equal(canvases.length, WILDLIFE_SPRITE_GROUPS.length);
|
||||
unsubscribe();
|
||||
});
|
||||
|
||||
test('unavailable font keeps plain badges and does not paint a ligature word', async () => {
|
||||
const cache = createWildlifeSpriteCache({
|
||||
documentRef: {
|
||||
fonts: { load: async () => [] },
|
||||
createElement() {
|
||||
assert.fail('no canvas before the icon font is ready');
|
||||
},
|
||||
},
|
||||
});
|
||||
const fallback = cache.get('Aves');
|
||||
assert.equal(await cache.load(), false);
|
||||
assert.equal(cache.get('Aves'), fallback);
|
||||
});
|
||||
|
||||
async function visiblePixels(texture, size) {
|
||||
const svg = texture.includes(';base64,')
|
||||
? Buffer.from(texture.slice(texture.indexOf(',') + 1), 'base64')
|
||||
: Buffer.from(decodeURIComponent(texture.slice(texture.indexOf(',') + 1)));
|
||||
const { data, info } = await sharp(svg)
|
||||
.resize(size, size)
|
||||
.ensureAlpha()
|
||||
.raw()
|
||||
.toBuffer({ resolveWithObject: true });
|
||||
let pixels = 0;
|
||||
for (let i = 0; i < data.length; i += info.channels)
|
||||
if (Math.max(data[i], data[i + 1], data[i + 2]) > 150 && data[i + 3] > 127)
|
||||
pixels += 1;
|
||||
return pixels;
|
||||
}
|
||||
|
||||
test('compact badge fill remains legible at its near and far footprints', async () => {
|
||||
assert.equal(WILDLIFE_SPRITE_PX, 20);
|
||||
for (const size of [12, 16, WILDLIFE_SPRITE_PX, 22]) {
|
||||
const flightPixels = await visiblePixels(aircraftIcon('airliner'), size);
|
||||
for (const group of WILDLIFE_SPRITE_GROUPS)
|
||||
assert.ok(
|
||||
(await visiblePixels(sprites.get(group), size)) >= flightPixels,
|
||||
`${group} at ${size}px`,
|
||||
);
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,15 @@
|
||||
/**
|
||||
* @module layers/wildlifeSightings/view
|
||||
* @description What the layer reads of the eye, through the camera port.
|
||||
*/
|
||||
import { findCamera } from '../../render/rendererOf.js';
|
||||
|
||||
/** The eye's height above the ellipsoid, metres; undefined with no camera. */
|
||||
export function wildlifeEyeHeight(viewer) {
|
||||
return viewer ? findCamera(viewer)?.pose().height : undefined;
|
||||
}
|
||||
|
||||
/** The view rectangle in degrees (`viewRectangle()`), or null. */
|
||||
export function wildlifeViewRectangle(viewer) {
|
||||
return (viewer ? findCamera(viewer)?.viewRectangle() : null) ?? null;
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
import {
|
||||
WILDLIFE_MAX_VIEW_DEGREES,
|
||||
WILDLIFE_RETRY_MIN_MS,
|
||||
WILDLIFE_RETRY_MAX_MS,
|
||||
} from './policy.js';
|
||||
|
||||
export { snapWildlifeBox } from './bounds.js';
|
||||
|
||||
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(rectangle) {
|
||||
// `rectangle`: the camera's view rectangle in degrees, or null.
|
||||
if (!rectangle) return null;
|
||||
const box = Object.fromEntries(
|
||||
['south', 'west', 'north', 'east'].map((key) => [
|
||||
key,
|
||||
cleanDegree(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,126 @@
|
||||
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';
|
||||
|
||||
// The camera port's view rectangle is in degrees.
|
||||
const viewer = (rectangle) => rectangle;
|
||||
|
||||
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), null);
|
||||
});
|
||||
|
||||
test('height bands retain representations across +/-5% and switch beyond +/-10%', () => {
|
||||
assert.equal(getWildlifeHeightBand(3_000_001), 'global');
|
||||
assert.equal(getWildlifeHeightBand(3_000_000), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(3_150_000, 'regional'), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(2_850_000, 'global'), 'global');
|
||||
assert.equal(getWildlifeHeightBand(3_310_000, 'regional'), 'global');
|
||||
assert.equal(getWildlifeHeightBand(2_690_000, 'global'), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(1_600_000), 'regional');
|
||||
assert.equal(getWildlifeHeightBand(1_000_000), 'cells');
|
||||
assert.equal(getWildlifeHeightBand(30_000), 'cards');
|
||||
assert.equal(getWildlifeHeightBand(30_000, 'global'), 'cards');
|
||||
});
|
||||
|
||||
test('retry guidance doubles from 30 seconds to a four-minute ceiling', () => {
|
||||
assert.deepEqual(
|
||||
[undefined, 30_000, 60_000, 120_000, 240_000].map(retryDelayMs),
|
||||
[30_000, 60_000, 120_000, 240_000, 240_000],
|
||||
);
|
||||
});
|
||||
Reference in new issue
Block a user