feat(mapillary): street-level layer core — coverage, sequences, viewer bridge, query engine

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]>
This commit is contained in:
Said TurkseverandClaude Fable 5.1 committed 2026-09-23 15:44:32 +01:00
1 parent 0d41b6be54
commit fa5710bcf2
46 files changed
+9935 -32

No files matched your search

+516
View File
@@ -0,0 +1,516 @@
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 };
}