refactor(street-level): drop hover, legend and byte-budget cache; flatten the provider directory

- No pointer cursor over coverage lines (no other layer has one); a click
  test replaces the hover tests.
- No legend: one source, one colour.
- The on-globe credit lives in index.js; credits.js is gone.
- Billboard glyphs are SVG data URLs with the same geometry, so tests need
  no canvas stub.
- The tile cache keeps the 120 most recently used tiles, same 24 h TTL,
  instead of a byte budget; listTileLayers was test-only.
- providers/mapillary/ is flattened into the layer and its policy merged
  into one policy.js; the source's method list is a literal in the catalog.
- One fakeCesiumViewer for the layer tests.
- The fixture gate keeps the steps the unit tests do not cover: coverage and
  credit, a rejected key, line -> cone -> photo, close, a keyless page.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
This commit is contained in:
German KhokhlovandClaude Fable 5.1 committed 2026-10-08 19:17:45 +04:00
1 parent 34d43c7e3f
commit e214129e45
41 files changed
+335 -909

No files matched your search

@@ -1,437 +0,0 @@
import * as Cesium from 'cesium';
import { decodeCoverageTile } from './decode.js';
import { passesImageryFilter, resolveFilter } from '../../filter.js';
import { isActive } from '../../state.js';
import { groundUnderCamera, viewFocus, visibleBbox } from '../../view.js';
import { coverageZoomForHeight, tilesForBbox } from '../../tileMath.js';
import {
COLORS,
COVERAGE_LINE_WIDTH_PX,
COVERAGE_MAX_SEQUENCES,
COVERAGE_MAX_TILES,
COVERAGE_MOVE_DEBOUNCE_MS,
KEY_REJECTED_MESSAGE,
PICK_PREFIX,
RATE_LIMITED_MESSAGE,
SEQUENCE_VIEW_RANGE_MIN_M,
SEQUENCE_VIEW_RANGE_PER_HEIGHT,
} from './policy.js';
/** Sequences per primitive: smaller batches build, and show, sooner. */
const SEQUENCE_PRIMITIVE_BATCH = 120;
const PER_TILE_SEQUENCE_CAP = Math.floor(
COVERAGE_MAX_SEQUENCES / COVERAGE_MAX_TILES,
);
/** Sequence id for a line's pick id (`mly:seq:<id>`), else null. */
export function sequenceIdFromPick(pickId) {
if (typeof pickId !== 'string' || !pickId.startsWith(PICK_PREFIX.sequence))
return null;
return pickId.slice(PICK_PREFIX.sequence.length);
}
/** Line instances for sequences' parts, every part picking its sequence. */
function lineInstances(sequences, color, width) {
const attributes = {
color: Cesium.ColorGeometryInstanceAttribute.fromColor(color),
};
const instances = [];
for (const sequence of sequences)
for (const coordinates of sequence.parts) {
let positions;
try {
positions = Cesium.Cartesian3.fromDegreesArray(coordinates.flat());
} catch {
continue;
}
if (positions.length < 2) continue;
instances.push(
new Cesium.GeometryInstance({
geometry: new Cesium.GroundPolylineGeometry({ positions, width }),
id: `${PICK_PREFIX.sequence}${sequence.id}`,
attributes,
}),
);
}
return instances;
}
/** Draped lines that follow terrain and 3D tiles (Google 3D) alike. */
function linePrimitive(geometryInstances, asynchronous) {
return new Cesium.GroundPolylinePrimitive({
geometryInstances,
appearance: new Cesium.PolylineColorAppearance(),
classificationType: Cesium.ClassificationType.BOTH,
asynchronous,
allowPicking: true,
});
}
/** Hint above the street-zoom ceiling, where no coverage is drawn. */
export const ZOOM_IN_HINT = 'Zoom in to see street-level coverage';
/** Hint when no ground is in view within range (looking at the sky). */
const NO_GROUND_HINT =
'Point the camera at the ground for street-level coverage';
/**
* Camera-driven coverage: Mapillary sequence lines (z11–14) near the ground,
* draped on terrain and 3D tiles alike. Nothing is drawn from orbit.
*/
export function createCoverage({ state, source }) {
const { render } = state.services;
function requestRender() {
render?.governorRequestRender?.('mapillary-coverage');
}
function ensureTerrainReady() {
return (state.coverage.terrainReady ||=
Cesium.GroundPolylinePrimitive.initializeTerrainHeights());
}
function tileKey({ x, y, z }) {
return `${z}/${x}/${y}`;
}
/** The imagery filter, resolved now: "since N days" moves with the clock. */
function filter() {
return resolveFilter(state.filter);
}
/**
* A tile's sequences, filtered then capped: capping first could leave a
* dense tile of newer flat captures with no 360° lines at all.
*/
function drawnSequences(entry) {
const drawn = [];
const current = filter();
for (const sequence of entry.sequenceList) {
if (drawn.length >= PER_TILE_SEQUENCE_CAP) break;
if (passesImageryFilter(sequence, current)) drawn.push(sequence);
}
return drawn;
}
/** Batched draped primitives for a tile's sequences. */
function buildSequencePrimitives(sequences) {
const instances = lineInstances(
sequences,
Cesium.Color.fromCssColorString(COLORS.coverage).withAlpha(0.92),
COVERAGE_LINE_WIDTH_PX,
);
const primitives = [];
for (let i = 0; i < instances.length; i += SEQUENCE_PRIMITIVE_BATCH)
primitives.push(
linePrimitive(instances.slice(i, i + SEQUENCE_PRIMITIVE_BATCH), true),
);
return primitives;
}
/**
* Draw the selected sequence again over the coverage, in the selection
* colour, from every loaded tile it crosses; none when nothing is selected.
* Built at once: its tiles loaded, so the terrain table has too.
*/
function highlight(sequenceId = state.sequence.selectedId) {
const scene = state.viewer?.scene;
if (state.coverage.highlight) {
scene?.groundPrimitives?.remove(state.coverage.highlight);
state.coverage.highlight = null;
}
if (!sequenceId || !scene) return;
const parts = [];
for (const entry of state.coverage.tiles.values())
parts.push(...(entry.sequences.get(sequenceId)?.parts || []));
const instances = lineInstances(
[{ id: sequenceId, parts }],
Cesium.Color.fromCssColorString(COLORS.selected),
COVERAGE_LINE_WIDTH_PX + 1,
);
if (!instances.length) return;
state.coverage.highlight = scene.groundPrimitives.add(
linePrimitive(instances, false),
);
requestRender();
}
function attachPrimitive(entry) {
const scene = state.viewer?.scene;
if (!scene) return;
// Lookup, picking and counts follow what is drawn, not the whole tile.
const sequences = drawnSequences(entry);
entry.sequences = new Map(sequences.map((s) => [s.id, s]));
entry.primitives = buildSequencePrimitives(sequences);
for (const primitive of entry.primitives)
scene.groundPrimitives.add(primitive);
}
function detachPrimitive(entry) {
const scene = state.viewer?.scene;
for (const primitive of entry.primitives || []) {
try {
scene?.groundPrimitives?.remove(primitive);
} catch {
/* already gone */
}
}
entry.primitives = [];
}
function removeTile(key) {
const entry = state.coverage.tiles.get(key);
if (!entry) return;
detachPrimitive(entry);
state.coverage.tiles.delete(key);
}
async function loadTile(tile) {
const key = tileKey(tile);
if (state.coverage.tiles.has(key) || state.coverage.pending.has(key))
return;
const controller = new AbortController();
state.coverage.pending.set(key, controller);
notify();
try {
// Fetch and the one-time terrain-height table load run side by side,
// both handled from the start so an early tile failure is not unhandled.
const [bytes] = await Promise.all([
source.getTile('coverage', tile.z, tile.x, tile.y, {
signal: controller.signal,
}),
ensureTerrainReady(),
]);
// Only an abort, a zoom change, a clear or a newer request for this tile
// discards the bytes; a refresh that still wants the tile keeps them.
if (
controller.signal.aborted ||
state.coverage.pending.get(key) !== controller ||
state.coverage.tiles.has(key) ||
tile.z !== state.coverage.zoom
)
return;
const decoded = decodeCoverageTile(bytes, tile);
const entry = { primitives: [], sequences: new Map() };
// Newest first; the per-tile cap applies to what passes the filter.
entry.sequenceList = decoded.sequences.sort(
(a, b) => (b.capturedAt || 0) - (a.capturedAt || 0),
);
attachPrimitive(entry);
state.coverage.tiles.set(key, entry);
state.coverage.lastError = null;
// Over the new lines, and along any of the selection's parts they add.
if (entry.sequences.has(state.sequence.selectedId)) highlight();
requestRender();
} catch (error) {
if (
controller.signal.aborted ||
state.coverage.pending.get(key) !== controller
)
return;
// Every other tile would be refused too: stop asking.
if (error?.keyRejected) block('rejected');
else if (error?.keyRequired) block('no-key');
else if (error?.retryAfterSec) block('rate-limited', error.retryAfterSec);
else state.coverage.lastError = error?.message || 'Coverage tile failed';
} finally {
// Only the request that still owns the key settles it: a superseded one
// must not drop a newer request's entry (which is what counts as loading).
if (state.coverage.pending.get(key) === controller)
state.coverage.pending.delete(key);
notify();
}
}
/**
* Pause tile requests (see `blocked` in state.js). A rate limit keeps what
* is drawn and refreshes once its wait is over; a key problem outranks it,
* and a rejected key holds until `unblock` (the layer goes off).
*/
function block(reason, retryAfterSec = 0) {
const current = state.coverage.blocked;
if (current === 'rejected') return;
if (reason === 'rate-limited' && current === 'no-key') return;
clearTimeout(state.coverage.blockTimer);
state.coverage.blockTimer = null;
state.coverage.blocked = reason;
if (reason === 'rate-limited')
state.coverage.blockTimer = setTimeout(() => {
state.coverage.blockTimer = null;
state.coverage.blocked = null;
refresh();
}, retryAfterSec * 1000);
}
/** The layer went off: forget refusals and errors, so the next run asks again. */
function unblock() {
clearTimeout(state.coverage.blockTimer);
state.coverage.blockTimer = null;
if (['rejected', 'rate-limited'].includes(state.coverage.blocked))
state.coverage.blocked = null;
state.coverage.lastError = null;
}
/** The server's key status: until it answers, nothing is requested. */
function setKeyStatus(configured) {
if (!configured) block('no-key');
else if (['status', 'no-key'].includes(state.coverage.blocked)) {
state.coverage.blocked = null;
refresh();
}
notify();
}
function notify() {
state.notify?.();
}
/**
* The tiles for the camera: what the screen shows within range of it, at
* the zoom for its height above ground, nearest the camera first.
*/
function wantedTiles(viewer) {
const ground = groundUnderCamera(viewer);
const cameraHeight = viewer.camera?.positionCartographic?.height;
const height = Number.isFinite(cameraHeight)
? cameraHeight - (ground ?? 0)
: null;
const zoom = coverageZoomForHeight(height);
if (zoom == null) return { hint: ZOOM_IN_HINT };
// Rays meet the ground where it really is (1,600 m up in Denver) and stop
// short of the horizon, which would stretch the box to the world.
const ranged = {
groundHeight: ground,
maxRange: Math.max(
SEQUENCE_VIEW_RANGE_MIN_M,
height * SEQUENCE_VIEW_RANGE_PER_HEIGHT,
),
};
const bbox = visibleBbox(viewer, ranged);
if (!bbox) return { hint: NO_GROUND_HINT };
// Ranked from between the camera's ground point and the screen centre's:
// a tilted view's box centre can sit kilometres past both.
const tiles = tilesForBbox(bbox, zoom, {
limit: COVERAGE_MAX_TILES,
from: viewFocus(viewer, ranged),
});
return { zoom, tiles };
}
/** Recompute the tile set for the current camera and reconcile primitives. */
function refresh() {
const viewer = state.viewer;
if (!viewer || !isActive(state) || state.coverage.blocked) return;
const { zoom, tiles, hint } = wantedTiles(viewer);
if (hint) {
state.coverage.hint = hint;
clear();
notify();
return;
}
state.coverage.hint = '';
state.coverage.zoom = zoom;
const wanted = new Set(tiles.map(tileKey));
for (const key of [...state.coverage.tiles.keys()])
if (!wanted.has(key)) removeTile(key);
for (const [key, controller] of [...state.coverage.pending])
if (!wanted.has(key)) {
// The aborted request no longer owns its key, so its `finally` will
// not settle it: settle it here.
controller.abort();
state.coverage.pending.delete(key);
}
for (const tile of tiles) loadTile(tile);
notify();
}
function scheduleRefresh() {
clearTimeout(state.coverage.debounceTimer);
state.coverage.debounceTimer = setTimeout(
refresh,
COVERAGE_MOVE_DEBOUNCE_MS,
);
}
function attach(viewer) {
detach();
const remove = viewer.camera.changed.addEventListener(scheduleRefresh);
const removeEnd = viewer.camera.moveEnd.addEventListener(scheduleRefresh);
state.coverage.removeCameraListener = () => {
remove();
removeEnd();
};
refresh();
}
function detach() {
clearTimeout(state.coverage.debounceTimer);
state.coverage.debounceTimer = null;
state.coverage.removeCameraListener?.();
state.coverage.removeCameraListener = null;
}
function clear() {
for (const controller of state.coverage.pending.values())
controller.abort();
state.coverage.pending.clear();
for (const key of [...state.coverage.tiles.keys()]) removeTile(key);
highlight(null);
state.coverage.zoom = null;
requestRender();
}
/** Rebuild every loaded tile from its decoded cache (after a filter change). */
function rebuild() {
for (const entry of state.coverage.tiles.values()) {
detachPrimitive(entry);
attachPrimitive(entry);
}
highlight();
requestRender();
notify();
}
/**
* Sequences drawn. A sequence that crosses a tile edge is in both tiles'
* lists, so sequences count once by id.
*/
function sequenceCount() {
const ids = new Set();
for (const entry of state.coverage.tiles.values())
for (const id of entry.sequences.keys()) ids.add(id);
return ids.size;
}
/** What the panel and the layer list show: count, LOADING, key gate, error. */
function stats() {
const { blocked } = state.coverage;
return {
count: sequenceCount(),
// Waiting for the key status is loading too, not an empty view.
loading:
state.coverage.pending.size > 0 ||
(blocked === 'status' && isActive(state)),
hint: state.coverage.hint,
keyRequired: blocked === 'no-key' || blocked === 'rejected',
keyRejected: blocked === 'rejected',
error:
blocked === 'rejected'
? KEY_REJECTED_MESSAGE
: blocked === 'rate-limited'
? RATE_LIMITED_MESSAGE
: state.coverage.lastError,
};
}
return {
attach,
detach,
refresh,
clear,
unblock,
setKeyStatus,
rebuild,
highlight,
stats,
};
}
@@ -1,549 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import { createCoverage, ZOOM_IN_HINT } from './coverage.js';
import { freshCoverage } from '../../state.js';
import { encodeCoverageTile } from './coverageFixture.mjs';
import { rayCamera } from '../../../../testSupport/streetLevelFakes.mjs';
import { COVERAGE_MAX_SEQUENCES, COVERAGE_MAX_TILES } from './policy.js';
import { lonToTileX, latToTileY, tileBounds } from '../../tileMath.js';
const RAD = Math.PI / 180;
// Node has no WebGL context to report line-width limits; a browser's
// context sets these on startup, and appearances validate against them.
Cesium.ContextLimits._minimumAliasedLineWidth = 1;
Cesium.ContextLimits._maximumAliasedLineWidth = 10;
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
/** A scene collection that remembers what is on the globe. */
function collection() {
const items = new Set();
return {
items,
add(primitive) {
items.add(primitive);
return primitive;
},
remove(primitive) {
return items.delete(primitive);
},
};
}
/** The centre of the z14 tile holding a point, so a small view is one tile. */
function tileCentre(lon, lat) {
const x = lonToTileX(lon, 14);
const y = latToTileY(lat, 14);
const { west, east, south, north } = tileBounds(x, y, 14);
return {
tile: { x, y, z: 14 },
lon: (west + east) / 2,
lat: (south + north) / 2,
};
}
/** A viewer looking straight down on a 0.004° square around `view`. */
function fakeViewer(view) {
return {
view,
scene: {
canvas: { clientWidth: 100, clientHeight: 100 },
globe: { show: false, ellipsoid: Cesium.Ellipsoid.WGS84 },
groundPrimitives: collection(),
primitives: collection(),
},
camera: {
get positionCartographic() {
return {
longitude: view.lon * RAD,
latitude: view.lat * RAD,
height: view.height,
};
},
pickEllipsoid(point) {
return Cesium.Cartesian3.fromDegrees(
view.lon - 0.002 + (point.x / 100) * 0.004,
view.lat + 0.002 - (point.y / 100) * 0.004,
);
},
},
};
}
/** A source whose tile requests the test resolves, one call at a time. */
function deferredSource() {
const calls = [];
return {
calls,
getTile(layer, z, x, y, { signal } = {}) {
return new Promise((resolve, reject) => {
calls.push({ key: `${z}/${x}/${y}`, z, signal, resolve, reject });
});
},
};
}
function setup() {
const centre = tileCentre(-121.4944, 38.5816);
const viewer = fakeViewer({ lon: centre.lon, lat: centre.lat, height: 900 });
const source = deferredSource();
const state = {
viewer,
services: {},
enabled: true,
providerOn: true,
filter: { pano: 'all', sinceDays: 0 },
notify() {},
coverage: {
...freshCoverage(),
// The key status is in; skip Cesium's one-time terrain table download.
blocked: null,
terrainReady: Promise.resolve(),
},
sequence: { selectedId: null },
};
const coverage = createCoverage({ state, source });
const bytes = encodeCoverageTile(centre.tile, {
sequences: [
{
id: 'seq-1',
parts: [
[
[centre.lon - 0.001, centre.lat],
[centre.lon + 0.001, centre.lat],
],
],
},
],
});
const tileKey = `14/${centre.tile.x}/${centre.tile.y}`;
const onGlobe = () =>
viewer.scene.groundPrimitives.items.size +
viewer.scene.primitives.items.size;
return { viewer, source, state, coverage, bytes, tileKey, onGlobe, centre };
}
test('a superseded tile request cannot strand lines on the globe', async () => {
const { viewer, source, state, coverage, bytes, tileKey, onGlobe } = setup();
const forTile = () => source.calls.filter((call) => call.key === tileKey);
coverage.refresh(); // street zoom: request #1 for the tile
assert.equal(forTile().length, 1);
viewer.view.height = 100_000; // zoom out: clear() drops request #1
coverage.refresh();
viewer.view.height = 900; // back in before #1 settles: request #2
coverage.refresh();
assert.equal(forTile().length, 2);
await settle();
// The superseded request finishes late. It must not settle request #2's
// key, or the next refresh would start a duplicate load.
forTile()[0].resolve(bytes);
await settle();
assert.equal(
state.coverage.pending.has(tileKey),
true,
'#2 still owns the key',
);
assert.equal(state.coverage.pending.size, 1, 'still loading');
coverage.refresh();
assert.equal(forTile().length, 2, 'no duplicate request');
forTile()[1].resolve(bytes);
await settle();
assert.equal(state.coverage.tiles.size, 1);
assert.ok(onGlobe() > 0, 'the tile drew its lines');
// Everything drawn can be removed: nothing is orphaned.
coverage.clear();
assert.equal(onGlobe(), 0);
});
test('sequence lines are draped on the globe and on 3D tiles alike', async () => {
const { viewer, source, coverage, bytes } = setup();
coverage.refresh();
source.calls[0].resolve(bytes);
await settle();
const { groundPrimitives, primitives } = viewer.scene;
assert.equal(primitives.items.size, 0);
assert.equal(groundPrimitives.items.size, 1);
const [line] = groundPrimitives.items;
assert.ok(line instanceof Cesium.GroundPolylinePrimitive);
assert.equal(line.classificationType, Cesium.ClassificationType.BOTH);
coverage.clear();
assert.equal(groundPrimitives.items.size, 0);
});
test('panning off a tile that is still loading stops counting it as loading', async () => {
const { viewer, source, state, coverage } = setup();
coverage.refresh();
assert.equal(state.coverage.pending.size, 1);
// Same zoom, two tiles east: the first request is dropped, a new one starts.
viewer.view.lon += 0.05;
coverage.refresh();
assert.equal(source.calls.length, 2);
assert.equal(source.calls[0].signal.aborted, true);
assert.equal(
state.coverage.pending.size,
1,
'only the live request counts as loading',
);
source.calls[0].reject(new DOMException('aborted', 'AbortError'));
source.calls[1].resolve(new Uint8Array());
await settle();
assert.equal(state.coverage.pending.size, 0, 'LOADING clears');
coverage.clear();
});
test('from orbit nothing is requested or drawn, and the hint says to zoom in', async () => {
const { viewer, source, state, coverage, bytes } = setup();
coverage.refresh();
source.calls[0].resolve(bytes);
await settle();
assert.ok(viewer.scene.groundPrimitives.items.size > 0, 'street lines');
viewer.view.height = 20_000_000;
coverage.refresh();
assert.equal(source.calls.length, 1, 'no tile is asked for');
assert.equal(viewer.scene.groundPrimitives.items.size, 0, 'nothing drawn');
assert.equal(state.coverage.zoom, null);
assert.equal(coverage.stats().hint, ZOOM_IN_HINT);
viewer.view.height = 900;
coverage.refresh();
assert.equal(coverage.stats().hint, '', 'back at street zoom');
assert.equal(source.calls.length, 2);
coverage.clear();
});
test('the key status gates coverage: nothing before it answers, nothing without a key', () => {
for (const configured of [false, true]) {
const { source, state, coverage } = setup();
state.coverage.blocked = 'status';
coverage.refresh();
assert.equal(source.calls.length, 0, 'nothing before the status answers');
assert.equal(coverage.stats().loading, true, 'waiting reads as loading');
state.enabled = false;
assert.equal(coverage.stats().loading, false, 'but not while off');
state.enabled = true;
coverage.setKeyStatus(configured);
if (configured)
assert.equal(source.calls.length, 1, 'coverage loads once it is known');
else {
assert.equal(source.calls.length, 0, 'a key-less install never asks');
assert.equal(coverage.stats().loading, false);
assert.equal(coverage.stats().keyRequired, true);
assert.equal(coverage.stats().keyRejected, false);
coverage.unblock();
assert.equal(
coverage.stats().keyRequired,
true,
'kept: it is no refusal',
);
}
coverage.clear();
}
});
test('a rejected key stops coverage requests until the layer goes off', async () => {
const { viewer, source, state, coverage } = setup();
coverage.refresh();
const rejected = Object.assign(
new Error('Mapillary rejected the access token'),
{
keyRejected: true,
},
);
source.calls[0].reject(rejected);
await settle();
assert.equal(state.coverage.blocked, 'rejected');
assert.equal(coverage.stats().keyRequired, true, 'gated like a missing key');
assert.equal(coverage.stats().keyRejected, true);
assert.match(coverage.stats().error, /rejected MAPILLARY_CLIENT_TOKEN/);
viewer.view.lon += 0.05;
coverage.refresh();
assert.equal(source.calls.length, 1, 'panning asks for nothing more');
// Turning the layer off forgets the verdict; the next run asks again.
coverage.clear();
coverage.unblock();
assert.equal(coverage.stats().keyRejected, false);
assert.equal(coverage.stats().error, null);
coverage.refresh();
assert.equal(source.calls.length, 2);
coverage.clear();
});
test('a rate limit keeps the drawn tiles and asks again once the wait is over', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
const { viewer, source, state, coverage } = setup();
coverage.refresh();
source.calls[0].reject(
Object.assign(new Error('rate limited'), { retryAfterSec: 30 }),
);
await Promise.resolve();
await Promise.resolve();
await Promise.resolve();
assert.match(coverage.stats().error, /rate-limited/);
assert.equal(coverage.stats().keyRequired, false);
viewer.view.lon += 0.05;
coverage.refresh();
assert.equal(source.calls.length, 1, 'held: nothing is requested');
t.mock.timers.tick(30_000);
assert.equal(source.calls.length, 2, 'one refresh once the wait is over');
assert.equal(coverage.stats().error, null);
coverage.clear();
coverage.unblock();
});
test('the per-tile cap applies after the imagery filter, so a dense tile keeps its 360° lines', async () => {
const { state, source, coverage, centre } = setup();
const line = (n) => [
[
[centre.lon - 0.001, centre.lat + n * 1e-6],
[centre.lon + 0.001, centre.lat + n * 1e-6],
],
];
// 700 newer flat sequences, then 300 older 360° ones.
const sequences = [];
for (let i = 0; i < 700; i++)
sequences.push({
id: `flat-${i}`,
parts: line(i),
capturedAt: 2_000_000_000_000 + i,
});
for (let i = 0; i < 300; i++)
sequences.push({
id: `pano-${i}`,
parts: line(i),
capturedAt: 1_000_000_000_000 + i,
isPano: true,
});
state.filter = { pano: 'pano', sinceDays: 0 };
coverage.refresh();
source.calls[0].resolve(encodeCoverageTile(centre.tile, { sequences }));
await settle();
const [entry] = state.coverage.tiles.values();
const cap = Math.floor(COVERAGE_MAX_SEQUENCES / COVERAGE_MAX_TILES);
assert.equal(
entry.sequences.size,
Math.min(300, cap),
'every 360° line is drawn',
);
assert.equal(coverage.stats().count, Math.min(300, cap));
// Picking and the highlight look sequences up among the drawn lines.
assert.ok(entry.sequences.has('pano-0'), 'drawn lines can be looked up');
assert.equal(entry.sequences.has('flat-699'), false);
state.filter = { pano: 'all', sinceDays: 0 };
coverage.rebuild();
assert.equal(entry.sequences.size, cap, 'all imagery is capped as before');
assert.ok(entry.sequences.has('flat-699'), 'the newest flat line is drawn');
assert.equal(entry.sequences.has('pano-299'), false, 'over the cap');
coverage.clear();
});
test('a sequence that crosses a tile edge is counted once', async () => {
const { viewer, source, coverage, centre } = setup();
// Look straight down on the edge between this tile and its east neighbour.
const { east } = tileBounds(centre.tile.x, centre.tile.y, 14);
viewer.view.lon = east;
coverage.refresh();
assert.equal(source.calls.length, 2, 'two tiles in view');
const across = [
[
[east - 0.001, centre.lat],
[east + 0.001, centre.lat],
],
];
for (const call of source.calls) {
const [, x, y] = call.key.split('/').map(Number);
call.resolve(
encodeCoverageTile(
{ x, y, z: 14 },
{
sequences: [
{ id: 'across', parts: across },
{ id: `only-${x}`, parts: across },
],
},
),
);
}
await settle();
assert.equal(coverage.stats().count, 3, 'across, plus one per tile');
coverage.clear();
});
/** A camera over a 100×100 canvas with a 60°×40° view (see rayCamera). */
function tiltedCamera({ lon, lat, height, heading, pitch }) {
return rayCamera({
lon,
lat,
altitude: height,
heading,
pitch,
width: 100,
height: 100,
fovX: 60,
fovY: 40,
});
}
/**
* Denver: 300 m above a street 1,600 m up, at a z14 tile centre, looking east
* at ground `aheadM` metres out; the globe terrain knows the ground.
*/
function denverStreetView(aheadM) {
const z = 14;
const x = lonToTileX(-104.99, z);
const y = latToTileY(39.74, z);
const tile = tileBounds(x, y, z);
const lon = (tile.west + tile.east) / 2;
const lat = (tile.south + tile.north) / 2;
const ground = 1600;
const above = 300;
const context = setup();
context.viewer.scene.globe = {
show: true,
ellipsoid: Cesium.Ellipsoid.WGS84,
getHeight: () => ground,
};
const tileWidthM = (tile.east - tile.west) * 111_320 * Math.cos(lat * RAD);
context.viewer.camera = tiltedCamera({
lon,
lat,
height: ground + above,
heading: 90,
pitch: -Math.atan(above / aheadM(tileWidthM)) / RAD,
});
context.coverage.refresh();
const keys = context.source.calls.map((call) => call.key);
/** Requested tiles as [dx, dy] from the tile under the camera. */
const offsets = keys.map((k) => {
const [, tx, ty] = k.split('/').map(Number);
return [tx - x, ty - y];
});
return {
...context,
keys,
offsets,
key: (dx, dy) => `${z}/${x + dx}/${y + dy}`,
};
}
test('a tilted street view over ground 1,600 m up asks for the ground it looks at, nearest the camera first', () => {
// The screen centre meets the ground at the centre of the next tile east.
const { state, coverage, keys, offsets, key } = denverStreetView(
(tileWidthM) => tileWidthM,
);
assert.equal(state.coverage.zoom, 14, 'height measured from the ground');
assert.equal(keys[0], key(0, 0), 'the tile under the camera first');
assert.ok(keys.includes(key(1, 0)), 'the tile the screen centre looks at');
for (const [dx, dy] of offsets)
assert.ok(dx >= 0 && dx <= 2 && Math.abs(dy) <= 1, `${dx},${dy} in view`);
coverage.clear();
});
test('a street view toward the horizon asks only for the ground within range', () => {
// The screen centre meets the ground 6 km out, past the 3 km range.
const { coverage, keys, offsets, key } = denverStreetView(() => 6000);
assert.equal(keys[0], key(0, 0), 'the tile under the camera first');
for (const [dx, dy] of offsets)
assert.ok(dx >= 0 && dx <= 1 && Math.abs(dy) <= 1, `${dx},${dy} near it`);
coverage.clear();
});
test('the selected sequence is drawn over the coverage, and goes with the selection', async () => {
const { viewer, source, state, coverage, bytes } = setup();
coverage.refresh();
source.calls[0].resolve(bytes);
await settle();
const lines = () => [...viewer.scene.groundPrimitives.items];
assert.equal(lines().length, 1, 'the coverage');
coverage.highlight('seq-1');
assert.equal(lines().length, 2);
const highlight = lines().at(-1);
assert.equal(state.coverage.highlight, highlight, 'drawn last, on top');
assert.equal(highlight.classificationType, Cesium.ClassificationType.BOTH);
coverage.highlight('not-drawn');
assert.equal(lines().length, 1, 'nothing to highlight off the map');
coverage.highlight(null);
assert.equal(state.coverage.highlight, null);
coverage.clear();
assert.equal(lines().length, 0);
});
test('a tile that lands with the selected sequence draws the highlight again, on top', async () => {
const { viewer, source, state, coverage, bytes } = setup();
state.sequence.selectedId = 'seq-1';
coverage.refresh();
assert.equal(state.coverage.highlight, null, 'nothing loaded yet');
source.calls[0].resolve(bytes);
await settle();
assert.ok(state.coverage.highlight, 'highlighted once its tile is in');
assert.equal(
[...viewer.scene.groundPrimitives.items].at(-1),
state.coverage.highlight,
);
coverage.clear();
});
test("a zoom change drops the old zoom's lines", async () => {
const { viewer, source, state, coverage, bytes } = setup();
coverage.refresh();
source.calls[0].resolve(bytes);
await settle();
const [old] = viewer.scene.groundPrimitives.items;
assert.ok(old, 'the z14 lines are drawn');
viewer.view.height = 3000; // zoom out to z13
coverage.refresh();
assert.equal(state.coverage.zoom, 13);
assert.equal(viewer.scene.groundPrimitives.items.has(old), false);
assert.ok(state.coverage.pending.size > 0, 'the new zoom is loading');
coverage.clear();
});
test('a rate limit holds every refresh inside its wait, not only the first', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
const { viewer, source, coverage } = setup();
coverage.refresh();
source.calls[0].reject(
Object.assign(new Error('rate limited'), { retryAfterSec: 30 }),
);
await Promise.resolve();
await Promise.resolve();
await Promise.resolve();
t.mock.timers.tick(1000);
viewer.view.lon += 0.05;
coverage.refresh();
assert.equal(source.calls.length, 1, 'held 1 s into a 30 s wait');
t.mock.timers.tick(28_000);
viewer.view.lon += 0.05;
coverage.refresh();
assert.equal(source.calls.length, 1, 'held 29 s into a 30 s wait');
t.mock.timers.tick(1000);
assert.ok(source.calls.length > 1, 'asked again once the wait is over');
coverage.clear();
coverage.unblock();
});
test('a tile that fails before the terrain table loads is reported at once, never unhandled', async () => {
const { source, state, coverage, tileKey } = setup();
let terrainLoaded;
state.coverage.terrainReady = new Promise((resolve) => {
terrainLoaded = resolve;
});
const unhandled = [];
const onUnhandled = (reason) => unhandled.push(reason);
process.on('unhandledRejection', onUnhandled);
try {
coverage.refresh();
source.calls
.find((call) => call.key === tileKey)
.reject(new Error('Mapillary tiles HTTP 500'));
await new Promise((resolve) => setTimeout(resolve, 20));
assert.equal(state.coverage.lastError, 'Mapillary tiles HTTP 500');
assert.deepEqual(unhandled, []);
} finally {
terrainLoaded();
await settle();
process.off('unhandledRejection', onUnhandled);
}
});
@@ -1,115 +0,0 @@
import { PbfWriter } from 'pbf';
const zigzag = (value) => (value << 1) ^ (value >> 31);
/** Tile-local [x, y] (0..extent) of a lon/lat inside tile (x, y, z). */
function lonLatToTileLocal([lon, lat], { x, y, z }, extent = 4096) {
const n = 2 ** z;
const rad = (lat * Math.PI) / 180;
const tx = ((lon + 180) / 360) * n;
const ty =
((1 - Math.log(Math.tan(rad) + 1 / Math.cos(rad)) / Math.PI) / 2) * n;
return [Math.round((tx - x) * extent), Math.round((ty - y) * extent)];
}
/** One MVT layer writer with deduplicated keys and appended values. */
function layerWriter(name, extent) {
const keys = new Map();
const values = [];
const features = [];
function tags(properties) {
const out = [];
for (const [key, value] of Object.entries(properties)) {
if (value === undefined || value === null) continue;
if (!keys.has(key)) keys.set(key, keys.size);
out.push(keys.get(key), values.length);
values.push(value);
}
return out;
}
return {
add(type, geometry, properties, id) {
features.push({ type, geometry, tags: tags(properties), id });
},
write(pbf) {
pbf.writeVarintField(15, 2);
pbf.writeStringField(1, name);
pbf.writeVarintField(5, extent);
for (const feature of features)
pbf.writeMessage(
2,
(f, out) => {
if (Number.isInteger(f.id)) out.writeVarintField(1, f.id);
out.writePackedVarint(2, f.tags);
out.writeVarintField(3, f.type);
out.writePackedVarint(4, f.geometry);
},
feature,
);
for (const key of keys.keys()) pbf.writeStringField(3, key);
for (const value of values)
pbf.writeMessage(
4,
(v, out) => {
if (typeof v === 'boolean') out.writeBooleanField(7, v);
else if (typeof v === 'number') out.writeVarintField(5, v);
else out.writeStringField(1, String(v));
},
value,
);
},
};
}
/** MVT MoveTo/LineTo commands; the cursor carries over between parts. */
function lineGeometry(parts) {
const out = [];
let cx = 0;
let cy = 0;
for (const part of parts) {
if (part.length < 2) continue;
const [x0, y0] = part[0];
out.push(9, zigzag(x0 - cx), zigzag(y0 - cy));
cx = x0;
cy = y0;
out.push(((part.length - 1) << 3) | 2);
for (const [x, y] of part.slice(1)) {
out.push(zigzag(x - cx), zigzag(y - cy));
cx = x;
cy = y;
}
}
return out;
}
/**
* Encode a `mly1_public`-shaped tile from lon/lat features, for tests and
* the hermetic QA gate.
* @param {{x: number, y: number, z: number}} tile
* @param {{sequences?: Array<{id: string, capturedAt?: number, isPano?: boolean, parts: Array<Array<[number, number]>>}>, extent?: number}} [content]
*/
export function encodeCoverageTile(
tile,
{ sequences = [], extent = 4096 } = {},
) {
const pbf = new PbfWriter();
if (sequences.length) {
const layer = layerWriter('sequence', extent);
for (const sequence of sequences)
layer.add(
2,
lineGeometry(
sequence.parts.map((part) =>
part.map((point) => lonLatToTileLocal(point, tile, extent)),
),
),
{
id: sequence.id,
captured_at: sequence.capturedAt ?? Date.now(),
is_pano: sequence.isPano === true,
},
);
pbf.writeMessage(3, (_, out) => layer.write(out), null);
}
return new Uint8Array(pbf.finish());
}
@@ -1,40 +0,0 @@
import { PbfReader } from 'pbf';
import { VectorTile } from '@mapbox/vector-tile';
import { tileLocalToLonLat } from '../../tileMath.js';
/**
* Decode a `mly1_public` coverage tile (z11–14) into sequences. The z14
* `image` layer, which can hold >150k points, is skipped.
* @param {Uint8Array} bytes
* @param {{x:number,y:number,z:number}} address
*/
export function decodeCoverageTile(bytes, address) {
const result = { sequences: [] };
if (!bytes || !bytes.length) return result;
const tile = new VectorTile(new PbfReader(bytes));
const { x, y, z } = address;
const sequenceLayer = tile.layers.sequence;
if (sequenceLayer) {
for (let i = 0; i < sequenceLayer.length; i++) {
const feature = sequenceLayer.feature(i);
const props = feature.properties || {};
// A sequence with a capture gap is a multi-line: keep each part as its
// own line, so no straight segment is drawn across the gap.
const parts = [];
for (const line of feature.loadGeometry()) {
const part = line.map((point) =>
tileLocalToLonLat(point.x, point.y, sequenceLayer.extent, x, y, z),
);
if (part.length >= 2) parts.push(part);
}
if (!parts.length) continue;
result.sequences.push({
id: String(props.id ?? feature.id ?? `${x}/${y}/${i}`),
capturedAt: Number(props.captured_at) || 0,
isPano: props.is_pano === true,
parts,
});
}
}
return result;
}
@@ -1,155 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { PbfWriter } from 'pbf';
import { decodeCoverageTile } from './decode.js';
const zigzag = (value) => (value << 1) ^ (value >> 31);
/** One line part: MoveTo the first point, LineTo the rest (relative). */
function linePart(points) {
const out = [9, zigzag(points[0][0]), zigzag(points[0][1])];
out.push(((points.length - 1) << 3) | 2);
for (let i = 1; i < points.length; i++)
out.push(
zigzag(points[i][0] - points[i - 1][0]),
zigzag(points[i][1] - points[i - 1][1]),
);
return out;
}
/**
* A minimal mly1_public-shaped tile: one sequence line, plus one point in the
* z14 `image` layer the decoder skips.
*/
function sampleTile({ geometry = null } = {}) {
const writer = new PbfWriter();
writer.writeMessage(
3,
(_, layer) => {
layer.writeVarintField(15, 2);
layer.writeStringField(1, 'sequence');
layer.writeVarintField(5, 4096);
for (const key of ['id', 'captured_at', 'is_pano'])
layer.writeStringField(3, key);
layer.writeMessage(
4,
(__, value) => value.writeStringField(1, 'seq-42'),
null,
);
layer.writeMessage(
4,
(__, value) => value.writeVarintField(5, 1_700_000_000),
null,
);
layer.writeMessage(
4,
(__, value) => value.writeBooleanField(7, true),
null,
);
layer.writeMessage(
2,
(__, feature) => {
feature.writeVarintField(1, 7);
feature.writePackedVarint(2, [0, 0, 1, 1, 2, 2]);
feature.writeVarintField(3, 2); // LineString
feature.writePackedVarint(
4,
geometry || [
9,
zigzag(100),
zigzag(100), // MoveTo
10,
zigzag(200),
zigzag(200), // LineTo ×1
],
);
},
null,
);
},
null,
);
writer.writeMessage(
3,
(_, layer) => {
layer.writeVarintField(15, 2);
layer.writeStringField(1, 'image');
layer.writeVarintField(5, 4096);
layer.writeStringField(3, 'is_pano');
layer.writeMessage(
4,
(__, value) => value.writeBooleanField(7, false),
null,
);
layer.writeMessage(
2,
(__, feature) => {
feature.writeVarintField(1, 3);
feature.writePackedVarint(2, [0, 0]);
feature.writeVarintField(3, 1); // Point
feature.writePackedVarint(4, [9, zigzag(2048), zigzag(2048)]);
},
null,
);
},
null,
);
return new Uint8Array(writer.finish());
}
test('sequences decode into lon/lat records; image points are skipped', () => {
const decoded = decodeCoverageTile(sampleTile(), { x: 0, y: 0, z: 1 });
assert.equal(decoded.sequences.length, 1);
const [sequence] = decoded.sequences;
assert.equal(sequence.id, 'seq-42');
assert.equal(sequence.capturedAt, 1_700_000_000);
assert.equal(sequence.isPano, true);
assert.equal(sequence.parts.length, 1);
assert.equal(sequence.parts[0].length, 2);
const [[lon0, lat0], [lon1, lat1]] = sequence.parts[0];
assert.ok(
lon0 > -180 && lon0 < 0 && lon1 > lon0,
'west half of tile 0/0 at z1',
);
assert.ok(lat0 > 0 && lat1 < lat0, 'northern hemisphere, moving south');
assert.deepEqual(Object.keys(decoded), ['sequences']);
});
test('an empty tile decodes to empty lists', () => {
assert.deepEqual(
decodeCoverageTile(new Uint8Array(0), { x: 0, y: 0, z: 0 }),
{ sequences: [] },
);
});
test('a sequence with a capture gap keeps its parts as separate lines', () => {
// Two parts with a gap between (300,300) and (1000,1000); the second part's
// MoveTo is relative to the end of the first, as in the MVT encoding.
const first = [
[100, 100],
[300, 300],
];
const second = [
[700, 700],
[900, 700],
];
const geometry = [
...linePart(first),
9,
zigzag(second[0][0] - first[1][0]),
zigzag(second[0][1] - first[1][1]),
((second.length - 1) << 3) | 2,
zigzag(second[1][0] - second[0][0]),
zigzag(second[1][1] - second[0][1]),
];
const [sequence] = decodeCoverageTile(sampleTile({ geometry }), {
x: 0,
y: 0,
z: 1,
}).sequences;
assert.equal(sequence.parts.length, 2);
assert.equal(sequence.parts[0].length, 2);
assert.equal(sequence.parts[1].length, 2);
// No part ends where the next begins: the gap is not bridged.
assert.notDeepEqual(sequence.parts[0].at(-1), sequence.parts[1][0]);
});
@@ -1,36 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { mapillaryImageUrl } from './policy.js';
import { sequenceIdFromPick } from './coverage.js';
import { thinImages } from './sequences.js';
test('image deep links match the mapillary.com share format', () => {
assert.equal(
mapillaryImageUrl(1814275685699406),
'https://www.mapillary.com/app/?pKey=1814275685699406&focus=photo',
);
assert.equal(mapillaryImageUrl(' '), 'https://www.mapillary.com/app/');
});
test('a sequence line pick names its sequence; other picks do not', () => {
assert.equal(sequenceIdFromPick('mly:seq:abc'), 'abc');
assert.equal(sequenceIdFromPick('mly:img:abc'), null);
assert.equal(sequenceIdFromPick(null), null);
});
test('cone thinning across the date line drops images metres apart', () => {
const image = (id, lon) => ({ id, lon, lat: 0 });
// A sequence driving east over ±180° with images ~1 m apart, then ~11 m on.
const kept = thinImages(
[
image('a', 179.99999),
image('b', -179.99999), // ~2 m from a, across the date line
image('c', -179.9999), // ~11 m from a
],
3,
);
assert.deepEqual(
kept.map(({ id }) => id),
['a', 'c'],
);
});
@@ -1,63 +0,0 @@
import { COLORS as SHARED_COLORS } from '../../policy.js';
/** Identity and tuning for Street Level's Mapillary imagery. */
export const MAPILLARY_KEY_ID = 'mapillary';
export const MAPILLARY_GRAPH_HOST = 'https://graph.mapillary.com';
/** Methods a source (./source.js or a stand-in) must have. */
export const MAPILLARY_SOURCE_METHODS = Object.freeze([
'getStatus',
'getTile',
'getSequenceImages',
]);
/** Stable id prefixes for picked primitives; every one starts with `mly:`. */
export const PICK_PREFIX = Object.freeze({
root: 'mly:',
sequence: 'mly:seq:',
image: 'mly:img:',
});
/** Mapillary green for lines, cones and the legend; GEV cyan for selection. */
export const COLORS = Object.freeze({
coverage: '#05cb63',
selected: SHARED_COLORS.selected,
});
/** Camera-driven coverage refresh. */
export const COVERAGE_MOVE_DEBOUNCE_MS = 320;
export const COVERAGE_MAX_TILES = 9;
/** Shown when Mapillary refuses the server's token (401/403). */
export const KEY_REJECTED_MESSAGE =
'Mapillary rejected MAPILLARY_CLIENT_TOKEN — replace it in Provider Settings';
/** Shown while Mapillary rate-limits tile requests (429). */
export const RATE_LIMITED_MESSAGE =
'Coverage requests are being rate-limited — they resume on their own';
/**
* Street-zoom coverage reaches this far from the camera: camera height times
* the factor, never below the floor, even when a tilted view sees further.
*/
export const SEQUENCE_VIEW_RANGE_MIN_M = 2_500;
export const SEQUENCE_VIEW_RANGE_PER_HEIGHT = 10;
export const COVERAGE_MAX_SEQUENCES = 6000;
export const COVERAGE_LINE_WIDTH_PX = 2.5;
/** Per-sequence image cones after a sequence is selected. */
export const SEQUENCE_IMAGES_LIMIT = 2000;
export const IMAGE_CONE_SIZE_PX = 26;
export const IMAGE_CONE_MIN_SPACING_M = 3;
/** On-globe credit: Mapillary imagery is CC BY-SA 4.0 and needs attribution. */
export const MAPILLARY_CREDIT_HTML =
'Street Level: imagery © <a href="https://www.mapillary.com" target="_blank" rel="noopener">Mapillary</a> contributors, CC BY-SA 4.0';
/** Deep link to an image on mapillary.com, as the web app shares them. */
export function mapillaryImageUrl(imageId) {
const id = String(imageId || '').trim();
if (!id) return 'https://www.mapillary.com/app/';
return `https://www.mapillary.com/app/?pKey=${encodeURIComponent(id)}&focus=photo`;
}
/** Fields requested for a sequence's images. */
export const SEQUENCE_IMAGE_FIELDS =
'id,captured_at,compass_angle,geometry,is_pano';
@@ -1,212 +0,0 @@
import * as Cesium from 'cesium';
import { imageConeGlyph } from '../../glyphs.js';
import { passesImageryFilter, resolveFilter } from '../../filter.js';
import { createHorizonCull, metresBetween } from '../../view.js';
import {
COLORS,
IMAGE_CONE_MIN_SPACING_M,
IMAGE_CONE_SIZE_PX,
PICK_PREFIX,
} from './policy.js';
const SPRITE_ID = 'street-level:mapillary-cones';
/** Normalize a graph image record into the shape the cones use. */
function normalizeSequenceImage(record) {
const coordinates = record?.geometry?.coordinates;
if (!Array.isArray(coordinates) || coordinates.length < 2) return null;
return {
id: String(record.id),
lon: Number(coordinates[0]),
lat: Number(coordinates[1]),
compassAngle: Number(record.compass_angle) || 0,
capturedAt: Number(record.captured_at) || 0,
isPano: record.is_pano === true,
};
}
/** Drop images closer than the spacing to the previous kept one. */
export function thinImages(images, spacingM = IMAGE_CONE_MIN_SPACING_M) {
const kept = [];
let last = null;
for (const image of images) {
if (!last || metresBetween(last, image) >= spacingM) {
kept.push(image);
last = image;
}
}
return kept;
}
/** Image cones for one selected sequence. */
export function createSequences({ state, source, parts }) {
const { render, sprites } = state.services;
function requestRender() {
render?.governorRequestRender?.('mapillary-sequence');
}
function notify() {
state.notify?.();
}
/** Drawn cone billboards. */
let cones = [];
// The cones skip the depth test: hide the ones behind the globe.
const horizon = createHorizonCull({
getViewer: () => state.viewer,
items: () => cones,
onChange: requestRender,
});
function ensureCollections(viewer) {
if (state.sequence.collection) return;
state.sequence.collection = new Cesium.BillboardCollection({
scene: viewer.scene,
});
viewer.scene.primitives.add(state.sequence.collection);
sprites?.registerSpriteCollection?.(SPRITE_ID, state.sequence.collection);
}
function clearCones() {
state.sequence.collection?.removeAll();
state.sequence.images = [];
cones = [];
horizon.stop();
}
function renderCones(images) {
const collection = state.sequence.collection;
if (!collection) return;
collection.removeAll();
cones = [];
// One colour per source; 360° images keep the ring shape.
const cone = imageConeGlyph({ size: 32, color: COLORS.coverage });
const ring = imageConeGlyph({
size: 32,
color: COLORS.coverage,
pano: true,
});
// Resolved now, so a "since N days" window keeps up with the clock.
const filter = resolveFilter(state.filter);
for (const image of images) {
if (!passesImageryFilter(image, filter)) continue;
const billboard = collection.add({
id: `${PICK_PREFIX.image}${image.id}`,
position: Cesium.Cartesian3.fromDegrees(image.lon, image.lat),
heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
image: image.isPano ? ring : cone,
imageId: image.isPano ? 'mly-cone-pano' : 'mly-cone',
width: IMAGE_CONE_SIZE_PX,
height: IMAGE_CONE_SIZE_PX,
rotation: -Cesium.Math.toRadians(image.compassAngle),
alignedAxis: Cesium.Cartesian3.UNIT_Z,
disableDepthTestDistance: Number.POSITIVE_INFINITY,
verticalOrigin: Cesium.VerticalOrigin.CENTER,
scaleByDistance: new Cesium.NearFarScalar(200, 1.1, 6000, 0.35),
});
cones.push(billboard);
}
horizon.update();
requestRender();
}
/** Select a sequence: highlight its line and load its image cones. */
async function select(sequenceId) {
if (!sequenceId || !state.viewer) return;
// Already on screen, or already on its way.
if (
state.sequence.selectedId === sequenceId &&
(state.sequence.images.length || state.sequence.abort)
)
return;
state.sequence.abort?.abort();
state.sequence.selectedId = sequenceId;
parts.coverage.highlight(sequenceId);
// The previous sequence's cones must not stay clickable under the new
// highlight while this one loads, nor after its load fails.
clearCones();
requestRender();
const controller = new AbortController();
state.sequence.abort = controller;
state.sequence.loading = true;
// An earlier sequence's error does not belong to this one.
state.sequence.error = null;
notify();
try {
const records = await source.getSequenceImages(sequenceId, {
signal: controller.signal,
});
if (controller.signal.aborted) return;
const images = thinImages(
records
.map(normalizeSequenceImage)
.filter(Boolean)
.sort((a, b) => a.capturedAt - b.capturedAt),
);
state.sequence.images = images;
renderCones(images);
state.sequence.error = null;
} catch (error) {
if (!controller.signal.aborted) {
// Nothing to show: drop the highlight, so a click asks again.
parts.coverage.highlight(null);
state.sequence.selectedId = null;
state.sequence.error = error?.message || 'Sequence images unavailable';
}
} finally {
if (state.sequence.abort === controller) {
state.sequence.loading = false;
state.sequence.abort = null;
}
notify();
}
}
function clearSelection() {
state.sequence.abort?.abort();
state.sequence.abort = null;
if (state.sequence.selectedId) parts.coverage.highlight(null);
state.sequence.selectedId = null;
state.sequence.loading = false;
clearCones();
// An error about the sequence goes with it.
state.sequence.error = null;
requestRender();
notify();
}
/** Re-draw the current sequence's cones (after an imagery filter change). */
function rerender() {
if (state.sequence.images.length) renderCones(state.sequence.images);
}
function setVisible(visible) {
if (state.sequence.collection) state.sequence.collection.show = visible;
requestRender();
}
function destroy(viewer) {
state.sequence.abort?.abort();
horizon.stop();
cones = [];
const collection = state.sequence.collection;
if (collection) {
sprites?.unregisterSpriteCollection?.(SPRITE_ID, collection);
viewer?.scene?.primitives?.remove(collection);
state.sequence.collection = null;
}
state.sequence.images = [];
state.sequence.selectedId = null;
}
return {
ensureCollections,
select,
clearSelection,
rerender,
setVisible,
destroy,
};
}
@@ -1,205 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import { createSequences } from './sequences.js';
// The cone glyphs draw on a canvas; Node has none, so any drawing is a no-op.
const noop = () => {};
const context2d = new Proxy({}, { get: () => noop, set: () => true });
globalThis.document ??= {
createElement: () => ({ getContext: () => context2d }),
};
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
/** A billboard collection that remembers the cones on the globe. */
function cones() {
const items = [];
return {
items,
show: true,
add(options) {
items.push(options);
return options;
},
removeAll() {
items.length = 0;
},
};
}
/** A source whose sequence lookups the test answers, one call at a time. */
function deferredSource() {
const calls = [];
return {
calls,
getSequenceImages(sequenceId, { signal } = {}) {
return new Promise((resolve, reject) => {
calls.push({ sequenceId, signal, resolve, reject });
});
},
/** The latest lookup for a sequence. */
last(sequenceId) {
return calls.filter((call) => call.sequenceId === sequenceId).at(-1);
},
};
}
/** Graph image records for a sequence, a few metres apart. */
function records(sequenceId, count = 2) {
return Array.from({ length: count }, (_, i) => ({
id: `${sequenceId}-${i}`,
geometry: { coordinates: [-121.49 + i * 0.001, 38.58] },
compass_angle: 90,
captured_at: 1_700_000_000_000 + i,
}));
}
function setup() {
const source = deferredSource();
/** Every highlight asked of the coverage: a sequence id, or null for none. */
const highlights = [];
const state = {
services: {},
viewer: {},
filter: { pano: 'all', sinceDays: 0 },
notify() {},
sequence: {
selectedId: null,
images: [],
collection: cones(),
loading: false,
error: null,
abort: null,
},
};
const parts = {
coverage: {
highlight: (id) => highlights.push(id),
},
};
const sequences = createSequences({ state, source, parts });
const drawn = () =>
state.sequence.collection.items.map((cone) => cone.id.split(':').at(-1));
return { state, source, sequences, highlights, drawn };
}
test('a failed sequence load leaves no stale cones and can be retried', async () => {
const { state, source, sequences, highlights, drawn } = setup();
sequences.select('A');
source.last('A').resolve(records('A'));
await settle();
assert.deepEqual(drawn(), ['A-0', 'A-1']);
sequences.select('B');
assert.deepEqual(drawn(), [], "A's cones go while B loads");
source.last('B').reject(new Error('Sequence images unavailable'));
await settle();
assert.deepEqual(drawn(), [], 'nothing of A is left to click');
assert.equal(state.sequence.loading, false);
assert.equal(state.sequence.selectedId, null, 'B is not left highlighted');
assert.equal(highlights.at(-1), null);
assert.equal(state.sequence.error, 'Sequence images unavailable');
// Clicking B again asks again, without the old error.
sequences.select('B');
assert.equal(source.calls.filter((c) => c.sequenceId === 'B').length, 2);
assert.equal(state.sequence.error, null, 'not shown while B loads again');
source.last('B').resolve(records('B'));
await settle();
assert.deepEqual(drawn(), ['B-0', 'B-1']);
assert.equal(state.sequence.selectedId, 'B');
assert.equal(state.sequence.error, null, 'cleared once B loads');
});
test('a late answer for a superseded sequence draws nothing', async () => {
const { state, source, sequences, drawn } = setup();
sequences.select('A');
sequences.select('B');
assert.equal(source.last('A').signal.aborted, true, 'A was cancelled');
source.last('B').resolve(records('B'));
await settle();
source.last('A').resolve(records('A'));
await settle();
assert.deepEqual(drawn(), ['B-0', 'B-1']);
assert.equal(state.sequence.selectedId, 'B');
assert.equal(state.sequence.loading, false);
});
test('a second click on a loading sequence does not start another lookup', async () => {
const { source, sequences } = setup();
sequences.select('A');
sequences.select('A');
assert.equal(source.calls.length, 1);
assert.equal(source.calls[0].signal.aborted, false);
});
test('clearSelection cancels the lookup and drops the highlight', async () => {
const { state, source, sequences, highlights, drawn } = setup();
sequences.select('A');
sequences.clearSelection();
assert.equal(source.last('A').signal.aborted, true);
assert.deepEqual(highlights, ['A', null]);
assert.equal(state.sequence.selectedId, null);
assert.equal(state.sequence.loading, false);
assert.equal(state.sequence.error, null, 'an error about it goes too');
source.last('A').resolve(records('A'));
await settle();
assert.deepEqual(drawn(), [], 'the late answer draws nothing');
});
test('cones are clamped to the ground and turned to their compass angle', async () => {
const { state, source, sequences } = setup();
sequences.select('A');
source.last('A').resolve(records('A', 2));
await settle();
const items = state.sequence.collection.items;
assert.equal(items.length, 2);
for (const cone of items) {
assert.equal(cone.heightReference, Cesium.HeightReference.CLAMP_TO_GROUND);
assert.equal(cone.rotation, -Cesium.Math.toRadians(90));
}
});
test('cones behind the globe are hidden, and show again from the other side', async () => {
const { state, source, sequences } = setup();
const view = { lon: -121.49, lat: 38.58, height: 20_000_000 };
const preRender = new Set();
state.viewer = {
camera: {
get positionWC() {
return Cesium.Cartesian3.fromDegrees(view.lon, view.lat, view.height);
},
},
scene: {
preRender: {
addEventListener(listener) {
preRender.add(listener);
return () => preRender.delete(listener);
},
},
},
};
sequences.select('A');
// One image under the camera, one near its antipode.
source.last('A').resolve([
...records('A', 1),
{
id: 'A-far',
geometry: { coordinates: [58.51, -38.58] },
captured_at: 1_800_000_000_000,
},
]);
await settle();
const [near, far] = state.sequence.collection.items;
assert.equal(near.show, true, 'the near side stays visible');
assert.equal(far.show, false, 'the far side does not show through');
// Fly round to the other hemisphere: the two swap.
view.lon = 58.51;
view.lat = -38.58;
for (const listener of [...preRender]) listener();
assert.equal(near.show, false);
assert.equal(far.show, true);
sequences.clearSelection();
assert.equal(preRender.size, 0, 'the cull listener is gone');
});
@@ -1,127 +0,0 @@
import {
MAPILLARY_GRAPH_HOST,
SEQUENCE_IMAGE_FIELDS,
SEQUENCE_IMAGES_LIMIT,
} from './policy.js';
/** HTTP error flagged `keyRequired`, `keyRejected` or `retryAfterSec` (429). */
export class MapillarySourceError extends Error {
constructor(message, { status = 0, payload = null, retryAfterSec } = {}) {
super(message);
this.name = 'MapillarySourceError';
this.status = status;
this.payload = payload;
this.keyRequired = payload?.keyRequired ?? payload?.error === 'no_key';
this.keyRejected = payload?.keyRejected === true;
const wait = Number(retryAfterSec ?? payload?.retryAfter);
this.retryAfterSec =
status === 429 ? (Number.isFinite(wait) && wait > 0 ? wait : 60) : null;
}
}
async function readJsonOrThrow(response, label) {
let payload = null;
try {
payload = await response.json();
} catch {
/* status is authoritative */
}
if (!response.ok)
throw new MapillarySourceError(
payload?.error?.message ||
payload?.error ||
`${label} HTTP ${response.status}`,
{ status: response.status, payload },
);
return payload;
}
/**
* Mapillary network access: tiles via the local proxy, which adds the token
* and caches; Graph API lookups direct with the client token, as MapillaryJS.
* @param {{token?: string, fetchImpl?: Function, endpoints?: object}} options
*/
export function createMapillarySource({
token = '',
fetchImpl = (...args) => globalThis.fetch(...args),
endpoints = {},
} = {}) {
const urls = {
status: '/api/mapillary/status',
tiles: '/api/mapillary/tiles',
graph: MAPILLARY_GRAPH_HOST,
...endpoints,
};
async function graph(path, params = {}, { signal } = {}) {
if (!token)
throw new MapillarySourceError('Mapillary token not configured', {
status: 503,
payload: { keyRequired: true },
});
const search = new URLSearchParams({ access_token: token, ...params });
const response = await fetchImpl(`${urls.graph}/${path}?${search}`, {
signal,
});
return readJsonOrThrow(response, 'Mapillary graph');
}
return {
get token() {
return token;
},
hasToken: () => Boolean(token),
async getStatus({ signal } = {}) {
const response = await fetchImpl(urls.status, {
signal,
cache: 'no-store',
});
return readJsonOrThrow(response, 'Mapillary status');
},
/** Raw protobuf bytes for one tile; an empty array means no data. */
async getTile(layer, z, x, y, { signal } = {}) {
const response = await fetchImpl(
`${urls.tiles}/${layer}/${z}/${x}/${y}`,
{
signal,
},
);
if (response.status === 204) return new Uint8Array(0);
if (!response.ok) {
let payload = null;
try {
payload = await response.json();
} catch {
/* ignore */
}
throw new MapillarySourceError(
payload?.error || `Tile HTTP ${response.status}`,
{
status: response.status,
payload,
retryAfterSec: response.headers?.get?.('retry-after') ?? undefined,
},
);
}
return new Uint8Array(await response.arrayBuffer());
},
async getSequenceImages(
sequenceId,
{ signal, limit = SEQUENCE_IMAGES_LIMIT } = {},
) {
const payload = await graph(
'images',
{
sequence_ids: String(sequenceId),
fields: SEQUENCE_IMAGE_FIELDS,
limit: String(limit),
},
{ signal },
);
return Array.isArray(payload?.data) ? payload.data : [];
},
};
}
@@ -1,127 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createMapillarySource, MapillarySourceError } from './source.js';
function fakeFetch(handler) {
const calls = [];
const fetchImpl = async (url, init = {}) => {
calls.push({ url: String(url), init });
return handler(String(url), init);
};
return { calls, fetchImpl };
}
const jsonResponse = (payload, status = 200) =>
new Response(JSON.stringify(payload), {
status,
headers: { 'content-type': 'application/json' },
});
test('tiles go through the local proxy and never carry the token', async () => {
const { calls, fetchImpl } = fakeFetch(
() => new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
);
const source = createMapillarySource({ token: 'MLY|1|abc', fetchImpl });
const bytes = await source.getTile('coverage', 14, 2662, 6285);
assert.deepEqual([...bytes], [1, 2, 3]);
assert.equal(calls[0].url, '/api/mapillary/tiles/coverage/14/2662/6285');
assert.doesNotMatch(calls[0].url, /MLY/);
});
test('an empty tile (204) is an empty byte array, not an error', async () => {
const { fetchImpl } = fakeFetch(() => new Response(null, { status: 204 }));
const source = createMapillarySource({ token: 'MLY|1|abc', fetchImpl });
assert.equal((await source.getTile('coverage', 14, 1, 1)).length, 0);
});
test('a missing key on the proxy surfaces as keyRequired', async () => {
const { fetchImpl } = fakeFetch(() =>
jsonResponse({ error: 'no_key', keyRequired: true }, 503),
);
const source = createMapillarySource({ token: '', fetchImpl });
assert.equal(source.hasToken(), false);
await assert.rejects(
() => source.getTile('coverage', 14, 1, 1),
(error) =>
error instanceof MapillarySourceError &&
error.status === 503 &&
error.keyRequired === true,
);
});
test('graph lookups call graph.mapillary.com with the client token and requested fields', async () => {
const { calls, fetchImpl } = fakeFetch(() =>
jsonResponse({ data: [{ id: '1', geometry: { coordinates: [1, 2] } }] }),
);
const source = createMapillarySource({ token: 'MLY|1|abc', fetchImpl });
const images = await source.getSequenceImages('seq-1');
assert.equal(images.length, 1);
const url = new URL(calls[0].url);
assert.equal(url.host, 'graph.mapillary.com');
assert.equal(url.pathname, '/images');
assert.equal(url.searchParams.get('access_token'), 'MLY|1|abc');
assert.equal(url.searchParams.get('sequence_ids'), 'seq-1');
assert.match(url.searchParams.get('fields'), /geometry/);
});
test('graph calls without a token fail fast as keyRequired without a request', async () => {
const { calls, fetchImpl } = fakeFetch(() => jsonResponse({}));
const source = createMapillarySource({ token: '', fetchImpl });
await assert.rejects(
() => source.getSequenceImages('123'),
(error) =>
error instanceof MapillarySourceError && error.keyRequired === true,
);
assert.equal(calls.length, 0);
});
test('graph API errors carry the upstream message and status', async () => {
const { fetchImpl } = fakeFetch(() =>
jsonResponse({ error: { message: 'Invalid OAuth 2.0 Access Token' } }, 400),
);
const source = createMapillarySource({ token: 'MLY|1|abc', fetchImpl });
await assert.rejects(
() => source.getSequenceImages('999'),
(error) =>
error instanceof MapillarySourceError &&
error.status === 400 &&
/Invalid OAuth/.test(error.message),
);
});
test('a rejected key and a rate limit are told apart from other tile errors', async () => {
const rejectedSource = createMapillarySource({
token: 'MLY|1|abc',
fetchImpl: fakeFetch(() =>
jsonResponse(
{ error: 'Mapillary rejected the access token', keyRejected: true },
403,
),
).fetchImpl,
});
await assert.rejects(
() => rejectedSource.getTile('coverage', 14, 1, 1),
(error) =>
error.keyRejected === true &&
error.keyRequired === false &&
error.retryAfterSec === null,
);
const limitedSource = createMapillarySource({
token: 'MLY|1|abc',
fetchImpl: fakeFetch(
() =>
new Response(
JSON.stringify({ error: 'rate limited', retryAfter: 45 }),
{
status: 429,
headers: { 'retry-after': '30' },
},
),
).fetchImpl,
});
await assert.rejects(
() => limitedSource.getTile('coverage', 14, 1, 1),
(error) => error.retryAfterSec === 30 && error.keyRejected === false,
'the Retry-After header wins over the body',
);
});
@@ -1,209 +0,0 @@
import { mapillaryImageUrl } from './policy.js';
/**
* @typedef {object} StreetPose
* @property {string} imageId
* @property {{lon: number, lat: number}} position
* @property {number|null} bearing
* @property {number|null} altitude
* @property {boolean} isPano
* @property {number|null} capturedAt Epoch milliseconds.
* @property {string|null} creator
* @property {string|null} sequenceId
* @property {string} externalUrl Deep link to the image on mapillary.com.
*/
/**
* The panel's photo viewer: loads MapillaryJS on the first `mount` and emits
* a pose on every image, view or position change.
*/
export function createMapillaryViewer({ source, render } = {}) {
let viewer = null;
let Library = null;
let container = null;
let pendingOpen = null;
/** Bumped by `unmount`, so a construction it overtook builds nothing. */
let generation = 0;
let renderMode = 'letterbox';
/** Metadata of the image on screen; pov/position events reuse it. */
let current = null;
/** The pose listener (the viewer host); one at a time. */
let poseListener = null;
function requestRender() {
render?.governorRequestRender?.('mapillary-viewer');
}
function libraryRenderMode(mode) {
const { RenderMode } = Library || {};
if (!RenderMode) return undefined;
return mode === 'fill' ? RenderMode.Fill : RenderMode.Letterbox;
}
async function ensureLibrary() {
if (Library) return Library;
// Lazy CSS: Vite applies it before the import resolves, so the viewer is
// styled from its first frame without ~90 KB of render-blocking CSS.
const [library] = await Promise.all([
import('mapillary-js'),
import('mapillary-js/dist/mapillary.css'),
]);
Library = library;
return Library;
}
function emit(pose) {
try {
poseListener?.(pose);
} catch {
/* listener errors are the core's to log */
}
}
/** Read MapillaryJS image metadata into the pose shape. */
function describe(image) {
return {
imageId: String(image.id),
isPano: image.cameraType === 'spherical',
capturedAt: image.capturedAt ?? null,
sequenceId: image.sequenceId ?? null,
altitude: Number.isFinite(image.computedAltitude)
? image.computedAltitude
: Number.isFinite(image.originalAltitude)
? image.originalAltitude
: null,
creator: image.creatorUsername || null,
};
}
async function publishPose(image) {
if (!viewer) return;
try {
const [lngLat, pov] = await Promise.all([
viewer.getPosition(),
viewer.getPointOfView(),
]);
// Closed (or never opened) while the pose was in flight: a late
// `image` event must not bring the photo back.
if (pendingOpen === null) return;
if (image) current = describe(image);
if (!current || !viewer) return;
emit({
...current,
position: { lon: lngLat.lng, lat: lngLat.lat },
bearing: Number.isFinite(pov?.bearing) ? pov.bearing : null,
externalUrl: mapillaryImageUrl(current.imageId),
});
requestRender();
} catch {
/* viewer torn down mid-flight */
}
}
async function ensureViewer(host) {
if (viewer && container === host) return viewer;
const built = generation;
destroyViewer();
const { Viewer } = await ensureLibrary();
// Unmounted (layer off) while the library loaded: a viewer built now
// would hold a WebGL context nobody releases.
if (built !== generation) throw new Error('Mapillary viewer was unmounted');
viewer = new Viewer({
accessToken: source.token,
container: host,
component: {
cover: false,
bearing: true,
zoom: true,
attribution: true,
},
// The panel's ResizeObserver resizes the viewer, and skips it while it
// is hidden (0x0); MapillaryJS's own window tracking would resize a
// hidden viewer and ask for a tile at z=NaN.
trackResize: false,
renderMode: libraryRenderMode(renderMode),
});
container = host;
viewer.on('image', (event) => publishPose(event.image));
viewer.on('pov', () => publishPose(null));
viewer.on('position', () => publishPose(null));
return viewer;
}
function destroyViewer() {
if (viewer) {
try {
viewer.remove();
} catch {
/* already removed */
}
}
viewer = null;
container = null;
current = null;
}
return {
async mount(host) {
if (!host) throw new Error('Street Level viewer has no host element');
await ensureViewer(host);
},
/** Resolves once the image is on screen and its first pose was emitted. */
async open(imageId) {
const id = String(imageId);
if (!container) throw new Error('Mapillary viewer is not mounted');
pendingOpen = id;
const instance = await ensureViewer(container);
if (pendingOpen !== id) return;
const image = await instance.moveTo(id);
if (pendingOpen !== id) return;
await publishPose(image);
},
close() {
pendingOpen = null;
current = null;
// A playing sequence would keep stepping through (and downloading)
// images in the hidden viewer.
try {
viewer?.getComponent('sequence')?.stop();
} catch {
/* sequence component not available */
}
},
unmount() {
pendingOpen = null;
// A build still waiting for the library gives up when it arrives.
generation++;
destroyViewer();
},
resize() {
try {
viewer?.resize();
} catch {
/* no-op */
}
},
/** Show the whole image ('letterbox') or crop it to the frame ('fill'). */
setRenderMode(mode) {
renderMode = mode === 'fill' ? 'fill' : 'letterbox';
try {
const value = libraryRenderMode(renderMode);
if (viewer && value !== undefined) viewer.setRenderMode(value);
} catch {
/* viewer not ready */
}
},
onPose(listener) {
poseListener = listener;
return () => {
if (poseListener === listener) poseListener = null;
};
},
};
}