Merge origin/main: Panoramax, bikeshare Norway/Detroit, cloud filter strength, Overpass cache

Conflicts:
- KartaView viewer moved into the shared photoViewer.js on main; its
  labels now take the provider name ("{name} street-level photo") and
  are translated there.
- Weather: main's cloud filter strength slider, with its labels in t().
- Street Level caption: translated creator line plus main's licence.

Panoramax status and error texts are marked like KartaView's, and
"Panoramax answered HTTP {status}" gets a template in the panel and the
layer row. Catalogs: es/ru 2553 messages each, complete.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
German KhokhlovandClaude Opus 5.5 committed 2026-10-16 00:06:45 +04:00
commit 7fd1dd867f
77 files changed
+9201 -919

No files matched your search

@@ -1,4 +1,7 @@
import { createLineCoverage } from '../../lineCoverage.js';
import { createLru, createTileCache } from '../../tileCache.js';
export { createTileCache } from '../../tileCache.js';
import { createSequenceCones, thinImages } from '../../sequenceCones.js';
import { metresBetween } from '../../view.js';
import {
@@ -42,9 +45,6 @@ import {
const PHOTO_CACHE_SIZE = 4000;
/** Sequence pages kept in memory. */
const PAGE_CACHE_SIZE = 12;
/** Decoded coverage tiles kept, and for how long (masks too). */
const TILE_CACHE_SIZE = 24;
const TILE_CACHE_TTL_MS = 10 * 60_000;
/** z14 near the street, z13 a little higher, nothing above. */
export function kartaViewZoomFor(heightM) {
@@ -55,54 +55,6 @@ export function kartaViewZoomFor(heightM) {
};
}
/** Least-recently-used map: reading an entry renews it. */
function createLru(limit) {
const map = new Map();
return {
get(key) {
if (!map.has(key)) return undefined;
const value = map.get(key);
map.delete(key);
map.set(key, value);
return value;
},
set(key, value) {
map.delete(key);
map.set(key, value);
while (map.size > limit) map.delete(map.keys().next().value);
},
delete: (key) => map.delete(key),
clear: () => map.clear(),
};
}
/**
* Loaded coverage tiles by `z/x/y`, at most `size`, each for `ttlMs`. KartaView
* sends tiles uncompressed and uncacheable (hundreds of kB, seconds each), so
* a pan back or a zoom across z13/z14 would fetch them all again.
*/
export function createTileCache({
load,
size = TILE_CACHE_SIZE,
ttlMs = TILE_CACHE_TTL_MS,
now = Date.now,
keyOf = (tile) => `${tile.z}/${tile.x}/${tile.y}`,
}) {
const kept = createLru(size);
return {
async get(tile, options) {
const key = keyOf(tile);
const entry = kept.get(key);
if (entry && now() - entry.at < ttlMs) return entry.tile;
const loaded = await load(tile, options);
kept.set(key, { at: now(), tile: loaded });
return loaded;
},
/** Drop every tile (the provider was switched off). */
clear: () => kept.clear(),
};
}
/** The 1-based page of a sequence that holds `index`, if no photo is missing. */
function pageOf(index) {
return Math.floor(Math.max(0, index) / SEQUENCE_PAGE_SIZE) + 1;
@@ -497,6 +449,13 @@ export function createKartaViewProvider({
msg('The KartaView photo could not be loaded'),
),
),
// Esc in the viewer clears the selected drive, as the panel says.
onEscape: () => {
if (!state.sequence.selectedId) return false;
cones.clearSelection();
drawnPage = null;
return true;
},
render: context.services?.render,
...viewerOptions,
});
@@ -1,243 +0,0 @@
/**
* A minimal equirectangular panorama renderer on WebGL: one full-screen
* triangle whose fragment shader turns each pixel's view ray into texture
* coordinates. The image centre is the camera's forward direction; yaw turns
* right from it, pitch looks up.
*/
export const PANO_FOV_DEFAULT_DEG = 80;
export const PANO_FOV_MIN_DEG = 30;
export const PANO_FOV_MAX_DEG = 100;
export const PANO_PITCH_LIMIT_DEG = 85;
const VERTEX = `
attribute vec2 a_position;
varying vec2 v_ndc;
void main() {
v_ndc = a_position;
gl_Position = vec4(a_position, 0.0, 1.0);
}`;
const FRAGMENT = `
precision highp float;
uniform sampler2D u_image;
uniform float u_yaw;
uniform float u_pitch;
uniform float u_tanHalfFov;
uniform float u_aspect;
varying vec2 v_ndc;
const float PI = 3.141592653589793;
void main() {
vec3 ray = normalize(vec3(v_ndc.x * u_tanHalfFov * u_aspect, v_ndc.y * u_tanHalfFov, -1.0));
float cp = cos(u_pitch), sp = sin(u_pitch);
ray = vec3(ray.x, ray.y * cp - ray.z * sp, ray.y * sp + ray.z * cp);
float cy = cos(u_yaw), sy = sin(u_yaw);
ray = vec3(ray.x * cy - ray.z * sy, ray.y, ray.x * sy + ray.z * cy);
float lon = atan(ray.x, -ray.z);
float lat = asin(clamp(ray.y, -1.0, 1.0));
gl_FragColor = texture2D(u_image, vec2(0.5 + lon / (2.0 * PI), 0.5 - lat / PI));
}`;
/** Wrap degrees into [0, 360). */
export function wrapDegrees(value) {
return ((value % 360) + 360) % 360;
}
export function clampPitch(degrees) {
return Math.max(
-PANO_PITCH_LIMIT_DEG,
Math.min(PANO_PITCH_LIMIT_DEG, degrees),
);
}
export function clampFov(degrees) {
return Math.max(PANO_FOV_MIN_DEG, Math.min(PANO_FOV_MAX_DEG, degrees));
}
/**
* Texture coordinates the shader samples for a view ray, for tests and
* picking: `yaw`/`pitch` in degrees, the ray in camera space (x right, y up,
* z backward).
*/
export function rayToUv(ray, { yaw = 0, pitch = 0 } = {}) {
const p = (pitch * Math.PI) / 180;
const w = (yaw * Math.PI) / 180;
const length = Math.hypot(ray[0], ray[1], ray[2]) || 1;
let [x, y, z] = ray.map((v) => v / length);
[y, z] = [
y * Math.cos(p) - z * Math.sin(p),
y * Math.sin(p) + z * Math.cos(p),
];
[x, z] = [
x * Math.cos(w) - z * Math.sin(w),
x * Math.sin(w) + z * Math.cos(w),
];
const lon = Math.atan2(x, -z);
const lat = Math.asin(Math.max(-1, Math.min(1, y)));
return [0.5 + lon / (2 * Math.PI), 0.5 - lat / Math.PI];
}
function compile(gl, type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
const log = gl.getShaderInfoLog(shader);
gl.deleteShader(shader);
throw new Error(`Panorama shader failed: ${log}`);
}
return shader;
}
const isPowerOfTwo = (n) => n > 0 && (n & (n - 1)) === 0;
/**
* A panorama view on `canvas`. Throws when WebGL is unavailable, so the
* caller can fall back to a flat picture.
* @param {HTMLCanvasElement} canvas
* @returns {{setImage: (image: TexImageSource) => void, setView: (view: {yaw?: number, pitch?: number, fov?: number}) => void, getView: () => {yaw: number, pitch: number, fov: number}, resize: () => void, render: () => void, hasImage: () => boolean, destroy: () => void}}
*/
export function createPanoramaRenderer(canvas) {
const gl =
canvas.getContext('webgl', {
antialias: false,
depth: false,
preserveDrawingBuffer: false,
}) || canvas.getContext('experimental-webgl');
if (!gl) throw new Error('WebGL is unavailable');
const program = gl.createProgram();
gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, VERTEX));
gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, FRAGMENT));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS))
throw new Error('Panorama program failed to link');
gl.useProgram(program);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
// One triangle covering the screen.
gl.bufferData(
gl.ARRAY_BUFFER,
new Float32Array([-1, -1, 3, -1, -1, 3]),
gl.STATIC_DRAW,
);
const position = gl.getAttribLocation(program, 'a_position');
gl.enableVertexAttribArray(position);
gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
const uniforms = Object.fromEntries(
['u_image', 'u_yaw', 'u_pitch', 'u_tanHalfFov', 'u_aspect'].map((name) => [
name,
gl.getUniformLocation(program, name),
]),
);
const texture = gl.createTexture();
let loaded = false;
let frame = 0;
const view = { yaw: 0, pitch: 0, fov: PANO_FOV_DEFAULT_DEG };
/** Match the drawing buffer to the canvas's laid-out size. */
function syncSize() {
const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
const width = Math.max(1, Math.round(canvas.clientWidth * ratio));
const height = Math.max(1, Math.round(canvas.clientHeight * ratio));
if (canvas.width !== width || canvas.height !== height) {
canvas.width = width;
canvas.height = height;
}
}
function resize() {
syncSize();
scheduleRender();
}
function draw() {
frame = 0;
if (gl.isContextLost()) return;
// Every frame: the canvas may have been laid out since the last one.
syncSize();
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
if (!loaded) return;
gl.uniform1i(uniforms.u_image, 0);
gl.uniform1f(uniforms.u_yaw, (view.yaw * Math.PI) / 180);
gl.uniform1f(uniforms.u_pitch, (view.pitch * Math.PI) / 180);
gl.uniform1f(uniforms.u_tanHalfFov, Math.tan((view.fov * Math.PI) / 360));
gl.uniform1f(uniforms.u_aspect, canvas.width / Math.max(1, canvas.height));
gl.drawArrays(gl.TRIANGLES, 0, 3);
}
function scheduleRender() {
if (frame) return;
frame = requestAnimationFrame(draw);
}
return {
setImage(image) {
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
// RGBA: the format a decoded ImageBitmap uploads without conversion.
gl.texImage2D(
gl.TEXTURE_2D,
0,
gl.RGBA,
gl.RGBA,
gl.UNSIGNED_BYTE,
image,
);
// The pixels are on the GPU now; a bitmap's copy can go.
image.close?.();
// Linear only: a mipmapped lookup draws a seam where longitude wraps.
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
const repeat =
isPowerOfTwo(image.width) && isPowerOfTwo(image.height)
? gl.REPEAT
: gl.CLAMP_TO_EDGE;
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, repeat);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
loaded = true;
resize();
scheduleRender();
},
setView(next = {}) {
if (Number.isFinite(next.yaw)) view.yaw = wrapDegrees(next.yaw);
if (Number.isFinite(next.pitch)) view.pitch = clampPitch(next.pitch);
if (Number.isFinite(next.fov)) view.fov = clampFov(next.fov);
scheduleRender();
},
getView: () => ({ ...view }),
resize,
render: scheduleRender,
hasImage: () => loaded,
clear() {
loaded = false;
// Hand the 32 MB texture back: a closed viewer keeps only 1×1.
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(
gl.TEXTURE_2D,
0,
gl.RGBA,
1,
1,
0,
gl.RGBA,
gl.UNSIGNED_BYTE,
new Uint8Array(4),
);
scheduleRender();
},
destroy() {
if (frame) cancelAnimationFrame(frame);
frame = 0;
loaded = false;
gl.deleteTexture(texture);
gl.deleteBuffer(buffer);
gl.deleteProgram(program);
gl.getExtension('WEBGL_lose_context')?.loseContext();
},
};
}
@@ -1,169 +0,0 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {
PANO_FOV_MAX_DEG,
PANO_FOV_MIN_DEG,
PANO_PITCH_LIMIT_DEG,
clampFov,
clampPitch,
createPanoramaRenderer,
rayToUv,
wrapDegrees,
} from './panorama.js';
const close = (actual, expected) =>
actual.forEach((value, i) =>
assert.ok(Math.abs(value - expected[i]) < 1e-9, `${actual} ≉ ${expected}`),
);
test('straight ahead samples the image centre; yaw turns right, pitch looks up', () => {
close(rayToUv([0, 0, -1]), [0.5, 0.5]);
close(rayToUv([0, 0, -1], { yaw: 90 }), [0.75, 0.5]);
close(rayToUv([0, 0, -1], { yaw: -90 }), [0.25, 0.5]);
close(rayToUv([0, 0, -1], { pitch: 45 }), [0.5, 0.25]);
close(rayToUv([0, 0, -1], { pitch: -90 }), [0.5, 1]);
// Pitch first, then yaw: looking up-right stays up.
close(rayToUv([0, 0, -1], { yaw: 90, pitch: 45 }), [0.75, 0.25]);
// A ray to the right of the screen is the same as turning right.
close(rayToUv([1, 0, 0]), [0.75, 0.5]);
});
test('view limits: pitch stops short of the poles, field of view stays usable', () => {
assert.equal(clampPitch(120), PANO_PITCH_LIMIT_DEG);
assert.equal(clampPitch(-120), -PANO_PITCH_LIMIT_DEG);
assert.equal(clampFov(5), PANO_FOV_MIN_DEG);
assert.equal(clampFov(170), PANO_FOV_MAX_DEG);
assert.equal(wrapDegrees(-30), 330);
assert.equal(wrapDegrees(725), 5);
});
/**
* A WebGL stand-in that records draw calls and uniform values; `lost` makes
* it report a lost context.
*/
function stubGl() {
const gl = {
lost: false,
calls: [],
uniforms: {},
isContextLost: () => gl.lost,
getShaderParameter: () => true,
getProgramParameter: () => true,
getUniformLocation: (program, name) => name,
getExtension: () => null,
uniform1f: (name, value) => (gl.uniforms[name] = value),
};
return new Proxy(gl, {
get(target, key) {
if (key in target) return target[key];
if (typeof key === 'string' && /^[A-Z_0-9]+$/.test(key)) return key;
return (...args) => {
target.calls.push(key);
return { key, args };
};
},
});
}
/** A panorama on a stub canvas, with frames run when the test says. */
function stubPanorama(t, { width = 400, height = 250 } = {}) {
const gl = stubGl();
const canvas = {
clientWidth: width,
clientHeight: height,
width: 300,
height: 150,
getContext: () => gl,
};
const frames = [];
const saved = {
request: globalThis.requestAnimationFrame,
cancel: globalThis.cancelAnimationFrame,
};
globalThis.requestAnimationFrame = (callback) => frames.push(callback);
globalThis.cancelAnimationFrame = () => {};
t.after(() => {
globalThis.requestAnimationFrame = saved.request;
globalThis.cancelAnimationFrame = saved.cancel;
});
const renderer = createPanoramaRenderer(canvas);
const runFrames = () => {
while (frames.length) frames.shift()();
};
return { gl, canvas, renderer, runFrames };
}
const IMAGE = { width: 1024, height: 512 };
test('a panorama draws once it has an image; looking up and right are positive angles', (t) => {
const { gl, renderer, runFrames } = stubPanorama(t);
renderer.render();
runFrames();
assert.equal(gl.calls.includes('drawArrays'), false, 'nothing to draw yet');
renderer.setImage(IMAGE);
renderer.setView({ yaw: 30, pitch: 30 });
runFrames();
assert.ok(gl.calls.includes('drawArrays'));
assert.ok(gl.uniforms.u_pitch > 0, `u_pitch ${gl.uniforms.u_pitch}`);
assert.ok(Math.abs(gl.uniforms.u_pitch - Math.PI / 6) < 1e-9);
assert.ok(Math.abs(gl.uniforms.u_yaw - Math.PI / 6) < 1e-9);
renderer.setView({ pitch: -20 });
runFrames();
assert.ok(gl.uniforms.u_pitch < 0, 'looking down is negative');
});
test('a lost WebGL context draws nothing', (t) => {
const { gl, renderer, runFrames } = stubPanorama(t);
renderer.setImage(IMAGE);
gl.lost = true;
gl.calls.length = 0;
runFrames();
assert.deepEqual(
gl.calls.filter((call) =>
['viewport', 'clear', 'drawArrays'].includes(call),
),
[],
);
});
test('the canvas is measured again when it draws, not only when its image arrived', (t) => {
// The image arrives while the canvas is still hidden (0×0)…
const { canvas, renderer, runFrames } = stubPanorama(t, {
width: 0,
height: 0,
});
renderer.setImage(IMAGE);
assert.deepEqual([canvas.width, canvas.height], [1, 1]);
// …and is laid out before the frame draws.
canvas.clientWidth = 400;
canvas.clientHeight = 250;
runFrames();
assert.deepEqual([canvas.width, canvas.height], [400, 250]);
});
test('an image uploads as RGBA and its bitmap is released; closing hands the texture back as 1×1', (t) => {
const { gl, renderer } = stubPanorama(t);
const uploads = [];
gl.texImage2D = (...args) => uploads.push(args);
let closed = false;
renderer.setImage({
width: 2048,
height: 1024,
close: () => (closed = true),
});
assert.equal(uploads.length, 1);
assert.equal(
uploads[0][2],
'RGBA',
'the format a decoded bitmap uploads without conversion',
);
assert.equal(closed, true, 'the decoded copy is freed once on the GPU');
renderer.clear();
const last = uploads.at(-1);
assert.deepEqual(
[last[3], last[4]],
[1, 1],
'a closed viewer keeps a 1×1 texture',
);
assert.equal(renderer.hasImage(), false);
});
@@ -103,9 +103,6 @@ export const SEQUENCE_PAGE_EDGE = 12;
/** Equirectangular panorama sizes: a quick preview, then the sharp one. */
export const PANO_PREVIEW_SIZE = Object.freeze([1024, 512]);
/** Enough for a docked viewer; an expanded one gets the full size. */
export const PANO_MID_SIZE = Object.freeze([2048, 1024]);
export const PANO_FULL_SIZE = Object.freeze([4096, 2048]);
/** A flat photo's first version, then its sharp one. */
export const FLAT_VIEW_SIZE = Object.freeze([1280, 1280]);
export const FLAT_FULL_SIZE = Object.freeze([2560, 2560]);
@@ -896,6 +896,27 @@ test('a photo no page lists steps to the photos either side of its index', async
assert.equal(env.poses.at(-1), 's-4');
});
test('Esc in the docked viewer clears the selected drive and is consumed; with none, it goes on to the panel', async (t) => {
const env = await mounted({ sequences: { s: [0, 1, 2, 3] } });
await withCones(t, env);
await env.instance.viewer.open('s-1');
await env.instance.selectSequence('s');
assert.ok(await until(() => env.instance.sequenceStats().images === 4));
const root = env.next.parentNode;
const press = () => {
const flags = { stopped: false, prevented: false };
root.fire('keydown', {
key: 'Escape',
stopPropagation: () => (flags.stopped = true),
preventDefault: () => (flags.prevented = true),
});
return flags;
};
assert.deepEqual(press(), { stopped: true, prevented: true });
assert.equal(env.instance.sequenceStats().selectedId, null, 'drive cleared');
assert.deepEqual(press(), { stopped: false, prevented: false });
});
test('the panel counts the drive’s photos, not the thinned page of them the cones show', async (t) => {
const env = await mounted({
sequences: { s: Array.from({ length: 40 }, (_, i) => i) },
@@ -22,6 +22,9 @@ import {
photoFilterParams,
} from './policy.js';
import { msg } from '../../../../i18n/index.js';
import { createLimiter } from '../../limiter.js';
export { createLimiter } from '../../limiter.js';
/**
* An HTTP or API failure; `retryAfterSec` is set while KartaView rate-limits,
@@ -72,56 +75,6 @@ function retryAfterSeconds(response) {
return Number.isFinite(value) && value >= 0 ? value : null;
}
/**
* A gate letting at most `limit` tasks run at once, first in first out, or
* newest first with `lifo` (the last request is the one the user waits on).
*/
export function createLimiter(limit, { lifo = false } = {}) {
let running = 0;
const queue = [];
function next() {
while (running < limit && queue.length) {
const { task, resolve, reject, signal } = lifo
? queue.pop()
: queue.shift();
if (signal?.aborted) {
reject(signal.reason);
continue;
}
running++;
Promise.resolve()
.then(task)
.then(resolve, reject)
.finally(() => {
running--;
next();
});
}
}
return {
run(task, { signal } = {}) {
return new Promise((resolve, reject) => {
const item = { task, resolve, reject, signal };
queue.push(item);
signal?.addEventListener(
'abort',
() => {
const at = queue.indexOf(item);
if (at === -1) return;
queue.splice(at, 1);
reject(signal.reason);
},
{ once: true },
);
next();
});
},
get pending() {
return running + queue.length;
},
};
}
/**
* KartaView's public API, browser-side and keyless (it allows any origin).
* It speaks HTTP/1.1, so the browser opens six connections to it: tiles take
@@ -1,702 +1,93 @@
import {
createPanoramaRenderer,
PANO_FOV_DEFAULT_DEG,
wrapDegrees,
} from './panorama.js';
import { msg, t } from '../../../../i18n/index.js';
createPhotoViewer,
loadImage as loadAnyImage,
} from '../../photoViewer.js';
import {
FLAT_FULL_SIZE,
FLAT_VIEW_SIZE,
IMAGE_TIMEOUT_MS,
KARTAVIEW_NAME,
KARTAVIEW_PROVIDER_ID,
PANO_FULL_SIZE,
PANO_MID_SIZE,
PANO_PREVIEW_SIZE,
cameraBearing,
kartaViewPhotoUrl,
resizedImageUrl,
} from './policy.js';
import { msg } from '../../../../i18n/index.js';
export { panoSizeFor } from '../../photoViewer.js';
/** English data: the Street Level panel translates it (translateKnown). */
const LOAD_FAILED = msg('The KartaView photo could not be loaded');
/**
* Load an image within the timeout. A CORS-clean one (for WebGL) is decoded
* off the main thread into an ImageBitmap where the browser can: uploading
* a decoded bitmap costs a fraction of uploading an <img> (90 ms → 15 ms for
* 4096×2048 on a phone-class CPU).
*/
export function loadImage(
url,
{ crossOrigin = true, timeoutMs = IMAGE_TIMEOUT_MS } = {},
) {
if (
crossOrigin &&
url &&
typeof globalThis.createImageBitmap === 'function' &&
typeof globalThis.fetch === 'function'
)
return loadBitmap(url, timeoutMs);
return new Promise((resolve, reject) => {
if (!url) return reject(new Error(LOAD_FAILED));
const image = new Image();
if (crossOrigin) image.crossOrigin = 'anonymous';
image.decoding = 'async';
const timer = setTimeout(() => {
image.src = '';
reject(new Error(LOAD_FAILED));
}, timeoutMs);
image.onload = () => {
clearTimeout(timer);
resolve(image);
};
image.onerror = () => {
clearTimeout(timer);
reject(new Error(LOAD_FAILED));
};
image.src = url;
/** Load a KartaView photo (see photoViewer.js `loadImage`). */
export function loadImage(url, options = {}) {
return loadAnyImage(url, {
timeoutMs: IMAGE_TIMEOUT_MS,
failure: LOAD_FAILED,
...options,
});
}
async function loadBitmap(url, timeoutMs) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(url, {
mode: 'cors',
signal: controller.signal,
});
if (!response.ok) throw new Error(LOAD_FAILED);
return await createImageBitmap(await response.blob());
} catch {
throw new Error(LOAD_FAILED);
} finally {
clearTimeout(timer);
}
}
/** Free a decoded bitmap nobody will draw (an <img> has nothing to free). */
function release(image) {
image?.close?.();
}
/** The panorama size a canvas this wide can show sharply at this field of view. */
export function panoSizeFor(canvasPixels, fovDeg) {
const needed = (Math.max(1, canvasPixels) * 360) / Math.max(1, fovDeg);
return needed > PANO_MID_SIZE[0] ? PANO_FULL_SIZE : PANO_MID_SIZE;
}
/**
* Where KartaView photos come from. Only KartaView's image proxy can shrink
* a 13,000 px panorama, so panoramas and flat upgrades go through it.
* @type {import('../../photoViewer.js').PhotoSources}
*/
const KARTAVIEW_SOURCES = Object.freeze({
hasPano: (photo) => Boolean(photo.isPano && photo.urls.pano),
panoFirst: (photo) => ({
url: resizedImageUrl(photo.urls.pano, PANO_PREVIEW_SIZE),
width: 0,
resize: PANO_PREVIEW_SIZE,
}),
panoSharp: (photo, size) => ({
url: resizedImageUrl(photo.urls.pano, size),
}),
// The proxy's 1,280 px version is a few hundred kB; KartaView's own
// "large thumbnail" can be 1.7 MB. Either serves when the other fails.
// A 360° photo's front view is only on storage.
flatFirst: (photo) => [
photo.isPano ? null : resizedImageUrl(photo.urls.full, FLAT_VIEW_SIZE),
photo.urls.view,
],
// A docked viewer shows the 1,280 px version in full: the 2,560 px one
// (~0.6 MB a photo) waits until the viewer is bigger than that.
flatSharp: (photo, pixels) =>
pixels > FLAT_VIEW_SIZE[0]
? resizedImageUrl(photo.urls.full, FLAT_FULL_SIZE)
: null,
// The camera's direction, which the drive's track may refine.
bearingOf: (photo) => cameraBearing(photo),
describe: (photo) => ({
// KartaView's only place name is the sequence's, where the drive began.
title: null,
creator: null,
externalUrl: kartaViewPhotoUrl(photo),
}),
});
/**
* Viewer adapter for KartaView photos: a flat photo in an <img>, a 360°
* photo on a WebGL panorama (drag to look, wheel to zoom), and ‹ › to step
* along the sequence (also ← →). Poses follow the view direction.
* photo on a WebGL panorama, and ‹ › along the sequence (photoViewer.js).
*
* @param {object} options
* @param {(photoId: string) => Promise<object>} options.getPhoto A normalized photo (policy.js normalizePhoto).
* @param {(photo: object, delta: -1|1) => Promise<string|null>} options.step The photo `delta` along the sequence, or null at its end.
* @param {(imageId: string) => void} options.onStep Open the photo ‹ › chose (through the core, so loading and errors show).
* @param {(photo: object) => void} [options.onShown] A photo is on screen.
* @param {(imageId: string) => void} [options.onReopen] Draw the same photo again after a GPU reset (default: `onStep`).
* @param {object} [options.render] Render governor.
* @param {(photo: object, delta: -1|1) => Promise<string|null>} options.step
* @param {(imageId: string) => void} options.onStep
* @param {(photo: object) => void} [options.onShown]
* @param {object} [options.render]
* @param {(url: string, options?: object) => Promise<HTMLImageElement>} [options.load]
* @param {(canvas: HTMLCanvasElement) => object} [options.createRenderer]
* @returns {import('../../registry.js').ViewerAdapter}
*/
export function createKartaViewViewer({
getPhoto,
step,
onStep,
onShown = () => {},
onReopen = onStep,
render,
load = loadImage,
createRenderer = createPanoramaRenderer,
}) {
const listeners = new Set();
let root = null;
let picture = null;
let canvas = null;
let prevButton = null;
let nextButton = null;
let renderer = null;
/** WebGL failed once: 360° photos show their front view instead. */
let rendererFailed = false;
let photo = null;
/** What shows: 'flat', 'pano' or null. */
let showing = null;
let openSeq = 0;
let renderMode = 'letterbox';
let drag = null;
let poseFrame = 0;
let removeListeners = [];
/** The document the viewer was built in (new canvases come from it). */
let documentOf = null;
/** A context loss's look direction, for the reopen of that photo. */
let restoreView = null;
/** Width of the panorama texture on screen (0: the preview). */
let panoWidth = 0;
/** The flat photo on screen is the 2,560 px version. */
let flatSharp = false;
/** The sharper version loading ({seq, kind}): a resize starts no second one. */
let upgrading = null;
/** A resize came while it loaded: look again once it lands. */
let upgradeAgain = false;
/** The photo an open is fetching: ‹ › step on from it, not the old one. */
let openingId = null;
/** ‹ › chose this photo: keep the panorama's look direction for it. */
let keepViewFor = null;
/** ‹ › presses run one after another, each from where the last one went. */
let steps = Promise.resolve();
function requestRender() {
render?.governorRequestRender?.('kartaview-viewer');
}
function emit() {
if (!photo || !showing) return;
// A lost GPU context, still being recovered: the open that redraws the
// panorama poses once it is on screen.
if (showing === 'pano' && !renderer) return;
const view = showing === 'pano' ? renderer.getView() : null;
const heading = cameraBearing(photo);
const pose = {
providerId: KARTAVIEW_PROVIDER_ID,
imageId: photo.id,
position: { lon: photo.lon, lat: photo.lat },
bearing:
heading === null
? null
: view
? wrapDegrees(heading + view.yaw)
: heading,
tilt: view ? view.pitch : 0,
altitude: null,
isPano: showing === 'pano',
capturedAt: photo.capturedAt,
capturedAtPrecision: 'day',
// KartaView's only place name is the sequence's, where the drive began.
title: null,
creator: null,
sequenceId: photo.sequenceId,
externalUrl: kartaViewPhotoUrl(photo),
};
for (const listener of [...listeners]) {
try {
listener(pose);
} catch {
/* listener errors are the core's to log */
}
}
requestRender();
}
/** Re-emit on the next frame: a drag moves the view many times a frame. */
function emitSoon() {
if (poseFrame) return;
poseFrame = requestAnimationFrame(() => {
poseFrame = 0;
emit();
});
}
function syncButtons() {
const enabled = Boolean(photo?.sequenceId) && showing !== null;
if (prevButton) prevButton.disabled = !enabled;
if (nextButton) nextButton.disabled = !enabled;
if (enabled) checkEnds(photo);
}
/** Disable ‹ or › at once where the sequence ends (it also warms the neighbours). */
function checkEnds(target) {
for (const [delta, button] of [
[-1, prevButton],
[1, nextButton],
])
step(target, delta).then(
(id) => {
if (photo === target && button && !id) disable(button);
},
() => {},
);
}
/** Disable a step button, keeping keyboard focus in the viewer. */
function disable(button) {
if (button.ownerDocument?.activeElement === button) root?.focus?.();
button.disabled = true;
}
function show(kind) {
showing = kind;
if (picture) picture.hidden = kind !== 'flat';
if (canvas) canvas.hidden = kind !== 'pano';
if (root) root.dataset.kind = kind || '';
syncButtons();
}
function applyRenderMode() {
if (picture)
picture.style.objectFit = renderMode === 'fill' ? 'cover' : 'contain';
}
function ensureRenderer() {
if (renderer || rendererFailed || !canvas) return renderer;
try {
renderer = createRenderer(canvas);
} catch {
rendererFailed = true;
renderer = null;
}
return renderer;
}
/**
* A lost WebGL context (GPU reset, memory pressure) takes the panorama
* with it: drop the renderer, and show the photo again on a new one.
*/
function onContextLost(event) {
event.preventDefault?.();
const lost = renderer;
renderer = null;
// The new renderer starts facing the photo's heading: keep the user's look.
if (showing === 'pano' && photo && lost)
restoreView = { id: photo.id, view: lost.getView() };
try {
lost?.destroy();
} catch {
/* already gone */
}
// A lost canvas hands back its lost context: draw on a new element.
const fresh = makeCanvas(documentOf);
fresh.hidden = canvas.hidden;
canvas.replaceWith?.(fresh);
canvas = fresh;
// Show the photo again through the core, unless a newer one is opening.
if (showing === 'pano' && photo && openingId === null) {
const again = photo.id;
show(null);
openingId = again;
onReopen(again);
}
}
/** The panorama canvas, wired for drag, pinch, wheel and context loss. */
function makeCanvas(doc) {
const element = doc.createElement('canvas');
element.className = 'sl-kv-pano';
element.hidden = true;
listen(element, 'pointerdown', onPointerDown);
listen(element, 'pointermove', onPointerMove);
listen(element, 'pointerup', onPointerUp);
listen(element, 'pointercancel', onPointerUp);
listen(element, 'wheel', onWheel, { passive: false });
listen(element, 'webglcontextlost', onContextLost);
return element;
}
/**
* Step along the sequence from the photo showing, or from the one on its
* way after an earlier press, and open it through the core.
*/
function stepBy(delta) {
steps = steps.then(async () => {
const fromId = openingId ?? photo?.id;
if (!fromId || !root) return;
let from;
let nextId = null;
try {
from = await getPhoto(fromId);
if (from.sequenceId) nextId = await step(from, delta);
} catch {
// Not the end of the sequence, just no answer: the press is lost.
return;
}
// Closed, or another photo was opened meanwhile.
if ((openingId ?? photo?.id) !== fromId) return;
if (!nextId) {
const button = delta < 0 ? prevButton : nextButton;
if (button && photo?.id === fromId) disable(button);
return;
}
openingId = nextId;
keepViewFor = nextId;
onStep(nextId);
});
}
/** Pointers on the panorama: one drags the view, two pinch the zoom. */
const pointers = new Map();
let pinch = null;
function pinchSpan() {
const [a, b] = [...pointers.values()];
return Math.max(1, Math.hypot(a.x - b.x, a.y - b.y));
}
function onPointerDown(event) {
if (showing !== 'pano' || !renderer) return;
if (event.pointerType === 'mouse' && event.button !== 0) return;
pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
canvas.setPointerCapture?.(event.pointerId);
if (pointers.size === 2) {
drag = null;
pinch = { span: pinchSpan(), fov: renderer.getView().fov };
return;
}
drag = {
id: event.pointerId,
x: event.clientX,
y: event.clientY,
view: renderer.getView(),
};
canvas.classList.add('sl-kv-dragging');
}
function onPointerMove(event) {
if (pointers.has(event.pointerId))
pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
if (pinch && pointers.size === 2 && renderer) {
renderer.setView({ fov: pinch.fov * (pinch.span / pinchSpan()) });
return;
}
if (!drag || event.pointerId !== drag.id || !renderer) return;
const { fov } = drag.view;
const width = Math.max(1, canvas.clientWidth);
const height = Math.max(1, canvas.clientHeight);
const vertical = fov;
const horizontal = fov * (width / height);
renderer.setView({
yaw: drag.view.yaw - ((event.clientX - drag.x) / width) * horizontal,
pitch: drag.view.pitch + ((event.clientY - drag.y) / height) * vertical,
});
emitSoon();
}
function onPointerUp(event) {
pointers.delete(event.pointerId);
if (pointers.size < 2) pinch = null;
if (!drag || event.pointerId !== drag.id) return;
drag = null;
canvas.classList.remove('sl-kv-dragging');
}
function onWheel(event) {
if (showing !== 'pano' || !renderer) return;
event.preventDefault();
const { fov } = renderer.getView();
renderer.setView({ fov: fov * Math.exp(event.deltaY * 0.001) });
}
function onKeyDown(event) {
if (
event.defaultPrevented ||
event.altKey ||
event.ctrlKey ||
event.metaKey
)
return;
const pano = showing === 'pano' && renderer;
const turn = { ArrowLeft: -1, ArrowRight: 1 }[event.key];
// Shift+← → look around a panorama; ← → step along the sequence.
if (turn && event.shiftKey && pano) {
event.preventDefault();
const { yaw, fov } = renderer.getView();
renderer.setView({ yaw: yaw + (turn * fov) / 4 });
emitSoon();
} else if (turn) {
event.preventDefault();
stepBy(turn);
} else if ((event.key === 'ArrowUp' || event.key === 'ArrowDown') && pano) {
event.preventDefault();
const { pitch, fov } = renderer.getView();
renderer.setView({
pitch: pitch + ((event.key === 'ArrowUp' ? 1 : -1) * fov) / 6,
});
emitSoon();
} else if (['+', '=', '-', '_'].includes(event.key) && pano) {
event.preventDefault();
const { fov } = renderer.getView();
renderer.setView({
fov: fov * (event.key === '+' || event.key === '=' ? 0.85 : 1 / 0.85),
});
}
}
function listen(target, type, handler, options) {
target.addEventListener(type, handler, options);
removeListeners.push(() =>
target.removeEventListener(type, handler, options),
);
}
function build(host) {
const doc = host.ownerDocument;
documentOf = doc;
root = doc.createElement('div');
root.className = 'sl-kv-viewer';
root.tabIndex = 0;
root.setAttribute('role', 'group');
root.setAttribute(
'aria-label',
t(
'KartaView photo. ← and → step along the sequence. On a 360° photo, drag or use Shift+← →, ↑ ↓ to look around, and + − to zoom',
),
);
picture = doc.createElement('img');
picture.className = 'sl-kv-photo';
picture.alt = t('KartaView street-level photo');
picture.draggable = false;
picture.hidden = true;
canvas = makeCanvas(doc);
const nav = (label, glyph, delta) => {
const button = doc.createElement('button');
button.type = 'button';
button.className = `sl-kv-step sl-kv-step-${delta < 0 ? 'prev' : 'next'}`;
button.textContent = glyph;
button.title = label;
button.setAttribute('aria-label', label);
button.disabled = true;
listen(button, 'click', (event) => {
event.stopPropagation();
stepBy(delta);
});
return button;
};
prevButton = nav('Previous photo in this sequence (←)', '‹', -1);
nextButton = nav('Next photo in this sequence (→)', '›', 1);
root.append(picture, canvas, prevButton, nextButton);
host.append(root);
listen(root, 'keydown', onKeyDown);
applyRenderMode();
}
function teardown() {
pointers.clear();
pinch = null;
for (const remove of removeListeners) remove();
removeListeners = [];
if (poseFrame) cancelAnimationFrame(poseFrame);
poseFrame = 0;
drag = null;
renderer?.destroy();
renderer = null;
root?.remove();
root = picture = canvas = prevButton = nextButton = null;
showing = null;
photo = null;
}
/** A sharper version once the first is on screen, if nothing replaced it. */
async function upgrade(target, seq, kind) {
// A 360° photo shown flat (no WebGL) keeps its front view.
if (kind === 'flat' && target.isPano) return;
const size = kind === 'pano' ? panoSizeNow() : FLAT_FULL_SIZE;
if (kind === 'pano' && size[0] <= panoWidth) return;
// A docked viewer shows the 1,280 px version in full: the 2,560 px one
// (~0.6 MB a photo) waits until the viewer is bigger than that.
if (kind === 'flat' && (flatSharp || flatPixels() <= FLAT_VIEW_SIZE[0]))
return;
const url =
kind === 'pano'
? resizedImageUrl(target.urls.pano, size)
: resizedImageUrl(target.urls.full, size);
if (!url) return;
// Resizes come in bursts while the panel animates: one load at a time
// for this photo, and one more look once it lands.
if (upgrading?.seq === seq && upgrading.kind === kind) {
upgradeAgain = true;
return;
}
const pending = (upgrading = { seq, kind });
upgradeAgain = false;
let image = null;
try {
image = await load(url, { crossOrigin: kind === 'pano' });
if (seq !== openSeq || photo !== target || showing !== kind) return;
if (kind === 'pano') {
if (!renderer || size[0] <= panoWidth) return;
renderer.setImage(image);
image = null;
panoWidth = size[0];
} else {
picture.src = image.src;
image = null;
flatSharp = true;
}
requestRender();
} catch {
/* the first version stays */
} finally {
release(image);
if (upgrading === pending) {
upgrading = null;
if (upgradeAgain && seq === openSeq && photo === target) {
upgradeAgain = false;
upgrade(target, seq, showing);
}
}
}
}
/** Device pixels across the flat photo's frame. */
function flatPixels() {
const ratio = globalThis.devicePixelRatio || 1;
return (
Math.max(picture?.clientWidth || 0, picture?.clientHeight || 0) * ratio
);
}
/** The sharp panorama this viewer needs now: 2,048 docked, 4,096 expanded. */
function panoSizeNow() {
const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
const width = (canvas?.clientWidth || 0) * ratio;
return panoSizeFor(width, renderer?.getView().fov ?? PANO_FOV_DEFAULT_DEG);
}
async function showPano(target, seq, keepView) {
// Only the proxy can shrink a 13,000 px panorama: if it fails, the
// caller shows the front view rather than waiting on it twice.
const image = await load(
resizedImageUrl(target.urls.pano, PANO_PREVIEW_SIZE),
{ crossOrigin: true },
);
if (seq !== openSeq) {
release(image);
return false;
}
// The context may have been lost while this loaded: build on the new
// canvas, or let the caller show the front view.
if (!ensureRenderer()) {
release(image);
throw new Error(LOAD_FAILED);
}
const restore = restoreView?.id === target.id ? restoreView.view : null;
restoreView = null;
if (restore) renderer.setView(restore);
else if (!keepView || showing !== 'pano')
renderer.setView({ yaw: 0, pitch: 0, fov: PANO_FOV_DEFAULT_DEG });
photo = target;
// Shown first: a hidden canvas measures 0 and would be sized 1×1.
show('pano');
renderer.setImage(image);
panoWidth = 0;
return true;
}
async function showFlat(target, seq) {
// The proxy's 1,280 px version is a few hundred kB; KartaView's own
// "large thumbnail" can be 1.7 MB. Either serves when the other fails.
// A 360° photo's front view is only on storage.
const proxied = target.isPano
? null
: resizedImageUrl(target.urls.full, FLAT_VIEW_SIZE);
const sources = [proxied, target.urls.view].filter(Boolean);
let image;
let failure = null;
for (const url of sources) {
try {
image = await load(url, { crossOrigin: false });
break;
} catch (error) {
failure = error;
if (seq !== openSeq) return false;
}
}
if (!image) throw failure || new Error(LOAD_FAILED);
if (seq !== openSeq) return false;
picture.src = image.src;
flatSharp = false;
photo = target;
show('flat');
return true;
}
async function openPhoto(id, seq, keepView) {
const target = await getPhoto(id);
if (seq !== openSeq) return;
let shown = false;
if (target.isPano && target.urls.pano && ensureRenderer()) {
try {
shown = await showPano(target, seq, keepView);
} catch {
// The panorama failed: its front view is better than nothing.
if (seq !== openSeq) return;
shown = await showFlat(target, seq);
}
} else shown = await showFlat(target, seq);
if (!shown) return;
emit();
onShown(target);
upgrade(target, seq, showing);
}
const adapter = {
async mount(host) {
if (!host) throw new Error('Street Level viewer has no host element');
if (root && root.parentNode === host) return;
teardown();
rendererFailed = false;
build(host);
},
/** Resolves once the photo is on screen and its pose was emitted. */
async open(imageId) {
if (!root) throw new Error('KartaView viewer is not mounted');
const id = String(imageId);
const seq = ++openSeq;
const keepView = keepViewFor === id;
keepViewFor = null;
openingId = id;
try {
await openPhoto(id, seq, keepView);
} finally {
if (openingId === id && seq === openSeq) openingId = null;
}
},
close() {
openSeq++;
openingId = null;
keepViewFor = null;
photo = null;
show(null);
if (picture) picture.removeAttribute('src');
renderer?.clear?.();
},
unmount() {
openSeq++;
openingId = null;
keepViewFor = null;
teardown();
},
resize() {
renderer?.resize();
// Expanded: a docked viewer's first version is now too soft.
if (showing === 'pano' && photo && panoSizeNow()[0] > panoWidth)
upgrade(photo, openSeq, 'pano');
if (showing === 'flat' && photo && !flatSharp)
upgrade(photo, openSeq, 'flat');
},
/** FIT / FILL frame a flat photo; a panorama has no frame to fit. */
supportsRenderModes: () => showing !== 'pano',
setRenderMode(mode) {
renderMode = mode === 'fill' ? 'fill' : 'letterbox';
applyRenderMode();
},
/** The photo's direction became known (its drive loaded): pose again. */
refreshPose() {
emit();
},
onPose(listener) {
listeners.add(listener);
return () => listeners.delete(listener);
},
};
return adapter;
export function createKartaViewViewer({ load = loadImage, ...options }) {
return createPhotoViewer({
providerId: KARTAVIEW_PROVIDER_ID,
name: KARTAVIEW_NAME,
sources: KARTAVIEW_SOURCES,
load,
...options,
});
}
@@ -883,6 +883,11 @@ test('the panorama is as sharp as the viewer needs: 2,048 docked, 4,096 once exp
});
test('a CORS image is decoded off the main thread into an ImageBitmap where the browser can', async (t) => {
// A blob whose header names no size (the viewer then reads none).
const fakeBlob = {
size: 4,
slice: () => ({ arrayBuffer: async () => new ArrayBuffer(0) }),
};
const saved = {
fetch: globalThis.fetch,
bitmap: globalThis.createImageBitmap,
@@ -896,7 +901,7 @@ test('a CORS image is decoded off the main thread into an ImageBitmap where the
fetched.push({ url, mode: init.mode });
return url.includes('gone')
? { ok: false, status: 409 }
: { ok: true, blob: async () => 'blob' };
: { ok: true, blob: async () => fakeBlob };
};
globalThis.createImageBitmap = async (blob) => ({
blob,
@@ -906,7 +911,7 @@ test('a CORS image is decoded off the main thread into an ImageBitmap where the
const bitmap = await loadImage('https://cdn.kartaview.org/a', {
crossOrigin: true,
});
assert.deepEqual(bitmap, { blob: 'blob', width: 4096, height: 2048 });
assert.deepEqual(bitmap, { blob: fakeBlob, width: 4096, height: 2048 });
assert.deepEqual(fetched, [
{ url: 'https://cdn.kartaview.org/a', mode: 'cors' },
]);
@@ -1,6 +1,6 @@
import { PbfWriter } from 'pbf';
const zigzag = (value) => (value << 1) ^ (value >> 31);
export const zigzag = (value) => (value << 1) ^ (value >> 31);
/** Tile-local [x, y] (0..extent) of a lon/lat inside tile (x, y, z). */
export function lonLatToTileLocal([lon, lat], { x, y, z }, extent = 4096) {
@@ -13,7 +13,7 @@ export function lonLatToTileLocal([lon, lat], { x, y, z }, extent = 4096) {
}
/** One MVT layer writer with deduplicated keys and appended values. */
function layerWriter(name, extent) {
export function layerWriter(name, extent) {
const keys = new Map();
const values = [];
const features = [];
@@ -62,7 +62,7 @@ function layerWriter(name, extent) {
}
/** MVT MoveTo/LineTo commands; the cursor carries over between parts. */
function lineGeometry(parts) {
export function lineGeometry(parts) {
const out = [];
let cx = 0;
let cy = 0;
@@ -0,0 +1,291 @@
import { PbfReader } from 'pbf';
import { VectorTile } from '@mapbox/vector-tile';
import { tileLocalToLonLat } from '../../tileMath.js';
import {
DECODE_SLICE_MS,
OVERVIEW_BINS_PER_AXIS,
SIMPLIFY_TOLERANCE_UNITS,
panoramaxTimeMs,
} from './policy.js';
/**
* Douglas–Peucker in tile units: the points of `line` ({x, y}) that keep
* it within `tolerance` of the original (measured to each segment, so
* dead ends and U-turns stay), first and last always kept.
* Iterative, so a long track cannot overflow the stack.
*/
export function simplifyLine(line, tolerance) {
if (line.length < 3 || !(tolerance > 0)) return line;
const keep = new Uint8Array(line.length);
keep[0] = 1;
keep[line.length - 1] = 1;
const spans = [[0, line.length - 1]];
while (spans.length) {
const [from, to] = spans.pop();
const a = line[from];
const b = line[to];
const dx = b.x - a.x;
const dy = b.y - a.y;
const span2 = dx * dx + dy * dy;
let far = -1;
let farthest = tolerance;
for (let i = from + 1; i < to; i++) {
const p = line[i];
// Distance to the segment, not the infinite line: a dead end or a
// U-turn (a point beyond the chord's ends) is kept.
const t = span2
? Math.max(
0,
Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / span2),
)
: 0;
const d = Math.hypot(p.x - (a.x + t * dx), p.y - (a.y + t * dy));
if (d > farthest) {
farthest = d;
far = i;
}
}
if (far === -1) continue;
keep[far] = 1;
spans.push([from, far], [far, to]);
}
return line.filter((_, i) => keep[i]);
}
/** Epoch ms of a sequence's day ('2025-08-11'), or 0 when undated. */
function dayMs(value) {
return panoramaxTimeMs(typeof value === 'string' ? value : '') ?? 0;
}
/**
* Decode a Panoramax coverage tile (`/api/map/{z}/{x}/{y}.mvt`).
*
* - `sequences` (z7–15): one line per sequence, its parts kept apart so no
* segment is drawn across a gap, with its day and camera type; longest
* first, so a cap on lines drawn drops the shortest.
* - `grid` (z0–6): picture-density cells, as overview points binned to at
* most OVERVIEW_BINS_PER_AXIS² a tile (a z0 tile holds ~70,000 cells). A
* cell has 360° and flat counts but no date.
* - `pictures` (z15) is left for `decodePictures`.
*
* In one go; `decodeCoverageTileSliced` gives the page a turn between
* slices.
* @param {Uint8Array} bytes
* @param {{x: number, y: number, z: number}} address
* @returns {{sequences: Array<{id: string, parts: Array<Array<[number, number]>>, capturedAt: number, isPano: boolean}>, overview: Array<{id: string, lon: number, lat: number, capturedAt: null, isPano: boolean, hasPano: boolean, hasFlat: boolean, weight: number}>}}
*/
export function decodeCoverageTile(bytes, address) {
const steps = coverageSteps(bytes, address);
let step = steps.next();
while (!step.done) step = steps.next();
return step.value;
}
/** Give the page a turn: input and rendering run before the next slice. */
function nextTask() {
if (typeof globalThis.scheduler?.yield === 'function')
return globalThis.scheduler.yield();
return new Promise((resolve) => setTimeout(resolve, 0));
}
/**
* `decodeCoverageTile` in slices of about `sliceMs`, the page getting a
* turn between them: a 2 MB z10 tile over Paris is ~200 ms of decoding on
* a fast laptop, more on a phone, and would freeze the globe while the
* camera approaches. Stops at the next slice once `signal` aborts.
* @param {Uint8Array} bytes
* @param {{x: number, y: number, z: number}} address
* @param {{signal?: AbortSignal, sliceMs?: number, pause?: () => Promise<void>, now?: () => number}} [options]
*/
export async function decodeCoverageTileSliced(
bytes,
address,
{
signal,
sliceMs = DECODE_SLICE_MS,
pause = nextTask,
now = () => performance.now(),
} = {},
) {
const steps = coverageSteps(bytes, address);
let started = now();
let step = steps.next();
while (!step.done) {
if (now() - started >= sliceMs) {
await pause();
signal?.throwIfAborted();
started = now();
}
step = steps.next();
}
return step.value;
}
/** The decode, a step a feature (see `decodeCoverageTile`). */
function* coverageSteps(bytes, address) {
const result = { sequences: [], overview: [] };
if (!bytes || !bytes.length) return result;
const tile = new VectorTile(new PbfReader(bytes));
const { x, y, z } = address;
const sequences = tile.layers.sequences;
if (sequences) {
const measured = [];
for (let i = 0; i < sequences.length; i++) {
const feature = sequences.feature(i);
const props = feature.properties || {};
const parts = [];
let length = 0;
const tolerance = (SIMPLIFY_TOLERANCE_UNITS * sequences.extent) / 4096;
for (const line of feature.loadGeometry()) {
if (line.length < 2) continue;
for (let k = 1; k < line.length; k++)
length += Math.hypot(
line[k].x - line[k - 1].x,
line[k].y - line[k - 1].y,
);
// Simplified before anything else: GPS tracks carry a point every
// few metres, and each becomes ~8 ground-line vertices on the GPU.
parts.push(
simplifyLine(line, tolerance).map((point) =>
tileLocalToLonLat(point.x, point.y, sequences.extent, x, y, z),
),
);
}
if (!parts.length || props.id == null) continue;
const sequence = {
id: String(props.id),
parts,
capturedAt: dayMs(props.date),
// A sequence with no camera type is neither (the filters keep it).
isPano:
props.type === 'equirectangular'
? true
: props.type === 'flat'
? false
: null,
};
measured.push({ sequence, length });
yield;
}
// A turn before the sort: over a city it is thousands of lines.
yield;
measured.sort((a, b) => b.length - a.length);
result.sequences = measured.map(({ sequence }) => sequence);
}
const grid = tile.layers.grid;
if (grid) {
const bins = new Map();
const size = grid.extent / OVERVIEW_BINS_PER_AXIS;
for (let i = 0; i < grid.length; i++) {
const feature = grid.feature(i);
const props = feature.properties || {};
const point = feature.loadGeometry()?.[0]?.[0];
if (i % 64 === 63) yield;
if (!point) continue;
const pano = Number(props.nb_360_pictures) || 0;
const flat = Number(props.nb_flat_pictures) || 0;
const weight = Number(props.nb_pictures) || pano + flat;
if (weight <= 0) continue;
const key = `${Math.floor(point.x / size)}:${Math.floor(point.y / size)}`;
const bin = bins.get(key);
if (!bin) {
bins.set(key, { point, weight, pano, flat, top: weight });
continue;
}
// The bin sits on its busiest cell and counts them all.
bin.weight += weight;
bin.pano += pano;
bin.flat += flat;
if (weight > bin.top) {
bin.top = weight;
bin.point = point;
}
}
for (const [key, bin] of bins) {
const [lon, lat] = tileLocalToLonLat(
bin.point.x,
bin.point.y,
grid.extent,
x,
y,
z,
);
result.overview.push({
id: `${z}/${x}/${y}/${key}`,
lon,
lat,
capturedAt: null,
isPano: bin.pano > bin.flat,
hasPano: bin.pano > 0,
hasFlat: bin.flat > 0,
weight: bin.weight,
});
}
}
return result;
}
/** A picture's sequence ids: the tile stores them as a JSON array in a string. */
function sequenceIdsOf(props) {
const raw = props.sequences;
if (typeof raw === 'string' && raw.startsWith('[')) {
try {
const ids = JSON.parse(raw);
if (Array.isArray(ids)) return ids.map(String);
} catch {
/* fall through to the first sequence */
}
}
return props.first_sequence != null ? [String(props.first_sequence)] : [];
}
/**
* The pictures of a z15 tile that belong to `sequenceId`, as cones draw
* them (unsorted).
* @param {Uint8Array} bytes
* @param {{x: number, y: number, z: number}} address
* @param {string} sequenceId
* @returns {Array<{id: string, lon: number, lat: number, compassAngle: number, capturedAt: number, isPano: boolean}>}
*/
export function decodePictures(bytes, address, sequenceId) {
if (!bytes || !bytes.length) return [];
const tile = new VectorTile(new PbfReader(bytes));
const layer = tile.layers.pictures;
if (!layer) return [];
const { x, y, z } = address;
const wanted = String(sequenceId);
const out = [];
for (let i = 0; i < layer.length; i++) {
const feature = layer.feature(i);
const props = feature.properties || {};
// A cheap test first: most pictures in a tile are other sequences'.
if (
typeof props.sequences === 'string' &&
!props.sequences.includes(wanted)
)
continue;
if (!sequenceIdsOf(props).includes(wanted) || props.id == null) continue;
const point = feature.loadGeometry()?.[0]?.[0];
if (!point) continue;
const [lon, lat] = tileLocalToLonLat(
point.x,
point.y,
layer.extent,
x,
y,
z,
);
const heading = Number(props.heading);
out.push({
id: String(props.id),
lon,
lat,
compassAngle: Number.isFinite(heading) ? heading : 0,
capturedAt: panoramaxTimeMs(String(props.ts ?? '')) ?? 0,
isPano: props.type === 'equirectangular',
});
}
return out;
}
@@ -0,0 +1,317 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {
decodeCoverageTile,
decodeCoverageTileSliced,
decodePictures,
simplifyLine,
} 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);
const untyped = decodeCoverageTile(
encodePanoramaxTile(tile, {
sequences: [
{
id: 'u',
type: '',
parts: [
[
[lon, lat],
[lon + 0.001, lat],
],
],
},
],
}),
tile,
).sequences[0];
assert.equal(untyped.isPano, null, 'no camera type: neither');
});
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 (3.75° wide at z0) far enough apart to tell
// which it sits on, one far away, one empty.
const grid = [
{ lon: 0.3, lat: 48.85, pano: 0, flat: 5 },
{ lon: 3.4, 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, 3.4, 0.2),
`sits on the busiest cell: ${paris.lon}`,
);
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',
);
});
/** A tile with many lines and a dense grid, for the sliced decode. */
function busyTile() {
const { tile, lon, lat } = tileCentre(2.35, 48.85);
const sequences = Array.from({ length: 200 }, (_, i) => ({
id: `s${i}`,
parts: [
[
[lon, lat + i / 1e6],
[lon + (i + 1) / 73_000, lat + i / 1e6],
],
],
}));
const grid = Array.from({ length: 500 }, (_, i) => ({
lon: lon + (i % 25) / 1e4,
lat: lat + Math.floor(i / 25) / 1e4,
}));
return { tile, bytes: encodePanoramaxTile(tile, { sequences, grid }) };
}
test('a sliced decode gives the page turns and decodes the same as one in one go', async () => {
const { tile, bytes } = busyTile();
let clock = 0;
let pauses = 0;
const sliced = await decodeCoverageTileSliced(bytes, tile, {
sliceMs: 8,
// Each step "takes" a millisecond: a turn every eight features.
now: () => clock++,
pause: async () => {
pauses++;
},
});
assert.ok(pauses > 20, `${pauses} turns`);
assert.deepEqual(sliced, decodeCoverageTile(bytes, tile));
});
test('a sliced decode stops at the next turn once aborted', async () => {
const { tile, bytes } = busyTile();
const controller = new AbortController();
let clock = 0;
let pauses = 0;
await assert.rejects(
decodeCoverageTileSliced(bytes, tile, {
signal: controller.signal,
now: () => (clock += 10),
pause: async () => {
if (++pauses === 2) controller.abort();
},
}),
{ name: 'AbortError' },
);
assert.equal(pauses, 2, 'no work after the abort');
});
test('a fast sliced decode takes no turns', async () => {
const { tile, bytes } = busyTile();
let pauses = 0;
await decodeCoverageTileSliced(bytes, tile, {
now: () => 0,
pause: async () => {
pauses++;
},
});
assert.equal(pauses, 0);
});
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'), []);
});
test('lines are simplified within a few tile units, ends and corners kept', () => {
const zigzag = Array.from({ length: 1000 }, (_, i) => ({
x: i,
y: i % 2 ? 1 : 0,
}));
assert.deepEqual(
simplifyLine(zigzag, 4),
[zigzag[0], zigzag.at(-1)],
'a 1-unit wobble goes',
);
const corner = [
{ x: 0, y: 0 },
{ x: 50, y: 1 },
{ x: 100, y: 0 },
{ x: 100, y: 100 },
];
assert.deepEqual(simplifyLine(corner, 4), [corner[0], corner[2], corner[3]]);
assert.equal(simplifyLine(corner.slice(0, 2), 4).length, 2);
// A loop back to its start (no chord) keeps its far point.
const loop = [
{ x: 0, y: 0 },
{ x: 40, y: 0 },
{ x: 0, y: 0 },
];
assert.equal(simplifyLine(loop, 4).length, 3);
assert.equal(simplifyLine(zigzag, 0).length, 1000, 'no tolerance, no change');
// A dead end: out to 100 and back to 50 keeps its far end.
const deadEnd = [
{ x: 0, y: 0 },
{ x: 100, y: 0 },
{ x: 50, y: 0 },
];
assert.deepEqual(simplifyLine(deadEnd, 4), deadEnd);
});
test('a decoded GPS track keeps a fraction of its points', () => {
const { tile, lon, lat } = tileCentre(2.35, 48.85);
const track = Array.from({ length: 500 }, (_, i) => [
lon - 0.004 + i * 0.000016,
lat + Math.sin(i / 40) * 0.0004,
]);
const [sequence] = decodeCoverageTile(
encodePanoramaxTile(tile, { sequences: [{ id: 'gps', parts: [track] }] }),
tile,
).sequences;
assert.ok(
sequence.parts[0].length < 100,
`${sequence.parts[0].length} points`,
);
assert.ok(sequence.parts[0].length > 5);
});
@@ -0,0 +1,644 @@
import { createLineCoverage, sequenceIdFromPick } from '../../lineCoverage.js';
import { createSequenceCones, thinImages } from '../../sequenceCones.js';
import { passesImageryFilter } from '../../filter.js';
import {
lonToTileX,
latToTileY,
overviewZoomForHeight,
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,
OVERVIEW_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,
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);
}
}
/**
* A density dot's size: busier places draw bigger (2.5 px for one picture,
* 8 px from a few hundred thousand), so a city does not read like farmland.
*/
export function overviewPointSize(point) {
const weight = Math.max(1, Number(point?.weight) || 1);
return Math.min(8, 2.5 + Math.log10(weight));
}
/** 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, the density grid at z5 and
* coarser.
*/
export function panoramaxZoomFor(heightM) {
if (!Number.isFinite(heightM)) return null;
if (heightM <= COVERAGE_LINES_BELOW_M) {
const zoom =
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;
return { zoom, kind: 'sequence' };
}
return {
zoom: Math.min(5, overviewZoomForHeight(heightM) ?? 5),
kind: 'overview',
};
}
/**
* The imagery filter for lines and grid cells. A cell (undated, with 360°
* and flat counts) stays while it holds pictures of the kind asked for. 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;
if ('hasPano' in record) {
if (filter.pano === 'pano') return record.hasPano;
if (filter.pano === 'flat') return record.hasFlat;
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 (density points
* from orbit, sequence lines near the ground); 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,
keyRequired: false,
keyRejected: false,
statusKnown: true,
coverage: {
zoom: null,
tiles: new Map(),
stale: new Map(),
staleTimer: null,
pending: new Map(),
lastError: null,
holdUntil: 0,
holdTimer: null,
debounceTimer: null,
removeCameraListener: null,
terrainReady: null,
hint: '',
kind: null,
},
sequence: {
selectedId: null,
images: [],
cache: new Map(),
collection: null,
loading: false,
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 },
passes: passesCoverage,
overviewPointSize,
});
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, selected) =>
coverage.recolorSequence(sequenceId, selected),
});
/**
* 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.resetErrors();
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.resetErrors();
cones.destroy(cesiumViewer);
},
refreshCoverage: () => coverage.refresh(),
/** The filter changed: redraw. Each draw reads it from the context. */
setFilter() {
coverage.rebuild();
cones.rerender();
},
setSurface() {
coverage.setSurface();
cones.rerender();
},
coverageStats() {
const { kind } = state.coverage;
const lines = kind === 'sequence';
const shown = coverage.sequenceCount();
// Density dots are not sequences: they are not counted as such.
const count = lines ? shown : 0;
const loading = state.coverage.pending.size > 0;
const settled = !loading && !state.coverage.lastError;
let fallback = '';
// Tiles that held something the filter hid all of.
const filteredOut = [...state.coverage.tiles.values()].some(
(tile) => tile.total > 0,
);
if (kind === 'overview')
fallback =
shown > 0 || !settled
? OVERVIEW_HINT
: filteredOut
? FILTERED_HINT
: NO_COVERAGE_HINT;
else if (lines && settled && count === 0)
fallback = filteredOut ? FILTERED_HINT : NO_COVERAGE_HINT;
return {
count,
zoom: state.coverage.zoom,
kind: state.coverage.kind,
loading,
hint: state.coverage.hint || fallback,
error: state.coverage.lastError,
keyRequired: false,
keyRejected: false,
};
},
/**
* 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,
}),
/**
* 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,
};
},
});
}
@@ -0,0 +1,322 @@
import { COLORS as SHARED_COLORS, PROVIDER_COLORS } from '../../policy.js';
import { msg } from '../../../../i18n/index.js';
export { NEAREST_RADIUS_M } from '../../policy.js';
/** Identity and tuning for the Panoramax street-level provider (keyless). */
export const PANORAMAX_PROVIDER_ID = 'panoramax';
export const PANORAMAX_NAME = 'Panoramax';
export const PANORAMAX_LABEL = 'PANORAMAX';
/**
* The Panoramax meta-catalogue: one keyless, CORS-enabled STAC API over
* every federated instance (OpenStreetMap France, IGN, MapComplete…). Its
* pictures are served by the instance that holds them.
*/
export const PANORAMAX_API = 'https://api.panoramax.xyz/api';
/** The meta-catalogue's web viewer, where the caption link goes. */
export const PANORAMAX_VIEWER = 'https://api.panoramax.xyz/';
/** Stable id prefixes for picked primitives; every one starts with `pnx:`. */
export const PICK_PREFIX = Object.freeze({
root: 'pnx:',
sequence: 'pnx:seq:',
image: 'pnx:img:',
});
export const COLORS = Object.freeze({
coverage: PROVIDER_COLORS.panoramax,
selected: SHARED_COLORS.selected,
});
/**
* Sequence lines come from z7–15 tiles; z10–14 are drawn below 60 km, as
* Mapillary's are (a dense tile over Paris: z10 ~2.1 MB and 8,600
* sequences, z11 ~1.4 MB, z12 ~800 kB). Higher up, the z0–5 `grid` layer's
* density cells (0.1°, ~10 km) draw as points: lower down they would be a
* handful of dots over a whole city, which reads as no coverage.
*/
export const COVERAGE_Z14_BELOW_M = 1_800;
export const COVERAGE_Z13_BELOW_M = 5_000;
export const COVERAGE_Z12_BELOW_M = 12_000;
export const COVERAGE_Z11_BELOW_M = 30_000;
export const COVERAGE_LINES_BELOW_M = 60_000;
export const COVERAGE_TUNING = Object.freeze({
maxTiles: 9,
overviewMaxTiles: 6,
// Each tile draws at most 1,600 lines, its longest first (as decoded,
// `keepOrder`): a dense z11
// tile over Paris holds 3,800, and a lower cap left the city centre
// looking emptier than its suburbs. (KartaView draws as many.)
maxSequences: 14_400,
keepOrder: true,
// Points drawn at most, over every tile (each becomes ~8 ground-line
// vertices, ~1.4 kB of geometry): the simplified Paris z10 tile alone
// holds 57,000, unsimplified 750,000, which hung the tab.
maxPoints: 90_000,
lineWidthPx: 2.5,
overviewPointPx: 4,
moveDebounceMs: 320,
viewRangeMinM: 2_500,
viewRangePerHeight: 10,
viewNearM: 1_000,
});
/**
* Lines are simplified (Douglas–Peucker) to this many tile units of a
* 4,096 extent: about a pixel where each zoom is drawn (1.6 m at z14,
* within GPS noise), and 6–10% of the points GPS tracks carry.
*/
export const SIMPLIFY_TOLERANCE_UNITS = 4;
/**
* Coverage tiles decode in slices of this many ms, the page getting a turn
* between them (decode.js `decodeCoverageTileSliced`): under a frame.
*/
export const DECODE_SLICE_MS = 8;
/**
* Grid cells per overview tile, at most: a z0 tile holds ~70,000 cells
* (1.9 MB), drawn as this many binned points.
*/
export const OVERVIEW_BINS_PER_AXIS = 96;
export const RATE_LIMITED_MESSAGE = msg(
'Panoramax is busy — coverage resumes on its own',
);
export const NO_COVERAGE_HINT = msg('no Panoramax photos in view');
/** Lines in view, all hidden by the imagery filter. */
export const FILTERED_HINT = msg('no Panoramax photos here match the filters');
export const UNREADABLE_TILE_MESSAGE = msg(
'Panoramax sent a map tile that could not be read',
);
export const GONE_MESSAGE = msg('This Panoramax photo is no longer available');
/** From high up the dots are where pictures are, not sequences to click. */
export const OVERVIEW_HINT = msg('zoom in to see Panoramax coverage');
/** Cones come from z15 tiles' `pictures` layer (~110 bytes a picture). */
export const PICTURE_TILE_ZOOM = 15;
/** Within this of a z15 tile's edge, the neighbouring tile's pictures join. */
export const PICTURE_TILE_EDGE_M = 150;
export const TILE_TIMEOUT_MS = 20_000;
/**
* Once an answer has started, it may take as long as it keeps coming: a
* 2 MB tile on a slow link outlasts any whole-request timeout, so only a
* stream silent this long is given up.
*/
export const STREAM_IDLE_TIMEOUT_MS = 15_000;
/** Busy (429/503) without a Retry-After the browser can read: back off from this. */
export const BUSY_BACKOFF_BASE_SEC = 5;
export const API_TIMEOUT_MS = 12_000;
/** Real tiles are under 6 MB (z6 over France); refuse anything absurd. */
export const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
/**
* The meta-catalogue speaks HTTP/1.1 only, so the browser opens six
* connections to it: coverage tiles take three, searches two and the
* cones' tiles one, so a click's lookup never queues behind megabyte tiles
* (it timed out doing so).
*/
export const API_CONCURRENCY = 2;
export const TILE_CONCURRENCY = 3;
/** The selected sequence's z15 tiles (cones) take the sixth. */
export const PICTURE_TILE_CONCURRENCY = 1;
/** Pictures asked for around a point; the API returns them nearest first. */
export const NEAREST_LIMIT = 10;
/**
* The widest the API allows: the point may be beside a picture, but a
* picture looking away from it is still left out (the bounding-box search
* beside it has those).
*/
export const NEAREST_FOV_TOLERANCE_DEG = 180;
/**
* Pictures in the bounding box around a click, at most. The API returns
* them roughly nearest first (the first ten of 100 are the first ten of
* 10), and the browser ranks them exactly: 20 is ~60 kB, 100 ~600 kB.
*/
export const NEAREST_BOX_LIMIT = 20;
/**
* A line clicked from high up may be tens of metres off the click: its
* sequence is searched within the camera height / 100 (50–400 m).
*/
export const LINE_CLICK_RADIUS_PER_HEIGHT = 0.01;
export const LINE_CLICK_RADIUS_MAX_M = 400;
/** A full-resolution panorama is only fetched up to this width (memory). */
export const PANO_HD_MAX_WIDTH = 8_192;
/** An HD panorama can be several megabytes. */
export const HD_TIMEOUT_MS = 30_000;
/** Panoramax's SD derivative is 2,048 px wide, its thumbnail 500 px. */
export const SD_WIDTH = 2_048;
/** On-globe credit: licences are per picture, named in the caption. */
export const PANORAMAX_CREDIT_HTML =
'Street Level: imagery © <a href="https://panoramax.fr" target="_blank" rel="noopener">Panoramax</a> contributors, licence per picture';
export const LINE_CLICK_HINT = 'click a line for its nearest photo';
/** Licence ids Panoramax uses, as the caption names them. */
const LICENSE_LABELS = Object.freeze({
'CC-BY-SA-4.0': 'CC BY-SA 4.0',
'CC-BY-4.0': 'CC BY 4.0',
'CC0-1.0': 'CC0',
'etalab-2.0': 'Licence Ouverte 2.0',
});
/** The caption's licence name for a STAC licence id, or null. */
export function licenseLabel(license) {
if (typeof license !== 'string' || !license.trim()) return null;
const id = license.trim();
if (id === 'proprietary' || id === 'other') return null;
return LICENSE_LABELS[id] || id.slice(0, 40);
}
/** Deep link to a picture in the Panoramax web viewer. */
export function panoramaxPictureUrl(pictureId) {
const id = String(pictureId ?? '').trim();
if (!id) return PANORAMAX_VIEWER;
return `${PANORAMAX_VIEWER}#${new URLSearchParams({ pic: id, focus: 'pic' })}`;
}
/** Epoch ms for a capture time ('2023-12-12T07:54:47+00:00', '2023-12-12 07:56:37+00'), or null. */
export function panoramaxTimeMs(value) {
if (typeof value !== 'string' || !value) return null;
// Tile timestamps are Postgres text: a space and an hour-only offset.
const iso = /\d[T ]\d/.test(value)
? value
.replace(' ', 'T')
.replace(/([+-]\d{2})$/, '$1:00')
.replace(/\.(\d{3})\d+/, '.$1')
: value;
const ms = Date.parse(iso);
return Number.isFinite(ms) && ms > Date.UTC(1990, 0, 1) ? ms : null;
}
/** An https address, or null (asset links come from federated instances). */
function httpsUrl(value) {
try {
const url = new URL(String(value));
return url.protocol === 'https:' ? url.href : null;
} catch {
return null;
}
}
/** Last path segment of an item's `rel` link: the linked picture's id. */
function linkedId(item, rel) {
const href = item?.links?.find?.((link) => link?.rel === rel)?.href;
if (typeof href !== 'string') return null;
const id = href.split(/[?#]/)[0].split('/').filter(Boolean).pop();
if (!id) return null;
try {
return decodeURIComponent(id);
} catch {
// A malformed escape is no link, not a failed lookup.
return null;
}
}
/**
* An email address anywhere in a name, at any of its '@'s. Linear: names
* come from any instance, and each run between '@'s is scanned once.
*/
function looksLikeEmail(name) {
return /[^\s@]@[^\s@]+\.[^\s@]/.test(name);
}
/**
* Who took the picture. Producers are account names, and some accounts
* are named by an email address: those are not repeated in the caption.
*/
function creatorOf(item) {
const props = item.properties || {};
const names = [
props['geovisio:producer'],
...(Array.isArray(item.providers)
? item.providers
.filter((p) => p?.roles?.includes?.('producer'))
.map((p) => p.name)
: []),
];
// Every producer is credited (an uploading app and its photographer),
// each name once, none that is an email address.
const credited = [];
const seen = new Set();
for (const value of names) {
if (typeof value !== 'string') continue;
const name = value.trim().slice(0, 80);
if (!name || looksLikeEmail(value)) continue;
const key = name.toLowerCase();
if (seen.has(key)) continue;
seen.add(key);
credited.push(name);
}
return credited.length ? credited.join(', ').slice(0, 120) : null;
}
/** The federated instance holding a picture (its `via` link's host), or null. */
function instanceOf(item) {
const href = item?.links?.find?.((link) => link?.rel === 'via')?.href;
try {
const url = new URL(String(href));
return url.protocol === 'https:' ? url.hostname.slice(0, 80) : null;
} catch {
return null;
}
}
/** A 360° picture: a full-sphere field of view or an equirectangular projection. */
export function isEquirectangular(item) {
const props = item?.properties || {};
const orientation = props['pers:interior_orientation'];
if (Number(orientation?.field_of_view) >= 360) return true;
return props['pers:projection'] === 'equirectangular';
}
/**
* A STAC item (from search or a collection) in the shape the provider and
* viewer use, or null without an id or a position.
* @returns {{id: string, sequenceId: string|null, lon: number, lat: number, heading: number|null, isPano: boolean, capturedAt: number|null, creator: string|null, license: string|null, width: number|null, prevId: string|null, nextId: string|null, urls: {thumb: string|null, sd: string|null, hd: string|null}}|null}
*/
export function normalizeItem(item) {
if (!item || item.id == null) return null;
// Only numbers: Number(null) and Number('') would put a picture at 0,0.
const [lon, lat] = Array.isArray(item.geometry?.coordinates)
? item.geometry.coordinates.map((value) =>
typeof value === 'number' ? value : NaN,
)
: [NaN, NaN];
if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return null;
const props = item.properties || {};
const assets = item.assets || {};
const azimuth =
props['view:azimuth'] === '' || props['view:azimuth'] == null
? NaN
: Number(props['view:azimuth']);
const width = Number(
props['pers:interior_orientation']?.sensor_array_dimensions?.[0],
);
return {
id: String(item.id),
sequenceId: item.collection != null ? String(item.collection) : null,
lon,
lat,
heading: Number.isFinite(azimuth) ? ((azimuth % 360) + 360) % 360 : null,
isPano: isEquirectangular(item),
capturedAt: panoramaxTimeMs(props.datetime),
creator: creatorOf(item),
// Licences ask for the source to be named: where no author can be
// named, the caption names the instance holding the picture.
via: instanceOf(item),
license: licenseLabel(props.license),
width: Number.isFinite(width) && width > 0 ? width : null,
prevId: linkedId(item, 'prev'),
nextId: linkedId(item, 'next'),
urls: {
thumb: httpsUrl(assets.thumb?.href),
sd: httpsUrl(assets.sd?.href),
hd: httpsUrl(assets.hd?.href),
},
};
}
@@ -0,0 +1,281 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {
COLORS,
PICK_PREFIX,
isEquirectangular,
licenseLabel,
normalizeItem,
panoramaxPictureUrl,
panoramaxTimeMs,
} from './policy.js';
import { PROVIDER_COLORS } from '../../policy.js';
import { stacItem } from '../../../../testSupport/panoramaxFixtures.mjs';
test('Panoramax draws in its own orange, and every pick id starts pnx:', () => {
assert.equal(COLORS.coverage, '#ff6f00');
assert.equal(PROVIDER_COLORS.panoramax, '#ff6f00');
for (const prefix of Object.values(PICK_PREFIX))
assert.ok(prefix.startsWith('pnx:'));
// One colour per source.
assert.equal(
new Set(Object.values(PROVIDER_COLORS)).size,
Object.keys(PROVIDER_COLORS).length,
);
});
test('capture times parse in the API’s ISO form, the tiles’ Postgres form, and as bare days', () => {
assert.equal(
panoramaxTimeMs('2023-12-12T07:54:47+00:00'),
Date.UTC(2023, 11, 12, 7, 54, 47),
);
assert.equal(
panoramaxTimeMs('2023-12-12 07:56:37+00'),
Date.UTC(2023, 11, 12, 7, 56, 37),
);
assert.equal(
panoramaxTimeMs('2025-08-13 07:45:51.98+00'),
Date.UTC(2025, 7, 13, 7, 45, 51, 980),
);
// Microseconds are cut to what Date.parse reads.
assert.equal(
panoramaxTimeMs('2025-08-03T14:38:51.838000+00:00'),
Date.UTC(2025, 7, 3, 14, 38, 51, 838),
);
// A sequence's day: its trailing "-11" is the day, not a UTC offset.
assert.equal(panoramaxTimeMs('2025-08-11'), Date.UTC(2025, 7, 11));
assert.equal(
panoramaxTimeMs('2025-08-13 09:00:00+02'),
Date.UTC(2025, 7, 13, 7),
);
for (const bad of ['', 'junk', '1970-01-01', null, 42])
assert.equal(panoramaxTimeMs(bad), null, String(bad));
});
test('a STAC item becomes a picture: position, heading, 360°, licence, links and assets', () => {
const photo = normalizeItem(
stacItem({
id: 'a',
lon: 2.35,
lat: 48.85,
sequenceId: 's',
heading: 370,
pano: true,
license: 'etalab-2.0',
prevId: 'p',
nextId: 'n',
}),
);
assert.deepEqual(
{
id: photo.id,
sequenceId: photo.sequenceId,
lon: photo.lon,
lat: photo.lat,
heading: photo.heading,
isPano: photo.isPano,
license: photo.license,
width: photo.width,
prevId: photo.prevId,
nextId: photo.nextId,
creator: photo.creator,
},
{
id: 'a',
sequenceId: 's',
lon: 2.35,
lat: 48.85,
heading: 10,
isPano: true,
license: 'Licence Ouverte 2.0',
width: 5760,
prevId: 'p',
nextId: 'n',
creator: 'tester',
},
);
assert.equal(
photo.urls.sd,
'https://panoramax.example.org/pictures/a/sd.jpg',
);
assert.equal(photo.capturedAt, Date.UTC(2025, 5, 1, 10));
});
test('a picture without links, heading or a usable position', () => {
const bare = normalizeItem({
id: 7,
geometry: { coordinates: [1, 2] },
properties: {},
});
assert.equal(bare.id, '7');
assert.equal(bare.heading, null);
assert.equal(bare.prevId, null);
assert.equal(bare.nextId, null);
assert.equal(bare.sequenceId, null);
assert.equal(bare.isPano, false);
assert.equal(bare.capturedAt, null);
assert.deepEqual(bare.urls, { thumb: null, sd: null, hd: null });
for (const item of [
null,
{ geometry: { coordinates: [1, 2] } },
{ id: 'x', geometry: { coordinates: ['a', 2] } },
{ id: 'x', geometry: { coordinates: [181, 2] } },
{ id: 'x', geometry: { coordinates: [1, 91] } },
{ id: 'x' },
])
assert.equal(normalizeItem(item), null, JSON.stringify(item));
});
test('asset links that are not https are dropped', () => {
const item = stacItem({ id: 'a', lon: 1, lat: 2 });
item.assets.sd.href = 'http://insecure.example/sd.jpg';
item.assets.hd.href = 'javascript:alert(1)';
const photo = normalizeItem(item);
assert.equal(photo.urls.sd, null);
assert.equal(photo.urls.hd, null);
assert.ok(photo.urls.thumb.startsWith('https://'));
});
test('an account named by an email address is not shown as the creator', () => {
const named = (producer) =>
normalizeItem(stacItem({ id: 'a', lon: 1, lat: 2, producer })).creator;
assert.equal(named('[email protected]'), null);
assert.equal(named('Robot8A'), 'Robot8A');
assert.equal(named(' padded '), 'padded');
assert.equal(named('x'.repeat(200)).length, 80);
// The producer role among the providers serves when the property is missing.
const item = stacItem({ id: 'a', lon: 1, lat: 2 });
delete item.properties['geovisio:producer'];
item.providers = [
{ name: 'host', roles: ['host'] },
{ name: 'mapper', roles: ['producer'] },
];
assert.equal(normalizeItem(item).creator, 'mapper');
});
test('360°: a full field of view, or the equirectangular projection', () => {
assert.equal(
isEquirectangular({
properties: { 'pers:interior_orientation': { field_of_view: 360 } },
}),
true,
);
assert.equal(
isEquirectangular({ properties: { 'pers:projection': 'equirectangular' } }),
true,
);
assert.equal(
isEquirectangular({
properties: { 'pers:interior_orientation': { field_of_view: 92 } },
}),
false,
);
assert.equal(isEquirectangular(null), false);
});
test('licences read as the caption names them', () => {
assert.equal(licenseLabel('CC-BY-SA-4.0'), 'CC BY-SA 4.0');
assert.equal(licenseLabel('etalab-2.0'), 'Licence Ouverte 2.0');
assert.equal(licenseLabel('CC0-1.0'), 'CC0');
assert.equal(licenseLabel('ODbL-1.0'), 'ODbL-1.0');
assert.equal(licenseLabel('proprietary'), null);
assert.equal(licenseLabel(''), null);
assert.equal(licenseLabel(undefined), null);
assert.equal(licenseLabel('x'.repeat(100)).length, 40);
});
test('the caption link opens the picture in the Panoramax viewer', () => {
assert.equal(
panoramaxPictureUrl('d5467bbb-4357'),
'https://api.panoramax.xyz/#pic=d5467bbb-4357&focus=pic',
);
assert.equal(panoramaxPictureUrl(''), 'https://api.panoramax.xyz/');
assert.equal(panoramaxPictureUrl(null), 'https://api.panoramax.xyz/');
assert.ok(panoramaxPictureUrl('a&b=c').includes('pic=a%26b%3Dc'));
});
test('hostile item data: a malformed link escape, null coordinates, a huge producer name', () => {
const item = stacItem({ id: 'a', lon: 1, lat: 2, nextId: 'n' });
item.links.push({
rel: 'prev',
href: 'https://api.panoramax.xyz/api/collections/s/items/%E0%A4%A',
});
const photo = normalizeItem(item);
assert.equal(photo.prevId, null, 'no link, no throw');
assert.equal(photo.nextId, 'n');
for (const coordinates of [[null, null], ['', ''], ['2.35', '48.85'], [2.35]])
assert.equal(
normalizeItem({ id: 'x', geometry: { coordinates } }),
null,
JSON.stringify(coordinates),
);
// A million characters without spaces is checked in linear time.
const started = Date.now();
const huge = normalizeItem(
stacItem({ id: 'a', lon: 1, lat: 2, producer: 'a'.repeat(1_000_000) }),
);
assert.ok(Date.now() - started < 500, `${Date.now() - started} ms`);
assert.equal(huge.creator.length, 80);
const named = (producer) =>
normalizeItem(stacItem({ id: 'a', lon: 1, lat: 2, producer })).creator;
assert.equal(named(`${'x'.repeat(200_000)}@example.org`), null);
assert.equal(
named('Carto@Cité'),
'Carto@Cité',
'an @ without a domain is a name',
);
// The address need not follow the first '@'.
assert.equal(named('@team [email protected]'), null);
assert.equal(named('Carto@Cité ([email protected])'), null);
assert.equal(named(`${'@'.repeat(100_000)}x`), `${'@'.repeat(80)}`);
});
test('thousands of producers are credited in linear time', () => {
const item = stacItem({ id: 'a', lon: 1, lat: 2 });
item.providers = Array.from({ length: 50_000 }, (_, i) => ({
name: `producer-${i}`,
roles: ['producer'],
}));
const started = performance.now();
const { creator } = normalizeItem(item);
assert.ok(performance.now() - started < 1000);
assert.ok(creator.startsWith('tester, producer-0, producer-1'));
assert.ok(creator.length <= 120);
});
test('the instance holding a picture is named (its via host), never as its author', () => {
const item = stacItem({
id: 'a',
lon: 1,
lat: 2,
producer: '[email protected]',
});
item.links.push({ rel: 'via', href: 'https://panoramax.ign.fr' });
assert.equal(normalizeItem(item).creator, null);
assert.equal(normalizeItem(item).via, 'panoramax.ign.fr');
item.links.at(-1).href = 'http://insecure.example';
assert.equal(normalizeItem(item).via, null);
item.links.at(-1).href = 'not a url';
assert.equal(normalizeItem(item).via, null);
});
test('every producer is credited once: the uploading app and its photographer', () => {
const item = stacItem({ id: 'a', lon: 1, lat: 2, producer: 'mapcomplete' });
item.providers = [
{ name: 'mapcomplete', roles: ['producer'] },
{ name: 'pyrog', roles: ['producer'] },
{ name: 'MapComplete', roles: ['producer'] },
{ name: '[email protected]', roles: ['producer'] },
{ name: 'host', roles: ['host'] },
];
assert.equal(normalizeItem(item).creator, 'mapcomplete, pyrog');
const hidden = stacItem({ id: 'b', lon: 1, lat: 2, producer: '[email protected]' });
hidden.providers = [{ name: '[email protected]', roles: ['producer'] }];
assert.equal(normalizeItem(hidden).creator, null);
const many = stacItem({ id: 'c', lon: 1, lat: 2 });
many.providers = Array.from({ length: 50 }, (_, i) => ({
name: `producer-${i}`,
roles: ['producer'],
}));
assert.ok(normalizeItem(many).creator.length <= 120);
});
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,306 @@
import { createLimiter } from '../../limiter.js';
import { msg } from '../../../../i18n/index.js';
import {
API_CONCURRENCY,
API_TIMEOUT_MS,
BUSY_BACKOFF_BASE_SEC,
MAX_RESPONSE_BYTES,
NEAREST_BOX_LIMIT,
NEAREST_FOV_TOLERANCE_DEG,
NEAREST_LIMIT,
NEAREST_RADIUS_M,
PANORAMAX_API,
PICTURE_TILE_CONCURRENCY,
STREAM_IDLE_TIMEOUT_MS,
TILE_CONCURRENCY,
TILE_TIMEOUT_MS,
} from './policy.js';
/** Longest wait a Retry-After (or the backoff) asks for. */
const RETRY_AFTER_MAX_SEC = 300;
/** 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 = msg('Panoramax did not answer in time — try again');
const UNREACHABLE = msg(
'Panoramax could not be reached — check the connection',
);
/**
* Seconds from a Retry-After header (delay seconds or an HTTP date), or
* null. The meta-catalogue exposes no headers to the browser, so in the
* app this is usually null and the caller backs off on its own.
*/
export function retryAfterSeconds(response, now = Date.now()) {
const header = response.headers?.get?.('retry-after');
if (header == null || header === '') return null;
let value = Number(header);
if (!Number.isFinite(value)) {
const at = Date.parse(header);
if (!Number.isFinite(at)) return null;
value = Math.ceil((at - now) / 1000);
}
if (value < 0) return null;
// A maintenance page's hour must not freeze coverage for an hour.
return Math.min(RETRY_AFTER_MAX_SEC, Math.max(1, value));
}
/**
* The body as bytes, refusing more than MAX_RESPONSE_BYTES whatever the
* headers say. `onChunk` hears each piece arrive (the idle timeout).
*/
async function readBounded(response, onChunk = () => {}) {
const tooMuch = () =>
new PanoramaxSourceError(msg('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;
onChunk();
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);
// The cones' z15 tiles have their own connection: a selection never
// waits behind coverage tiles.
const pictureLimiter = createLimiter(PICTURE_TILE_CONCURRENCY, {
lifo: true,
});
/** Busy answers in a row with no readable Retry-After (the backoff grows). */
let busyStreak = 0;
/**
* GET: its headers within `timeoutMs`, then a body that may take as long
* as it keeps arriving (silent for STREAM_IDLE_TIMEOUT_MS is given up).
* The caller's abort wins over both.
*/
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 giveUp = () => controller.abort(new PanoramaxSourceError(NO_ANSWER));
let timer = setTimeout(giveUp, timeoutMs);
try {
const response = await fetchImpl(url, { signal: controller.signal });
if (empty.includes(response.status)) {
busyStreak = 0;
return null;
}
if (response.status === 429 || response.status === 503) {
const told = retryAfterSeconds(response);
// Not told how long: back off, longer each time (5, 10, 20… 300 s).
const wait =
told ??
Math.min(
RETRY_AFTER_MAX_SEC,
BUSY_BACKOFF_BASE_SEC * 2 ** Math.min(busyStreak, 8),
);
busyStreak++;
throw new PanoramaxSourceError(msg('Panoramax is busy'), {
status: response.status,
retryAfterSec: wait,
});
}
if (!response.ok)
throw new PanoramaxSourceError(
`Panoramax answered HTTP ${response.status}`,
{ status: response.status },
);
busyStreak = 0;
// The answer has begun: from here only silence is timed.
clearTimeout(timer);
timer = setTimeout(giveUp, STREAM_IDLE_TIMEOUT_MS);
return await readBounded(response, () => {
clearTimeout(timer);
timer = setTimeout(giveUp, STREAM_IDLE_TIMEOUT_MS);
});
} catch (error) {
if (signal?.aborted) throw signal.reason;
if (controller.signal.aborted) throw controller.signal.reason;
if (error instanceof PanoramaxSourceError) throw error;
// Offline, or a CORS or TLS failure: not a timeout, not worth a retry.
throw new PanoramaxSourceError(UNREACHABLE);
} finally {
clearTimeout(timer);
signal?.removeEventListener('abort', onAbort);
}
}
/**
* A STAC search, through the API gate (newest request first). One that
* timed out is asked once more: a search is quick once the connection
* is free.
*/
async function search(params, { signal } = {}) {
const url = `${root}/search?${new URLSearchParams(params)}`;
const once = () =>
apiLimiter.run(() => get(url, { signal, timeoutMs: API_TIMEOUT_MS }), {
signal,
});
let bytes;
try {
bytes = await once();
} catch (error) {
if (signal?.aborted || error?.message !== NO_ANSWER) throw error;
bytes = await once();
}
let payload;
try {
payload = JSON.parse(new TextDecoder().decode(bytes));
} catch {
throw new PanoramaxSourceError(
msg('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, lane = 'coverage' } = {}) {
const url = `${root}/map/${z}/${x}/${y}.mvt`;
const gate = lane === 'pictures' ? pictureLimiter : tileLimiter;
const bytes = await gate.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, unranked: the caller ranks
* them by distance. Two searches side by side, since neither finds them
* all: `place_position` (nearest first) leaves out pictures looking
* away from the point, whatever the tolerance; a bounding box has them,
* roughly nearest first (not exactly: the caller ranks the union).
* `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 metres = Math.min(1000, Math.max(1, Math.round(radius)));
const shared = {};
if (collections) shared.collections = String(collections);
if (pano === 'pano') shared.filter = 'field_of_view=360';
else if (pano === 'flat') shared.filter = 'field_of_view<360';
if (Number.isFinite(sinceMs) && sinceMs > 0)
shared.datetime = `${new Date(sinceMs).toISOString()}/..`;
const dLat = metres / 111_320;
const dLon =
metres / (111_320 * Math.max(0.01, Math.cos((lat * Math.PI) / 180)));
// Clamped to the map: the API finds nothing in a box past ±180°.
const box = [
Math.max(-180, lon - dLon),
Math.max(-90, lat - dLat),
Math.min(180, lon + dLon),
Math.min(90, lat + dLat),
].map((v) => v.toFixed(7));
// One search failing (busy, no answer) leaves the other's pictures;
// only both failing fails the lookup. The caller's abort stops both.
const both = new AbortController();
const onAbort = () => both.abort(signal.reason);
if (signal?.aborted) throw signal.reason;
signal?.addEventListener('abort', onAbort, { once: true });
const run = (params) =>
search(params, { signal: both.signal }).catch((error) => {
if (!both.signal.aborted && !signal?.aborted) failures.push(error);
throw error;
});
const failures = [];
let settled;
try {
settled = await Promise.allSettled([
run({
place_position: `${Number(lon).toFixed(7)},${Number(lat).toFixed(7)}`,
place_distance: `0-${metres}`,
place_fov_tolerance: String(NEAREST_FOV_TOLERANCE_DEG),
limit: String(Math.min(100, Math.max(1, limit))),
...shared,
}),
run({
bbox: box.join(','),
limit: String(NEAREST_BOX_LIMIT),
...shared,
}),
]);
} finally {
signal?.removeEventListener('abort', onAbort);
}
if (signal?.aborted) throw signal.reason;
const found = settled
.filter((result) => result.status === 'fulfilled')
.map((result) => result.value);
if (!found.length) throw failures[0] ?? settled[0].reason;
const byId = new Map();
for (const item of found.flat())
if (item?.id != null && !byId.has(String(item.id)))
byId.set(String(item.id), item);
return [...byId.values()];
},
};
}
@@ -0,0 +1,513 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {
PanoramaxSourceError,
createPanoramaxSource,
retryAfterSeconds,
} from './source.js';
import {
MAX_RESPONSE_BYTES,
NEAREST_BOX_LIMIT,
STREAM_IDLE_TIMEOUT_MS,
TILE_TIMEOUT_MS,
} from './policy.js';
/** A fetch answering from `respond(url)`, recording every URL asked. */
function fakeFetch(respond) {
const urls = [];
const fetchImpl = async (url, { signal } = {}) => {
urls.push(url);
const answer = await respond(url, signal);
if (answer instanceof Response) return answer;
const { status = 200, body = '', headers = {} } = answer;
return new Response(status === 204 ? null : body, { status, headers });
};
return { urls, fetchImpl };
}
const json = (value) => ({ body: JSON.stringify(value) });
test('a tile is the raw vector-tile bytes; 204 and 404 mean no coverage', async () => {
const { urls, fetchImpl } = fakeFetch((url) =>
url.includes('/14/')
? { body: new Uint8Array([1, 2, 3]) }
: { status: 204 },
);
const source = createPanoramaxSource({ fetchImpl });
assert.deepEqual(
[...(await source.getTile({ x: 8299, y: 5634, z: 14 }))],
[1, 2, 3],
);
assert.equal(urls[0], 'https://api.panoramax.xyz/api/map/14/8299/5634.mvt');
assert.equal((await source.getTile({ x: 1, y: 1, z: 13 })).length, 0);
const missing = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({ status: 404 })).fetchImpl,
});
assert.equal((await missing.getTile({ x: 1, y: 1, z: 13 })).length, 0);
});
test('a busy API says so and when to come back; other failures name the status', async () => {
const busy = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({
status: 429,
headers: { 'retry-after': '12' },
})).fetchImpl,
});
await assert.rejects(busy.getTile({ x: 0, y: 0, z: 0 }), (error) => {
assert.ok(error instanceof PanoramaxSourceError);
assert.equal(error.status, 429);
assert.equal(error.retryAfterSec, 12);
return true;
});
const down = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({ status: 503 })).fetchImpl,
});
await assert.rejects(down.getTile({ x: 0, y: 0, z: 0 }), (error) => {
assert.equal(error.retryAfterSec, 5, 'a default wait without the header');
return true;
});
const broken = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({ status: 500 })).fetchImpl,
});
await assert.rejects(broken.getItem('x'), /HTTP 500/);
});
test('an oversized answer is refused while it streams', async () => {
let pulled = 0;
const huge = new ReadableStream({
pull(controller) {
pulled++;
controller.enqueue(new Uint8Array(4 * 1024 * 1024));
},
});
const source = createPanoramaxSource({
fetchImpl: async () => new Response(huge, { status: 200 }),
});
await assert.rejects(source.getTile({ x: 0, y: 0, z: 0 }), /too much data/);
assert.ok(pulled * 4 * 1024 * 1024 <= MAX_RESPONSE_BYTES + 8 * 1024 * 1024);
// A declared length over the cap is refused before reading.
const declared = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({
body: 'x',
headers: { 'content-length': String(MAX_RESPONSE_BYTES + 1) },
})).fetchImpl,
});
await assert.rejects(declared.getItem('a'), /too much data/);
});
test('a picture by id is a STAC search; another id in the answer is not taken for it', async () => {
const { urls, fetchImpl } = fakeFetch((url) =>
url.includes('ids=good')
? json({ features: [{ id: 'good' }] })
: json({ features: [{ id: 'other' }] }),
);
const source = createPanoramaxSource({ fetchImpl });
assert.deepEqual(await source.getItem('good'), { id: 'good' });
assert.equal(await source.getItem('bad'), null);
const asked = new URL(urls[0]);
assert.equal(asked.pathname, '/api/search');
assert.equal(asked.searchParams.get('ids'), 'good');
assert.equal(asked.searchParams.get('limit'), '1');
});
test('nearest pictures: a place search and a box search side by side, both filtered as the imagery filter asks', async () => {
const { urls, fetchImpl } = fakeFetch(() => json({ features: [] }));
const source = createPanoramaxSource({ fetchImpl });
await source.nearestItems({ lat: 48.85, lon: 2.35 });
await source.nearestItems({
lat: 48.85,
lon: 2.35,
collections: 'seq',
pano: 'pano',
sinceMs: Date.UTC(2025, 0, 1),
radius: 5000,
limit: 500,
});
await source.nearestItems({ lat: 48.85, lon: 2.35, pano: 'flat' });
const asked = urls.map((u) => new URL(u).searchParams);
assert.equal(asked.length, 6, 'two searches a lookup');
const place = asked.filter((q) => q.has('place_position'));
const box = asked.filter((q) => q.has('bbox'));
assert.equal(place.length, 3);
assert.equal(box.length, 3);
const [plain, filtered, flat] = place;
assert.equal(plain.get('place_position'), '2.3500000,48.8500000');
assert.equal(plain.get('place_distance'), '0-50');
assert.equal(plain.get('place_fov_tolerance'), '180');
assert.equal(plain.get('collections'), null);
assert.equal(plain.get('filter'), null);
assert.equal(plain.get('datetime'), null);
assert.equal(filtered.get('collections'), 'seq');
assert.equal(filtered.get('filter'), 'field_of_view=360');
assert.equal(filtered.get('datetime'), '2025-01-01T00:00:00.000Z/..');
assert.equal(filtered.get('place_distance'), '0-1000', 'capped');
assert.equal(filtered.get('limit'), '100', 'capped');
assert.equal(flat.get('filter'), 'field_of_view<360');
// The box spans the radius each way, and carries the same filters.
const [w, s, e, n] = box[0].get('bbox').split(',').map(Number);
assert.ok(Math.abs((n - s) * 111_320 - 100) < 1, `${n - s}°`);
assert.ok(
Math.abs((e - w) * 111_320 * Math.cos((48.85 * Math.PI) / 180) - 100) < 1,
);
assert.equal(box[1].get('collections'), 'seq');
assert.equal(box[1].get('filter'), 'field_of_view=360');
assert.equal(box[1].get('datetime'), '2025-01-01T00:00:00.000Z/..');
assert.equal(box[2].get('filter'), 'field_of_view<360');
});
test('a picture both searches find is listed once', async () => {
const source = createPanoramaxSource({
fetchImpl: fakeFetch((url) =>
url.includes('bbox')
? json({ features: [{ id: 'b' }, { id: 'a' }, { id: null }] })
: json({ features: [{ id: 'a' }] }),
).fetchImpl,
});
const items = await source.nearestItems({ lat: 1, lon: 2 });
assert.deepEqual(
items.map((i) => i.id),
['a', 'b'],
);
});
test('the newest search goes first when the API gate is full', async () => {
const waiting = [];
const order = [];
const source = createPanoramaxSource({
fetchImpl: async (url) => {
order.push(new URL(url).searchParams.get('ids'));
await new Promise((resolve) => waiting.push(resolve));
return new Response(JSON.stringify({ features: [] }));
},
});
const all = ['1', '2', '3', '4', '5', '6'].map((id) => source.getItem(id));
await new Promise((resolve) => setTimeout(resolve, 0));
assert.deepEqual(order, ['1', '2'], 'two at once');
waiting.shift()();
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(order.at(-1), '6', 'the latest waiting one next');
let done = false;
Promise.allSettled(all).then(() => (done = true));
while (!done) {
waiting.splice(0).forEach((go) => go());
await new Promise((resolve) => setTimeout(resolve, 0));
}
});
test('an unreadable search answer, or one with no features, is handled', async () => {
const garbled = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({ body: '<html>' })).fetchImpl,
});
await assert.rejects(garbled.getItem('a'), /unreadable/);
const empty = createPanoramaxSource({
fetchImpl: fakeFetch(() => json({ type: 'FeatureCollection' })).fetchImpl,
});
assert.deepEqual(await empty.nearestItems({ lat: 0, lon: 0 }), []);
});
test('the caller’s abort wins; a silent API times out with a readable message', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const hang = (url, signal) =>
new Promise((_, reject) =>
signal.addEventListener('abort', () => reject(signal.reason)),
);
const source = createPanoramaxSource({
fetchImpl: fakeFetch(hang).fetchImpl,
});
const controller = new AbortController();
const asked = source.getItem('a', { signal: controller.signal });
await Promise.resolve();
controller.abort(new Error('overtaken'));
await assert.rejects(asked, /overtaken/);
const slow = source.getTile({ x: 0, y: 0, z: 0 });
// Let the request start before the clock runs out.
for (let i = 0; i < 5; i++) await Promise.resolve();
t.mock.timers.tick(60_000);
await assert.rejects(slow, /did not answer in time/);
});
test('a network failure reads as unreachable, not as a stack trace', async () => {
const source = createPanoramaxSource({
fetchImpl: async () => {
throw new TypeError('Failed to fetch');
},
});
await assert.rejects(source.getTile({ x: 0, y: 0, z: 0 }), (error) => {
assert.ok(error instanceof PanoramaxSourceError);
assert.match(error.message, /could not be reached/);
return true;
});
});
test('a search that timed out is asked once more; a second timeout is reported', async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
let calls = 0;
const hang = (signal) =>
new Promise((_, reject) =>
signal.addEventListener('abort', () => reject(signal.reason)),
);
const source = createPanoramaxSource({
fetchImpl: async (url, { signal }) => {
calls++;
if (calls === 1) return hang(signal);
return new Response(JSON.stringify({ features: [{ id: 'a' }] }));
},
});
const asked = source.getItem('a');
for (let i = 0; i < 5; i++) await Promise.resolve();
t.mock.timers.tick(60_000);
assert.deepEqual(await asked, { id: 'a' });
assert.equal(calls, 2);
const stuck = createPanoramaxSource({
fetchImpl: async (url, { signal }) => hang(signal),
});
const never = stuck.getItem('b');
for (let round = 0; round < 2; round++) {
for (let i = 0; i < 10; i++) await Promise.resolve();
t.mock.timers.tick(60_000);
}
await assert.rejects(never, /did not answer in time/);
});
test('the HTTP/1.1 API never gets more than five requests at once: three tiles, two searches', async () => {
const { API_CONCURRENCY, TILE_CONCURRENCY } = await import('./policy.js');
assert.ok(API_CONCURRENCY + TILE_CONCURRENCY <= 5);
let open = 0;
let most = 0;
const waiting = [];
const source = createPanoramaxSource({
fetchImpl: async (url) => {
open++;
most = Math.max(most, open);
await new Promise((resolve) => waiting.push(resolve));
open--;
return url.includes('/map/')
? new Response(null, { status: 204 })
: new Response(JSON.stringify({ features: [] }));
},
});
const all = [
...Array.from({ length: 8 }, (_, i) =>
source.getTile({ x: i, y: 0, z: 14 }),
),
...Array.from({ length: 4 }, (_, i) => source.getItem(String(i))),
];
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(most, 5);
let done = false;
Promise.allSettled(all).then(() => (done = true));
while (!done) {
waiting.splice(0).forEach((go) => go());
await new Promise((resolve) => setTimeout(resolve, 0));
}
assert.equal(most, 5, 'never more');
});
test('one of the two nearest searches failing leaves the other’s pictures; both failing fails the lookup', async () => {
const half = createPanoramaxSource({
fetchImpl: fakeFetch((url) =>
url.includes('bbox')
? { status: 503 }
: json({ features: [{ id: 'facing' }] }),
).fetchImpl,
});
assert.deepEqual(
(await half.nearestItems({ lat: 1, lon: 2 })).map((i) => i.id),
['facing'],
);
const none = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({ status: 503 })).fetchImpl,
});
await assert.rejects(none.nearestItems({ lat: 1, lon: 2 }), /busy/);
});
test('only a timeout is asked again: a busy or failing API is asked once, an unreachable one says so', async () => {
for (const status of [429, 500, 503]) {
const { urls, fetchImpl } = fakeFetch(() => ({ status }));
const source = createPanoramaxSource({ fetchImpl });
await assert.rejects(source.getItem('a'));
assert.equal(urls.length, 1, `HTTP ${status}: one fetch`);
}
let calls = 0;
const offline = createPanoramaxSource({
fetchImpl: async () => {
calls++;
throw new TypeError('Failed to fetch');
},
});
await assert.rejects(offline.getItem('a'), /could not be reached/);
assert.equal(calls, 1, 'not retried');
});
test('a Retry-After is honoured up to five minutes', async () => {
const wait = async (header) => {
const source = createPanoramaxSource({
fetchImpl: fakeFetch(() => ({
status: 503,
headers: { 'retry-after': header },
})).fetchImpl,
});
return source
.getTile({ x: 0, y: 0, z: 0 })
.catch((error) => error.retryAfterSec);
};
assert.equal(await wait('3600'), 300);
assert.equal(await wait('99999999999'), 300);
assert.equal(await wait('0'), 1);
assert.equal(await wait('12'), 12);
});
test('a Retry-After may be an HTTP date', () => {
const now = Date.parse('2026-10-15T12:00:00Z');
const response = (value) =>
new Response(null, { status: 429, headers: { 'retry-after': value } });
assert.equal(
retryAfterSeconds(response('Thu, 15 Oct 2026 12:01:00 GMT'), now),
60,
);
assert.equal(
retryAfterSeconds(response('Thu, 15 Oct 2026 14:00:00 GMT'), now),
300,
);
assert.equal(
retryAfterSeconds(response('Thu, 15 Oct 2026 11:00:00 GMT'), now),
null,
'a date already past',
);
assert.equal(retryAfterSeconds(response('soon'), now), null);
assert.equal(
retryAfterSeconds(new Response(null, { status: 429 }), now),
null,
);
});
test('busy without a readable Retry-After (the browser hides it): the wait doubles, and resets once answered', async () => {
let busy = true;
const source = createPanoramaxSource({
fetchImpl: fakeFetch(() =>
busy ? { status: 429 } : { body: new Uint8Array([1]) },
).fetchImpl,
});
const wait = () =>
source.getTile({ x: 0, y: 0, z: 0 }).then(
() => 'ok',
(error) => error.retryAfterSec,
);
const waits = [];
for (let i = 0; i < 9; i++) waits.push(await wait());
assert.deepEqual(waits, [5, 10, 20, 40, 80, 160, 300, 300, 300]);
busy = false;
assert.equal(await wait(), 'ok');
busy = true;
assert.equal(await wait(), 5, 'back to the first wait');
});
test(
'a body that keeps arriving is not cut off by the request timeout; one that stalls is',
{ timeout: 10_000 },
async (t) => {
t.mock.timers.enable({ apis: ['setTimeout'] });
const settle = async () => {
for (let i = 0; i < 20; i++) await Promise.resolve();
};
// Headers at once, then a chunk every 10 s for twice the tile timeout.
const chunks = Math.ceil((2 * TILE_TIMEOUT_MS) / 10_000);
let push;
const slowBody = (signal) =>
new Response(
new ReadableStream({
start(controller) {
push = (last) => {
controller.enqueue(new Uint8Array([7]));
if (last) controller.close();
};
signal.addEventListener('abort', () =>
controller.error(signal.reason),
);
},
}),
{ status: 200 },
);
const source = createPanoramaxSource({
fetchImpl: async (url, { signal }) => slowBody(signal),
});
const slow = source.getTile({ x: 0, y: 0, z: 0 });
await settle();
for (let i = 1; i <= chunks; i++) {
t.mock.timers.tick(10_000);
push(i === chunks);
await settle();
}
assert.equal((await slow).length, chunks, 'every chunk read');
const stalled = source.getTile({ x: 0, y: 0, z: 0 });
await settle();
push(false);
await settle();
t.mock.timers.tick(STREAM_IDLE_TIMEOUT_MS);
await assert.rejects(stalled, /did not answer in time/);
},
);
test('the box search asks for a few pictures: the API returns them nearest first', async () => {
const { urls, fetchImpl } = fakeFetch(() => json({ features: [] }));
const source = createPanoramaxSource({ fetchImpl });
await source.nearestItems({ lon: 2.35, lat: 48.85 });
const box = urls
.map((url) => new URL(url))
.find((url) => url.searchParams.has('bbox'));
assert.ok(box, 'a box search');
assert.equal(box.searchParams.get('limit'), String(NEAREST_BOX_LIMIT));
assert.ok(NEAREST_BOX_LIMIT <= 20);
});
test('the cones’ tiles have their own connection: never behind coverage tiles, the newest first', async () => {
const { PICTURE_TILE_CONCURRENCY, TILE_CONCURRENCY } =
await import('./policy.js');
assert.equal(PICTURE_TILE_CONCURRENCY, 1);
const held = new Map();
const asked = [];
const source = createPanoramaxSource({
fetchImpl: (url) => {
asked.push(url.replace(/^.*\/map\//, ''));
return new Promise((resolve) =>
held.set(url.replace(/^.*\/map\//, ''), () =>
resolve(new Response(null, { status: 204 })),
),
);
},
});
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
// Coverage fills its lane and queues.
const coverage = Array.from({ length: TILE_CONCURRENCY + 2 }, (_, i) =>
source.getTile({ x: i, y: 0, z: 10 }),
);
await settle();
assert.equal(asked.length, TILE_CONCURRENCY);
// A cone tile goes at once; two more wait, the newer first.
const pictures = [1, 2, 3].map((x) =>
source.getTile({ x, y: 9, z: 15 }, { lane: 'pictures' }),
);
await settle();
assert.deepEqual(asked.slice(TILE_CONCURRENCY), ['15/1/9.mvt']);
held.get('15/1/9.mvt')();
await settle();
assert.deepEqual(asked.slice(TILE_CONCURRENCY), ['15/1/9.mvt', '15/3/9.mvt']);
for (let round = 0; round < 6; round++) {
for (const go of held.values()) go();
await settle();
}
await Promise.all([...coverage, ...pictures]);
});
test('a lookup near the antimeridian keeps its box on the map', async () => {
const { urls, fetchImpl } = fakeFetch(() => json({ features: [] }));
const source = createPanoramaxSource({ fetchImpl });
await source.nearestItems({ lat: -16, lon: 179.9999 });
const box = urls
.map((u) => new URL(u).searchParams.get('bbox'))
.find(Boolean)
.split(',')
.map(Number);
assert.equal(box[2], 180);
assert.ok(box[0] < 180);
});
@@ -0,0 +1,97 @@
import {
PANO_FULL_SIZE,
createPhotoViewer,
loadImage,
} from '../../photoViewer.js';
import {
HD_TIMEOUT_MS,
PANORAMAX_NAME,
PANORAMAX_PROVIDER_ID,
PANO_HD_MAX_WIDTH,
SD_WIDTH,
panoramaxPictureUrl,
} from './policy.js';
/** An HD original small enough to decode (its width is known and under the cap). */
function hdDecodable(photo) {
return Boolean(
photo.urls.hd && photo.width && photo.width <= PANO_HD_MAX_WIDTH,
);
}
/**
* Where Panoramax pictures come from: the instance holding each one serves
* a 2,048 px SD derivative (equirectangular for a 360° picture) and the HD
* original. SD shows first; HD only once the viewer is wide enough to use
* it. A 360° original is shrunk to the texture size while it decodes.
* @type {import('../../photoViewer.js').PhotoSources}
*/
export const PANORAMAX_SOURCES = Object.freeze({
hasPano: (photo) =>
Boolean(photo.isPano && (photo.urls.sd || hdDecodable(photo))),
// Without an SD derivative the original goes straight to the texture size.
panoFirst: (photo) => {
// Decoded at SD's own size, whatever the host actually serves.
if (photo.urls.sd)
return {
url: photo.urls.sd,
width: SD_WIDTH,
resize: [SD_WIDTH, SD_WIDTH / 2],
};
if (!hdDecodable(photo)) return null;
const width = Math.min(photo.width, PANO_FULL_SIZE[0]);
return { url: photo.urls.hd, width, resize: [width, width / 2] };
},
// The original is several megabytes with no server to shrink it: only
// for the expanded viewer (a docked one on a dense screen asks too).
panoSharp: (photo, size, { expanded = false } = {}) => {
const width = photo.width || 0;
if (!expanded || !photo.urls.hd || !photo.urls.sd) return null;
// An original no wider than the SD one adds nothing; a huge one would
// take hundreds of megabytes to decode.
if (width <= SD_WIDTH || width > PANO_HD_MAX_WIDTH) return null;
const target = Math.min(size[0], width);
return {
url: photo.urls.hd,
resize: [target, target / 2],
timeoutMs: HD_TIMEOUT_MS,
};
},
// A 360° picture shown flat (no WebGL) is its whole equirectangular image.
// When SD fails the thumbnail stands in; the original (megabytes) only
// for the expanded viewer, and only one of a size it may decode.
flatFirst: (photo, { expanded = false } = {}) => [
photo.urls.sd,
expanded && hdDecodable(photo) ? photo.urls.hd : null,
photo.urls.thumb,
],
// The original once the viewer is wider than SD, if its width is known
// and decodable (a 200 MP phone photo is 16,000 px across).
flatSharp: (photo, pixels) =>
photo.urls.sd && hdDecodable(photo) && pixels > SD_WIDTH
? photo.urls.hd
: null,
describe: (photo) => ({
// Where no author can be named, the instance holding the photo is.
title: !photo.creator && photo.via ? `via ${photo.via}` : null,
creator: photo.creator,
license: photo.license,
externalUrl: panoramaxPictureUrl(photo.id),
}),
});
/**
* Viewer adapter for Panoramax pictures: flat in an <img>, 360° on the
* shared WebGL panorama, ‹ › along the sequence (photoViewer.js).
* @param {object} options See photoViewer.js `createPhotoViewer`.
* @returns {import('../../registry.js').ViewerAdapter}
*/
export function createPanoramaxViewer({ load = loadImage, ...options }) {
return createPhotoViewer({
providerId: PANORAMAX_PROVIDER_ID,
name: PANORAMAX_NAME,
sources: PANORAMAX_SOURCES,
load,
...options,
});
}
@@ -0,0 +1,341 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { PANORAMAX_SOURCES, createPanoramaxViewer } from './viewer.js';
import { normalizeItem } from './policy.js';
import { fakeHost, until } from '../../../../testSupport/kartaViewFakes.mjs';
import { stacItem } from '../../../../testSupport/panoramaxFixtures.mjs';
const photo = (options) =>
normalizeItem(stacItem({ lon: 2.35, lat: 48.85, ...options }));
const PHOTOS = {
flat: photo({ id: 'flat', prevId: 'p0', nextId: 'flat2', heading: 30 }),
flat2: photo({ id: 'flat2', prevId: 'flat', heading: 40 }),
pano: photo({ id: 'pano', pano: true, heading: 100, width: 5760 }),
bigPano: photo({ id: 'bigPano', pano: true, width: 11_000 }),
smallPano: photo({ id: 'smallPano', pano: true, width: 2048 }),
email: photo({ id: 'email', producer: '[email protected]' }),
};
function fakeRenderer() {
const view = { yaw: 0, pitch: 0, fov: 80 };
const images = [];
return {
images,
setImage: (image) => images.push(image),
setView(next) {
Object.assign(view, next);
},
getView: () => ({ ...view }),
resize() {},
clear() {},
destroy() {},
};
}
function setup() {
const loads = [];
const renderers = [];
const stepped = [];
const viewer = createPanoramaxViewer({
getPhoto: async (id) => {
if (!PHOTOS[id]) throw new Error('no such picture');
return PHOTOS[id];
},
step: async (from, delta) => (delta < 0 ? from.prevId : from.nextId),
onStep: (id) => {
stepped.push(id);
viewer.open(id).catch(() => {});
},
load: async (url, options) => {
loads.push({ url, ...options });
return { src: url, width: 1, height: 1 };
},
createRenderer: () => {
const renderer = fakeRenderer();
renderers.push(renderer);
return renderer;
},
});
const poses = [];
viewer.onPose((pose) => poses.push(pose));
return { viewer, poses, loads, renderers, stepped, host: fakeHost() };
}
const parts = (host) => {
const root = host.children[0];
const [picture, canvas, prev, next] = root.children;
return { root, picture, canvas, prev, next };
};
test('a flat picture shows its SD version with author, licence and a Panoramax link', async () => {
const { viewer, poses, loads, host } = setup();
await viewer.mount(host);
const { root, picture, canvas } = parts(host);
assert.equal(root.dataset.provider, 'panoramax', 'its colour in the CSS');
assert.match(root.attributes['aria-label'], /^Panoramax photo/);
await viewer.open('flat');
assert.equal(picture.hidden, false);
assert.equal(canvas.hidden, true);
assert.equal(
picture.src,
'https://panoramax.example.org/pictures/flat/sd.jpg',
);
assert.deepEqual(
loads.map((l) => l.url),
[PHOTOS.flat.urls.sd],
);
const pose = poses.at(-1);
assert.equal(pose.providerId, 'panoramax');
assert.equal(pose.bearing, 30);
assert.equal(pose.isPano, false);
assert.equal(pose.creator, 'tester');
assert.equal(pose.license, 'CC BY-SA 4.0');
assert.equal(pose.sequenceId, 'seq-1');
assert.equal(
pose.externalUrl,
'https://api.panoramax.xyz/#pic=flat&focus=pic',
);
assert.equal(viewer.supportsRenderModes(), true);
});
test('no creator in the caption for an account named by an email address', async () => {
const { viewer, poses, host } = setup();
await viewer.mount(host);
await viewer.open('email');
assert.equal(poses.at(-1).creator, null);
});
test('HD replaces SD only once the viewer is wide enough to use it', async (t) => {
const { viewer, loads, host } = setup();
await viewer.mount(host);
const { picture, root } = parts(host);
t.after(() => delete globalThis.devicePixelRatio);
globalThis.devicePixelRatio = 1;
picture.clientWidth = 400;
await viewer.open('flat');
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(loads.length, 1, 'docked: SD is sharp enough');
// EXPAND on a wide screen.
picture.clientWidth = root.clientWidth = 2600;
viewer.resize();
assert.ok(await until(() => picture.src === PHOTOS.flat.urls.hd));
viewer.resize();
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(
loads.filter((l) => l.url === PHOTOS.flat.urls.hd).length,
1,
'asked once',
);
});
test('a 360° picture shows its SD equirectangular image, then HD shrunk to 4,096 when expanded', async (t) => {
const { viewer, poses, loads, renderers, host } = setup();
await viewer.mount(host);
const { canvas, picture } = parts(host);
t.after(() => delete globalThis.devicePixelRatio);
globalThis.devicePixelRatio = 1;
canvas.clientWidth = 400;
await viewer.open('pano');
assert.equal(canvas.hidden, false);
assert.equal(picture.hidden, true);
assert.equal(viewer.supportsRenderModes(), false, 'no frame to fit');
const { signal, ...first } = loads[0];
assert.deepEqual(first, {
url: PHOTOS.pano.urls.sd,
crossOrigin: true,
resize: [2048, 1024],
failure: 'The Panoramax photo could not be loaded',
});
assert.equal(signal.aborted, false, 'the open can stop it');
assert.equal(poses.at(-1).isPano, true);
assert.equal(poses.at(-1).bearing, 100);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(loads.length, 1, 'docked: the 2,048 px SD is enough');
// Docked on a dense screen the canvas wants more, but the original is
// megabytes: not until the viewer is expanded.
canvas.clientWidth = 1800;
viewer.resize();
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(loads.length, 1, 'docked: still SD only');
const root = canvas.parentNode;
root.closest = (selector) =>
selector.includes('sl-viewer-wrap-expanded') ? {} : null;
// EXPAND resizes more than once while the panel settles.
viewer.resize();
viewer.resize();
viewer.resize();
assert.ok(await until(() => renderers[0].images.length === 2));
assert.equal(
loads.filter((l) => l.url === PHOTOS.pano.urls.hd).length,
1,
'the original is fetched once',
);
const hd = loads.at(-1);
assert.equal(hd.url, PHOTOS.pano.urls.hd);
assert.deepEqual(hd.resize, [4096, 2048]);
assert.equal(hd.timeoutMs, 30_000);
assert.ok(hd.signal, 'abortable');
});
test('HD panoramas too big to decode, or no bigger than SD, are never fetched; nor while docked', () => {
const size = [4096, 2048];
const expanded = { expanded: true };
assert.equal(
PANORAMAX_SOURCES.panoSharp(PHOTOS.pano, size, { expanded: false }),
null,
);
assert.equal(PANORAMAX_SOURCES.panoSharp(PHOTOS.pano, size), null);
assert.equal(
PANORAMAX_SOURCES.panoSharp(PHOTOS.bigPano, size, expanded),
null,
);
assert.equal(
PANORAMAX_SOURCES.panoSharp(PHOTOS.smallPano, size, expanded),
null,
);
assert.deepEqual(
PANORAMAX_SOURCES.panoSharp({ ...PHOTOS.pano, width: 3000 }, size, expanded)
.resize,
[3000, 1500],
'never enlarged',
);
// Without an SD derivative the HD one is the first and only.
const hdOnly = { ...PHOTOS.pano, urls: { ...PHOTOS.pano.urls, sd: null } };
assert.deepEqual(PANORAMAX_SOURCES.panoFirst(hdOnly), {
url: hdOnly.urls.hd,
width: 4096,
resize: [4096, 2048],
});
// …unless it is too big to decode: then no panorama, and the thumbnail.
const hugeOnly = { ...hdOnly, width: 11_904 };
assert.equal(PANORAMAX_SOURCES.panoFirst(hugeOnly), null);
assert.equal(PANORAMAX_SOURCES.hasPano(hugeOnly), false);
assert.deepEqual(PANORAMAX_SOURCES.flatFirst(hugeOnly).filter(Boolean), [
hugeOnly.urls.thumb,
]);
assert.equal(PANORAMAX_SOURCES.panoSharp(hdOnly, size, expanded), null);
assert.equal(PANORAMAX_SOURCES.flatSharp(PHOTOS.flat, 2048), null);
assert.equal(
PANORAMAX_SOURCES.flatSharp(PHOTOS.flat, 2049),
PHOTOS.flat.urls.hd,
);
assert.equal(
PANORAMAX_SOURCES.hasPano({ isPano: true, urls: { sd: null, hd: null } }),
false,
);
});
test('› and ‹ follow the picture’s own links; the ends disable the buttons', async () => {
const { viewer, poses, stepped, host } = setup();
await viewer.mount(host);
const { next, prev } = parts(host);
await viewer.open('flat');
next.fire('click');
assert.ok(await until(() => poses.at(-1)?.imageId === 'flat2'));
assert.deepEqual(stepped, ['flat2']);
assert.ok(await until(() => next.disabled), 'flat2 is the last');
assert.equal(prev.disabled, false);
});
test('without WebGL a 360° picture shows its whole equirectangular image flat', async () => {
const loads = [];
const viewer = createPanoramaxViewer({
getPhoto: async () => PHOTOS.pano,
step: async () => null,
onStep() {},
load: async (url) => {
loads.push(url);
return { src: url };
},
createRenderer: () => {
throw new Error('no WebGL');
},
});
const host = fakeHost();
await viewer.mount(host);
await viewer.open('pano');
const { picture } = parts(host);
assert.equal(picture.hidden, false);
assert.equal(picture.src, PHOTOS.pano.urls.sd);
});
test('a picture whose SD fails falls back to the thumbnail; the original only for the expanded viewer', async () => {
const tried = [];
const viewer = createPanoramaxViewer({
getPhoto: async () => PHOTOS.flat,
step: async () => null,
onStep() {},
load: async (url) => {
tried.push(url);
if (!url.endsWith('thumb.jpg')) throw new Error('gone');
return { src: url };
},
});
const host = fakeHost();
await viewer.mount(host);
await viewer.open('flat');
assert.deepEqual(tried, [PHOTOS.flat.urls.sd, PHOTOS.flat.urls.thumb]);
assert.equal(parts(host).picture.src, PHOTOS.flat.urls.thumb);
// Expanded, the original is worth its megabytes.
tried.length = 0;
parts(host).root.closest = (selector) =>
selector.includes('sl-viewer-wrap-expanded') ? {} : null;
await viewer.open('flat');
assert.deepEqual(tried, [
PHOTOS.flat.urls.sd,
PHOTOS.flat.urls.hd,
PHOTOS.flat.urls.thumb,
]);
});
test('a photo with no author to name is captioned with the instance holding it', () => {
const photo = normalizeItem(
stacItem({ id: 'x', lon: 1, lat: 2, producer: '[email protected]' }),
);
photo.via = 'panoramax.ign.fr';
assert.deepEqual(PANORAMAX_SOURCES.describe(photo), {
title: 'via panoramax.ign.fr',
creator: null,
license: 'CC BY-SA 4.0',
externalUrl: 'https://api.panoramax.xyz/#pic=x&focus=pic',
});
const named = { ...photo, creator: 'Robot8A' };
assert.equal(PANORAMAX_SOURCES.describe(named).title, null);
});
test('an SD panorama refused for its size is not fetched again as a flat photo', async () => {
const loads = [];
const viewer = createPanoramaxViewer({
getPhoto: async () => PHOTOS.pano,
step: async () => null,
onStep() {},
load: async (url, options = {}) => {
loads.push({ url, crossOrigin: options.crossOrigin });
// The picture host's SD file is past the viewer's size limits.
if (url === PHOTOS.pano.urls.sd)
throw Object.assign(new Error('too big'), { tooLarge: true });
return { src: url };
},
createRenderer: () => ({
setImage() {},
setView() {},
getView: () => ({ yaw: 0, pitch: 0, fov: 80 }),
resize() {},
clear() {},
destroy() {},
}),
});
const host = fakeHost();
await viewer.mount(host);
await viewer.open('pano');
const sdLoads = loads.filter((l) => l.url === PHOTOS.pano.urls.sd);
assert.equal(sdLoads.length, 1, 'tried once, as a bitmap, and refused');
assert.equal(sdLoads[0].crossOrigin, true);
const { picture } = parts(host);
assert.equal(picture.hidden, false, 'the flat fallback shows');
assert.notEqual(picture.src, PHOTOS.pano.urls.sd);
// Opened again later: the refused file is still not asked for.
await viewer.open('pano');
assert.equal(loads.filter((l) => l.url === PHOTOS.pano.urls.sd).length, 1);
});