Files
gods-eye-view/src/voice/imageryActions.js
T
Manjunath 40d8839589 fix(voice): localize the area, imagery and OSM cards and tidy OSM Places
From review:
- Card lines the actions write in English (area basis, part counts, merged
  duplicates, OSM caveats, the imagery window) are shown in the UI
  language through the analyst card's note path; the model still gets the
  English. One OSM place reads "1 hospital".
- Same-named clarification choices show their region code (WA, DC).
- OSM Places shows as unavailable once the server says no Overpass is
  configured, and its points are depth-tested past 2.5 km so they never
  show through the globe.
- find_imagery puts the operator's sources and mode back when a box is
  refused, and a voice search cancelled mid-flight leaves "Search
  cancelled" instead of an empty strip.
- The README lists OSM Places with the other Utilities.
2026-11-03 19:36:48 +05:30

406 lines
14 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* `find_imagery`: search the Recent Imagery layer's own catalog for an area,
* pick the best acquisition and show it through the layer's own selection
* (the pinned day in IMAGE mode), so the panel, the map and the answer agree.
*
* The area is an area handle's bounding box, the current view, or a 10 km box
* around a point. "This spot" arrives as that point: the runner resolves the
* `'pointer'` sentinel through the turn's pointer snapshot (deixis.js), with
* the same freshness and session rules as every other pointing tool. The
* layer's box limits apply unchanged: a box it refuses is refused here with
* the layer's own reason.
*
* The panel is the operator's. Voice owns it only from its own box until its
* pin shows; any hand change in between (box, pins, sources or mode) ends the
* request without touching the panel again.
*
* @module voice/imageryActions
*/
import { PRODUCTS, rankLatest } from '../layers/recentImagery/model.js';
import {
displacedLayerResult,
watchExplicitLayerOff,
} from './layerActionOwnership.js';
const LAYER_ID = 'recent-imagery';
/** How long the catalog search may take before the answer says "still searching". */
const SEARCH_WAIT_MS = 20_000;
/** How long to wait for the chosen day's pixels before answering anyway. */
const DRAPE_WAIT_MS = 8_000;
const DAY_MS = 86_400_000;
const round = (value) => Math.round(value);
/** Identity of a selection box, for telling ours from the operator's. */
const boxKey = (box) =>
box
? ['west', 'south', 'east', 'north']
.map((edge) => Number(box[edge]).toFixed(6))
.join(',')
: '';
/**
* Identity of everything the operator can change on the panel: box, both
* pins, sources and mode. Voice records it after each of its own changes;
* any other difference means the operator took the panel back.
*/
export function panelOwnershipKey(snapshot) {
return JSON.stringify([
snapshot?.enabled ?? null,
boxKey(snapshot?.box),
snapshot?.pins?.a?.key ?? null,
snapshot?.pins?.b?.key ?? null,
snapshot?.mode ?? null,
snapshot?.sources ?? null,
]);
}
/**
* Parse `dateRange` into epoch-ms bounds. Accepts `{from, to}` ISO dates or
* `{days}` (the last N days).
* @returns {{from: number, to: number}|null|{error: string}}
*/
export function imageryDateRange(dateRange, now = Date.now()) {
if (!dateRange || typeof dateRange !== 'object') return null;
if (Number.isFinite(Number(dateRange.days)) && Number(dateRange.days) > 0)
return { from: now - Number(dateRange.days) * DAY_MS, to: now };
const from = dateRange.from ? Date.parse(dateRange.from) : -Infinity;
// A bare end date means the whole of that day.
const to = dateRange.to
? Date.parse(dateRange.to) +
(/^\d{4}-\d{2}-\d{2}$/.test(dateRange.to) ? DAY_MS - 1 : 0)
: now;
if (Number.isNaN(from) || Number.isNaN(to))
return { error: 'dateRange needs ISO dates (YYYY-MM-DD) or days.' };
return { from, to };
}
/**
* The candidates that satisfy the filters, ranked by the layer's own rule
* (coverage, then clear sky, then newest).
* @param {Array<object>} candidates Layer snapshot candidates.
* @param {{from?: number, to?: number, maxCloudPct?: number|null, truncated?: boolean}} filters
*/
export function selectImagery(
candidates,
{
from = -Infinity,
to = Infinity,
maxCloudPct = null,
truncated = false,
} = {},
) {
// Compared as UTC days: an acquisition belongs to the day it was taken.
const dayOf = (ms) =>
Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : null;
const first = dayOf(from);
const last = dayOf(to);
const inRange = (candidate) =>
(!first || candidate.day >= first) && (!last || candidate.day <= last);
const cloudOk = (candidate) =>
maxCloudPct === null ||
PRODUCTS[candidate.product]?.overview ||
(candidate.cloud && candidate.cloud.max <= maxCloudPct);
const eligible = (candidates || []).filter(
(c) => c.availability !== 'empty' && inRange(c) && cloudOk(c),
);
const ranked = rankLatest(eligible, {
maxCloud: maxCloudPct ?? undefined,
truncated,
});
return { eligible, best: ranked.candidate, reason: ranked.reason };
}
/** Wait until `test(snapshot)` holds, the time runs out, or the turn is superseded. */
function waitFor(layer, test, { timeoutMs, isCurrent }) {
return new Promise((resolve) => {
let done = false;
let timer = null;
let unsubscribe = () => {};
const finish = (value) => {
if (done) return;
done = true;
clearTimeout(timer);
clearInterval(poll);
unsubscribe();
resolve(value);
};
const check = () => {
if (!isCurrent()) return finish('cancelled');
const snapshot = layer.getSnapshot();
if (test(snapshot)) finish('ready');
};
unsubscribe = layer.subscribe?.(check) || (() => {});
const poll = setInterval(check, 250);
timer = setTimeout(() => finish('timeout'), timeoutMs);
check();
});
}
/**
* Run one `find_imagery` call.
* @param {object} deps
* @param {object} deps.dataManager
* @param {object} deps.viewer
* @param {(areaId: string) => object|null} deps.getArea Stored area by id.
* @param {(enabled: boolean) => Promise<object>} deps.enableLayer set_layer_visibility for the layer.
* @param {(step: string, label?: string) => void} [deps.progress] Step reports.
* @param {object} args Tool arguments; `center` ({lat, lon}) is the resolved
* pointer, never a model argument.
* @param {{isCurrent?: () => boolean, signal?: AbortSignal}} [options]
*/
export async function findImagery(
{
dataManager,
viewer,
getArea,
enableLayer,
progress = () => {},
now = () => Date.now(),
},
args = {},
{ isCurrent = () => true, signal = null } = {},
) {
const fail = (code, error, extra = {}) => ({
ok: false,
action: 'find_imagery',
code,
error,
...extra,
});
const current = () => !signal?.aborted && isCurrent();
const layer = dataManager?.layers?.get(LAYER_ID)?.module;
if (!layer?.setBox || !layer?.getSnapshot)
return fail(
'LAYER_UNAVAILABLE',
'The Recent Imagery layer is not available.',
);
const range = imageryDateRange(args.dateRange, now());
if (range?.error) return fail('BAD_VALUE', range.error);
const maxCloudPct =
args.maxCloudPct === undefined || args.maxCloudPct === null
? null
: Math.max(0, Math.min(100, Number(args.maxCloudPct)));
if (maxCloudPct !== null && !Number.isFinite(maxCloudPct))
return fail('BAD_VALUE', 'maxCloudPct must be 0–100.');
// The area, resolved before anything changes on screen.
const center =
Number.isFinite(args.center?.lat) && Number.isFinite(args.center?.lon)
? { lat: args.center.lat, lon: args.center.lon }
: null;
const where = args.areaId ? 'area' : center ? 'point' : 'view';
// An unresolved sentinel never searches the view in its place.
if (!args.areaId && !center && args.area === 'pointer')
return fail('NO_POINTER', 'Point at the spot on the map first.');
let box = null;
let areaName = null;
if (where === 'area') {
const record = getArea(args.areaId);
if (!record)
return fail(
'AREA_UNKNOWN',
`No area "${args.areaId}" on this page — call resolve_area again.`,
);
const [west, south, east, north] = record.bbox;
if (west > east)
return fail(
'DATELINE',
`${record.name} crosses the date line; the imagery box needs one side of it.`,
);
// 30 m pixels over a landmark-sized area show a handful of blobs: a small
// area gets the layer's own 10 km box around its centre instead.
const small =
(north - south) * 111 < 5 &&
(east - west) * 111 * Math.cos((((north + south) / 2) * Math.PI) / 180) <
5;
box = small
? { pin: { lon: (west + east) / 2, lat: (south + north) / 2 } }
: { west, south, east, north };
areaName = record.name;
} else if (where === 'point') {
box = { pin: center };
areaName = args.centerLabel
? String(args.centerLabel)
: 'the spot under the pointer';
}
if (!current())
return fail('CANCELLED', 'This request was superseded.', {
cancelled: true,
});
const offWatch = watchExplicitLayerOff(dataManager, LAYER_ID);
let stopCallerAbort = () => {};
const displaced = () =>
offWatch.requested()
? displacedLayerResult(
dataManager,
LAYER_ID,
'find_imagery',
'Recent Imagery was turned off while I searched, so I left it off and discarded the result.',
)
: fail(
'DISPLACED',
'The imagery panel was changed by hand while I searched, so I left it as it is.',
{ cancelled: true, ...(areaName ? { area: areaName } : {}) },
);
try {
if (!dataManager.isEnabled?.(LAYER_ID)) {
const enabled = await enableLayer(true);
if (offWatch.requested()) return displaced();
if (!current())
return fail('CANCELLED', 'This request was superseded.', {
cancelled: true,
});
if (enabled?.ok === false)
return fail(
'LAYER_OFF',
enabled.error || 'Recent Imagery could not be turned on.',
);
}
const sources =
args.source === 'hls'
? { hls: true, viirs: false }
: args.source === 'viirs'
? { hls: false, viirs: true }
: args.source === 'any'
? { hls: true, viirs: true }
: { hls: true };
// The operator's own settings, put back if the box is refused.
const before = layer.getSnapshot();
layer.setSources(sources);
layer.setMode?.('image');
const accepted = box?.pin
? layer.boxFromPinAt(box.pin.lon, box.pin.lat)
: box
? layer.setBox(box)
: layer.useCurrentView(viewer);
if (!accepted) {
const reason =
layer.getSnapshot().boxError || 'That area cannot be searched.';
if (before?.sources) layer.setSources(before.sources);
if (before?.mode) layer.setMode?.(before.mode);
return fail('BOX_REFUSED', `${reason}. Zoom in or pick a smaller area.`, {
...(areaName ? { area: areaName } : {}),
});
}
// This request owns the panel state it just set. The operator can take
// the panel back at any moment (a new box, CLEAR, a pin, a source or mode
// switch); from then on it is theirs and this request stops without
// touching it. Checked in every wait and before every write.
let owned = panelOwnershipKey(layer.getSnapshot());
const isOurs = (snap) =>
!offWatch.requested() && panelOwnershipKey(snap) === owned;
const cancelOwnedSearch = () => {
if (isOurs(layer.getSnapshot())) layer.cancelPendingSearch?.();
};
signal?.addEventListener?.('abort', cancelOwnedSearch, { once: true });
stopCallerAbort = () =>
signal?.removeEventListener?.('abort', cancelOwnedSearch);
if (signal?.aborted) cancelOwnedSearch();
progress('catalog', areaName || 'the view');
const searched = await waitFor(
layer,
(snap) => !snap.searching || !isOurs(snap),
{ timeoutMs: SEARCH_WAIT_MS, isCurrent: current },
);
if (searched === 'cancelled')
return fail('CANCELLED', 'This request was superseded.', {
cancelled: true,
});
let snapshot = layer.getSnapshot();
if (!isOurs(snapshot)) return displaced();
if (searched === 'timeout' || snapshot.searching)
return fail(
'SEARCH_TIMEOUT',
'The imagery catalog is slow — the panel will fill in when it answers.',
);
if (snapshot.error && !snapshot.candidates.length)
return fail('CATALOG_UNAVAILABLE', snapshot.error);
const { eligible, best } = selectImagery(snapshot.candidates, {
...(range || {}),
maxCloudPct,
truncated: snapshot.notes?.some((note) => /truncated/i.test(note)),
});
const windowNote = 'the catalog covers the last 30 days';
if (!best) {
return {
ok: true,
action: 'find_imagery',
count: 0,
total: snapshot.candidates.length,
shown: null,
say: `No imagery matches${maxCloudPct !== null ? ` under ${maxCloudPct}% cloud` : ''} — ${windowNote}.`,
display: { window: windowNote },
};
}
// Re-checked at the commit: the candidate list must still be this box's.
if (!current())
return fail('CANCELLED', 'This request was superseded.', {
cancelled: true,
});
if (!isOurs(layer.getSnapshot())) return displaced();
const pinned =
layer.setAssignment('a', best.key) ||
layer.getSnapshot().pins?.a?.key === best.key;
owned = panelOwnershipKey(layer.getSnapshot());
if (!pinned)
return fail(
'PIN_REJECTED',
`The ${best.day} acquisition could not be shown — it has no pixels over this area.`,
);
const pinIsOurs = (snap) => isOurs(snap) && snap.pins?.a?.key === best.key;
progress('drape', best.day);
const draped = await waitFor(
layer,
(snap) => snap.shown?.a === best.key || !pinIsOurs(snap),
{ timeoutMs: DRAPE_WAIT_MS, isCurrent: current },
);
if (draped === 'cancelled')
return fail('CANCELLED', 'This request was superseded.', {
cancelled: true,
});
snapshot = layer.getSnapshot();
// A pin the operator replaced, or the layer dropped as empty, is not "still
// loading" — it is not ours any more.
if (!pinIsOurs(snapshot)) return displaced();
const onMap = snapshot.shown?.a === best.key;
const product = PRODUCTS[best.product];
const cloudPct = best.cloud ? round(best.cloud.max) : null;
// The catalog stops at its record cap; say so rather than imply it is all.
const capped = snapshot.notes?.find((note) => /truncated/i.test(note));
const date = best.timeRange?.start || best.day;
return {
ok: true,
action: 'find_imagery',
count: eligible.length,
total: snapshot.candidates.length,
shown: {
date: best.day,
source: product?.name || best.product,
resolutionM: product?.resolutionM ?? null,
cloudPct,
onMap,
},
...(areaName ? { area: areaName } : {}),
say: `${product?.name || best.product} from ${best.day}${cloudPct !== null ? `, ${cloudPct}% cloud` : ''}${onMap ? '' : ' — still loading'}`,
display: {
acquired: date,
window: windowNote,
...(capped ? { caveat: capped } : {}),
...(snapshot.pins?.a?.label ? { label: snapshot.pins.a.label } : {}),
},
};
} finally {
stopCallerAbort();
offWatch.stop();
}
}