feat(street-level): Panoramax as a fourth, keyless imagery provider

Panoramax, the open federated street-level commons, registers beside
Mapillary, Google Street View and KartaView. Its meta-catalogue
(api.panoramax.xyz) is keyless and CORS-open, so it runs in the browser:

- coverage from its vector tiles: sequence lines at z11–14 below 30 km
  (longest first under the per-tile cap), and above that the grid layer's
  density cells as binned points, not counted as sequences;
- a click on a line opens that sequence's picture nearest the click
  (STAC search, any direction), without moving the camera, then any
  sequence's if it has none within 50 m; the 360° and since filters go to
  the lines and to the API;
- cones from the z15 tiles' pictures layer around the open picture
  (~110 bytes a picture, against ~7.5 kB for a STAC item), re-centred when
  a picture opens outside them; ‹ › follow the picture's prev/next links;
- the caption names the author (not an account named by an email
  address) and the picture's licence (StreetPose `license`), and links to
  the picture in the Panoramax viewer; the globe credits Panoramax.

KartaView's viewer becomes the shared photoViewer.js (flat <img>, 360° on
panorama.js, ‹ ›, keyboard, pinch, context loss), driven by a per-provider
PhotoSources table; the request limiter moves to limiter.js. Panoramax shows
the 2,048 px SD derivative and fetches the HD original only when the viewer
is wide enough, once, shrunk while it decodes (never above 8,192 px).

Orange #ff6f00 (Panoramax's own), off by default, share option
0.m.0_0.r.panoramax-1. The MCP panel allows the meta-catalogue and the
biggest instances. Tests: policy, decode, source, viewer, provider, and a
Panoramax fixture in the hermetic browser gate.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Said TurkseverandClaude Opus 5.5 committed 2026-10-14 13:10:40 +01:00
1 parent c99eb93174
commit 00d2b73b6a
37 files changed
+4235 -711

No files matched your search

@@ -0,0 +1,184 @@
import { createLimiter } from '../../limiter.js';
import {
API_CONCURRENCY,
API_TIMEOUT_MS,
MAX_RESPONSE_BYTES,
NEAREST_FOV_TOLERANCE_DEG,
NEAREST_LIMIT,
NEAREST_RADIUS_M,
PANORAMAX_API,
TILE_CONCURRENCY,
TILE_TIMEOUT_MS,
} from './policy.js';
/** An HTTP or API failure; `retryAfterSec` is set while Panoramax is busy. */
export class PanoramaxSourceError extends Error {
constructor(message, { status = 0, retryAfterSec = null } = {}) {
super(message);
this.name = 'PanoramaxSourceError';
this.status = status;
this.retryAfterSec = retryAfterSec;
}
}
const NO_ANSWER = 'Panoramax did not answer in time — try again';
/** Seconds from a Retry-After header, or null. */
function retryAfterSeconds(response) {
const header = response.headers?.get?.('retry-after');
const value = header == null || header === '' ? NaN : Number(header);
return Number.isFinite(value) && value >= 0 ? value : null;
}
/** The body as bytes, refusing more than MAX_RESPONSE_BYTES whatever the headers say. */
async function readBounded(response) {
const tooMuch = () =>
new PanoramaxSourceError('Panoramax sent too much data', {
status: response.status,
});
const length = Number(response.headers?.get?.('content-length'));
if (length > MAX_RESPONSE_BYTES) throw tooMuch();
const reader = response.body?.getReader?.();
if (!reader) {
const bytes = new Uint8Array(await response.arrayBuffer());
if (bytes.byteLength > MAX_RESPONSE_BYTES) throw tooMuch();
return bytes;
}
const chunks = [];
let total = 0;
for (;;) {
const { done, value } = await reader.read();
if (done) break;
total += value.byteLength;
if (total > MAX_RESPONSE_BYTES) {
reader.cancel().catch(() => {});
throw tooMuch();
}
chunks.push(value);
}
const body = new Uint8Array(total);
let offset = 0;
for (const chunk of chunks) {
body.set(chunk, offset);
offset += chunk.byteLength;
}
return body;
}
/**
* Every network path the Panoramax provider uses, browser-side and keyless:
* the meta-catalogue allows any origin. Vector tiles for coverage and
* cones, STAC search for single pictures and nearest ones.
* @param {{fetchImpl?: typeof fetch, api?: string}} [options]
*/
export function createPanoramaxSource({
fetchImpl = (...args) => globalThis.fetch(...args),
api = PANORAMAX_API,
} = {}) {
const root = api.replace(/\/+$/, '');
const apiLimiter = createLimiter(API_CONCURRENCY, { lifo: true });
const tileLimiter = createLimiter(TILE_CONCURRENCY);
/** GET within `timeoutMs`; the caller's abort wins over the timeout. */
async function get(url, { signal, timeoutMs, empty = [] }) {
const controller = new AbortController();
const onAbort = () => controller.abort(signal.reason);
if (signal?.aborted) throw signal.reason;
signal?.addEventListener('abort', onAbort, { once: true });
const timer = setTimeout(
() => controller.abort(new PanoramaxSourceError(NO_ANSWER)),
timeoutMs,
);
try {
const response = await fetchImpl(url, { signal: controller.signal });
if (empty.includes(response.status)) return null;
if (response.status === 429 || response.status === 503)
throw new PanoramaxSourceError('Panoramax is busy', {
status: response.status,
retryAfterSec: retryAfterSeconds(response) ?? 5,
});
if (!response.ok)
throw new PanoramaxSourceError(
`Panoramax answered HTTP ${response.status}`,
{ status: response.status },
);
return await readBounded(response);
} catch (error) {
if (signal?.aborted) throw signal.reason;
if (controller.signal.aborted) throw controller.signal.reason;
if (error instanceof PanoramaxSourceError) throw error;
throw new PanoramaxSourceError(NO_ANSWER);
} finally {
clearTimeout(timer);
signal?.removeEventListener('abort', onAbort);
}
}
/** A STAC search, through the API gate (newest request first). */
async function search(params, { signal } = {}) {
const url = `${root}/search?${new URLSearchParams(params)}`;
const bytes = await apiLimiter.run(
() => get(url, { signal, timeoutMs: API_TIMEOUT_MS }),
{ signal },
);
let payload;
try {
payload = JSON.parse(new TextDecoder().decode(bytes));
} catch {
throw new PanoramaxSourceError('Panoramax sent an unreadable answer');
}
return Array.isArray(payload?.features) ? payload.features : [];
}
return {
api: root,
/** Raw vector-tile bytes; an empty array where there is no coverage. */
async getTile({ x, y, z }, { signal } = {}) {
const url = `${root}/map/${z}/${x}/${y}.mvt`;
const bytes = await tileLimiter.run(
() =>
get(url, { signal, timeoutMs: TILE_TIMEOUT_MS, empty: [204, 404] }),
{ signal },
);
return bytes ?? new Uint8Array(0);
},
/** One picture (a STAC item) by id, or null. */
async getItem(id, { signal } = {}) {
const [item] = await search({ ids: String(id), limit: '1' }, { signal });
return item && String(item.id) === String(id) ? item : null;
},
/**
* Pictures within `radius` metres of a point, nearest first, whichever
* way they look; `collections` keeps one sequence's, `pano` and
* `sinceMs` filter as the imagery filter does.
*/
async nearestItems(
{
lat,
lon,
radius = NEAREST_RADIUS_M,
limit = NEAREST_LIMIT,
collections = null,
pano = 'all',
sinceMs = null,
},
{ signal } = {},
) {
const params = {
place_position: `${Number(lon).toFixed(7)},${Number(lat).toFixed(7)}`,
place_distance: `0-${Math.min(1000, Math.max(1, Math.round(radius)))}`,
place_fov_tolerance: String(NEAREST_FOV_TOLERANCE_DEG),
limit: String(Math.min(100, Math.max(1, limit))),
};
if (collections) params.collections = String(collections);
if (pano === 'pano') params.filter = 'field_of_view=360';
else if (pano === 'flat') params.filter = 'field_of_view<360';
if (Number.isFinite(sinceMs) && sinceMs > 0)
params.datetime = `${new Date(sinceMs).toISOString()}/..`;
return search(params, { signal });
},
};
}