mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-22 11:12:18 +00:00
Camera-driven Mapillary coverage (z0–5 overview points from orbit, z11–14 ground-clamped sequence lines below 60 km), per-sequence image cones, an embedded MapillaryJS viewer bridge with a camera-follow mode, sprite icons for map features, and a query engine that turns a plan into a streamed z14 tile fan-out. Registers an on-globe CC BY-SA 4.0 credit while enabled. Co-Authored-By: Claude Fable 5.1 <[email protected]>
517 lines
17 KiB
JavaScript
517 lines
17 KiB
JavaScript
import * as Cesium from 'cesium';
|
||
import { passesImageryFilter, visibleBbox } from './coverage.js';
|
||
import { countTilesForBbox, normalizeBbox } from './tileMath.js';
|
||
import { groupCountsByLabel } from './values.js';
|
||
|
||
/** Fallback half-size (degrees) around a geocoded point with no bounds. */
|
||
const POINT_PLACE_HALF_DEG = 0.02;
|
||
/**
|
||
* Smallest place box worth querying (degrees, ~1.1 km). Nominatim returns a
|
||
* node-sized box for many neighbourhoods and landmarks; a query on that would
|
||
* cover one intersection and read as "nothing here".
|
||
*/
|
||
const MIN_PLACE_SPAN_DEG = 0.01;
|
||
/** Radii (metres) of the probe rings used when nothing sits within 50 m. */
|
||
const NEAREST_RING_M = [90, 180, 300];
|
||
/** Cap for a "current view" query when the server does not report one. */
|
||
const DEFAULT_MAX_TILES = 600;
|
||
const FEATURE_ZOOM = 14;
|
||
/** A current-view query wider than this is the horizon, not an area. */
|
||
const MAX_VIEW_SPAN_DEG = 4;
|
||
|
||
/** Shrink a bbox around its centre until it fits the tile budget. */
|
||
export function fitBboxToTileBudget(bbox, maxTiles, zoom = FEATURE_ZOOM) {
|
||
let box = normalizeBbox(bbox);
|
||
if (!box) return null;
|
||
let guard = 0;
|
||
while (
|
||
countTilesForBbox([box.west, box.south, box.east, box.north], zoom) >
|
||
maxTiles &&
|
||
guard++ < 40
|
||
) {
|
||
const cx = (box.west + box.east) / 2;
|
||
const cy = (box.south + box.north) / 2;
|
||
const hw = ((box.east - box.west) / 2) * 0.85;
|
||
const hh = ((box.north - box.south) / 2) * 0.85;
|
||
box = { west: cx - hw, east: cx + hw, south: cy - hh, north: cy + hh };
|
||
}
|
||
return [box.west, box.south, box.east, box.north];
|
||
}
|
||
|
||
/** Approximate metres between two lon/lat points (small distances). */
|
||
function metresBetween(a, b) {
|
||
const lat = ((a.lat + b.lat) / 2) * (Math.PI / 180);
|
||
const dx = (b.lon - a.lon) * 111_320 * Math.cos(lat);
|
||
const dy = (b.lat - a.lat) * 110_540;
|
||
return Math.hypot(dx, dy);
|
||
}
|
||
|
||
/** Grow a bbox symmetrically until both sides reach `minSpan` degrees. */
|
||
export function enforceMinimumSpan(bbox, minSpan) {
|
||
const [west, south, east, north] = bbox;
|
||
if (east - west >= minSpan && north - south >= minSpan) return bbox;
|
||
const cx = (west + east) / 2;
|
||
const cy = (south + north) / 2;
|
||
const hw = Math.max((east - west) / 2, minSpan / 2);
|
||
const hh = Math.max((north - south) / 2, minSpan / 2);
|
||
return [cx - hw, cy - hh, cx + hw, cy + hh];
|
||
}
|
||
|
||
/** Turn a geocode result into a bbox, label and centre. */
|
||
export function bboxFromGeocode(result) {
|
||
const geometry = result?.geometry;
|
||
const location = geometry?.location;
|
||
if (
|
||
!location ||
|
||
!Number.isFinite(location.lat) ||
|
||
!Number.isFinite(location.lng)
|
||
)
|
||
return null;
|
||
const bounds = geometry.bounds || geometry.viewport;
|
||
const bbox = bounds
|
||
? [
|
||
bounds.southwest.lng,
|
||
bounds.southwest.lat,
|
||
bounds.northeast.lng,
|
||
bounds.northeast.lat,
|
||
]
|
||
: [
|
||
location.lng - POINT_PLACE_HALF_DEG,
|
||
location.lat - POINT_PLACE_HALF_DEG,
|
||
location.lng + POINT_PLACE_HALF_DEG,
|
||
location.lat + POINT_PLACE_HALF_DEG,
|
||
];
|
||
return {
|
||
bbox: enforceMinimumSpan(bbox, MIN_PLACE_SPAN_DEG),
|
||
label: result.formatted_address || '',
|
||
center: { lat: location.lat, lon: location.lng },
|
||
};
|
||
}
|
||
|
||
/** "1 tile" / "3 tiles". */
|
||
function plural(count, singular, pluralForm = `${singular}s`) {
|
||
return `${count.toLocaleString()} ${count === 1 ? singular : pluralForm}`;
|
||
}
|
||
|
||
/** Pluralise a humanised class label for a count ("fire hydrant" → "fire hydrants"). */
|
||
export function pluralLabel(label, count) {
|
||
const word = String(label || '').toLowerCase();
|
||
if (count === 1 || !word) return word;
|
||
if (/(s|x|z|ch|sh)$/.test(word)) return `${word}es`;
|
||
if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
|
||
return `${word}s`;
|
||
}
|
||
|
||
/**
|
||
* Compose the one-line result summary shown under the query box. Returns an
|
||
* empty string for zero results so the caller can replace, not append to,
|
||
* the planner's optimistic answer.
|
||
*/
|
||
export function summarizeResults(features) {
|
||
const total = features.total || 0;
|
||
if (!total) return '';
|
||
const values = groupCountsByLabel(features.counts.entries());
|
||
const classes = values
|
||
.slice(0, 3)
|
||
.map(
|
||
({ label, count }) =>
|
||
`${count.toLocaleString()} ${pluralLabel(label, count)}`,
|
||
)
|
||
.join(', ');
|
||
const more =
|
||
values.length > 3
|
||
? ` and ${plural(values.length - 3, 'more class', 'more classes')}`
|
||
: '';
|
||
const years =
|
||
features.earliest && features.latest
|
||
? ` · seen ${new Date(features.earliest).getFullYear()}–${new Date(features.latest).getFullYear()}`
|
||
: '';
|
||
const truncated = features.truncated ? ' · capped' : '';
|
||
const failed = features.failed
|
||
? ` · ${plural(features.failed, 'tile')} failed`
|
||
: '';
|
||
// One class: "834 fire hydrants · seen 2017–2021". Several: lead with the total.
|
||
const head =
|
||
values.length === 1
|
||
? classes
|
||
: `${plural(total, 'feature')}: ${classes}${more}`;
|
||
return `${head}${years}${truncated}${failed}`;
|
||
}
|
||
|
||
/** What the panel says when a query found nothing where it looked. */
|
||
export function noResultsAnswer(plan, area) {
|
||
const subject = (plan?.title || 'matching features')
|
||
.replace(/\s*·.*$/, '')
|
||
.toLowerCase();
|
||
const where = area?.label ? ` in ${area.label}` : ' here';
|
||
return `No ${subject} mapped${where} yet. Try a larger area, another place, or set SINCE back to any date.`;
|
||
}
|
||
|
||
/** Natural-language query orchestration: plan → resolve area → stream → draw. */
|
||
export function createQuery({ state, source, parts }) {
|
||
function notify() {
|
||
state.notify?.();
|
||
}
|
||
|
||
function viewContext() {
|
||
const viewer = state.viewer;
|
||
if (!viewer) return {};
|
||
const carto = viewer.camera.positionCartographic;
|
||
const bbox = visibleBbox(viewer);
|
||
const center = bbox
|
||
? { lat: (bbox[1] + bbox[3]) / 2, lon: (bbox[0] + bbox[2]) / 2 }
|
||
: {
|
||
lat: Cesium.Math.toDegrees(carto.latitude),
|
||
lon: Cesium.Math.toDegrees(carto.longitude),
|
||
};
|
||
const ground = viewer.scene.globe?.getHeight?.(carto);
|
||
return {
|
||
lat: center.lat,
|
||
lon: center.lon,
|
||
heightM: carto.height - (Number.isFinite(ground) ? ground : 0),
|
||
};
|
||
}
|
||
|
||
function maxTiles() {
|
||
return state.status?.limits?.maxTiles || DEFAULT_MAX_TILES;
|
||
}
|
||
|
||
async function resolveArea(plan, signal) {
|
||
if (plan.place) {
|
||
const results = await source.geocode(plan.place, { signal });
|
||
const resolved = bboxFromGeocode(results[0]);
|
||
if (!resolved)
|
||
throw new Error(`Could not find "${plan.place}" on the map`);
|
||
return {
|
||
...resolved,
|
||
bbox: fitBboxToTileBudget(resolved.bbox, maxTiles()),
|
||
fromPlace: true,
|
||
};
|
||
}
|
||
const bbox = visibleBbox(state.viewer);
|
||
// The horizon (or a camera still in flight) yields a continent-sized
|
||
// rectangle; querying that would silently pick a box in the middle of it.
|
||
if (
|
||
!bbox ||
|
||
bbox[2] - bbox[0] > MAX_VIEW_SPAN_DEG ||
|
||
bbox[3] - bbox[1] > MAX_VIEW_SPAN_DEG
|
||
)
|
||
throw new Error('Zoom in closer to the ground, or name a place');
|
||
const view = viewContext();
|
||
return {
|
||
bbox: fitBboxToTileBudget(bbox, maxTiles()),
|
||
label: 'current view',
|
||
center: { lat: view.lat, lon: view.lon },
|
||
fromPlace: false,
|
||
};
|
||
}
|
||
|
||
async function runFeatures(plan, area, signal) {
|
||
const features = state.features;
|
||
parts.features.reset();
|
||
Object.assign(features, {
|
||
bbox: area.bbox,
|
||
title: plan.title,
|
||
layer: plan.layer,
|
||
values: plan.values,
|
||
loading: true,
|
||
});
|
||
state.query.stage = 'fetching';
|
||
notify();
|
||
// Results are the subject now: rest the coverage web until CLEAR so tens
|
||
// of thousands of markers are not read against a web of green lines.
|
||
parts.coverage.setResting(true);
|
||
// A named place is somewhere else: fly there. The current view already
|
||
// shows the area, so leave the camera where the user put it.
|
||
if (area.fromPlace) parts.features.frame(area.bbox);
|
||
let lastNotify = 0;
|
||
await source.queryFeatures(
|
||
{
|
||
bbox: area.bbox,
|
||
layer: plan.layer,
|
||
values: plan.values,
|
||
seenAfter: plan.seen_after,
|
||
seenBefore: plan.seen_before,
|
||
},
|
||
(record) => {
|
||
if (record.type === 'start')
|
||
features.progress = { done: 0, tiles: record.tiles };
|
||
else if (record.type === 'tile') {
|
||
features.progress.done++;
|
||
if (record.rows?.length) parts.features.appendRows(record.rows);
|
||
const now = Date.now();
|
||
if (now - lastNotify > 120) {
|
||
lastNotify = now;
|
||
notify();
|
||
}
|
||
} else if (record.type === 'done') {
|
||
features.truncated = record.truncated === true;
|
||
features.failed = record.failed || 0;
|
||
}
|
||
},
|
||
{ signal },
|
||
);
|
||
features.loading = false;
|
||
notify();
|
||
await parts.features.upgradeToIcons();
|
||
const summary = summarizeResults(features);
|
||
state.query.answer = summary
|
||
? `${plan.answer} ${summary}`.trim()
|
||
: noResultsAnswer(plan, area);
|
||
notify();
|
||
}
|
||
|
||
async function runNearest(plan, area, signal) {
|
||
const found = await nearestImageAround(area.center, signal, {
|
||
preferPano:
|
||
plan.prefer_pano === true || state.coverage.filter.pano === 'pano',
|
||
});
|
||
if (!found)
|
||
throw new Error(
|
||
`No Mapillary imagery within ${NEAREST_RING_M[NEAREST_RING_M.length - 1] + 50} m of ${area.label || 'that point'}`,
|
||
);
|
||
await parts.street.openImage(found.image.id);
|
||
state.query.answer = `${plan.answer} Opened the closest image, about ${Math.round(found.distanceM)} m away.`;
|
||
}
|
||
|
||
/**
|
||
* Mapillary's radius search stops at 50 m, which misses a landmark whose
|
||
* geocoded centre sits inside a large footprint. Probe the centre first,
|
||
* then rings of points around it, and keep the closest hit overall.
|
||
*/
|
||
async function nearestImageAround(
|
||
center,
|
||
signal,
|
||
{ preferPano = false } = {},
|
||
) {
|
||
const rings = [[center]];
|
||
for (const ring of NEAREST_RING_M) {
|
||
const probes = [];
|
||
for (let k = 0; k < 8; k++) {
|
||
const angle = (k / 8) * Math.PI * 2;
|
||
probes.push({
|
||
lat: center.lat + (ring * Math.cos(angle)) / 110_540,
|
||
lon:
|
||
center.lon +
|
||
(ring * Math.sin(angle)) /
|
||
(111_320 * Math.cos((center.lat * Math.PI) / 180)),
|
||
});
|
||
}
|
||
rings.push(probes);
|
||
}
|
||
for (const probes of rings) {
|
||
const results = await Promise.all(
|
||
probes.map((probe) =>
|
||
source
|
||
.nearestImages(
|
||
{ lat: probe.lat, lon: probe.lon, radius: 50, limit: 3 },
|
||
{ signal },
|
||
)
|
||
.catch(() => []),
|
||
),
|
||
);
|
||
let best = null;
|
||
let fallback = null;
|
||
for (const images of results)
|
||
for (const image of images) {
|
||
const coordinates =
|
||
image?.computed_geometry?.coordinates ||
|
||
image?.geometry?.coordinates;
|
||
if (!coordinates) continue;
|
||
const distanceM = metresBetween(center, {
|
||
lon: coordinates[0],
|
||
lat: coordinates[1],
|
||
});
|
||
const record = {
|
||
isPano: image.is_pano === true,
|
||
capturedAt: Number(image.captured_at) || 0,
|
||
};
|
||
// The dock's imagery filter is a hard constraint; a 360° preference
|
||
// from the request only breaks ties within the filtered set.
|
||
const candidate = {
|
||
image,
|
||
distanceM,
|
||
score: distanceM + (preferPano && !record.isPano ? 1000 : 0),
|
||
};
|
||
if (!fallback || distanceM < fallback.distanceM) fallback = candidate;
|
||
if (!passesImageryFilter(record, state.coverage.filter)) continue;
|
||
if (!best || candidate.score < best.score) best = candidate;
|
||
}
|
||
if (best) return best;
|
||
if (
|
||
fallback &&
|
||
state.coverage.filter.pano === 'all' &&
|
||
!state.coverage.filter.sinceMs
|
||
)
|
||
return fallback;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/**
|
||
* Execute an already-built plan (from the planner, the voice agent, or a
|
||
* test). Resolves the area, streams features or opens imagery, and records
|
||
* the turn in the history.
|
||
*/
|
||
async function execute(plan, { prompt = plan?.title || '', signal } = {}) {
|
||
if (!plan || typeof plan !== 'object')
|
||
throw new Error('A plan is required');
|
||
state.query.lastPlan = plan;
|
||
state.query.answer = plan.answer || '';
|
||
state.query.title = plan.title || '';
|
||
notify();
|
||
if (plan.intent === 'unsupported') {
|
||
state.query.stage = 'idle';
|
||
} else if (plan.intent === 'coverage') {
|
||
state.query.stage = 'resolving';
|
||
notify();
|
||
const area = await resolveArea(plan, signal);
|
||
state.query.place = area?.label || plan.place || null;
|
||
parts.features.frame(area.bbox, { duration: 2.4 });
|
||
state.query.stage = 'idle';
|
||
} else if (plan.intent === 'nearest_image') {
|
||
state.query.stage = 'resolving';
|
||
notify();
|
||
const area = await resolveArea(plan, signal);
|
||
state.query.place = area?.label || plan.place || null;
|
||
await runNearest(plan, area, signal);
|
||
state.query.stage = 'idle';
|
||
} else {
|
||
if (!plan.layer) plan = { ...plan, layer: 'points' };
|
||
state.query.stage = 'resolving';
|
||
notify();
|
||
const area = await resolveArea(plan, signal);
|
||
state.query.place = area?.label || plan.place || null;
|
||
await runFeatures(plan, area, signal);
|
||
state.query.stage = 'done';
|
||
}
|
||
state.query.history.push({ prompt, plan, total: state.features.total });
|
||
}
|
||
|
||
/** Run one natural-language request end to end. */
|
||
async function run(prompt) {
|
||
const text = String(prompt || '').trim();
|
||
if (!text) return;
|
||
abort();
|
||
const controller = new AbortController();
|
||
state.query.abort = controller;
|
||
Object.assign(state.query, {
|
||
busy: true,
|
||
stage: 'planning',
|
||
prompt: text,
|
||
answer: '',
|
||
error: null,
|
||
usage: null,
|
||
});
|
||
notify();
|
||
try {
|
||
const { plan, usage, model } = await source.plan(
|
||
{
|
||
query: text,
|
||
context: { view: viewContext(), previousPlan: state.query.lastPlan },
|
||
},
|
||
{ signal: controller.signal },
|
||
);
|
||
if (controller.signal.aborted) return;
|
||
state.query.usage = usage ? { ...usage, model } : null;
|
||
await execute(plan, { prompt: text, signal: controller.signal });
|
||
} catch (error) {
|
||
if (controller.signal.aborted) return;
|
||
state.features.loading = false;
|
||
state.query.stage = 'error';
|
||
state.query.error = describeError(error);
|
||
} finally {
|
||
if (state.query.abort === controller) {
|
||
state.query.busy = false;
|
||
state.query.abort = null;
|
||
}
|
||
notify();
|
||
}
|
||
}
|
||
|
||
/** Execute a supplied plan with the same lifecycle bookkeeping as run(). */
|
||
async function runPlan(plan, { prompt } = {}) {
|
||
abort();
|
||
const controller = new AbortController();
|
||
state.query.abort = controller;
|
||
Object.assign(state.query, {
|
||
busy: true,
|
||
stage: 'resolving',
|
||
prompt: prompt || plan?.title || '',
|
||
answer: '',
|
||
error: null,
|
||
usage: null,
|
||
});
|
||
notify();
|
||
try {
|
||
await execute(plan, { prompt, signal: controller.signal });
|
||
} catch (error) {
|
||
if (controller.signal.aborted) return;
|
||
state.features.loading = false;
|
||
state.query.stage = 'error';
|
||
state.query.error = describeError(error);
|
||
} finally {
|
||
if (state.query.abort === controller) {
|
||
state.query.busy = false;
|
||
state.query.abort = null;
|
||
}
|
||
notify();
|
||
}
|
||
}
|
||
|
||
function describeError(error) {
|
||
if (
|
||
error?.keyRequired === 'anthropic' ||
|
||
error?.payload?.keyRequired === 'anthropic'
|
||
)
|
||
return 'Mapillary AI needs an Anthropic key — add one in POWER UP.';
|
||
if (
|
||
error?.keyRequired === 'mapillary' ||
|
||
error?.payload?.keyRequired === 'mapillary' ||
|
||
error?.payload?.keyRequired === true
|
||
)
|
||
return 'Add a Mapillary client token in POWER UP first.';
|
||
if (error?.payload?.error === 'area_too_large') {
|
||
const { tiles, limit } = error.payload.detail || error.payload;
|
||
const times =
|
||
Number.isFinite(tiles) && Number.isFinite(limit) && limit > 0
|
||
? ` (about ${Math.max(2, Math.round(tiles / limit))}× what one query covers)`
|
||
: '';
|
||
return `That area is too large for one query${times}. Zoom in closer to the ground or name a smaller place.`;
|
||
}
|
||
return error?.message || 'Query failed';
|
||
}
|
||
|
||
function abort() {
|
||
state.query.abort?.abort();
|
||
state.query.abort = null;
|
||
state.query.busy = false;
|
||
state.features.loading = false;
|
||
}
|
||
|
||
/** Drop the drawn results and the conversational context. */
|
||
function clear() {
|
||
abort();
|
||
parts.features.reset();
|
||
parts.coverage.setResting(false);
|
||
Object.assign(state.query, {
|
||
stage: 'idle',
|
||
prompt: '',
|
||
answer: '',
|
||
error: null,
|
||
lastPlan: null,
|
||
usage: null,
|
||
title: '',
|
||
});
|
||
Object.assign(state.features, {
|
||
bbox: null,
|
||
title: '',
|
||
layer: null,
|
||
values: [],
|
||
});
|
||
notify();
|
||
}
|
||
|
||
return { run, runPlan, execute, clear, abort, viewContext };
|
||
}
|