Files
gods-eye-view/src/layers/wildlifeSightings/density.test.mjs
T
Yehe LiuandClaude Opus 5.5 14f88b3e08 feat: Wildlife Sightings layer from iNaturalist and Acartia
Recent community wildlife observations, as a new Wildlife group in the
layer panel.

- Server: keyless iNaturalist proxy (v2 observations with only the
  projected fields; undocumented v1 UTFGrid density tiles, decoded on the
  server) sharing one paced queue (burst 4, ~1/s, 60/min, 8,000/day budget,
  up to four in flight), in-memory caches and upstream-only cooldowns;
  Acartia Salish Sea marine-mammal feed rounded to 0.01 degrees with
  comments dropped.
- Layer: grid counts drawn as a soft view-ranked density glow; real sampled
  sightings as taxon badges at their true positions with ambient photo
  thumbnails and labels; obscured records stay privacy cells; a clicked
  sighting stays pinned through camera moves and refreshes.
- Anchored photo card per selection with the single iNaturalist link;
  attribution in the layer row and the Data attribution popover.
- Filters (CONFIRMED, taxa presets) round-trip in share links with token 9.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-05 16:17:12 -05:00

509 lines
16 KiB
JavaScript

import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import { wildlifeGridCellBounds } from './gridViewport.js';
import {
createWildlifeDensity,
wildlifeDensityIntensity,
wildlifeDensityRanks,
wildlifeDensityKernel,
WILDLIFE_DENSITY_MAX_ALPHA,
WILDLIFE_DENSITY_NEAR_FADE,
WILDLIFE_DENSITY_OVERLAP,
} from './density.js';
import { WILDLIFE_WORK_UNIT } from './performance.js';
function cell(column, count = 1, options = {}) {
const id = `grid:3/4/2:31:${column * 2 + 1}`;
const bounds = wildlifeGridCellBounds(id);
return {
id,
lat: (bounds.south + bounds.north) / 2,
lon: (bounds.west + bounds.east) / 2,
cellCount: count,
...options,
};
}
function harness({ documentStyle = 'normal', camera = {} } = {}) {
const counts = { positions: 0, writes: 0, created: 0, updates: 0 };
class BillboardCollection extends Cesium.BillboardCollection {
add(options) {
counts.created++;
const point = super.add(options);
return new Proxy(point, {
get: (target, key) => Reflect.get(target, key, target),
set(target, key, value) {
counts.writes++;
return Reflect.set(target, key, value, target);
},
});
}
update() {
counts.updates++;
}
}
const primitives = new Cesium.PrimitiveCollection();
let handle = 0;
const timers = new Map();
const idle = new Map();
const renders = [];
const listeners = new Map();
const eventTarget = {
addEventListener(name, listener) {
if (!listeners.has(name)) listeners.set(name, new Set());
listeners.get(name).add(listener);
},
removeEventListener(name, listener) {
listeners.get(name)?.delete(listener);
},
emit(name, detail) {
for (const listener of listeners.get(name) || []) listener({ detail });
},
};
const density = createWildlifeDensity({
cesium: { ...Cesium, BillboardCollection },
viewer: { scene: { primitives }, camera },
positionForCell(row) {
counts.positions++;
return Cesium.Cartesian3.fromDegrees(row.lon, row.lat);
},
requestRender: (reason) => renders.push(reason),
setTimer(fn) {
timers.set(++handle, fn);
return handle;
},
clearTimer: (id) => timers.delete(id),
requestIdle(fn) {
idle.set(++handle, fn);
return handle;
},
cancelIdle: (id) => idle.delete(id),
eventTarget,
documentRef: { documentElement: { dataset: { gevStyle: documentStyle } } },
});
function flushIdle() {
while (idle.size) {
const [id, fn] = idle.entries().next().value;
idle.delete(id);
fn();
}
}
function fadeStep() {
for (const [id, fn] of [...timers]) {
timers.delete(id);
fn();
}
flushIdle();
}
return {
density,
primitives,
counts,
renders,
timers,
idle,
listeners,
eventTarget,
flushIdle,
fadeStep,
settle() {
while (timers.size || idle.size) {
fadeStep();
flushIdle();
}
},
};
}
test('density intensity rises with view rank, is bounded, and leaves no background for zero data', () => {
for (const empty of [0, -1, null, undefined, NaN, Infinity])
assert.equal(wildlifeDensityIntensity(empty), 0);
const ranks = [0.01, 0.1, 0.25, 0.5, 0.75, 0.9, 1];
const values = ranks.map(wildlifeDensityIntensity);
assert.ok(values[0] > 0, 'the sparsest cell still leaves a trace');
assert.ok(values[0] < 0.02, 'sparse cells stay a trace, not a haze');
for (let i = 1; i < values.length; i++) assert.ok(values[i] > values[i - 1]);
assert.equal(values.at(-1), WILDLIFE_DENSITY_MAX_ALPHA);
assert.ok(
values[3] < WILDLIFE_DENSITY_MAX_ALPHA / 3,
'a median cell is well below a hotspot',
);
});
test('density ranks are relative to the view, so hotspots stay distinct at any zoom', () => {
const cells = (counts) => counts.map((cellCount) => ({ cellCount }));
const near = wildlifeDensityRanks(cells([1, 2, 3, 40]));
const far = wildlifeDensityRanks(cells([100, 200, 300, 4000]));
assert.equal(near(40), 1);
assert.equal(far(4000), 1, 'the top cell is brightest whatever its count');
assert.equal(near(1), far(100), 'the same position ranks the same');
assert.equal(wildlifeDensityRanks(cells([0, -1]))(5), 0);
assert.equal(wildlifeDensityRanks([])(5), 0);
});
test('an empty density snapshot creates no glow', () => {
const h = harness();
assert.deepEqual(h.density.update([]), {
sightingCount: 0,
changed: false,
size: 0,
});
h.density.update([
cell(0, 0),
cell(1, -1),
cell(2, 0.5),
cell(3, 1, { id: 'invalid' }),
]);
assert.equal(h.density.collection, null);
assert.equal(h.primitives.length, 0);
assert.equal(h.timers.size, 0);
h.density.destroy();
});
test('uniform occupied cells make a continuous field with no visible lattice', () => {
assert.ok(WILDLIFE_DENSITY_OVERLAP >= 1.5);
assert.equal(wildlifeDensityKernel(0), 1);
assert.equal(wildlifeDensityKernel(WILDLIFE_DENSITY_OVERLAP / 2), 0);
const samples = [];
for (let x = 0; x < 1; x += 0.1)
for (let y = 0; y < 1; y += 0.1) {
let value = 0;
for (let dx = -3; dx <= 3; dx++)
for (let dy = -3; dy <= 3; dy++)
value += wildlifeDensityKernel(Math.hypot(x - dx, y - dy));
samples.push(value);
}
const modulation =
(Math.max(...samples) - Math.min(...samples)) / Math.max(...samples);
assert.ok(modulation < 0.007, `${(100 * modulation).toFixed(3)}% modulation`);
});
test('each glow kernel fades on the GPU as the camera comes inside it, scaled to its own width', () => {
const h = harness();
h.density.update([cell(0, 4), cell(1, 9)]);
const collection = h.density.collection;
assert.equal(collection.length, 2);
for (let i = 0; i < collection.length; i++) {
const point = collection.get(i);
const width = point.scale * point.width;
const fade = point.translucencyByDistance;
assert.ok(fade, 'no screen-filling kernel when zoomed inside it');
assert.ok(
Math.abs(fade.near - width * WILDLIFE_DENSITY_NEAR_FADE.near) < 1e-6,
);
assert.equal(fade.nearValue, 0);
assert.ok(
Math.abs(fade.far - width * WILDLIFE_DENSITY_NEAR_FADE.far) < 1e-6,
);
assert.equal(fade.farValue, 1);
}
h.density.destroy();
});
test('occupied grid counts produce unlabelled world-sized glow billboards that never enter Cesium picking', () => {
const h = harness();
const rows = [cell(0, 1), cell(1, 100), cell(2, 1000000)];
const result = h.density.update(rows);
assert.equal(result.sightingCount, 1000101);
assert.equal(h.primitives.length, 1);
const collection = h.density.collection;
assert.equal(collection.allowPicking, false);
assert.equal(collection.length, 3);
const first = collection.get(0);
assert.equal(
first.id,
undefined,
'density has no sighting identity or pick payload',
);
assert.equal(first.sizeInMeters, true);
assert.equal(first.scaleByDistance, undefined);
assert.match(decodeURIComponent(first.image), /radialGradient/);
assert.doesNotMatch(decodeURIComponent(first.image), /text|badge|raven/);
const bounds = wildlifeGridCellBounds(rows[0].id);
const logicalHeight =
(((bounds.north - bounds.south) * Math.PI) / 180) * 6378137;
assert.ok(first.width * first.scale >= 1.5 * logicalHeight);
assert.equal(first.width, first.height);
assert.ok(
first.width <= 65536,
'encoded dimensions fit Cesium width packing',
);
assert.ok(
first.width * first.scale > 65536,
'continental splats retain their true footprint through scale',
);
collection.update({ passes: { pick: true } });
assert.equal(
h.counts.updates,
0,
'the real public pick update is suppressed',
);
collection.update({ passes: { render: true } });
assert.equal(h.counts.updates, 1);
h.settle();
const rankOf = wildlifeDensityRanks(rows);
for (let i = 0; i < collection.length; i++)
assert.ok(
Math.abs(
collection.get(i).color.alpha -
wildlifeDensityIntensity(rankOf(rows[i].cellCount)),
) < 1e-12,
);
h.density.destroy();
});
test('progressive tile arrival fades only new cells and reuses existing glow without flashing', () => {
const h = harness();
const one = cell(0, 4);
const two = cell(1, 10);
h.density.update([one]);
const first = h.density.collection.get(0);
const starting = first.color.alpha;
h.fadeStep();
assert.ok(first.color.alpha > starting);
const middle = first.color.alpha;
h.density.update([one, two]);
// The arriving tile re-ranks the incumbent (alone it was the hotspot; now
// it is the median) but its fade progress is kept, not restarted.
const progress = middle / wildlifeDensityIntensity(1);
assert.ok(
Math.abs(first.color.alpha - wildlifeDensityIntensity(0.5) * progress) <
1e-12,
'a streamed tile re-ranks but does not restart incumbents',
);
assert.equal(h.density.collection.get(0), first);
assert.equal(h.density.size, 2);
h.settle();
const settled = first.color.alpha;
h.density.update([one, two]);
assert.equal(first.color.alpha, settled);
h.density.update([two]);
assert.equal(h.density.size, 1);
assert.equal(h.density.collection.length, 1);
h.density.update([]);
assert.equal(h.density.size, 0);
assert.equal(
h.density.collection,
null,
'empty data releases the atlas and collection',
);
assert.equal(
h.primitives.length,
0,
'no full-view fill remains over empty data',
);
h.density.destroy();
});
test('visibility and antimeridian padding are applied on data/moveEnd work only', () => {
const h = harness();
const west = cell(1);
const east = cell(28);
const box = { ...wildlifeGridCellBounds(west.id) };
assert.equal(h.density.update([west, east], { boxes: [box] }).size, 1);
assert.equal(
h.density.update([west], { boxes: [box], isPointVisible: () => false })
.size,
0,
);
const id = 'grid:3/0/2:31:1';
const bounds = wildlifeGridCellBounds(id);
const wrapped = {
...west,
id,
lat: (bounds.south + bounds.north) / 2,
lon: -179.3,
};
const crossed = {
south: bounds.south,
north: bounds.north,
west: 179,
east: -179,
};
assert.equal(h.density.update([wrapped], { boxes: [crossed] }).size, 1);
h.density.destroy();
});
test('density culls far-side cells and front-side kernels that would spill over the limb', () => {
const camera = {
positionWC: Cesium.Cartesian3.fromDegrees(0, 0, 5_000_000),
positionCartographic: { height: 5_000_000 },
};
const h = harness({ camera });
const occluder = new Cesium.EllipsoidalOccluder(
Cesium.Ellipsoid.WGS84,
camera.positionWC,
);
const cells = [
cell(0, 1, { lat: 0, lon: 0 }),
cell(1, 2, { lat: 0, lon: 54 }),
cell(2, 4, { lat: 0, lon: 110 }),
];
assert.equal(
occluder.isPointVisible(Cesium.Cartesian3.fromDegrees(54, 0)),
true,
'the limb fixture has a visible centre but an overflowing footprint',
);
const result = h.density.update(cells, {
isPointVisible: (anchor) => occluder.isPointVisible(anchor),
});
assert.equal(result.size, 1, 'only the fully front-side kernel can glow');
assert.equal(
result.sightingCount,
3,
'visual limb padding never removes visible counts',
);
h.density.destroy();
});
test('density fades from regional detail to a clear whole-globe view without frame work or count loss', () => {
const camera = { positionCartographic: { height: 3_000_000 } };
const h = harness({ camera });
const cells = [cell(0, 12)];
h.density.update(cells);
h.settle();
const point = h.density.collection.get(0);
const fullAlpha = point.color.alpha;
camera.positionCartographic.height = 5_500_000;
h.density.update(cells);
assert.equal(h.density.collection.get(0), point);
assert.ok(Math.abs(point.color.alpha - fullAlpha / 2) < 1e-12);
const writes = h.counts.writes;
h.density.update(cells);
assert.equal(h.counts.writes, writes, 'unchanged height writes nothing');
camera.positionCartographic.height = 8_000_000;
assert.equal(h.density.update(cells).sightingCount, 12);
assert.equal(h.density.collection, null);
assert.equal(h.timers.size, 0, 'no invisible fade or frame loop');
const positions = h.counts.positions;
camera.positionCartographic.height = 3_000_000;
h.density.update(cells);
h.settle();
assert.equal(
h.counts.positions,
positions,
'altitude changes reuse decoded positions',
);
assert.equal(h.density.collection.get(0).color.alpha, fullAlpha);
h.density.destroy();
});
test('styles follow persisted mono/CRT and cockpit vision overrides, without adding a second ramp', () => {
const h = harness({ documentStyle: 'thermal' });
h.density.update([cell(0)]);
h.settle();
const point = h.density.collection.get(0);
assert.equal(point.color.red, point.color.green);
assert.equal(point.color.green, point.color.blue);
const alpha = point.color.alpha;
h.eventTarget.emit('gev:style-change', { style: 'retro' });
h.flushIdle();
assert.ok(point.color.green > point.color.red);
h.eventTarget.emit('gev:vision-change', { cockpit: true, style: 'nvg' });
h.flushIdle();
assert.equal(point.color.red, point.color.green);
h.eventTarget.emit('gev:style-change', { style: 'normal' });
h.flushIdle();
assert.equal(
point.color.red,
point.color.green,
'cockpit vision wins while active',
);
h.eventTarget.emit('gev:vision-change', { cockpit: false, style: 'normal' });
h.flushIdle();
assert.notEqual(point.color.red, point.color.green);
assert.equal(point.color.alpha, alpha);
h.density.destroy();
});
test('clear/disable and destroy release the atlas, primitives, coordinates, timers and listeners', () => {
const h = harness();
const row = cell(0);
h.density.update([row]);
const old = h.density.collection;
assert.equal(h.timers.size, 1);
h.fadeStep();
h.density.clear();
assert.equal(old.isDestroyed(), true);
assert.equal(h.density.collection, null);
assert.equal(h.density.size, 0);
assert.equal(h.primitives.length, 0);
assert.equal(h.timers.size, 0);
assert.equal(h.idle.size, 0);
for (const values of h.listeners.values()) assert.equal(values.size, 0);
const priorPositions = h.counts.positions;
h.density.update([row]);
assert.equal(
h.counts.positions,
priorPositions + 1,
'disable released cached coordinates',
);
const work = h.density.updateWork([cell(2)]);
work.next();
h.density.destroy();
assert.equal(
work.next().done,
true,
'obsolete data work cannot resurrect a destroyed layer',
);
assert.equal(h.density.collection, null);
assert.equal(h.primitives.length, 0);
assert.equal(h.timers.size, 0);
assert.equal(h.idle.size, 0);
});
test('dense six-tile updates have a deterministic linear operation budget and no warmed writes/projections', (t) => {
const h = harness();
const cells = [];
for (let x = 1; x < 3; x++)
for (let y = 1; y < 4; y++)
for (let row = 1; row < 64; row += 2)
for (let column = 1; column < 64; column += 2) {
const id = `grid:3/${x}/${y}:${row}:${column}`;
const box = wildlifeGridCellBounds(id);
cells.push({
id,
lat: (box.south + box.north) / 2,
lon: (box.west + box.east) / 2,
cellCount: row * 64 + column,
});
}
let operations;
h.density.update(cells, {
onOperations: (value) => {
operations = value;
},
});
h.settle();
assert.equal(operations.densityVisits, 6144);
assert.equal(operations.densityMetadataBuilds, 6144);
assert.equal(operations.densityPositionBuilds, 6144);
assert.equal(operations.densityCreated, 6144);
const positions = h.counts.positions;
const writes = h.counts.writes;
let units = 0;
const work = h.density.updateWork(cells, {
onOperations: (value) => {
operations = value;
},
});
while (!work.next().done) units++;
assert.deepEqual(operations, {
densityVisits: 6144,
densityRetirementVisits: 6144,
densityMetadataBuilds: 0,
densityPositionBuilds: 0,
densityWrites: 0,
densityCreated: 0,
densityRemoved: 0,
});
assert.equal(units, Math.ceil(6144 / WILDLIFE_WORK_UNIT) * 2);
assert.equal(h.counts.positions, positions);
assert.equal(h.counts.writes, writes);
t.diagnostic(
`6,144 occupied cells: ${units} bounded units, 12,288 linear visits, zero warmed metadata/Cartesian builds, projections or billboard writes`,
);
h.density.destroy();
});