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,173 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { decodeCoverageTile, decodePictures } from './decode.js';
import { OVERVIEW_BINS_PER_AXIS } from './policy.js';
import { encodePanoramaxTile } from '../../../../testSupport/panoramaxFixtures.mjs';
import { tileCentre } from '../../../../testSupport/streetLevelFakes.mjs';
const near = (a, b, eps = 1e-4) => Math.abs(a - b) < eps;
test('sequence lines keep their parts apart, with their day and camera type', () => {
const { tile, lon, lat } = tileCentre(2.35, 48.85);
const bytes = encodePanoramaxTile(tile, {
sequences: [
{
id: 'pano-seq',
type: 'equirectangular',
date: '2024-03-05',
parts: [
[
[lon - 0.001, lat],
[lon, lat],
],
[
[lon + 0.0005, lat],
[lon + 0.001, lat],
],
],
},
{
id: 'flat-seq',
parts: [
[
[lon, lat - 0.001],
[lon, lat],
],
],
},
],
});
const { sequences, overview } = decodeCoverageTile(bytes, tile);
assert.equal(overview.length, 0);
assert.equal(sequences.length, 2);
const pano = sequences.find((s) => s.id === 'pano-seq');
const flat = sequences.find((s) => s.id === 'flat-seq');
assert.equal(pano.isPano, true);
assert.equal(pano.capturedAt, Date.UTC(2024, 2, 5));
assert.equal(pano.parts.length, 2, 'the gap is not bridged');
assert.ok(near(pano.parts[1][1][0], lon + 0.001));
assert.equal(flat.isPano, false);
});
test('density cells bin to a bounded number of points that keep the counts and kinds', () => {
const tile = { x: 0, y: 0, z: 0 };
// Two cells in one bin, one far away, one empty.
const grid = [
{ lon: 2.35, lat: 48.85, pano: 0, flat: 5 },
{ lon: 2.36, lat: 48.85, pano: 30, flat: 0 },
{ lon: -73.9, lat: 40.7, pano: 1, flat: 0 },
{ lon: 10, lat: 10, pano: 0, flat: 0 },
];
const { overview } = decodeCoverageTile(
encodePanoramaxTile(tile, { grid }),
tile,
);
assert.equal(overview.length, 2, 'Paris cells share a bin; empty cells go');
const paris = overview.find((p) => p.lon > 0);
assert.equal(paris.weight, 35);
assert.equal(paris.hasPano, true);
assert.equal(paris.hasFlat, true);
assert.equal(paris.isPano, true, 'mostly 360°');
assert.equal(paris.capturedAt, null, 'cells are undated');
assert.ok(near(paris.lon, 2.36, 0.2), 'sits on the busiest cell');
const nyc = overview.find((p) => p.lon < 0);
assert.deepEqual([nyc.hasPano, nyc.hasFlat, nyc.weight], [true, false, 1]);
});
test('lines come longest first, so a cap on lines drawn drops the shortest', () => {
const { tile, lon, lat } = tileCentre(2.35, 48.85);
const span = (id, metres) => ({
id,
parts: [
[
[lon, lat],
[lon + metres / 73_000, lat],
],
],
});
const { sequences } = decodeCoverageTile(
encodePanoramaxTile(tile, {
sequences: [span('short', 20), span('long', 900), span('mid', 300)],
}),
tile,
);
assert.deepEqual(
sequences.map((s) => s.id),
['long', 'mid', 'short'],
);
});
test('a dense grid tile never draws more than the bins allow', () => {
const tile = { x: 0, y: 0, z: 0 };
const grid = [];
for (let i = 0; i < 300; i++)
for (let j = 0; j < 60; j++)
grid.push({ lon: -170 + i * 1.1, lat: -60 + j * 2 });
const { overview } = decodeCoverageTile(
encodePanoramaxTile(tile, { grid }),
tile,
);
assert.ok(overview.length <= OVERVIEW_BINS_PER_AXIS ** 2);
assert.ok(overview.length > 1000);
assert.equal(
overview.reduce((sum, p) => sum + p.weight, 0),
grid.length,
'every picture is still counted',
);
});
test('an empty tile decodes to nothing', () => {
for (const bytes of [new Uint8Array(0), null, undefined])
assert.deepEqual(decodeCoverageTile(bytes, { x: 0, y: 0, z: 0 }), {
sequences: [],
overview: [],
});
assert.deepEqual(
decodePictures(new Uint8Array(0), { x: 0, y: 0, z: 15 }, 's'),
[],
);
});
test('a z15 tile’s pictures of one sequence become cones; other sequences’ are skipped', () => {
const { tile, lon, lat } = tileCentre(2.35, 48.85, 15);
const bytes = encodePanoramaxTile(tile, {
pictures: [
{
id: 'a',
lon,
lat,
sequenceId: 's1',
heading: 45,
type: 'equirectangular',
ts: '2023-12-12 07:56:37+00',
},
{ id: 'b', lon: lon + 0.0001, lat, sequenceId: 's2' },
{ id: 'c', lon: lon + 0.0002, lat, sequenceId: 's1' },
],
});
const images = decodePictures(bytes, tile, 's1');
assert.deepEqual(
images.map((i) => i.id),
['a', 'c'],
);
assert.equal(images[0].compassAngle, 45);
assert.equal(images[0].isPano, true);
assert.equal(images[0].capturedAt, Date.UTC(2023, 11, 12, 7, 56, 37));
assert.ok(near(images[1].lon, lon + 0.0002));
assert.deepEqual(decodePictures(bytes, tile, 'nope'), []);
// A tile without pictures (below z15) has none to give.
const lines = encodePanoramaxTile(tile, {
sequences: [
{
id: 's1',
parts: [
[
[lon, lat],
[lon + 0.001, lat],
],
],
},
],
});
assert.deepEqual(decodePictures(lines, tile, 's1'), []);
});