Merge origin/main: Google Street View, KartaView and Panoramax on the slim Street Level

Main gained three imagery providers (Google Street View, KartaView,
Panoramax), shared line-coverage, cone and photo-viewer modules, one source
lit at a time and the translated interface. Their shared modules still
carried what this branch removes, so the merge ports them onto it:

- lineCoverage.js is this branch's coverage.js made provider-neutral
  (draped lines near the ground only, the selection drawn over them, key
  and rate-limit blocking); sequenceCones.js is sequences.js the same way.
  Mapillary, KartaView and Panoramax all build on them; Mapillary moves
  back to providers/mapillary/ beside the others.
- No ground casting, mesh sampling, surface modes, FOLLOW, legend, prewarm,
  orbit overview points (Panoramax's density dots included), stale-tile
  swaps or water-filled point budget come back.
- Kept from main because the new providers need them: requiresMapStack and
  attachMapStackController (Street View on Google 3D only), ground clicks,
  openNearest with an optional provider nearestImage, openImage {frame},
  reportError, the view-cone marker (now an SVG glyph), filters /
  coverageLabel / sinceBasis, OPEN STREET VIEW, keyAlternatives and i18n.
- photoViewer.js treats the viewer as expanded when its wrap is full screen
  or the iPhone popover, as EXPAND now is.
- The fixture browser gate keeps its 8 steps and adds one each for
  KartaView and Panoramax; catalogs, docs, boundaries and format scope
  follow.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
German KhokhlovandClaude Opus 5.5 committed 2026-10-19 13:51:45 +04:00
commit 6390a3346f
809 files changed
+81825 -6035

No files matched your search

@@ -0,0 +1,578 @@
import {
createLineCoverage,
freshCoverage,
sequenceIdFromPick,
} from '../../lineCoverage.js';
import { createSequenceCones, thinImages } from '../../sequenceCones.js';
import { passesImageryFilter } from '../../filter.js';
import { lonToTileX, latToTileY, tileBounds } from '../../tileMath.js';
import { metresBetween } from '../../view.js';
import { createLru, createTileCache } from '../../tileCache.js';
import { decodeCoverageTileSliced, decodePictures } from './decode.js';
import { createPanoramaxSource } from './source.js';
import { createPanoramaxViewer } from './viewer.js';
import { msg } from '../../../../i18n/index.js';
import {
COLORS,
COVERAGE_LINES_BELOW_M,
COVERAGE_TUNING,
COVERAGE_Z11_BELOW_M,
COVERAGE_Z12_BELOW_M,
COVERAGE_Z13_BELOW_M,
COVERAGE_Z14_BELOW_M,
GONE_MESSAGE,
LINE_CLICK_HINT,
LINE_CLICK_RADIUS_MAX_M,
LINE_CLICK_RADIUS_PER_HEIGHT,
NEAREST_LIMIT,
NEAREST_RADIUS_M,
FILTERED_HINT,
NO_COVERAGE_HINT,
PANORAMAX_CREDIT_HTML,
PANORAMAX_LABEL,
PANORAMAX_NAME,
PANORAMAX_PROVIDER_ID,
PICK_PREFIX,
PICTURE_TILE_EDGE_M,
PICTURE_TILE_ZOOM,
RATE_LIMITED_MESSAGE,
UNREADABLE_TILE_MESSAGE,
ZOOM_IN_HINT,
normalizeItem,
} from './policy.js';
export { PANORAMAX_PROVIDER_ID } from './policy.js';
/**
* A tile's bytes decoded by `decode`; a body that is not a vector tile
* (an HTML error page, a cut-off answer) reads as such, not as a parser's
* "Unimplemented type: 4".
*/
async function readable(decode) {
try {
return await decode();
} catch (error) {
if (error?.name === 'AbortError' || error?.status !== undefined)
throw error;
throw new Error(UNREADABLE_TILE_MESSAGE);
}
}
/** Pictures kept in memory by id (lookups and ‹ › fill it). */
const PHOTO_CACHE_SIZE = 2000;
/** Sequences whose cone centre is remembered. */
const ANCHOR_CACHE_SIZE = 50;
/** Decoded coverage tiles kept (a simplified dense z10 tile is ~4 MB). */
const COVERAGE_TILE_CACHE_SIZE = 16;
/** One sequence's pictures in a z15 tile, kept for re-centring. */
const PICTURE_LIST_CACHE_SIZE = 32;
/**
* Sequence lines at z10–14 below 60 km; above, nothing is drawn (the hint
* says to zoom in).
*/
export function panoramaxZoomFor(heightM) {
if (!Number.isFinite(heightM) || heightM > COVERAGE_LINES_BELOW_M)
return null;
return heightM <= COVERAGE_Z14_BELOW_M
? 14
: heightM <= COVERAGE_Z13_BELOW_M
? 13
: heightM <= COVERAGE_Z12_BELOW_M
? 12
: heightM <= COVERAGE_Z11_BELOW_M
? 11
: 10;
}
/**
* The imagery filter for lines. A line is dated by its sequence's first
* day, so a sequence still growing may hide under "since" while its newer
* pictures can be opened; a line with no camera type or no day is kept (a
* click finds out).
*/
export function passesCoverage(record, filter) {
if (!filter) return true;
return passesImageryFilter(record, {
pano: typeof record.isPano === 'boolean' ? filter.pano : 'all',
sinceMs: record.capturedAt ? filter.sinceMs : null,
});
}
/** The z15 tile holding a point. */
function pictureTileOf({ lon, lat }) {
const z = PICTURE_TILE_ZOOM;
return { x: lonToTileX(lon, z), y: latToTileY(lat, z), z };
}
/**
* The z15 tiles whose pictures surround a point: its own first, and the
* neighbours it sits within PICTURE_TILE_EDGE_M of (at most nine).
*/
export function pictureTilesAround(point) {
const home = pictureTileOf(point);
const box = tileBounds(home.x, home.y, home.z);
const near = (lon, lat) =>
metresBetween(point, { lon, lat }) <= PICTURE_TILE_EDGE_M;
// Near both edges at once where tiles are narrow (high latitudes).
const dxs = [0];
if (near(box.west, point.lat)) dxs.push(-1);
if (near(box.east, point.lat)) dxs.push(1);
const dys = [0];
if (near(point.lon, box.north)) dys.push(-1);
if (near(point.lon, box.south)) dys.push(1);
const max = 2 ** home.z;
const tiles = [];
for (const dy of dys)
for (const dx of dxs) {
const y = home.y + dy;
if (y < 0 || y >= max) continue;
tiles.push({ x: (home.x + dx + max) % max, y, z: home.z });
}
return tiles;
}
const tileKey = ({ x, y, z }) => `${z}/${x}/${y}`;
/**
* Panoramax Street Level provider: the federated, keyless, open
* street-level commons. Coverage from its vector tiles (sequence lines
* near the ground, nothing from orbit); a click on a line opens that
* sequence's picture nearest the click, with cones along the sequence
* around it and ‹ › to step through it. Flat pictures show as photos, 360°
* ones on the shared WebGL panorama.
* @param {{source?: ReturnType<typeof createPanoramaxSource>, viewerOptions?: object}} [options]
* @returns {import('../../registry.js').StreetLevelProvider}
*/
export function createPanoramaxProvider({
source = createPanoramaxSource(),
viewerOptions = {},
} = {}) {
return Object.freeze({
id: PANORAMAX_PROVIDER_ID,
name: PANORAMAX_NAME,
label: PANORAMAX_LABEL,
requiresKeyId: null,
pickPrefix: PICK_PREFIX.root,
colors: COLORS,
credit: Object.freeze({ html: PANORAMAX_CREDIT_HTML }),
defaultOn: false,
coverageLabel: Object.freeze({
noun: 'sequences',
action: LINE_CLICK_HINT,
}),
create(context) {
const state = {
context,
services: context.services,
viewer: null,
coverage: freshCoverage({ keyless: true }),
sequence: {
selectedId: null,
images: [],
collection: null,
loading: false,
error: null,
abort: null,
},
};
const photos = createLru(PHOTO_CACHE_SIZE);
/** Where each sequence's cones centre: the picture last opened in it, or a click. */
const anchors = createLru(ANCHOR_CACHE_SIZE);
/** The z15 tiles the cones were drawn from. */
let drawn = null;
/** A line click: its sequence's pictures win the next nearest lookup there. */
let preferred = null;
function remember(item) {
const photo = normalizeItem(item);
if (photo) photos.set(photo.id, photo);
return photo;
}
/**
* Lookups in flight, shared: ‹ › and the viewer ask for the same
* picture. A lookup stops once every caller waiting on it has given up
* (its search would hold one of the two API connections for nothing).
*/
const inflight = new Map();
function getPhoto(photoId, { signal } = {}) {
const id = String(photoId);
const cached = photos.get(id);
if (cached) return Promise.resolve(cached);
if (signal?.aborted) return Promise.reject(signal.reason);
let lookup = inflight.get(id);
if (!lookup) {
const controller = new AbortController();
lookup = { controller, waiting: 0 };
lookup.promise = source
.getItem(id, { signal: controller.signal })
.catch((error) => {
// Ids are UUIDs: the API answers 400 to anything else.
if (error?.status === 400) return null;
throw error;
})
.then((item) => {
const photo = item && remember(item);
if (!photo) throw new Error(GONE_MESSAGE);
return photo;
})
.finally(() => {
if (inflight.get(id) === lookup) inflight.delete(id);
});
lookup.promise.catch(() => {});
inflight.set(id, lookup);
}
const shared = lookup;
shared.waiting++;
if (!signal) shared.waiting = Infinity;
return new Promise((resolve, reject) => {
const leave = () => {
reject(signal.reason);
shared.waiting--;
// A caller in the same tick (the same photo opened again) may
// still join: stop only if nobody has.
queueMicrotask(() => {
if (shared.waiting > 0) return;
shared.controller.abort(signal.reason);
if (inflight.get(id) === shared) inflight.delete(id);
});
};
signal?.addEventListener('abort', leave, { once: true });
shared.promise.then(
(photo) => {
signal?.removeEventListener('abort', leave);
resolve(photo);
},
(error) => {
signal?.removeEventListener('abort', leave);
reject(error);
},
);
});
}
/**
* How far from a line click its sequence's pictures are looked for:
* from high up the click may land tens of metres off the line.
*/
function lineClickRadius() {
const height = state.viewer?.camera?.positionCartographic?.height;
if (!Number.isFinite(height)) return NEAREST_RADIUS_M;
return Math.min(
LINE_CLICK_RADIUS_MAX_M,
Math.max(NEAREST_RADIUS_M, height * LINE_CLICK_RADIUS_PER_HEIGHT),
);
}
/** The picture `delta` along its sequence, from its own links (null at an end). */
async function step(photo, delta) {
if (!photo?.sequenceId) return null;
return (delta < 0 ? photo.prevId : photo.nextId) || null;
}
// Decoded tiles, kept a while: panning back, or across a zoom band and
// back, neither fetches nor decodes them again.
const coverageTiles = createTileCache({
size: COVERAGE_TILE_CACHE_SIZE,
load: (tile, { signal }) =>
readable(async () =>
decodeCoverageTileSliced(
await source.getTile(tile, { signal }),
tile,
{ signal },
),
),
});
/** A z15 tile's pictures of one sequence, by `z/x/y:sequence`. */
const pictureLists = createLru(PICTURE_LIST_CACHE_SIZE);
/**
* Only finished lists are kept: a load in flight belongs to its own
* selection, whose abort (a re-centre) must not empty the next one's.
*/
async function picturesIn(tile, sequenceId, signal) {
const key = `${tileKey(tile)}:${sequenceId}`;
const kept = pictureLists.get(key);
if (kept) return kept;
const list = await readable(async () =>
decodePictures(
await source.getTile(tile, { signal, lane: 'pictures' }),
tile,
sequenceId,
),
);
pictureLists.set(key, list);
return list;
}
const coverage = createLineCoverage({
state,
fetchTile: (tile, options) => coverageTiles.get(tile, options),
zoomFor: panoramaxZoomFor,
colors: COLORS,
pickPrefix: PICK_PREFIX.sequence,
renderKey: 'panoramax-coverage',
tuning: COVERAGE_TUNING,
messages: { rateLimited: RATE_LIMITED_MESSAGE, tooHigh: ZOOM_IN_HINT },
passes: passesCoverage,
});
const cones = createSequenceCones({
state,
async loadImages(sequenceId, { signal }) {
const anchor = anchors.get(sequenceId);
if (!anchor) return [];
const tiles = pictureTilesAround(anchor);
// Known from the start: a picture opening while these load is
// judged against them (re-centred if outside, left alone inside).
const covering = { sequenceId, tiles: new Set(tiles.map(tileKey)) };
drawn = covering;
const conesOf = (lists) =>
thinImages(
[
...new Map(
lists.flat().map((image) => [image.id, image]),
).values(),
].sort((a, b) => a.capturedAt - b.capturedAt),
);
const keyOf = (tile) => `${tileKey(tile)}:${sequenceId}`;
// The home tile is needed now (it holds the open picture).
const home = await picturesIn(tiles[0], sequenceId, signal);
signal?.throwIfAborted();
// Neighbours already read draw with it; the rest (each up to
// 1.4 MB in central Paris) join the cones as they arrive.
const neighbours = tiles.slice(1);
const kept = neighbours
.map((tile) => pictureLists.get(keyOf(tile)))
.filter(Boolean);
const missing = neighbours.filter(
(tile) => !pictureLists.get(keyOf(tile)),
);
if (missing.length)
Promise.allSettled(
missing.map((tile) => picturesIn(tile, sequenceId, signal)),
).then((lists) => {
if (signal?.aborted || drawn !== covering) return;
dropFailed(covering, missing, lists);
// Only a tile that arrived now redraws (no loop on failures).
if (lists.some((list) => list.status === 'fulfilled'))
cones.select(sequenceId, { force: true });
});
return conesOf([home, ...kept]);
},
colors: COLORS,
pickPrefix: PICK_PREFIX.image,
spriteId: 'street-level:panoramax-cones',
renderKey: 'panoramax-sequence',
onHighlight: (sequenceId) => coverage.highlight(sequenceId),
});
/**
* A tile that failed is not covered: a picture opening in it later
* re-centres the cones there (and asks for the tile again).
*/
function dropFailed(covering, tiles, lists) {
lists.forEach((list, i) => {
if (list.status === 'rejected')
covering.tiles.delete(tileKey(tiles[i]));
});
}
/**
* The cones show the z15 tiles around one picture: once a picture of
* the selected sequence opens outside them (‹ ›, a cone), re-centre.
*/
function recentreCones(photo) {
if (!photo?.sequenceId) return;
if (state.sequence.selectedId !== photo.sequenceId) return;
if (drawn?.sequenceId !== photo.sequenceId) return;
if (drawn.tiles.has(tileKey(pictureTileOf(photo)))) return;
cones.select(photo.sequenceId, { force: true });
}
const viewer = createPanoramaxViewer({
getPhoto,
// The cones centre on the picture actually shown, never on a
// lookup that came back after the user moved on.
onShowing: (photo) => {
if (photo.sequenceId) anchors.set(photo.sequenceId, photo);
},
// After a GPU reset the same picture is drawn again by the viewer
// itself: through the core it would cancel a lookup the user
// started. A failure still shows.
onReopen: (photoId) =>
viewer
.open(photoId)
.catch((error) =>
context.actions.reportError(
error?.message ||
msg('The Panoramax photo could not be loaded'),
),
),
step,
onStep: (photoId) =>
context.actions.openImage(photoId, { frame: false }),
onShown: recentreCones,
// Esc in the viewer clears the selected sequence, as the panel says.
onEscape: () => {
if (!state.sequence.selectedId) return false;
cones.clearSelection();
drawn = null;
return true;
},
render: context.services?.render,
...viewerOptions,
});
/** Nearest of `items` within `radius` metres of a point, or null. */
function nearestOf(items, point, radius = NEAREST_RADIUS_M) {
let best = null;
for (const item of items) {
const photo = remember(item);
if (!photo) continue;
const metres = metresBetween(point, photo);
if (metres > radius) continue;
if (!best || metres < best.metres) best = { photo, metres };
}
return best?.photo ?? null;
}
return {
async status() {
return { configured: true };
},
init(cesiumViewer) {
state.viewer = cesiumViewer;
cones.ensureCollections(cesiumViewer);
cones.setVisible(false);
},
activate(cesiumViewer) {
state.viewer = cesiumViewer;
cones.setVisible(true);
coverage.attach(cesiumViewer);
},
deactivate() {
coverage.detach();
coverage.clear();
coverage.unblock();
cones.clearSelection();
cones.setVisible(false);
drawn = null;
preferred = null;
// Off: decoded tiles and lists go (several MB each over a city).
coverageTiles.clear();
pictureLists.clear();
},
destroy(cesiumViewer) {
coverage.detach();
coverage.clear();
coverage.unblock();
cones.destroy(cesiumViewer);
},
/** The filter changed: redraw. Each draw reads it from the context. */
setFilter() {
coverage.rebuild();
cones.rerender();
},
coverageStats() {
const stats = coverage.stats();
let fallback = '';
// Lines drawn for the camera (a zoom), all settled, none shown.
const settled =
state.coverage.zoom != null && !stats.loading && !stats.error;
if (settled && stats.count === 0) {
// Tiles that held lines the filter hid all of.
const filteredOut = [...state.coverage.tiles.values()].some(
(tile) => tile.total > 0,
);
fallback = filteredOut ? FILTERED_HINT : NO_COVERAGE_HINT;
}
return { ...stats, hint: stats.hint || fallback };
},
/**
* A line opens its sequence's picture nearest the click (the cones
* follow once it is on screen); a cone opens its picture.
*/
handlePick(pickId, { groundPoint } = {}) {
if (pickId.startsWith(PICK_PREFIX.image)) {
context.actions.openImage(pickId.slice(PICK_PREFIX.image.length));
return true;
}
const sequenceId = sequenceIdFromPick(pickId, PICK_PREFIX.sequence);
if (!sequenceId) return false;
const point = groundPoint?.();
// No ground under the click (the sky beyond a line): nothing to open.
if (!point) return true;
anchors.set(sequenceId, { ...point, sequenceId });
preferred = {
sequenceId,
lon: point.lon,
lat: point.lat,
radius: lineClickRadius(),
};
context.actions.openNearest(point);
return true;
},
selectSequence: (sequenceId) =>
cones.select(sequenceId, { force: true }),
clearSequence: () => {
cones.clearSelection();
drawn = null;
},
sequenceStats: () => ({
selectedId: state.sequence.selectedId,
images: state.sequence.images.length,
loading: state.sequence.loading,
error: state.sequence.error,
}),
/**
* The nearest picture within the search radius that passes the
* imagery filter, or null. After a click on a line, that line's
* sequence is asked first.
*/
async nearestImage({ lat, lon }, { signal } = {}) {
const point = { lat, lon };
const filter = context.getFilter();
// Only the lookup the click itself asked for (the same point).
const wanted =
preferred && metresBetween(preferred, point) < 1 ? preferred : null;
preferred = null;
const ask = (collections, radius = NEAREST_RADIUS_M) =>
source.nearestItems(
{
lat,
lon,
radius,
limit: NEAREST_LIMIT,
collections,
pano: filter.pano,
sinceMs: filter.sinceMs,
},
{ signal },
);
if (wanted) {
const hit = nearestOf(
await ask(wanted.sequenceId, wanted.radius),
point,
wanted.radius,
);
if (hit) return hit.id;
}
return nearestOf(await ask(null), point)?.id ?? null;
},
viewer,
};
},
});
}