Files
gods-eye-view/src/layers/wildlifeSightings/records.js
T
Sameh Khamis 3cb30c3f97 fix(wildlife): point the Acartia card link only at acartia.io
The card's "Acartia" link was built from the contributor-supplied
photo_url, so any https site could appear labelled as Acartia. Acartia
has no documented per-sighting page, so the source link is now always
the Acartia site, on the server projection and again in the card.
The separate "Open on Acartia" fallback link is no longer needed.
2026-11-05 16:05:02 -08:00

342 lines
12 KiB
JavaScript

// 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()];
}