A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.
JavaScript 3d-globecesiumflight-trackinggeospatialgeospatial-intelligencegisosintphotogrammetrysatellite-trackingspatial-intelligencewebglworldview
import { isUnavailableCapability } from '../sources/capability.js';
import { defaultGeospatial } from '../search/defaults.js';
import * as Cesium from 'cesium';
import { greatCircleMeters } from '../geoDistance.js';
import {
holdContinuousRender,
releaseContinuousRender,
} from '../renderGovernor.js';
import {
isRateLimitedOutcome,
resolveAnnotationTarget,
sampleGroundHeight,
} from './annotationResolver.js';
import { ringCentroid } from './drawMode.js';
// Dev convenience: expose the app's Cesium instance for console/preview probing
// (single shared module instance — avoids dual-Cesium state bugs when testing).
if (typeof window !== 'undefined' && !window.__CESIUM__)
window.__CESIUM__ = Cesium;
/**
* Annotation engine — the voice agent's "whiteboard" over the 3D world.
*
* Responsibilities:
* - resolve voice annotation requests (names → world anchors + footprints)
* - own annotation state and the ephemeral fade-out lifecycle
* - delegate drawing to a pluggable renderer (world-space or screen-space)
*
* The data model is always world-anchored (lon/lat), so annotations track the
* camera and persist across moves regardless of which renderer draws them.
*/
let _seq = 0;
const COLORS = new Set(['primary', 'amber', 'cyan', 'green', 'red']);
// Entity FACTS the voice model may attach to an annotation (annotate_map.entityKind) —
// what kind of thing the target IS, routing the resolver (e.g. point_feature keeps a
// monument point-first). Unknown values are dropped, never guessed.
const ENTITY_KINDS = new Set([
'building',
'compound',
'district',
'street',
'point_feature',
]);
const DEFAULT_TTL_MS = 22_000;
const FADE_MS = 1200;
// Hard ceiling on simultaneously-live marks. Protects against a runaway voice
// session (or a bad model call that keeps appending) from accumulating unbounded
// Cesium entities + SVG nodes. Persistent marks accumulate until cleared.
const MAX_LIVE_ANNOTATIONS = 120;
// Deferred-outline retry backoff. A TRANSIENT Overpass failure (slow mirror, network
// blip) aborts the client fetch, but the /api/overpass proxy keeps the upstream
// request going and caches the late completion — so a re-run ~8 s later is usually a
// warm cache hit, and one more at ~25 s covers a genuinely slow mirror. A DEFINITIVE
// no-polygon answer is never retried.
const OUTLINE_RETRY_DELAYS_MS = [8000, 25000];
const OUTLINE_UPGRADE_CONCURRENCY = 2;
/**
* Run a deferred-outline resolver with transient-retry backoff. Tri-state contract
* (same as resolveAnnotationTarget's resolveOutline):
* footprint object — resolved;
* null — DEFINITIVE no-polygon (never retried; the honest point stands);
* undefined — TRANSIENT failure (re-run once per delaysMs entry, then give up);
* rate-limit object — OVERPASS THROTTLE (one retry, honoring Retry-After + ladder).
* `isStale()` is consulted after each backoff wait so a cleared/superseded board stops
* retrying immediately. A thrown resolver counts as definitive — the pre-retry
* catch→point behavior. Exported for tests.
*/
export async function resolveOutlineWithRetry(
resolveOutline,
{
delaysMs = OUTLINE_RETRY_DELAYS_MS,
isStale = () => false,
waitFn = wait,
} = {},
) {
let retriedRateLimit = false;
for (let attempt = 0; ; attempt += 1) {
let fp;
try {
fp = await resolveOutline();
} catch {
fp = null; // hard failure — definitive, keep the honest point
}
if (isUnavailableCapability(fp)) return fp;
if (isRateLimitedOutcome(fp)) {
// A throttle gets one deliberately spaced retry. If that retry is throttled
// too, stop this mark's outline task instead of replaying the batch storm.
if (retriedRateLimit || attempt >= delaysMs.length) return undefined;
const retryAfterMs = Number.isFinite(fp.retryAfterMs)
? fp.retryAfterMs
: 0;
await waitFn(Math.max(retryAfterMs, delaysMs[attempt]));
if (isStale()) return undefined;
retriedRateLimit = true;
continue;
}
if (fp !== undefined) return fp;
if (attempt >= delaysMs.length) return undefined; // transient budget exhausted
await waitFn(delaysMs[attempt]);
if (isStale()) return undefined; // board cleared/superseded mid-backoff
}
}
/**
* Pending-phase dedup key for a NAMED target: lowercased, trimmed, and stripped of
* trailing comma-separated locality qualifiers — so "California" and "California,
* United States" are the same asked-for THING while their outlines resolve. Identity
* becomes GEOMETRY the moment the outline lands; this key is only the stand-in while
* geometry is unknown. Exported for tests.
*/
export function normalizeTargetKey(target) {
const raw = String(target ?? '')
.trim()
.toLowerCase();
if (!raw) return null;
const head = raw.split(',')[0].trim();
return head || raw;
}
export function createAnnotationEngine({
placeSearch = defaultGeospatial,
viewer,
renderer,
outlineRetryDelaysMs = OUTLINE_RETRY_DELAYS_MS,
resolveTarget = resolveAnnotationTarget,
}) {
/** @type {Map<string, object>} live annotations keyed by id */
const annotations = new Map();
let destroyed = false;
let tickHandle = null;
let assistFlightUntil = 0; // camera-assist debounce (see ensureMarksVisible)
// Generation token + in-flight fetch controllers guard against clear / new-topic
// races: a slow resolve belonging to a superseded annotate() call must never
// draw after a clear() (or after a newer clearPrevious) has wiped the board.
let generation = 0;
const activeControllers = new Set();
// Outline upgrades are intentionally narrower than the concurrent anchor phase:
// points render immediately, then expensive Overpass continuations drain FIFO.
const outlineQueue = [];
let activeOutlineUpgrades = 0;
// Deferred-outline lifecycle listeners (the voice layer): notified ONCE per upgrade
// task with the FINAL outcome — resolved or failed — so narration that said
// "tracing the boundary now" can later honestly confirm or correct itself.
const outlineListeners = new Set();
function emitOutlineEvent(evt) {
for (const listener of outlineListeners) {
try {
listener(evt);
} catch {
/* a listener error must never break the upgrade */
}
}
}
function abortPending() {
for (const c of activeControllers) {
try {
c.abort();
} catch {
/* no-op */
}
}
activeControllers.clear();
}
function dropQueuedOutlineUpgrades() {
while (outlineQueue.length) {
const task = outlineQueue.shift();
if (task.anno._outlineTask === task) task.anno._outlineTask = null;
releaseController(task.controller);
}
}
// A controller stays abortable (in activeControllers) while its annotate() call OR any
// progressive outline-upgrade task it spawned is still running — clear() must be able to
// abort in-flight Overpass fetches even after the tool result has already returned.
function retainController(c) {
c._retain = (c._retain || 0) + 1;
activeControllers.add(c);
}
function releaseController(c) {
c._retain = (c._retain || 0) - 1;
if (c._retain <= 0) activeControllers.delete(c);
}
// World annotations carry persistent per-frame scene animation (pulsing
// live colors, camera-scaled rings, route-flow uniforms in the renderer),
// so the scene must render continuously while any mark exists. (perf wave 2)
function syncAnnotationHold() {
if (annotations.size > 0) holdContinuousRender('annotations');
else releaseContinuousRender('annotations');
}
/**
* Undo a renderer add that threw PART-WAY through. The renderers build a mark
* across two sub-renderers / several DOM inserts, so a throw can leave world
* geometry or an SVG group behind that the engine's map rollback alone cannot
* reach — and the next annotate of the same geometry would then stack a fresh
* mark over the orphan. remove() tolerates partial and absent state, so this
* is safe to call unconditionally; it must never mask the original failure.
* (review round 2)
* @param {object} anno
* @returns {void}
*/
function rollbackRendererState(anno) {
try {
renderer.remove(anno);
} catch {
/* the renderer is already in a bad way; the original error wins */
}
}
function ensureTicking() {
if (destroyed || tickHandle != null) return;
const tick = () => {
const now = performance.now();
let changed = false;
let pending = false; // any mark still fading in / out, or with a TTL fade ahead
for (const anno of annotations.values()) {
const next = computeAlpha(anno, now);
if (next !== anno.alpha) {
anno.alpha = next;
changed = true;
}
if (anno.alpha <= 0 && anno.expiring) {
annotations.delete(anno.id);
renderer.remove(anno);
changed = true;
continue;
}
if (pendingAnimation(anno, now)) pending = true;
}
if (changed) {
renderer.sync(annotations);
syncAnnotationHold();
}
// Stop once the board is STABLE — persistent marks (persist=true is the default)
// finish fading in after ~260ms and never change again, so without this the loop
// would spin O(N) every frame forever. ensureTicking() restarts on the next
// add() or fadeOutAll().
if (annotations.size === 0 || !pending) {
cancelAnimationFrame(tickHandle);
tickHandle = null;
return;
}
tickHandle = requestAnimationFrame(tick);
};
tickHandle = requestAnimationFrame(tick);
}
/**
* Draw one or more annotations.
*
* @param {Array<object>} requests Raw annotation specs from the voice tool.
* @param {object} [opts]
* @param {boolean} [opts.clearPrevious]
* @param {boolean} [opts.persist] Keep until cleared (default true).
* @param {boolean} [opts.flyTo] Frame the first resolved annotation.
* @returns {Promise<{ok, drawn, failed, ids, results}>}
*/
async function annotate(requests, opts = {}) {
if (destroyed)
return {
ok: false,
drawn: 0,
failed: 0,
ids: [],
results: [],
error: 'destroyed',
};
const list = Array.isArray(requests) ? requests : [requests];
if (opts.clearPrevious) clear(); // bumps generation + aborts older pending work
const persist = opts.persist !== false;
// Per-call cancellation: bumped/aborted by any later clear() or destroy().
const controller = new AbortController();
retainController(controller);
const myGen = generation;
const superseded = () => myGen !== generation || controller.signal.aborted;
const results = [];
const ids = [];
let firstAnchor = null;
let capped = false;
// Resolve ALL items CONCURRENTLY (each resolveSpec is a chain of slow geocode/Overpass/Places
// fetches). Serial awaits made a list of monuments take ~a minute and time out the voice call.
// allSettled gives per-item error isolation (one failed item never aborts the batch); the
// mutation pass below then runs in ORDER, so de-dup, the synchronous live-cap check, and output
// order are all preserved exactly as the old serial loop had them.
const settled = await Promise.allSettled(
list.map((spec) =>
resolveSpec(spec, controller.signal, opts.flyTo === true),
),
);
try {
for (let i = 0; i < list.length; i += 1) {
const spec = list[i];
const outcome = settled[i];
if (superseded()) break;
try {
if (outcome.status === 'rejected') throw outcome.reason; // resolution threw → same path as before
const resolved = outcome.value;
if (!resolved) {
results.push(failResult(spec, 'could not resolve location'));
continue;
}
const anno = buildAnnotation(spec, resolved, persist);
// De-dup: the voice model re-narrates the same places across turns, and
// annotations now accumulate by default — so without this, "Presidio" / "Marina"
// pile up into duplicate stacked labels. A live mark that is semantically the SAME
// (same type+anchor AND equivalent geometry — keyed on GEOMETRY, not label/color, so
// "Marina" and "Marina District" collapse) is refreshed or replaced in place, never
// stacked. De-dup runs BEFORE the cap so a re-narration still refreshes when full.
const dup = findDuplicate(anno);
if (dup) {
const labelChanged =
String(dup.label || '')
.trim()
.toLowerCase() !==
String(anno.label || '')
.trim()
.toLowerCase();
const colorChanged =
(dup.color || 'primary') !== (anno.color || 'primary');
if (labelChanged || colorChanged) {
// Same place + shape, but a NEW label and/or color ("Marina" → "Marina District",
// or a recolor) → replace in place so the latest caption/color wins (count
// unchanged, so no cap concern; no stale copy stacked underneath).
// A progressive replacement inherits the dup's already-resolved geometry so an
// outline never visibly vanishes during a recaption; its own upgrade (below)
// refreshes it — usually instantly from the footprint cache.
if (anno.pendingOutline && !anno.ring && dup.ring) {
anno.ring = dup.ring;
anno.polygons = dup.polygons || null;
anno.footprintKind = dup.footprintKind || null;
anno.buildingHeight = dup.buildingHeight || null;
anno.synthesized = Boolean(dup.synthesized);
anno.anchor = { ...dup.anchor };
}
annotations.delete(dup.id);
annotations.set(anno.id, anno);
syncAnnotationHold();
try {
renderer.remove(dup);
renderer.add(anno);
} catch (swapError) {
// Same contract as the fresh path: a renderer/WebGL throw must
// not leave a phantom annotation behind — and with it a
// PERMANENT 'annotations' hold that defeats the idle governor
// until an explicit clear. Roll the map back and re-sync.
rollbackRendererState(anno);
annotations.delete(anno.id);
syncAnnotationHold();
throw swapError;
}
ids.push(anno.id);
if (!firstAnchor) firstAnchor = anno;
if (typeof resolved.resolveOutline === 'function') {
startOutlineUpgrade(
anno,
resolved.resolveOutline,
myGen,
controller,
);
}
results.push({
...okResult(anno, resolved, anno.id),
duplicate: true,
});
} else {
// Identical re-narration → refresh the existing mark's lifecycle in place (keep
// it visible whether persistent or TTL-based, and revive a fading-out one).
if (persist) {
dup.ttlMs = null;
} else {
dup.createdAt = performance.now();
dup.ttlMs = anno.ttlMs;
}
dup.expiring = false;
dup.fadeStart = null;
ids.push(dup.id);
if (!firstAnchor) firstAnchor = dup;
// A re-narration is also a RETRY: if the existing mark never got its outline
// (transient Overpass miss), attach this call's deferred resolver to it.
if (!dup.ring && typeof resolved.resolveOutline === 'function') {
startOutlineUpgrade(
dup,
resolved.resolveOutline,
myGen,
controller,
);
}
// Same result builder as the fresh path (full metadata) but the existing id —
// route fallback / approximate honesty fields survive a re-narration.
results.push({
...okResult(anno, resolved, dup.id),
duplicate: true,
});
}
continue;
}
// NEW mark — enforce the HARD live cap here, synchronously immediately before the
// set (no await in between), so overlapping annotate() calls can't both slip past.
if (annotations.size >= MAX_LIVE_ANNOTATIONS) {
capped = true;
results.push(failResult(spec, 'annotation limit reached'));
continue;
}
annotations.set(anno.id, anno);
syncAnnotationHold();
try {
renderer.add(anno);
} catch (addError) {
// A failed renderer add must not retain a phantom annotation (and
// with it a phantom continuous-render hold). (perf wave 2 fix)
rollbackRendererState(anno);
annotations.delete(anno.id);
syncAnnotationHold();
throw addError;
}
ids.push(anno.id);
if (!firstAnchor) firstAnchor = anno;
// Progressive: the point is on the board; trace the outline behind the narration.
if (typeof resolved.resolveOutline === 'function') {
startOutlineUpgrade(
anno,
resolved.resolveOutline,
myGen,
controller,
);
}
results.push(okResult(anno, resolved, anno.id));
} catch (error) {
if (superseded()) break;
results.push(
failResult(
spec,
error?.message || 'annotation failed',
Array.isArray(error?.failedTargets) ? error.failedTargets : null,
),
);
}
}
} finally {
releaseController(controller);
}
// A clear/new-topic landed mid-flight: drop everything this call produced and
// do not touch the renderer or camera — the board now belongs to a newer call.
if (superseded()) {
return {
ok: false,
drawn: 0,
failed: results.length,
ids: [],
results,
aborted: true,
};
}
if (ids.length) {
renderer.sync(annotations);
ensureTicking();
}
if (opts.flyTo && firstAnchor) frameAnnotation(firstAnchor);
else if (ids.length) ensureMarksVisible(ids);
const drawn = results.filter((r) => r.ok).length;
return {
ok: drawn > 0,
drawn,
failed: results.length - drawn,
ids,
results,
capped,
};
}
async function resolveSpec(spec, signal, allowDistant = false) {
const type = normalizeType(spec?.type);
// MANUAL geometry (drawTool.js): the person clicked the vertices, so there is
// nothing to resolve. Same record shapes as a resolved spec, source 'manual'.
if (isManualSpec(spec, type)) return resolveManualSpec(spec, type, viewer);
if (type === 'route') {
const points = Array.isArray(spec.points) ? spec.points : [];
if (points.length < 2)
throw new Error('a route needs at least 2 waypoints');
const resolvedPts = [];
const failed = [];
for (const pt of points) {
const name = pt.target ?? pt.name ?? null;
const r = await resolveTarget({
placeSearch,
viewer,
target: name,
latitude: pt.latitude,
longitude: pt.longitude,
screenX: pt.screenX,
screenY: pt.screenY,
footprint: false,
allowDistant,
signal,
});
if (r) resolvedPts.push(r);
else failed.push(name || 'a waypoint');
}
// Honesty: never silently drop waypoints. If any fail to resolve, this is not
// the route the user asked for (A→B→C must not become A→C), so fail loudly
// with the specific waypoint(s) so the agent can say what it couldn't find.
if (failed.length) {
// Static message (no raw place text in prose — names live in failedTargets,
// a structured DATA field, to avoid a prompt-injection surface in tool output).
const err = new Error('could not locate one or more route waypoints');
err.failedTargets = failed;
throw err;
}
// Real street-following route (OSM/OSRM), mode-aware.
const mode = normalizeMode(spec.mode);
const routed = await fetchRoute(
resolvedPts.map((p) => [p.lon, p.lat]),
mode,
signal,
placeSearch,
);
if (routed) {
return {
path: routed.geometry.map(([lon, lat]) => ({ lon, lat, height: 0 })),
distanceM: routed.distanceM,
durationS: routed.durationS,
mode,
source: resolvedPts[0].source,
fallback: false,
};
}
// Routing unavailable: do NOT pass off straight segments as a real route. Draw
// a clearly-labeled direct line with great-circle distance and NO travel time.
let straight = 0;
for (let i = 1; i < resolvedPts.length; i += 1)
straight += greatCircleM(resolvedPts[i - 1], resolvedPts[i]);
return {
path: resolvedPts,
distanceM: straight,
durationS: null,
mode,
source: resolvedPts[0].source,
fallback: true,
};
}
if (type === 'arrow') {
const from = await resolveTarget({
placeSearch,
viewer,
target: spec.target,
latitude: spec.latitude,
longitude: spec.longitude,
screenX: spec.screenX,
screenY: spec.screenY,
footprint: false,
allowDistant,
signal,
});
const to = await resolveTarget({
placeSearch,
viewer,
target: spec.toTarget,
latitude: spec.toLatitude,
longitude: spec.toLongitude,
screenX: spec.toScreenX,
screenY: spec.toScreenY,
footprint: false,
allowDistant,
signal,
});
if (!from || !to) {
// Name the endpoint(s) that actually failed so the partial voice path can't
// blame the wrong place (a valid origin → unresolved destination must report
// the destination, not the origin/caption).
const failed = [];
if (!from) failed.push(spec.target || 'the origin');
if (!to) failed.push(spec.toTarget || 'the destination');
// Static message; names go only into failedTargets (structured DATA).
const err = new Error('could not locate one or both arrow endpoints');
err.failedTargets = failed;
throw err;
}
return {
from,
to,
distanceM: greatCircleM(from, to),
source: from.source,
};
}
const wantFootprint =
type === 'area' ? spec.footprint !== false : Boolean(spec.footprint);
return resolveTarget({
placeSearch,
viewer,
target: spec.target,
latitude: spec.latitude,
longitude: spec.longitude,
screenX: spec.screenX,
screenY: spec.screenY,
footprint: wantFootprint,
intent:
spec.intent === 'around_the_thing' ? 'around_the_thing' : 'the_thing',
entityKind: ENTITY_KINDS.has(spec?.entityKind) ? spec.entityKind : null,
// The label often carries the ask's true shape when the target omits it
// ("target: Texas State Capitol" + "label: Capitol grounds") — a resolver HINT only.
labelHint: typeof spec?.label === 'string' ? spec.label : null,
// PROGRESSIVE resolution: anchor now (~100-400 ms Places/Geocode), outline later.
// Footprint fetches are the slow, flaky leg (Overpass p50 ≈ 1-3 s, p90 ≈ 12 s
// timeout — field test 7 logs); deferring them lets the mark appear and the tool
// result return while the outline resolves, then upgrades the mark in place.
deferFootprint: wantFootprint,
allowDistant,
signal,
});
}
/**
* PROGRESSIVE outline upgrade: the mark is already on the board as a point; when the
* deferred footprint resolves, mutate the SAME annotation in place (ring/kind/height +
* recentred anchor) and re-route it through the renderer (a ring moves an area from the
* screen-space callout to the world-space drape). The mark never disappears here: on a
* failed / aborted / superseded resolution it simply stays an honest point (marks are
* only ever removed by an explicit clear — the no-auto-clear invariant).
*/
function startOutlineUpgrade(anno, resolveOutline, myGen, controller) {
if (anno._outlineTask) return; // one upgrade per mark at a time
anno.pendingOutline = true;
retainController(controller); // keep the outline fetches abortable by clear()
const task = { anno, resolveOutline, myGen, controller };
anno._outlineTask = task;
outlineQueue.push(task);
drainOutlineQueue();
}
function drainOutlineQueue() {
while (
activeOutlineUpgrades < OUTLINE_UPGRADE_CONCURRENCY &&
outlineQueue.length
) {
const task = outlineQueue.shift();
const stale =
task.myGen !== generation ||
task.controller.signal.aborted ||
!annotations.has(task.anno.id);
if (stale) {
if (task.anno._outlineTask === task) task.anno._outlineTask = null;
releaseController(task.controller);
continue;
}
activeOutlineUpgrades += 1;
runOutlineUpgrade(task);
}
}
async function runOutlineUpgrade(task) {
const { anno, resolveOutline, myGen, controller } = task;
try {
let fp = null;
// Geometry upgrade is best-effort — the point stays on any failure. A TRANSIENT
// failure (slow Overpass mirror) re-runs on a short backoff: the /api/overpass
// proxy caches the late completion, so the retry is usually a warm cache hit.
fp = await resolveOutlineWithRetry(resolveOutline, {
delaysMs: outlineRetryDelaysMs,
isStale: () =>
myGen !== generation ||
controller.signal.aborted ||
!annotations.has(anno.id),
});
if (myGen !== generation || controller.signal.aborted) return; // board superseded
if (!annotations.has(anno.id)) return; // mark replaced/removed while resolving
anno.pendingOutline = false;
anno.outlineUnavailable = isUnavailableCapability(fp);
if (anno.outlineUnavailable) renderer.update(anno);
if (fp && !anno.outlineUnavailable) {
anno.ring = fp.ring;
anno.polygons = fp.polygons || null;
anno.footprintKind = fp.footprintKind || null;
anno.buildingHeight = fp.buildingHeight || null;
anno.synthesized = Boolean(fp.synthesized);
// Re-center on the footprint centroid, as the inline path always did.
if (Number.isFinite(fp.lat) && Number.isFinite(fp.lon)) {
anno.anchor = {
lon: fp.lon,
lat: fp.lat,
height: Number.isFinite(fp.height) ? fp.height : anno.anchor.height,
};
}
// Re-route: ring presence decides world-drape vs screen-space in the renderer.
renderer.update(anno);
// GEOMETRY dedup, now that geometry is known: two DIFFERENT targets can resolve
// to the SAME polygon ("Marina" / "Marina District") — the identity-is-geometry
// invariant says they are ONE mark. The pending-phase dedup keys on target (it
// can't see geometry yet), so enforce the invariant here: collapse any other
// resolved area with the same anchor + ring, keeping THIS mark (latest caption
// wins, exactly like the add-time replace path). Not an auto-clear — it removes
// a second representation of the same mark, never a distinct one.
for (const other of annotations.values()) {
if (
other.id === anno.id ||
other.type !== 'area' ||
other.pendingOutline
)
continue;
if (
!other.anchor ||
Math.abs(other.anchor.lon - anno.anchor.lon) >= 5e-4 ||
Math.abs(other.anchor.lat - anno.anchor.lat) >= 5e-4
)
continue;
if (Boolean(other.synthesized) !== Boolean(anno.synthesized))
continue;
if ((other.footprintKind || null) !== (anno.footprintKind || null))
continue;
if (!ringsEqual(other.ring, anno.ring)) continue;
annotations.delete(other.id);
renderer.remove(other);
}
}
renderer.sync(annotations);
// Final outcome → the voice layer (place names ride as structured DATA fields).
// 'failed' covers both the definitive no-polygon and an exhausted transient
// retry — either way the mark honestly stays a point.
emitOutlineEvent({
id: anno.id,
label: anno.label || null,
target: anno.targetKey || null,
status: anno.outlineUnavailable
? 'unavailable'
: fp
? 'resolved'
: 'failed',
...(anno.outlineUnavailable
? { message: 'Detailed outline unavailable' }
: {}),
...(fp && anno.synthesized ? { approximate: true } : {}),
});
} finally {
if (anno._outlineTask === task) anno._outlineTask = null;
releaseController(controller);
activeOutlineUpgrades -= 1;
drainOutlineQueue();
}
}
/** Build the success result for an annotation (fresh or duplicate), keeping the route
* fallback + synthesized-area honesty fields the voice layer relies on. */
function okResult(anno, resolved, id) {
return {
ok: true,
id,
type: anno.type,
label: anno.label,
latitude: round5(anno.anchor.lat),
longitude: round5(anno.anchor.lon),
resolvedVia: resolved.source,
outline: Boolean(anno.ring),
// The anchor is placed and returned fast; the footprint is still being traced and
// will appear on its own (or the mark honestly stays a point). Lets the voice
// layer narrate without waiting out a slow Overpass — and without calling the
// missing outline a failure.
...(anno.pendingOutline ? { outlinePending: true } : {}),
...(anno.outlineUnavailable
? { outlineUnavailable: true, message: 'Detailed outline unavailable' }
: {}),
// approximate=true means the area was SYNTHESIZED (a buffered blob around a label
// point), not a real OSM boundary — so the voice layer can be honest.
...(anno.synthesized ? { approximate: true } : {}),
// Route-specific signal so the voice layer can be honest about an OSRM outage:
// fallback=true means a straight direct line, not a real route.
...(anno.type === 'route'
? {
fallback: Boolean(anno.fallback),
mode: anno.mode,
distanceM: anno.distanceM,
durationS: anno.durationS,
}
: {}),
};
}
/** A live mark that is the SAME annotation as `anno`, or null. For shapes with real geometry
* (area/arrow/route) identity is GEOMETRY, not label/color — so "Marina" and "Marina District"
* (same polygon) collapse to one mark, while a same-anchor DIFFERENT shape ("the Capitol"
* building vs "around the Capitol" buffer) is NOT collapsed; the caller replaces label/color in
* place so the latest caption wins. For BARE POINTS (pin/highlight/label) there is no geometry
* to compare, so identity also requires the LABEL to match — otherwise distinct things that a
* degenerate geocode stacks on one point (several Capitol monuments) would erase each other. */
function findDuplicate(anno) {
if (!anno.anchor) return null;
const near = (a, b) =>
a &&
b &&
Math.abs(a.lon - b.lon) < 5e-4 &&
Math.abs(a.lat - b.lat) < 5e-4;
// FULL per-vertex geometry comparison (the live cap is only 120 and this runs solely for
// candidates that already matched type+label+anchor, so it's cheap) — so two DIFFERENT
// same-length rings/paths at the same anchor are never falsely merged.
const ringSame = ringsEqual;
const pathSame = (a, b) => {
const la = a ? a.length : 0;
const lb = b ? b.length : 0;
if (la !== lb) return false;
for (let i = 0; i < la; i++) if (!near(a[i], b[i])) return false;
return true;
};
for (const ex of annotations.values()) {
if (ex.type !== anno.type || !ex.anchor) continue;
// Identity is GEOMETRY, not label: "Marina" and "Marina District" resolve to the SAME
// polygon/anchor and must collapse to one mark (the caller replaces label/color in place
// so the latest caption wins). Resolution is deterministic, so the same place re-resolves
// to the same centroid; a ~50 m epsilon absorbs any rounding.
if (!near(ex.anchor, anno.anchor)) continue;
// Geometry equivalence per type — distinct shapes at the same anchor are NOT dupes.
if (anno.type === 'area') {
if (anno.pendingOutline || ex.pendingOutline) {
// Progressive outline still resolving on one side → geometry is unknowable yet,
// so identity falls back to the asked-for THING: same normalized target + same
// shape intent. This collapses a literal re-narration ("the Presidio" again)
// without collapsing different asks at one anchor ("the Capitol" vs "the
// Capitol grounds" pend ~the same point but are different targets). Same-place
// DIFFERENT-target asks ("Marina" / "Marina District") are collapsed later by
// the post-resolution geometry dedup in startOutlineUpgrade — geometry stays
// the identity; the target is only the stand-in while geometry is unknown.
if (!anno.targetKey || !ex.targetKey) continue;
if (anno.targetKey !== ex.targetKey) continue;
if ((ex.intentKey || 'thing') !== (anno.intentKey || 'thing'))
continue;
} else {
if (Boolean(ex.synthesized) !== Boolean(anno.synthesized)) continue;
if ((ex.footprintKind || null) !== (anno.footprintKind || null))
continue;
if (!ringSame(ex.ring, anno.ring)) continue;
}
} else if (anno.type === 'arrow') {
if (!near(ex.to, anno.to)) continue;
} else if (anno.type === 'route') {
if ((ex.mode || null) !== (anno.mode || null)) continue;
if (!pathSame(ex.path, anno.path)) continue;
} else {
// pin / highlight / label = a bare POINT with no distinguishing geometry. Two DIFFERENT
// labels at the same spot are two different things a degenerate geocode stacked on one
// point (e.g. several Texas Capitol monuments all geocoding to the dome centroid) — NOT a
// duplicate. Only collapse a genuine re-narration of the SAME point (same label); distinct
// labels stay as separate marks (their callouts de-collide in the renderer).
const sameLabel =
String(ex.label || '')
.trim()
.toLowerCase() ===
String(anno.label || '')
.trim()
.toLowerCase();
if (!sameLabel) continue;
}
return ex;
}
return null;
}
function buildAnnotation(spec, resolved, persist) {
const type = normalizeType(spec?.type);
const id = `anno-${++_seq}`;
const color = COLORS.has(spec?.color) ? spec.color : 'primary';
const label =
cleanLabel(spec?.label) ||
resolved?.label ||
resolved?.from?.label ||
null;
const now = performance.now();
const base = {
id,
type,
color,
label,
createdAt: now,
ttlMs: persist ? null : Number(spec?.ttlMs) || DEFAULT_TTL_MS,
alpha: 0, // animate in
bornAt: now,
expiring: false,
};
if (type === 'route') {
const path = resolved.path.map((p) => ({
lon: p.lon,
lat: p.lat,
height: p.height,
}));
return {
...base,
label: composeRouteLabel(
base.label,
resolved.distanceM,
resolved.durationS,
resolved.mode,
resolved.fallback,
),
anchor: path[0],
to: null,
path,
ring: null,
mode: resolved.mode || null,
distanceM: resolved.distanceM ?? null,
durationS: resolved.durationS ?? null,
fallback: Boolean(resolved.fallback),
};
}
if (type === 'arrow') {
return {
...base,
label: appendDistance(base.label, resolved.distanceM),
anchor: {
lon: resolved.from.lon,
lat: resolved.from.lat,
height: resolved.from.height,
},
to: {
lon: resolved.to.lon,
lat: resolved.to.lat,
height: resolved.to.height,
},
ring: null,
};
}
return {
...base,
anchor: { lon: resolved.lon, lat: resolved.lat, height: resolved.height },
to: null,
ring: resolved.ring || null,
// Every part with its holes ([outer, ...holes][]), when the outline has
// more than the main ring (Hawaii's islands, Berlin inside Brandenburg).
polygons: resolved.polygons || null,
footprintKind: resolved.footprintKind || null, // 'building' | 'area'
buildingHeight: resolved.buildingHeight || null, // meters, for extruded volume
synthesized: Boolean(resolved.synthesized), // approximate buffered area → dashed render
// Progressive outline: the anchor is placed, the footprint is still resolving —
// the upgrade task fills ring/kind in place when it lands. Transient render state
// (not persisted).
pendingOutline: typeof resolved.resolveOutline === 'function',
outlineUnavailable: Boolean(resolved.outlineUnavailable),
// Which THING + SHAPE was asked for — the dedup identity while geometry is still
// pending (see findDuplicate). targetKey is the normalized place name with trailing
// locality qualifiers stripped ("California, United States" ≡ "California"; null for
// coord/pixel specs, which never pending-collapse).
targetKey: normalizeTargetKey(spec?.target),
intentKey: spec?.intent === 'around_the_thing' ? 'around' : 'thing',
// Places viewport (lat/lng box framing the feature) — sizes the flyTo range while
// no ring exists yet.
viewport: resolved.viewport || null,
};
}
function clear() {
// Bump first so any in-flight annotate() sees itself as superseded, and abort
// its pending fetches so a slow resolve can never redraw onto the cleared board.
generation += 1;
abortPending();
dropQueuedOutlineUpgrades();
if (!annotations.size) return;
for (const anno of annotations.values()) renderer.remove(anno);
annotations.clear();
renderer.sync(annotations);
syncAnnotationHold();
}
/** Begin a graceful fade-out of everything, then remove. */
function fadeOutAll() {
const now = performance.now();
for (const anno of annotations.values()) {
anno.expiring = true;
anno.ttlMs = 0;
anno.fadeStart = now;
}
ensureTicking();
}
/**
* Camera assist (field test 8): the voice model leaves flyTo false when it believes the
* user is already looking at the subject — but after a fly_to elsewhere, a fresh mark can
* land entirely OFF-SCREEN and the user sees nothing happen (Lady Bird Lake → SRV statue).
* When NOTHING this call drew or refreshed is visible, gently frame those marks. Never
* fires when at least one mark is already in view (don't fight the user's camera), and
* never on a later outline upgrade (no mid-narration yanks).
*/
function ensureMarksVisible(markIds) {
try {
// One assist at a time: the model often issues annotate calls ~1 s apart, and
// re-checking mid-flight would see still-off-screen marks and restart the flight
// (a visible stutter). While an assist flight is presumed in progress, stand down.
if (performance.now() < assistFlightUntil) return;
const marks = markIds.map((id) => annotations.get(id)).filter(Boolean);
if (!marks.length) return;
const points = [];
for (const m of marks) {
if (m.anchor) points.push(m.anchor);
if (m.to) points.push(m.to);
}
if (!points.length || points.some((p) => isPointOnScreen(p))) return;
console.log(
`[Annotations] auto-framing ${marks.length} off-screen mark(s)`,
);
assistFlightUntil = performance.now() + 2600; // ~flight duration + settle
if (marks.length === 1) {
frameAnnotation(marks[0]);
return;
}
const cart = points.map((p) =>
Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0),
);
const sphere = Cesium.BoundingSphere.fromPoints(cart);
viewer.camera.flyToBoundingSphere(sphere, {
offset: new Cesium.HeadingPitchRange(
viewer.camera.heading,
Cesium.Math.toRadians(-35),
Math.max(900, sphere.radius * 2.6),
),
duration: 1.6,
});
} catch {
/* camera assist is best-effort */
}
}
/** Whether a lon/lat point is inside the camera frustum AND on the near side of the
* globe. On any API hiccup, report visible — bad data must never move the camera. */
function isPointOnScreen(p) {
try {
const camera = viewer.camera;
const pos = Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.height || 0);
const cv = camera.frustum.computeCullingVolume(
camera.position,
camera.direction,
camera.up,
);
if (
cv.computeVisibility(new Cesium.BoundingSphere(pos, 1)) ===
Cesium.Intersect.OUTSIDE
)
return false;
const occluder = new Cesium.EllipsoidalOccluder(
Cesium.Ellipsoid.WGS84,
camera.position,
);
return occluder.isPointVisible(pos);
} catch {
return true;
}
}
function frameAnnotation(anno) {
try {
const target = anno.to
? {
lon: (anno.anchor.lon + anno.to.lon) / 2,
lat: (anno.anchor.lat + anno.to.lat) / 2,
}
: anno.anchor;
// No ring yet (progressive outline still resolving) → size the flight from the
// Places viewport box when we have one, so a big compound isn't framed at
// building scale while its outline is traced. Never re-fly when the ring lands.
const range = anno.ring
? ringRange(
anno.polygons?.length
? anno.polygons.flatMap((poly) => poly[0])
: anno.ring,
)
: viewportRange(anno.viewport) || 600;
viewer.camera.flyToBoundingSphere(
new Cesium.BoundingSphere(
Cesium.Cartesian3.fromDegrees(
target.lon,
target.lat,
anno.anchor.height || 0,
),
range,
),
{
offset: new Cesium.HeadingPitchRange(
viewer.camera.heading,
Cesium.Math.toRadians(-35),
range * 2.4,
),
duration: 1.8,
},
);
} catch {
/* framing is best-effort */
}
}
const engine = {
annotate,
clear,
destroy() {
if (destroyed) return;
destroyed = true;
try {
clear();
} finally {
if (tickHandle != null) cancelAnimationFrame(tickHandle);
tickHandle = null;
outlineListeners.clear();
releaseContinuousRender('annotations');
renderer.destroy();
}
},
fadeOutAll,
count: () => annotations.size,
list: () => Array.from(annotations.values()),
/**
* Subscribe to deferred-outline outcomes. Listener receives
* `{ id, label, target, status: 'resolved'|'failed', approximate? }` once per
* upgrade task, AFTER the mark was mutated in place. Returns an unsubscribe fn.
*/
onOutlineEvent(listener) {
if (destroyed || typeof listener !== 'function') return () => {};
outlineListeners.add(listener);
return () => outlineListeners.delete(listener);
},
/**
* Scripted demo so the feature is verifiable without a live mic session.
* Lays down a small San Francisco "tour" the way the voice agent would.
*/
async demo() {
return annotate(
[
{
type: 'highlight',
target: 'Palace of Fine Arts, San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'Palace of Fine Arts',
color: 'amber',
},
{
type: 'area',
target: 'Presidio of San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'The Presidio (former Army base)',
color: 'green',
footprint: true,
},
{
type: 'pin',
target: 'Letterman Digital Arts Center, San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'ILM / Lucasfilm',
color: 'cyan',
},
{
type: 'arrow',
target: 'Palace of Fine Arts, San Francisco',
toTarget: 'Marina District, San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'next to the Marina',
},
],
{ flyTo: true, clearPrevious: true, persist: true },
);
},
/**
* Self-running narration "tour" — sequences camera moves and annotations
* with pauses the way the voice agent would, so the whole experience can be
* watched end-to-end without a mic. `window.__gevAnnotations.tour()`.
*/
async tour() {
clear();
flyTo({
lon: -122.4486,
lat: 37.796,
height: 520,
heading: 0,
pitch: -26,
duration: 3,
});
if (destroyed) return { ok: false };
await wait(3200);
await annotate(
[
{
type: 'highlight',
target: 'Palace of Fine Arts, San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'Palace of Fine Arts',
color: 'amber',
},
],
{ persist: true },
);
if (destroyed) return { ok: false };
await wait(2600);
await annotate(
[
{
type: 'arrow',
target: 'Palace of Fine Arts, San Francisco',
toTarget: 'Marina Green, San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'next to the Marina',
color: 'cyan',
},
],
{ persist: true },
);
if (destroyed) return { ok: false };
await wait(2600);
flyTo({
lon: -122.4545,
lat: 37.788,
height: 1500,
heading: 18,
pitch: -32,
duration: 3,
});
if (destroyed) return { ok: false };
await wait(3200);
await annotate(
[
{
type: 'area',
target: 'Presidio of San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'The Presidio — a former Army base',
color: 'green',
footprint: true,
},
],
{ persist: true },
);
if (destroyed) return { ok: false };
await wait(2800);
await annotate(
[
{
type: 'pin',
target: 'Letterman Digital Arts Center, San Francisco',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'ILM / Lucasfilm',
color: 'red',
},
],
{ persist: true },
);
if (destroyed) return { ok: false };
await wait(2600);
await annotate(
[
{
type: 'route',
color: 'amber',
// i18n-ignore: dev demo of voice-agent labels (not translated)
label: 'Crissy Field shoreline',
points: [
{ target: 'Palace of Fine Arts, San Francisco' },
{ target: 'Crissy Field, San Francisco' },
{ target: 'Fort Point, San Francisco' },
],
},
],
{ persist: true },
);
return { ok: true, steps: 6 };
},
};
function flyTo({
lon,
lat,
height,
heading = 0,
pitch = -30,
duration = 2.5,
}) {
if (destroyed) return;
try {
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(lon, lat, height),
orientation: {
heading: Cesium.Math.toRadians(heading),
pitch: Cesium.Math.toRadians(pitch),
roll: 0,
},
duration,
});
} catch {
/* camera flight best-effort */
}
}
return engine;
}
function wait(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
/** Exact per-vertex ring equality ([[lon,lat],…], ~1m epsilon) — the geometry-identity test. */
function ringsEqual(a, b) {
const la = a ? a.length : 0;
const lb = b ? b.length : 0;
if (la !== lb) return false;
for (let i = 0; i < la; i++) {
if (
Math.abs(a[i][0] - b[i][0]) >= 1e-5 ||
Math.abs(a[i][1] - b[i][1]) >= 1e-5
)
return false;
}
return true;
}
// --- helpers ----------------------------------------------------------------
/** The place name(s) a spec attempted to resolve (route waypoints, arrow endpoints, or a single target). */
function specTargets(spec) {
const type = normalizeType(spec?.type);
if (type === 'route' && Array.isArray(spec?.points)) {
return spec.points.map((p) => p?.target ?? p?.name).filter(Boolean);
}
if (type === 'arrow') {
return [spec?.target, spec?.toTarget].filter(Boolean);
}
return spec?.target ? [spec.target] : [];
}
/**
* One shared failed-result shape for EVERY annotation failure path (live-cap,
* unresolved, thrown), so the tool layer can always name the unresolved PLACE
* rather than the caption. Pass explicit failedTargets (e.g. only the missing
* arrow endpoint) when known; otherwise it derives them from the spec.
*/
function failResult(spec, error, failedTargets) {
const targets =
failedTargets && failedTargets.length ? failedTargets : specTargets(spec);
return {
ok: false,
label: spec?.label || spec?.target || targets[0] || null,
target: spec?.target ?? null,
failedTargets: targets.length ? targets : null,
error,
};
}
function normalizeType(type) {
const t = String(type || '').toLowerCase();
if (t === 'area' || t === 'polygon' || t === 'outline' || t === 'compound')
return 'area';
if (t === 'route' || t === 'path' || t === 'line') return 'route';
if (t === 'arrow' || t === 'vector' || t === 'connector') return 'arrow';
if (t === 'label' || t === 'callout' || t === 'text') return 'label';
if (t === 'pin' || t === 'marker' || t === 'point') return 'pin';
return 'highlight';
}
function computeAlpha(anno, now) {
const inT = (now - anno.bornAt) / 260;
const fadeIn = inT >= 1 ? 1 : Math.max(0, inT);
if (anno.ttlMs == null && !anno.expiring) return fadeIn;
const fadeStart =
anno.fadeStart != null
? anno.fadeStart
: anno.createdAt + (anno.ttlMs || 0);
if (now < fadeStart) return fadeIn;
const out = 1 - (now - fadeStart) / FADE_MS;
if (out <= 0) anno.expiring = true;
return Math.max(0, Math.min(fadeIn, out));
}
/** Whether a mark still has alpha animation ahead — fading in, fading out, or a TTL
* fade not yet finished. A persistent mark past its ~260ms fade-in is stable, so the
* tick loop can stop. */
function pendingAnimation(anno, now) {
if (now - anno.bornAt < 260) return true; // fading in
if (anno.expiring) return true; // fading out
if (anno.ttlMs != null) {
const fadeStart =
anno.fadeStart != null
? anno.fadeStart
: anno.createdAt + (anno.ttlMs || 0);
return now < fadeStart + FADE_MS; // TTL fade still ahead or in progress
}
return false; // persistent + faded in → stable
}
// Region-scale viewports (a mountain range, sea, or desert can span thousands of km)
// must not launch the assist flight to space: frameAnnotation flies at range × 2.4,
// so this cap keeps the camera at ≈290 km — the same regional swath scale the
// fly_to_location natural-region heuristic uses (owner field test 2026-07-23).
const VIEWPORT_ASSIST_RANGE_CAP_M = 120000;
/** flyTo range from a Places viewport box (low/high lat-lng corners), or null. */
function viewportRange(vp) {
if (!vp?.low || !vp?.high) return null;
try {
const span = Cesium.Cartesian3.distance(
Cesium.Cartesian3.fromDegrees(vp.low.longitude, vp.low.latitude),
Cesium.Cartesian3.fromDegrees(vp.high.longitude, vp.high.latitude),
);
return Number.isFinite(span) && span > 0
? Math.max(300, Math.min(span * 0.7, VIEWPORT_ASSIST_RANGE_CAP_M))
: null;
} catch {
return null;
}
}
function ringRange(ring) {
let minLat = Infinity;
let maxLat = -Infinity;
let minLon = Infinity;
let maxLon = -Infinity;
// Unwrap around the first vertex so parts cut at the antimeridian (the
// Aleutians) measure as neighbours, not as a globe-wide span.
const ref = ring[0]?.[0] ?? 0;
for (const [rawLon, lat] of ring) {
const lon = rawLon - 360 * Math.round((rawLon - ref) / 360);
if (lat < minLat) minLat = lat;
if (lat > maxLat) maxLat = lat;
if (lon < minLon) minLon = lon;
if (lon > maxLon) maxLon = lon;
}
const span = Cesium.Cartesian3.distance(
Cesium.Cartesian3.fromDegrees(minLon, minLat),
Cesium.Cartesian3.fromDegrees(maxLon, maxLat),
);
return Math.max(300, span * 0.7);
}
function cleanLabel(label) {
const text = String(label || '').trim();
return text ? text.slice(0, 80) : null;
}
function round5(n) {
return Number.isFinite(n) ? Math.round(n * 1e5) / 1e5 : null;
}
/** A spec whose geometry was supplied by hand (drawTool.js) rather than by a name. */
function isManualSpec(spec, type) {
if (!spec || spec.manual !== true) return false;
if (type === 'route')
return Array.isArray(spec.path) && spec.path.length >= 2;
if (type === 'area') return Array.isArray(spec.ring) && spec.ring.length >= 3;
return (
Number.isFinite(Number(spec.latitude)) &&
Number.isFinite(Number(spec.longitude))
);
}
/** [lon, lat] pairs or {lon, lat} objects → [lon, lat] pairs, invalid entries dropped. */
function manualPairs(list) {
return (Array.isArray(list) ? list : [])
.map((p) =>
Array.isArray(p)
? [Number(p[0]), Number(p[1])]
: [Number(p?.lon ?? p?.longitude), Number(p?.lat ?? p?.latitude)],
)
.filter(
([lon, lat]) =>
Number.isFinite(lon) &&
Number.isFinite(lat) &&
Math.abs(lat) <= 90 &&
Math.abs(lon) <= 180,
);
}
/**
* Resolve a hand-drawn spec without any fetch. An area keeps its ring as a real
* (not synthesized) outline so it drapes solid; a line is a `route` with mode
* 'manual', its length as distance and no travel time; a pin is a point.
*/
function resolveManualSpec(spec, type, viewer) {
if (type === 'route') {
// height 0 is a placeholder, not a placement: the world renderer draws a
// route with clampToGround + CESIUM_3D_TILE classification, so the line is
// draped onto the photoreal surface whatever this number says.
const pts = manualPairs(spec.path).map(([lon, lat]) => ({
lon,
lat,
height: 0,
}));
if (pts.length < 2) throw new Error('a drawn line needs at least 2 points');
let distanceM = 0;
for (let i = 1; i < pts.length; i += 1)
distanceM += greatCircleM(pts[i - 1], pts[i]);
return {
path: pts,
distanceM,
durationS: null,
mode: 'manual',
source: 'manual',
fallback: false,
};
}
if (type === 'area') {
const ring = manualPairs(spec.ring);
if (ring.length < 3)
throw new Error('a drawn area needs at least 3 points');
// Averaged through ringCentroid, which unwraps longitudes first: a ring
// straddling the antimeridian has coordinates like [179.999, -179.999], and
// a raw mean of those puts the anchor on the Greenwich meridian, half a
// world from the shape it belongs to. A repeated closing vertex is dropped
// so it does not weight its own corner twice.
const distinct = closedRingWithoutRepeat(ring);
const centre = ringCentroid(distinct.map(([lon, lat]) => ({ lon, lat })));
const lon = centre.lon;
const lat = centre.lat;
return {
lon,
lat,
height: sampleGroundHeight(viewer, lon, lat),
ring,
footprintKind: 'area',
buildingHeight: null,
synthesized: false,
source: 'manual',
};
}
const lon = Number(spec.longitude);
const lat = Number(spec.latitude);
return {
lon,
lat,
height: sampleGroundHeight(viewer, lon, lat),
ring: null,
source: 'manual',
};
}
/** The ring's distinct positions: a closing vertex that repeats the first is dropped. */
function closedRingWithoutRepeat(ring) {
if (ring.length < 2) return ring;
const [firstLon, firstLat] = ring[0];
const [lastLon, lastLat] = ring[ring.length - 1];
return firstLon === lastLon && firstLat === lastLat
? ring.slice(0, -1)
: ring;
}
function normalizeMode(m) {
const t = String(m || '').toLowerCase();
if (t === 'car' || t === 'drive' || t === 'driving') return 'car';
if (t === 'bike' || t === 'cycle' || t === 'cycling' || t === 'bicycle')
return 'bike';
return 'foot';
}
/** Route failure remains an explicitly labelled direct line in the caller. */
async function fetchRoute(coordPairs, mode, signal, service) {
try {
return (await service.route?.(coordPairs, mode, { signal })) || null;
} catch {
return null;
}
}
function greatCircleM(a, b) {
return greatCircleMeters(a, b);
}
function formatDistance(m) {
if (!Number.isFinite(m)) return null;
if (m >= 1000) return `${(m / 1000).toFixed(m >= 10000 ? 0 : 1)} km`;
return `${Math.round(m / 10) * 10} m`;
}
function composeRouteLabel(baseLabel, distM, durS, mode, fallback) {
const dist = formatDistance(distM);
if (!dist) return baseLabel;
const min = Number.isFinite(durS) ? Math.max(1, Math.round(durS / 60)) : null;
const word = mode === 'car' ? 'drive' : mode === 'bike' ? 'ride' : 'walk';
if (mode === 'manual') return baseLabel ? `${baseLabel} — ${dist}` : dist;
// Fallback = routing was unavailable, so we drew a straight line: label it as a
// direct line with no travel time (never claim an "X min walk" we didn't compute).
let metrics;
if (fallback) metrics = `${dist} · direct line (no route)`;
else metrics = min != null ? `${dist} · ${min} min ${word}` : dist;
return baseLabel ? `${baseLabel} — ${metrics}` : metrics;
}
function appendDistance(baseLabel, distM) {
const dist = formatDistance(distM);
if (!dist) return baseLabel;
return baseLabel ? `${baseLabel} — ${dist}` : dist;
}