Files
gods-eye-view/src/layers/wildlifeSightings/model.js
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

209 lines
6.3 KiB
JavaScript

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;
}