feat(street-level): KartaView as a third, keyless imagery provider

Coverage lines from KartaView's z13-14 JSON tiles (OSM ways with photos,
chained end to start), the photo nearest a clicked line, cones along its
sequence, and a viewer for flat photos and 360° panoramas (a small WebGL
equirectangular renderer, no new dependency) with ‹ › along the sequence.

Mapillary's camera-driven line coverage and sequence cones move to the
provider-neutral core (lineCoverage.js, sequenceCones.js) with the tile
fetch, zoom ladder, colours and pick prefixes injected; Mapillary keeps
thin wrappers and its tests pass unchanged.

KartaView quirks handled: api.kartaview.org (the documented
api.openstreetcam.org serves empty tiles), photo URLs that name storage1
for photos stored elsewhere, and a photo API that answers 429 to more than
about three requests at once (two in flight, retried with backoff).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Said TurkseverandClaude Opus 5.5 committed 2026-10-13 18:33:14 +01:00
1 parent 9beadbda63
commit cb01014e36
33 files changed
+4046 -1196

No files matched your search

@@ -0,0 +1,55 @@
/**
* Decode a KartaView coverage tile (`{lines: [{track: [{lat, lng}]}]}`) into
* line records for the shared coverage. The tile's lines are OSM way
* segments with photos; segments that meet end to start are chained, which
* cuts the line count about fourfold. Lines carry no sequence, date or
* projection, so nothing can filter them.
* @param {object} payload
* @param {{x: number, y: number, z: number}} address
* @returns {{sequences: Array<{id: string, parts: Array<Array<[number, number]>>, capturedAt: number, isPano: boolean}>, overview: Array<never>}}
*/
export function decodeCoverageTile(payload, { x, y, z }) {
const segments = [];
for (const line of Array.isArray(payload?.lines) ? payload.lines : []) {
const points = [];
for (const point of Array.isArray(line?.track) ? line.track : []) {
const lon = Number(point?.lng);
const lat = Number(point?.lat);
if (!Number.isFinite(lon) || !Number.isFinite(lat)) continue;
const last = points[points.length - 1];
if (last && last[0] === lon && last[1] === lat) continue;
points.push([lon, lat]);
}
if (points.length >= 2) segments.push(points);
}
const key = ([lon, lat]) => `${lon},${lat}`;
const startingAt = new Map();
segments.forEach((segment, index) => {
const at = key(segment[0]);
const list = startingAt.get(at);
if (list) list.push(index);
else startingAt.set(at, [index]);
});
const used = new Uint8Array(segments.length);
const sequences = [];
segments.forEach((segment, index) => {
if (used[index]) return;
used[index] = 1;
const chain = [...segment];
for (;;) {
const next = startingAt
.get(key(chain[chain.length - 1]))
?.find((candidate) => !used[candidate]);
if (next === undefined) break;
used[next] = 1;
chain.push(...segments[next].slice(1));
}
sequences.push({
id: `${z}/${x}/${y}/${sequences.length}`,
parts: [chain],
capturedAt: 0,
isPano: false,
});
});
return { sequences, overview: [] };
}
@@ -0,0 +1,75 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { decodeCoverageTile } from './decode.js';
const at = (lng, lat) => ({ lat: String(lat), lng: String(lng) });
const TILE = { x: 4412, y: 6061, z: 14 };
test('segments that meet end to start chain into one line', () => {
const { sequences, overview } = decodeCoverageTile(
{
lines: [
{ track: [at(1, 1), at(2, 1)], matched: '1' },
{ track: [at(5, 5), at(6, 6)], matched: '1' },
{ track: [at(2, 1), at(3, 1), at(4, 2)], matched: '1' },
],
},
TILE,
);
assert.deepEqual(overview, []);
assert.equal(sequences.length, 2);
assert.deepEqual(sequences[0].parts, [
[
[1, 1],
[2, 1],
[3, 1],
[4, 2],
],
]);
assert.equal(sequences[0].id, '14/4412/6061/0');
assert.equal(sequences[1].id, '14/4412/6061/1');
// Nothing to date or project: every line passes as flat and undated.
assert.equal(sequences[0].capturedAt, 0);
assert.equal(sequences[0].isPano, false);
});
test('a junction continues one way only, and every segment is drawn exactly once', () => {
const { sequences } = decodeCoverageTile(
{
lines: [
{ track: [at(0, 0), at(1, 0)] },
{ track: [at(1, 0), at(2, 0)] },
{ track: [at(1, 0), at(1, 1)] },
// A loop back to its own start must end, not spin.
{ track: [at(9, 9), at(9, 8)] },
{ track: [at(9, 8), at(9, 9)] },
],
},
TILE,
);
const points = sequences.reduce((sum, s) => sum + s.parts[0].length, 0);
assert.equal(sequences.length, 3);
// 5 segments of 2 points, 2 joins in chains: 10 - 2 = 8 points.
assert.equal(points, 8);
});
test('bad points, repeats and one-point tracks are skipped; an empty tile has no lines', () => {
const { sequences } = decodeCoverageTile(
{
lines: [
{ track: [at(1, 1), at(1, 1), { lat: 'x', lng: '2' }, at(2, 2)] },
{ track: [at(3, 3)] },
{ track: null },
null,
],
},
TILE,
);
assert.equal(sequences.length, 1);
assert.deepEqual(sequences[0].parts[0], [
[1, 1],
[2, 2],
]);
assert.deepEqual(decodeCoverageTile({ lines: [] }, TILE).sequences, []);
assert.deepEqual(decodeCoverageTile(null, TILE).sequences, []);
});
@@ -0,0 +1,374 @@
import { createLineCoverage } from '../../lineCoverage.js';
import { createSequenceCones, thinImages } from '../../sequenceCones.js';
import { metresBetween } from '../../view.js';
import { decodeCoverageTile } from './decode.js';
import { createKartaViewSource } from './source.js';
import { createKartaViewViewer } from './viewer.js';
import {
COLORS,
COVERAGE_MAX_HEIGHT_M,
COVERAGE_NOUN,
COVERAGE_STREET_ZOOM_BELOW_M,
COVERAGE_TUNING,
KARTAVIEW_CREDIT_HTML,
KARTAVIEW_LABEL,
KARTAVIEW_NAME,
KARTAVIEW_PROVIDER_ID,
LINE_CLICK_HINT,
NEAREST_RADIUS_M,
PICK_PREFIX,
RATE_LIMITED_MESSAGE,
SEQUENCE_PAGE_SIZE,
TOO_HIGH_HINT,
normalizePhoto,
} from './policy.js';
/** Photos kept in memory by id (sequence pages fill it). */
const PHOTO_CACHE_SIZE = 4000;
/** Sequence pages kept in memory. */
const PAGE_CACHE_SIZE = 8;
/** z14 near the street, z13 a little higher, nothing above. */
export function kartaViewZoomFor(heightM) {
if (!Number.isFinite(heightM) || heightM > COVERAGE_MAX_HEIGHT_M) return null;
return {
zoom: heightM > COVERAGE_STREET_ZOOM_BELOW_M ? 13 : 14,
kind: 'sequence',
};
}
/** 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(),
};
}
/** 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;
}
/**
* KartaView Street Level provider: keyless coverage lines from KartaView's
* tile API, the photos nearest a clicked line, cones along the photo's
* sequence, and a flat or 360° viewer with ‹ › along the sequence.
* @param {{source?: ReturnType<typeof createKartaViewSource>, viewerOptions?: object}} [options]
* @returns {import('../../registry.js').StreetLevelProvider}
*/
export function createKartaViewProvider({
source = createKartaViewSource(),
viewerOptions = {},
} = {}) {
return Object.freeze({
id: KARTAVIEW_PROVIDER_ID,
name: KARTAVIEW_NAME,
label: KARTAVIEW_LABEL,
requiresKeyId: null,
pickPrefix: PICK_PREFIX.root,
colors: COLORS,
credit: Object.freeze({ html: KARTAVIEW_CREDIT_HTML }),
defaultOn: false,
// Coverage lines carry no date or projection: no filter could thin them.
filters: [],
coverageLabel: Object.freeze({
noun: COVERAGE_NOUN,
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);
const pages = createLru(PAGE_CACHE_SIZE);
/** The photo last opened in each sequence: its cones centre on it. */
const anchors = new Map();
/** The sequence page the cones were drawn from. */
let drawnPage = null;
function remember(record) {
const photo = normalizePhoto(record);
if (photo) photos.set(photo.id, photo);
return photo;
}
async function getPhoto(photoId, { signal } = {}) {
const cached = photos.get(photoId);
if (cached) return cached;
const photo = remember(await source.getPhoto(photoId, { signal }));
if (!photo) throw new Error('KartaView has no position for this photo');
return photo;
}
/** A page of a sequence's photos, in index order (shared while in flight). */
function loadPage(sequenceId, page) {
const key = `${sequenceId}:${page}`;
let entry = pages.get(key);
if (!entry) {
entry = source
.getSequencePhotos(sequenceId, {
page,
itemsPerPage: SEQUENCE_PAGE_SIZE,
})
.then(({ photos: records, hasMore }) => ({
page,
hasMore,
photos: records
.map(remember)
.filter(Boolean)
.sort(
(a, b) => (a.sequenceIndex ?? 0) - (b.sequenceIndex ?? 0),
),
}));
pages.set(key, entry);
entry.catch(() => pages.delete(key));
}
return entry;
}
/** The page holding `photo` (an earlier one when photos are missing). */
async function windowOf(photo) {
let page = pageOf(photo.sequenceIndex ?? 0);
for (let tries = 0; tries < 3; tries++) {
const window = await loadPage(photo.sequenceId, page);
const first = window.photos[0];
if (
window.photos.some((p) => p.id === photo.id) ||
page === 1 ||
!first ||
(first.sequenceIndex ?? 0) <= (photo.sequenceIndex ?? 0)
)
return window;
page--;
}
return loadPage(photo.sequenceId, page);
}
async function step(photo, delta) {
if (!photo?.sequenceId) return null;
const window = await windowOf(photo);
const list = window.photos;
let at = list.findIndex((p) => p.id === photo.id);
if (at === -1)
at = list.findIndex(
(p) => (p.sequenceIndex ?? 0) >= (photo.sequenceIndex ?? 0),
);
const next = at === -1 ? -1 : at + delta;
if (next >= 0 && next < list.length) return list[next].id;
if (next < 0 && window.page > 1) {
const before = await loadPage(photo.sequenceId, window.page - 1);
return before.photos.at(-1)?.id ?? null;
}
if (next >= list.length && window.hasMore) {
const after = await loadPage(photo.sequenceId, window.page + 1);
return after.photos[0]?.id ?? null;
}
return null;
}
const coverage = createLineCoverage({
state,
fetchTile: async (tile, { signal }) =>
decodeCoverageTile(await source.getTile(tile, { signal }), tile),
zoomFor: kartaViewZoomFor,
colors: COLORS,
pickPrefix: PICK_PREFIX.line,
renderKey: 'kartaview-coverage',
tuning: COVERAGE_TUNING,
messages: { rateLimited: RATE_LIMITED_MESSAGE, tooHigh: TOO_HIGH_HINT },
passes: () => true,
});
const cones = createSequenceCones({
state,
async loadImages(sequenceId, { signal }) {
const anchor = anchors.get(sequenceId);
if (!anchor) return [];
const window = await windowOf(anchor);
signal?.throwIfAborted();
drawnPage = { sequenceId, page: window.page };
return thinImages(
window.photos.map((photo) => ({
id: photo.id,
lon: photo.lon,
lat: photo.lat,
compassAngle: photo.heading ?? 0,
capturedAt: photo.capturedAt ?? 0,
isPano: photo.isPano,
})),
);
},
colors: COLORS,
pickPrefix: PICK_PREFIX.image,
spriteId: 'street-level:kartaview-cones',
renderKey: 'kartaview-sequence',
});
/** Re-centre the cones when ‹ › walked off the page they show. */
async function followStep(photoId) {
const photo = photos.get(photoId);
if (!photo?.sequenceId) return;
anchors.set(photo.sequenceId, photo);
if (drawnPage?.sequenceId !== photo.sequenceId) return;
const window = await windowOf(photo).catch(() => null);
if (window && window.page !== drawnPage.page)
cones.select(photo.sequenceId, { force: true });
}
const viewer = createKartaViewViewer({
getPhoto: async (photoId) => {
const photo = await getPhoto(photoId);
if (photo.sequenceId) anchors.set(photo.sequenceId, photo);
return photo;
},
step,
onStepped: followStep,
render: context.services?.render,
...viewerOptions,
});
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);
drawnPage = null;
},
destroy(cesiumViewer) {
coverage.detach();
coverage.clear();
coverage.resetErrors();
cones.destroy(cesiumViewer);
},
refreshCoverage: () => coverage.refresh(),
/** No filter applies (see `filters`). */
setFilter() {},
setSurface() {
coverage.setSurface();
cones.rerender();
},
coverageStats() {
const { hint } = state.coverage;
const count = coverage.sequenceCount();
return {
count,
zoom: state.coverage.zoom,
kind: state.coverage.kind,
loading: state.coverage.pending.size > 0,
hint: hint || '',
error: state.coverage.lastError,
keyRequired: false,
keyRejected: false,
};
},
/** A line opens the photo nearest the click; a cone opens its photo. */
handlePick(pickId, { groundPoint } = {}) {
if (pickId.startsWith(PICK_PREFIX.image)) {
context.actions.openImage(pickId.slice(PICK_PREFIX.image.length));
return true;
}
if (pickId.startsWith(PICK_PREFIX.line)) {
const point = groundPoint?.();
if (point) context.actions.openNearest(point);
return true;
}
return false;
},
selectSequence: (sequenceId) => cones.select(sequenceId),
clearSequence: () => {
cones.clearSelection();
drawnPage = null;
},
sequenceStats: () => ({
selectedId: state.sequence.selectedId,
images: state.sequence.images.length,
loading: state.sequence.loading,
}),
/** The nearest photo within the search radius, or null. */
async nearestImage({ lat, lon }, { signal } = {}) {
const records = await source.nearestPhotos({ lat, lon }, { signal });
let best = null;
for (const record of records) {
const photo = remember(record);
if (!photo) continue;
const metres = metresBetween({ lat, lon }, photo);
if (metres <= NEAREST_RADIUS_M && (!best || metres < best.metres))
best = { photo, metres };
}
return best ? best.photo.id : null;
},
viewer,
};
},
});
}
@@ -0,0 +1,213 @@
/**
* 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 };
function resize() {
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;
}
scheduleRender();
}
function draw() {
frame = 0;
if (gl.isContextLost()) return;
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);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGB, gl.RGB, gl.UNSIGNED_BYTE, image);
// 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;
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();
},
};
}
@@ -0,0 +1,37 @@
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,
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);
});
@@ -0,0 +1,203 @@
import { COLORS as SHARED_COLORS, PROVIDER_COLORS } from '../../policy.js';
export { NEAREST_RADIUS_M } from '../../policy.js';
/** Identity and tuning for the KartaView street-level provider (keyless). */
export const KARTAVIEW_PROVIDER_ID = 'kartaview';
export const KARTAVIEW_NAME = 'KartaView';
export const KARTAVIEW_LABEL = 'KARTAVIEW';
/**
* The public API. Its documented twin, api.openstreetcam.org, still answers
* but serves empty coverage tiles.
*/
export const KARTAVIEW_API_HOST = 'https://api.kartaview.org';
/** KartaView's image proxy: resizes a photo given its base64url address. */
export const KARTAVIEW_CDN_HOST = 'https://cdn.kartaview.org';
/** Stable id prefixes for picked primitives; every one starts with `kv:`. */
export const PICK_PREFIX = Object.freeze({
root: 'kv:',
line: 'kv:line:',
image: 'kv:img:',
});
export const COLORS = Object.freeze({
coverage: PROVIDER_COLORS.kartaview,
selected: SHARED_COLORS.selected,
});
/**
* Coverage lines are OSM ways with photos, from z13–14 JSON tiles. Lower
* zooms take seconds per tile (z10 does not answer), so higher up the panel
* asks the user to zoom in.
*/
export const COVERAGE_STREET_ZOOM_BELOW_M = 2_500;
export const COVERAGE_MAX_HEIGHT_M = 6_000;
export const COVERAGE_TUNING = Object.freeze({
maxTiles: 9,
overviewMaxTiles: 0,
// Chained ways are short: a dense z13 tile holds ~1,300.
maxSequences: 9_000,
lineWidthPx: 2.5,
overviewPointPx: 2.5,
moveDebounceMs: 320,
viewRangeMinM: 2_500,
viewRangePerHeight: 10,
viewNearM: 1_000,
});
export const TOO_HIGH_HINT = 'zoom in to see KartaView coverage';
export const RATE_LIMITED_MESSAGE =
'KartaView is rate-limiting requests — they resume on their own';
/**
* The photo API answers 429 to more than about three requests at once, so
* at most two are in flight; a 429 is retried after a short wait.
*/
export const PHOTO_API_CONCURRENCY = 2;
export const PHOTO_API_RETRIES = 3;
export const PHOTO_API_RETRY_BASE_MS = 800;
export const TILE_TIMEOUT_MS = 20_000;
export const PHOTO_API_TIMEOUT_MS = 15_000;
/** A photo download (tens of kilobytes to a few megabytes). */
export const IMAGE_TIMEOUT_MS = 30_000;
/** Photos asked for around a point; the API returns them nearest first. */
export const NEAREST_LIMIT = 10;
/** The photo API's search zoom: 18 searches the few tens of metres around the point. */
export const NEAREST_SEARCH_ZOOM = 18;
/**
* Photos of a sequence fetched at once, around the open one. Records are
* ~2 kB each, so a page is ~2 MB; the cones and prev/next use it.
*/
export const SEQUENCE_PAGE_SIZE = 1000;
/** Equirectangular panorama sizes: a quick preview, then the sharp one. */
export const PANO_PREVIEW_SIZE = Object.freeze([1024, 512]);
export const PANO_FULL_SIZE = Object.freeze([4096, 2048]);
/** A flat photo's sharp version, after the 1280 px one is on screen. */
export const FLAT_FULL_SIZE = Object.freeze([2560, 2560]);
/** On-globe credit: KartaView imagery is CC BY-SA 4.0 and needs attribution. */
export const KARTAVIEW_CREDIT_HTML =
'Street Level: imagery © <a href="https://kartaview.org" target="_blank" rel="noopener">KartaView</a> contributors, CC BY-SA 4.0';
/** The cone and coverage noun: a line is a street with photos, not a sequence. */
export const COVERAGE_NOUN = 'streets';
export const LINE_CLICK_HINT = 'click a line for its nearest photo';
/** Base64url of a string, as the image proxy reads addresses. */
function base64Url(text) {
const bytes = new TextEncoder().encode(text);
let binary = '';
for (const byte of bytes) binary += String.fromCharCode(byte);
return btoa(binary)
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
/** A photo resized by KartaView's image proxy to fit `width`×`height`. */
export function resizedImageUrl(url, [width, height]) {
if (!url) return null;
return `${KARTAVIEW_CDN_HOST}/pr:sharp/rs:fit:${width}:${height}/${base64Url(url)}`;
}
/** Epoch ms for a KartaView timestamp ('2016-02-19 15:28:18.000', UTC), or null. */
export function kartaViewTimeMs(value) {
const match =
/^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?/.exec(
String(value ?? ''),
);
if (!match) return null;
const [, y, mo, d, h = '0', mi = '0', s = '0'] = match;
if (Number(y) < 1990) return null;
const ms = Date.UTC(+y, +mo - 1, +d, +h, +mi, +s);
return Number.isFinite(ms) ? ms : null;
}
/** A coordinate pair as numbers; the road-matched one when KartaView has it. */
function positionOf(record) {
const matchLat = Number(record.matchLat);
const matchLon = Number(record.matchLng);
if (
Number.isFinite(matchLat) &&
Number.isFinite(matchLon) &&
(matchLat !== 0 || matchLon !== 0)
)
return { lat: matchLat, lon: matchLon };
return { lat: Number(record.lat), lon: Number(record.lng) };
}
const STORAGE_HOST = /^storage\d+$/;
/**
* A photo file's address. The API's `fileurl*` fields always name storage1,
* but a photo whose `storage` is another host (storage2…) is only there, so
* the address is built from `storage` and the relative `filepath*`.
*/
function fileUrl(record, pathKey, urlKey) {
const path = record[pathKey];
if (STORAGE_HOST.test(record.storage || '') && path)
return `https://${record.storage}.openstreetcam.org/files/photo/${path}`;
return record[urlKey] || null;
}
/** A storage URL with its `{{sizeprefix}}` placeholder filled. */
function sized(record, prefix) {
const url = fileUrl(record, 'filepath', 'fileurl') || '';
return url.includes('{{sizeprefix}}')
? url.replace('{{sizeprefix}}', prefix)
: null;
}
/**
* A photo API record in the shape the provider uses, or null without an id
* or a position.
* @returns {{id: string, sequenceId: string|null, sequenceIndex: number|null, lon: number, lat: number, heading: number|null, isPano: boolean, capturedAt: number|null, urls: {view: string|null, full: string|null, pano: string|null}}|null}
*/
export function normalizePhoto(record) {
if (!record || record.id == null) return null;
const { lat, lon } = positionOf(record);
if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
const heading =
record.heading === '' || record.heading == null
? NaN
: Number(record.heading);
const isPano =
record.projection === 'SPHERE' || Number(record.fieldOfView) >= 360;
const full =
fileUrl(record, 'filepathProc', 'fileurlProc') || sized(record, 'proc');
const index = Number(record.sequenceIndex);
return {
id: String(record.id),
sequenceId: record.sequenceId != null ? String(record.sequenceId) : null,
sequenceIndex: Number.isFinite(index) ? index : null,
lon,
lat,
heading: Number.isFinite(heading) ? heading : null,
isPano,
capturedAt:
kartaViewTimeMs(record.shotDate) ?? kartaViewTimeMs(record.dateAdded),
urls: {
// A 1280 px rendition; for a 360° photo it is the front view only.
view:
fileUrl(record, 'filepathLTh', 'fileurlLTh') ||
sized(record, 'lth') ||
full,
full,
// A 360° photo's equirectangular image ('wrapped_proc').
pano: isPano && /wrapped/.test(full || '') ? full : null,
},
};
}
/**
* Where the image link goes. KartaView's photo pages fail for signed-out
* visitors ("Sequence cannot be loaded"), so it is the full-size photo on
* KartaView's own storage.
*/
export function kartaViewPhotoUrl(photo) {
return photo?.urls?.full || photo?.urls?.view || 'https://kartaview.org';
}
@@ -0,0 +1,146 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {
kartaViewPhotoUrl,
kartaViewTimeMs,
normalizePhoto,
resizedImageUrl,
} from './policy.js';
/** A photo record as /2.0/photo returns it (trimmed to what is read). */
function record(overrides = {}) {
return {
id: '7102491',
sequenceId: '14010',
sequenceIndex: '950',
lat: '42.335712',
lng: '-83.048301',
matchLat: '42.335731506347656',
matchLng: '-83.04828643798828',
heading: '299.58',
fieldOfView: '0',
projection: 'PLANE',
shotDate: '2016-08-23 20:17:47.000',
dateAdded: '2016-08-24 04:01:07',
storage: 'storage1',
filepath: '2016/8/24/{{sizeprefix}}/14010_ba53c_57bd1d23d50b7.jpg',
filepathLTh: '2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
filepathProc: '2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
fileurl:
'https://storage1.openstreetcam.org/files/photo/2016/8/24/{{sizeprefix}}/14010_ba53c_57bd1d23d50b7.jpg',
fileurlLTh:
'https://storage1.openstreetcam.org/files/photo/2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
fileurlProc:
'https://storage1.openstreetcam.org/files/photo/2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
...overrides,
};
}
test('a photo record normalizes to numbers, the road-matched position and UTC capture time', () => {
const photo = normalizePhoto(record());
assert.equal(photo.id, '7102491');
assert.equal(photo.sequenceId, '14010');
assert.equal(photo.sequenceIndex, 950);
assert.equal(photo.lat, 42.335731506347656);
assert.equal(photo.lon, -83.04828643798828);
assert.equal(photo.heading, 299.58);
assert.equal(photo.isPano, false);
assert.equal(photo.capturedAt, Date.UTC(2016, 7, 23, 20, 17, 47));
assert.equal(photo.urls.pano, null);
});
test('photo files come from the storage host the record names, not the one its URLs say', () => {
// The API writes storage1 into every URL; this photo lives on storage2.
const photo = normalizePhoto(record({ storage: 'storage2' }));
assert.equal(
photo.urls.view,
'https://storage2.openstreetcam.org/files/photo/2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
);
assert.equal(
photo.urls.full,
'https://storage2.openstreetcam.org/files/photo/2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
);
assert.equal(kartaViewPhotoUrl(photo), photo.urls.full);
// An unexpected storage value falls back to the URLs as given.
const odd = normalizePhoto(record({ storage: 'https://evil.example' }));
assert.match(odd.urls.view, /^https:\/\/storage1\.openstreetcam\.org\//);
// No large thumbnail path: the size prefix fills in.
const bare = normalizePhoto(
record({ filepathLTh: '', fileurlLTh: '', storage: 'storage3' }),
);
assert.equal(
bare.urls.view,
'https://storage3.openstreetcam.org/files/photo/2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
);
});
test('a 360° photo keeps its equirectangular image; the unmatched position is the fallback', () => {
const photo = normalizePhoto(
record({
projection: 'SPHERE',
fieldOfView: '360',
matchLat: '0',
matchLng: '0',
storage: 'storage13',
filepathProc: '2022/10/6/wrapped_proc/6187609_626b8.jpg',
}),
);
assert.equal(photo.isPano, true);
assert.equal(photo.lat, 42.335712);
assert.equal(
photo.urls.pano,
'https://storage13.openstreetcam.org/files/photo/2022/10/6/wrapped_proc/6187609_626b8.jpg',
);
// A sphere without a wrapped image has nothing to project.
assert.equal(
normalizePhoto(record({ projection: 'SPHERE', fieldOfView: '360' })).urls
.pano,
null,
);
});
test('records without an id or a position are dropped; a missing heading is null', () => {
assert.equal(normalizePhoto(null), null);
assert.equal(normalizePhoto(record({ id: undefined })), null);
assert.equal(
normalizePhoto(
record({ lat: 'x', lng: 'y', matchLat: undefined, matchLng: undefined }),
),
null,
);
assert.equal(normalizePhoto(record({ heading: '' })).heading, null);
assert.equal(normalizePhoto(record({ heading: '0' })).heading, 0);
assert.equal(normalizePhoto(record({ heading: 'n/a' })).heading, null);
});
test('timestamps parse as UTC; years before 1990 and garbage are unknown', () => {
assert.equal(kartaViewTimeMs('2022-03-21'), Date.UTC(2022, 2, 21));
assert.equal(
kartaViewTimeMs('2022-03-21T06:42:59'),
Date.UTC(2022, 2, 21, 6, 42, 59),
);
assert.equal(kartaViewTimeMs('0000-00-00 00:00:00'), null);
assert.equal(kartaViewTimeMs(''), null);
assert.equal(kartaViewTimeMs(null), null);
const fallback = normalizePhoto(record({ shotDate: null }));
assert.equal(fallback.capturedAt, Date.UTC(2016, 7, 24, 4, 1, 7));
});
test('resized images go through the proxy with a base64url address', () => {
const url = resizedImageUrl(
'https://storage13.openstreetcam.org/files/photo/a?b=c+d',
[1024, 512],
);
const [, encoded] = /\/rs:fit:1024:512\/(.+)$/.exec(url);
assert.match(url, /^https:\/\/cdn\.kartaview\.org\/pr:sharp\/rs:fit:/);
assert.doesNotMatch(encoded, /[+/=]/);
const decoded = Buffer.from(
encoded.replace(/-/g, '+').replace(/_/g, '/'),
'base64',
).toString();
assert.equal(
decoded,
'https://storage13.openstreetcam.org/files/photo/a?b=c+d',
);
assert.equal(resizedImageUrl(null, [1, 1]), null);
});
@@ -0,0 +1,231 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createKartaViewProvider, kartaViewZoomFor } from './index.js';
import { SEQUENCE_PAGE_SIZE } from './policy.js';
import { validateProviders } from '../../registry.js';
import { fakeHost } from '../../../../testSupport/kartaViewFakes.mjs';
/** A photo record `metres` east of (42.3314, -83.0458), in sequence `seq` at `index`. */
function photoRecord(id, { metres = 0, seq = '14010', index = 0 } = {}) {
const lon = -83.0458 + metres / 82_300;
return {
id: String(id),
sequenceId: seq,
sequenceIndex: String(index),
lat: '42.3314',
lng: String(lon),
heading: '90',
projection: 'PLANE',
fieldOfView: '0',
shotDate: '2016-08-23 20:17:47.000',
storage: 'storage2',
filepathLTh: `2016/8/24/lth/${id}.jpg`,
filepathProc: `2016/8/24/proc/${id}.jpg`,
};
}
/** A source over `sequences` (id → indexes present), recording calls. */
function fakeSource({ nearest = [], sequences = {} } = {}) {
const calls = { nearest: 0, photo: [], pages: [] };
return {
calls,
getTile: async () => ({ lines: [] }),
nearestPhotos: async () => {
calls.nearest++;
return nearest;
},
getPhoto: async (id) => {
calls.photo.push(id);
for (const [seq, indexes] of Object.entries(sequences))
for (const index of indexes)
if (`${seq}-${index}` === id) return photoRecord(id, { seq, index });
throw new Error('KartaView has no such photo');
},
getSequencePhotos: async (seq, { page, itemsPerPage }) => {
calls.pages.push(`${seq}:${page}`);
const indexes = sequences[seq] || [];
const rows = indexes.slice(
(page - 1) * itemsPerPage,
page * itemsPerPage,
);
return {
photos: rows.map((index) =>
photoRecord(`${seq}-${index}`, { seq, index }),
),
hasMore: page * itemsPerPage < indexes.length,
};
},
};
}
function fakeContext() {
const actions = { opened: [], nearest: [] };
return {
actions,
context: {
services: {},
getFilter: () => ({ pano: 'all', sinceMs: null }),
isActive: () => true,
groundCaster: null,
meshSampler: null,
getSurface: () => 'draped',
notify() {},
actions: {
openImage: (id) => actions.opened.push(id),
openNearest: (point) => actions.nearest.push(point),
reportError() {},
},
},
};
}
function setup(sourceOptions) {
const source = fakeSource(sourceOptions);
const loads = [];
const definition = createKartaViewProvider({
source,
viewerOptions: {
load: async (url) => {
loads.push(url);
return { src: url };
},
createRenderer: () => {
throw new Error('no WebGL in Node');
},
},
});
const { context, actions } = fakeContext();
const instance = definition.create(context);
return { definition, instance, source, actions, loads };
}
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
test('KartaView registers keyless, off by default, with no filters and its own wording', () => {
const { definition } = setup();
assert.equal(definition.id, 'kartaview');
assert.equal(definition.requiresKeyId, null);
assert.equal(definition.defaultOn, false);
assert.deepEqual(definition.filters, []);
assert.match(
definition.credit.html,
/KartaView<\/a> contributors, CC BY-SA 4\.0/,
);
assert.equal(definition.colors.coverage, '#635bff');
assert.deepEqual(definition.coverageLabel, {
noun: 'streets',
action: 'click a line for its nearest photo',
});
// Its prefix fits beside the others.
validateProviders([
{ ...definition, id: 'mapillary', pickPrefix: 'mly:' },
{ ...definition, id: 'google', pickPrefix: 'gsv:' },
definition,
]);
});
test('coverage is drawn from z14 near the street and z13 a little higher; never from orbit', () => {
assert.deepEqual(kartaViewZoomFor(300), { zoom: 14, kind: 'sequence' });
assert.deepEqual(kartaViewZoomFor(2_500), { zoom: 14, kind: 'sequence' });
assert.deepEqual(kartaViewZoomFor(4_000), { zoom: 13, kind: 'sequence' });
assert.equal(kartaViewZoomFor(6_001), null);
assert.equal(kartaViewZoomFor(NaN), null);
});
test('the nearest photo is the closest within 50 m, and opening it asks nothing more', async () => {
const { instance, source, loads } = setup({
nearest: [
photoRecord('far', { metres: 80 }),
photoRecord('mid', { metres: 30 }),
photoRecord('near', { metres: 12 }),
],
});
const id = await instance.nearestImage({ lat: 42.3314, lon: -83.0458 });
assert.equal(id, 'near');
const host = fakeHost();
await instance.viewer.mount(host);
await instance.viewer.open(id);
assert.deepEqual(source.calls.photo, [], 'the lookup filled the cache');
assert.equal(
loads[0],
'https://storage2.openstreetcam.org/files/photo/2016/8/24/lth/near.jpg',
);
const none = setup({ nearest: [photoRecord('far', { metres: 80 })] });
assert.equal(
await none.instance.nearestImage({ lat: 42.3314, lon: -83.0458 }),
null,
);
});
test('a cone opens its photo; a line opens the photo nearest the click', () => {
const { instance, actions } = setup();
assert.equal(instance.handlePick('kv:img:123'), true);
assert.deepEqual(actions.opened, ['123']);
const point = { lon: -83.0458, lat: 42.3314 };
assert.equal(
instance.handlePick('kv:line:14/1/2/3', { groundPoint: () => point }),
true,
);
assert.deepEqual(actions.nearest, [point]);
// Over the sky the line is still ours, but there is nowhere to look.
assert.equal(
instance.handlePick('kv:line:14/1/2/3', { groundPoint: () => null }),
true,
);
assert.equal(actions.nearest.length, 1);
assert.equal(instance.handlePick('mly:seq:1'), false);
});
test('coverage stats report KartaView as configured and key-free', async () => {
const { instance } = setup();
assert.deepEqual(await instance.status(), { configured: true });
const stats = instance.coverageStats();
assert.equal(stats.keyRequired, false);
assert.equal(stats.keyRejected, false);
assert.equal(stats.count, 0);
});
test('› walks across sequence pages; ‹ walks back; the ends stop', async () => {
const size = SEQUENCE_PAGE_SIZE;
const indexes = Array.from({ length: size + 5 }, (_, i) => i);
const { instance, source } = setup({ sequences: { s: indexes } });
const host = fakeHost();
await instance.viewer.mount(host);
const poses = [];
instance.viewer.onPose((pose) => poses.push(pose.imageId));
const [, , prev, next] = host.children[0].children;
const press = async (button) => {
button.fire('click');
for (let i = 0; i < 6; i++) await settle();
};
await instance.viewer.open(`s-${size - 1}`);
await press(next);
assert.equal(poses.at(-1), `s-${size}`, 'onto the second page');
assert.deepEqual(source.calls.pages, ['s:1', 's:2']);
await press(prev);
assert.equal(poses.at(-1), `s-${size - 1}`);
await instance.viewer.open('s-0');
await press(prev);
assert.equal(poses.at(-1), 's-0', 'nothing before the first photo');
assert.equal(prev.disabled, true);
});
test('a page with missing photos is found by stepping back a page', async () => {
const size = SEQUENCE_PAGE_SIZE;
// Index `size + 100` sits on page 1 when 200 earlier photos are gone.
const indexes = Array.from({ length: size + 300 }, (_, i) => i).filter(
(i) => i < 100 || i >= 300,
);
const { instance, source } = setup({ sequences: { s: indexes } });
const host = fakeHost();
await instance.viewer.mount(host);
const poses = [];
instance.viewer.onPose((pose) => poses.push(pose.imageId));
const target = size + 100;
await instance.viewer.open(`s-${target}`);
const [, , , next] = host.children[0].children;
next.fire('click');
for (let i = 0; i < 8; i++) await settle();
assert.equal(poses.at(-1), `s-${target + 1}`);
assert.deepEqual(source.calls.pages.slice(0, 2), ['s:2', 's:1']);
});
@@ -0,0 +1,226 @@
import {
KARTAVIEW_API_HOST,
NEAREST_LIMIT,
NEAREST_SEARCH_ZOOM,
PHOTO_API_CONCURRENCY,
PHOTO_API_RETRIES,
PHOTO_API_RETRY_BASE_MS,
PHOTO_API_TIMEOUT_MS,
TILE_TIMEOUT_MS,
} from './policy.js';
/** An HTTP or API failure; `retryAfterSec` is set while KartaView rate-limits. */
export class KartaViewSourceError extends Error {
constructor(message, { status = 0, retryAfterSec = null } = {}) {
super(message);
this.name = 'KartaViewSourceError';
this.status = status;
this.retryAfterSec = retryAfterSec;
}
}
const NO_ANSWER = 'KartaView did not answer — check the network and try again';
/** Resolves after `ms`, or rejects when `signal` aborts first. */
function wait(ms, signal) {
return new Promise((resolve, reject) => {
if (signal?.aborted) return reject(signal.reason);
const timer = setTimeout(done, ms);
const onAbort = () => {
clearTimeout(timer);
reject(signal.reason);
};
signal?.addEventListener('abort', onAbort, { once: true });
function done() {
signal?.removeEventListener('abort', onAbort);
resolve();
}
});
}
/** Seconds from a Retry-After header, or null. */
function retryAfterSeconds(response) {
const header = response.headers?.get?.('retry-after');
const value = header == null || header === '' ? NaN : Number(header);
return Number.isFinite(value) && value >= 0 ? value : null;
}
/** A first-in, first-out gate letting at most `limit` tasks run at once. */
export function createLimiter(limit) {
let running = 0;
const queue = [];
function next() {
while (running < limit && queue.length) {
const { task, resolve, reject, signal } = 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).
* Coverage tiles are not rate-limited; photo lookups are, so they queue two
* at a time and retry a 429.
* @param {{fetchImpl?: typeof fetch, apiHost?: string, retryBaseMs?: number}} [options]
*/
export function createKartaViewSource({
fetchImpl = (...args) => globalThis.fetch(...args),
apiHost = KARTAVIEW_API_HOST,
retryBaseMs = PHOTO_API_RETRY_BASE_MS,
} = {}) {
const limiter = createLimiter(PHOTO_API_CONCURRENCY);
/** GET JSON within `timeoutMs`; the caller's abort wins over the timeout. */
async function getJson(url, { signal, timeoutMs }) {
const controller = new AbortController();
const onAbort = () => controller.abort(signal.reason);
if (signal?.aborted) throw signal.reason;
signal?.addEventListener('abort', onAbort, { once: true });
const timer = setTimeout(
() => controller.abort(new KartaViewSourceError(NO_ANSWER)),
timeoutMs,
);
try {
const response = await fetchImpl(url, { signal: controller.signal });
if (response.status === 429)
throw new KartaViewSourceError('KartaView is rate-limiting requests', {
status: 429,
retryAfterSec: retryAfterSeconds(response) ?? 2,
});
if (!response.ok)
throw new KartaViewSourceError(
`KartaView answered HTTP ${response.status}`,
{ status: response.status },
);
return await response.json();
} catch (error) {
if (signal?.aborted) throw signal.reason;
if (controller.signal.aborted) throw controller.signal.reason;
if (error instanceof KartaViewSourceError) throw error;
throw new KartaViewSourceError(NO_ANSWER);
} finally {
clearTimeout(timer);
signal?.removeEventListener('abort', onAbort);
}
}
/** A photo-API call through the limiter, retrying 429s with backoff. */
async function photoApi(path, params, { signal } = {}) {
const query = params ? `?${new URLSearchParams(params)}` : '';
const url = `${apiHost}${path}${query}`;
for (let attempt = 0; ; attempt++) {
try {
const payload = await limiter.run(
() => getJson(url, { signal, timeoutMs: PHOTO_API_TIMEOUT_MS }),
{ signal },
);
const code = Number(payload?.status?.apiCode);
// 600 ok, 601 empty, 602 partial: anything else is a refusal.
if (Number.isFinite(code) && (code < 600 || code > 603))
throw new KartaViewSourceError(
String(
payload?.status?.apiMessage || 'KartaView refused the request',
).trim(),
{ status: Number(payload?.status?.httpCode) || 0 },
);
return payload?.result ?? {};
} catch (error) {
if (error?.status !== 429 || attempt >= PHOTO_API_RETRIES) throw error;
await wait(
Math.max(
retryBaseMs * 2 ** attempt,
(error.retryAfterSec ?? 0) * 1000,
),
signal,
);
}
}
}
return {
/** A coverage tile: `{lines: [{track: [{lat, lng}]}]}`. */
async getTile({ x, y, z }, { signal } = {}) {
return getJson(`${apiHost}/2.0/sequence/tiles/${x}/${y}/${z}.json`, {
signal,
timeoutMs: TILE_TIMEOUT_MS,
});
},
/** Photo records around a point, nearest first. */
async nearestPhotos({ lat, lon }, { signal } = {}) {
const result = await photoApi(
'/2.0/photo/',
{
lat: lat.toFixed(7),
lng: lon.toFixed(7),
zoomLevel: String(NEAREST_SEARCH_ZOOM),
itemsPerPage: String(NEAREST_LIMIT),
},
{ signal },
);
return Array.isArray(result.data) ? result.data : [];
},
/** One photo record. */
async getPhoto(photoId, { signal } = {}) {
const result = await photoApi(
`/2.0/photo/${encodeURIComponent(photoId)}`,
null,
{ signal },
);
if (!result.data || typeof result.data !== 'object')
throw new KartaViewSourceError('KartaView has no such photo');
return result.data;
},
/** A page of a sequence's photos in capture order (1-based `page`). */
async getSequencePhotos(
sequenceId,
{ page, itemsPerPage },
{ signal } = {},
) {
const result = await photoApi(
`/2.0/sequence/${encodeURIComponent(sequenceId)}/photos`,
{ page: String(page), itemsPerPage: String(itemsPerPage) },
{ signal },
);
return {
photos: Array.isArray(result.data) ? result.data : [],
hasMore: result.hasMoreData === true,
};
},
};
}
@@ -0,0 +1,192 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import {
KartaViewSourceError,
createKartaViewSource,
createLimiter,
} from './source.js';
import { PHOTO_API_CONCURRENCY, PHOTO_API_RETRIES } from './policy.js';
const ok = (body) => ({
ok: true,
status: 200,
headers: new Map(),
json: async () => body,
});
const status = (code, headers = new Map()) => ({
ok: false,
status: code,
headers,
json: async () => ({}),
});
const photoPayload = (data) => ({
status: { apiCode: 600, httpCode: 200 },
result: { data, hasMoreData: false },
});
test('coverage tiles come from api.kartaview.org as JSON', async () => {
const urls = [];
const source = createKartaViewSource({
fetchImpl: async (url) => {
urls.push(url);
return ok({ lines: [] });
},
});
assert.deepEqual(await source.getTile({ x: 4412, y: 6061, z: 14 }), {
lines: [],
});
assert.deepEqual(urls, [
'https://api.kartaview.org/2.0/sequence/tiles/4412/6061/14.json',
]);
});
test('photo lookups run at most two at a time', async () => {
let running = 0;
let peak = 0;
const source = createKartaViewSource({
fetchImpl: async () => {
running++;
peak = Math.max(peak, running);
await new Promise((resolve) => setTimeout(resolve, 5));
running--;
return ok(photoPayload({ id: '1' }));
},
});
await Promise.all(
Array.from({ length: 7 }, (_, i) => source.getPhoto(String(i))),
);
assert.equal(peak, PHOTO_API_CONCURRENCY);
});
test('a 429 is retried after a wait, then answered', async () => {
let calls = 0;
const source = createKartaViewSource({
retryBaseMs: 1,
fetchImpl: async () => {
calls++;
return calls < 3
? status(429, new Map([['retry-after', '0']]))
: ok(photoPayload([{ id: '9' }]));
},
});
const records = await source.nearestPhotos({ lat: 42.3, lon: -83.04 });
assert.deepEqual(records, [{ id: '9' }]);
assert.equal(calls, 3);
});
test('rate-limiting that outlasts the retries is reported with a wait', async () => {
let calls = 0;
const source = createKartaViewSource({
retryBaseMs: 1,
fetchImpl: async () => {
calls++;
return status(429, new Map([['retry-after', '0.001']]));
},
});
await assert.rejects(source.getPhoto('1'), (error) => {
assert.ok(error instanceof KartaViewSourceError);
assert.equal(error.status, 429);
assert.ok(error.retryAfterSec > 0);
return true;
});
assert.equal(calls, PHOTO_API_RETRIES + 1);
});
test('an API refusal inside a 200 is an error with KartaView’s message; 601 is just empty', async () => {
const refusing = createKartaViewSource({
fetchImpl: async () =>
ok({
status: { apiCode: 612, apiMessage: ' out of range ', httpCode: 400 },
result: {},
}),
});
await assert.rejects(refusing.getPhoto('1'), /out of range/);
const empty = createKartaViewSource({
fetchImpl: async () =>
ok({ status: { apiCode: 601 }, result: { data: [] } }),
});
assert.deepEqual(await empty.nearestPhotos({ lat: 0, lon: 0 }), []);
const page = await empty.getSequencePhotos('2008', {
page: 2,
itemsPerPage: 1000,
});
assert.deepEqual(page, { photos: [], hasMore: false });
});
test('HTTP errors, network failures and non-JSON become readable errors', async () => {
const http = createKartaViewSource({ fetchImpl: async () => status(500) });
await assert.rejects(http.getTile({ x: 0, y: 0, z: 14 }), /HTTP 500/);
const offline = createKartaViewSource({
fetchImpl: async () => {
throw new TypeError('Failed to fetch');
},
});
await assert.rejects(offline.getPhoto('1'), /did not answer/);
const garbled = createKartaViewSource({
fetchImpl: async () => ({
ok: true,
status: 200,
headers: new Map(),
json: async () => {
throw new SyntaxError('Unexpected token <');
},
}),
});
await assert.rejects(
garbled.getTile({ x: 0, y: 0, z: 14 }),
/did not answer/,
);
});
test('an abort stops a queued lookup without fetching, and wins over a retry wait', async () => {
let calls = 0;
let release;
const gate = new Promise((resolve) => (release = resolve));
const source = createKartaViewSource({
retryBaseMs: 10_000,
fetchImpl: async (url) => {
calls++;
if (url.includes('/slow')) await gate;
return status(429);
},
});
// Two slow lookups fill the queue; the third waits for a slot.
const first = new AbortController();
const slow = [
source.getPhoto('slow', { signal: first.signal }),
source.getPhoto('slow', { signal: first.signal }),
];
const controller = new AbortController();
const queued = source.getPhoto('queued', { signal: controller.signal });
controller.abort(new Error('overtaken'));
await assert.rejects(queued, /overtaken/);
assert.equal(calls, 2, 'the queued lookup never fetched');
release();
// Each slow one is now waiting 10 s to retry; nothing else is asked.
const retrying = new AbortController();
const waiting = source.getPhoto('slow', { signal: retrying.signal });
await new Promise((resolve) => setTimeout(resolve, 20));
retrying.abort(new Error('closed'));
await assert.rejects(waiting, /closed/);
// The two first lookups are still waiting out their backoff: drop them.
first.abort(new Error('done'));
for (const promise of slow) await assert.rejects(promise, /done/);
});
test('the limiter runs tasks in order and keeps going after a failure', async () => {
const limiter = createLimiter(1);
const order = [];
const failing = limiter.run(async () => {
order.push('a');
throw new Error('a failed');
});
const second = limiter.run(async () => {
order.push('b');
return 'b';
});
await assert.rejects(failing, /a failed/);
assert.equal(await second, 'b');
assert.deepEqual(order, ['a', 'b']);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(limiter.pending, 0);
});
@@ -0,0 +1,422 @@
import {
createPanoramaRenderer,
PANO_FOV_DEFAULT_DEG,
wrapDegrees,
} from './panorama.js';
import {
FLAT_FULL_SIZE,
IMAGE_TIMEOUT_MS,
KARTAVIEW_PROVIDER_ID,
PANO_FULL_SIZE,
PANO_PREVIEW_SIZE,
kartaViewPhotoUrl,
resizedImageUrl,
} from './policy.js';
const LOAD_FAILED = 'The KartaView photo could not be loaded';
/** Load an image (CORS-clean, for WebGL) within the timeout. */
export function loadImage(
url,
{ crossOrigin = true, timeoutMs = IMAGE_TIMEOUT_MS } = {},
) {
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;
});
}
/**
* 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.
*
* @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.onStepped] A photo opened from ‹ ›, after its pose.
* @param {object} [options.render] Render governor.
* @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,
onStepped = () => {},
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 = [];
function requestRender() {
render?.governorRequestRender?.('kartaview-viewer');
}
function emit() {
if (!photo || !showing) return;
const view = showing === 'pano' ? renderer.getView() : null;
const heading = photo.heading;
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;
}
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;
}
/** Step along the sequence from the open photo. */
async function stepBy(delta) {
const from = photo;
if (!from?.sequenceId || !showing) return;
const seq = openSeq;
let nextId = null;
try {
nextId = await step(from, delta);
} catch {
nextId = null;
}
if (seq !== openSeq || photo !== from) return;
if (!nextId) {
const button = delta < 0 ? prevButton : nextButton;
if (button) button.disabled = true;
return;
}
try {
await adapter.open(nextId, { keepView: true });
} catch {
return;
}
if (photo?.id === nextId) onStepped(nextId);
}
function onPointerDown(event) {
if (showing !== 'pano' || event.button !== 0) return;
drag = {
id: event.pointerId,
x: event.clientX,
y: event.clientY,
view: renderer.getView(),
};
canvas.setPointerCapture?.(event.pointerId);
canvas.classList.add('sl-kv-dragging');
}
function onPointerMove(event) {
if (!drag || event.pointerId !== drag.id) 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) {
if (!drag || event.pointerId !== drag.id) return;
drag = null;
canvas.classList.remove('sl-kv-dragging');
}
function onWheel(event) {
if (showing !== 'pano') 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;
if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
event.preventDefault();
stepBy(event.key === 'ArrowLeft' ? -1 : 1);
}
}
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;
root = doc.createElement('div');
root.className = 'sl-kv-viewer';
root.tabIndex = 0;
root.setAttribute('role', 'group');
root.setAttribute(
'aria-label',
'KartaView photo. Drag to look around a 360° photo; ← and → step along the sequence',
);
picture = doc.createElement('img');
picture.className = 'sl-kv-photo';
picture.alt = 'KartaView street-level photo';
picture.draggable = false;
picture.hidden = true;
canvas = doc.createElement('canvas');
canvas.className = 'sl-kv-pano';
canvas.hidden = true;
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(canvas, 'pointerdown', onPointerDown);
listen(canvas, 'pointermove', onPointerMove);
listen(canvas, 'pointerup', onPointerUp);
listen(canvas, 'pointercancel', onPointerUp);
listen(canvas, 'wheel', onWheel, { passive: false });
listen(root, 'keydown', onKeyDown);
applyRenderMode();
}
function teardown() {
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 url =
kind === 'pano'
? resizedImageUrl(target.urls.pano, PANO_FULL_SIZE)
: resizedImageUrl(target.urls.full, FLAT_FULL_SIZE);
if (!url) return;
try {
const image = await load(url, { crossOrigin: kind === 'pano' });
if (seq !== openSeq || photo !== target || showing !== kind) return;
if (kind === 'pano') renderer.setImage(image);
else picture.src = image.src;
requestRender();
} catch {
/* the first version stays */
}
}
async function showPano(target, seq, keepView) {
const preview = resizedImageUrl(target.urls.pano, PANO_PREVIEW_SIZE);
let image;
try {
image = await load(preview, { crossOrigin: true });
} catch {
image = await load(resizedImageUrl(target.urls.pano, PANO_FULL_SIZE), {
crossOrigin: true,
});
}
if (seq !== openSeq) return false;
if (!keepView || showing !== 'pano')
renderer.setView({ yaw: 0, pitch: 0, fov: PANO_FOV_DEFAULT_DEG });
renderer.setImage(image);
photo = target;
show('pano');
return true;
}
async function showFlat(target, seq) {
let image;
try {
image = await load(target.urls.view, { crossOrigin: false });
} catch (error) {
// No 1280 px rendition: the proxy can shrink the full-size photo.
const fallback = resizedImageUrl(target.urls.full, FLAT_FULL_SIZE);
if (target.isPano || !fallback || seq !== openSeq) throw error;
image = await load(fallback, { crossOrigin: false });
}
if (seq !== openSeq) return false;
picture.src = image.src;
photo = target;
show('flat');
return true;
}
const adapter = {
async mount(host) {
if (!host) throw new Error('Street Level viewer has no host element');
if (root && root.parentNode === host) return;
teardown();
build(host);
},
/** Resolves once the photo is on screen and its pose was emitted. */
async open(imageId, { keepView = false } = {}) {
if (!root) throw new Error('KartaView viewer is not mounted');
const seq = ++openSeq;
const target = await getPhoto(String(imageId));
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();
upgrade(target, seq, showing);
},
close() {
openSeq++;
photo = null;
show(null);
if (picture) picture.removeAttribute('src');
renderer?.clear?.();
},
unmount() {
openSeq++;
teardown();
},
resize() {
renderer?.resize();
},
/** FIT / FILL frame a flat photo; a panorama has no frame to fit. */
supportsRenderModes: () => showing !== 'pano',
setRenderMode(mode) {
renderMode = mode === 'fill' ? 'fill' : 'letterbox';
applyRenderMode();
},
onPose(listener) {
listeners.add(listener);
return () => listeners.delete(listener);
},
};
return adapter;
}
@@ -0,0 +1,270 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { createKartaViewViewer } from './viewer.js';
import { fakeHost } from '../../../../testSupport/kartaViewFakes.mjs';
const PHOTOS = {
flat1: {
id: 'flat1',
sequenceId: 's1',
sequenceIndex: 1,
lon: -83.04,
lat: 42.33,
heading: 90,
isPano: false,
capturedAt: Date.UTC(2016, 7, 23),
urls: {
view: 'https://storage2.openstreetcam.org/lth/a.jpg',
full: 'https://storage2.openstreetcam.org/proc/a.jpg',
pano: null,
},
},
flat2: {
id: 'flat2',
sequenceId: 's1',
sequenceIndex: 2,
lon: -83.0401,
lat: 42.33,
heading: 92,
isPano: false,
capturedAt: Date.UTC(2016, 7, 23),
urls: {
view: 'https://storage2.openstreetcam.org/lth/b.jpg',
full: 'https://storage2.openstreetcam.org/proc/b.jpg',
pano: null,
},
},
pano1: {
id: 'pano1',
sequenceId: 's2',
sequenceIndex: 7,
lon: 106.84,
lat: -6.19,
heading: 150,
isPano: true,
capturedAt: Date.UTC(2022, 2, 21),
urls: {
view: 'https://storage13.openstreetcam.org/lth/p.jpg',
full: 'https://storage13.openstreetcam.org/wrapped_proc/p.jpg',
pano: 'https://storage13.openstreetcam.org/wrapped_proc/p.jpg',
},
},
};
function fakeRenderer() {
const view = { yaw: 0, pitch: 0, fov: 80 };
return {
images: [],
setImage(image) {
this.images.push(image.src);
},
setView(next) {
Object.assign(view, next);
},
getView: () => ({ ...view }),
resize() {},
clear() {},
destroy() {
this.destroyed = true;
},
};
}
function setup({ failLoads = [], rendererThrows = false, steps = {} } = {}) {
const loads = [];
const renderers = [];
const stepped = [];
const viewer = createKartaViewViewer({
getPhoto: async (id) => {
if (!PHOTOS[id]) throw new Error('no such photo');
return PHOTOS[id];
},
step: async (photo, delta) => steps[`${photo.id}:${delta}`] ?? null,
onStepped: (id) => stepped.push(id),
load: async (url, options) => {
loads.push({ url, crossOrigin: options?.crossOrigin });
if (failLoads.some((part) => url.includes(part)))
throw new Error('The KartaView photo could not be loaded');
return { src: url };
},
createRenderer: () => {
if (rendererThrows) throw new Error('WebGL is unavailable');
const renderer = fakeRenderer();
renderers.push(renderer);
return renderer;
},
});
const poses = [];
viewer.onPose((pose) => poses.push(pose));
const host = fakeHost();
return { viewer, poses, host, loads, renderers, stepped };
}
const parts = (host) => {
const root = host.children[0];
const [picture, canvas, prev, next] = root.children;
return { root, picture, canvas, prev, next };
};
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
test('a flat photo shows its 1280 px version, then the sharp one, with a pose facing its heading', async () => {
const { viewer, poses, host, loads } = setup();
await viewer.mount(host);
const { picture, canvas, prev, next } = parts(host);
assert.equal(prev.disabled, true, 'nothing to step through yet');
await viewer.open('flat1');
assert.equal(picture.hidden, false);
assert.equal(canvas.hidden, true);
assert.equal(prev.disabled, false);
assert.equal(next.disabled, false);
const pose = poses.at(-1);
assert.deepEqual(
{
providerId: pose.providerId,
imageId: pose.imageId,
position: pose.position,
bearing: pose.bearing,
tilt: pose.tilt,
isPano: pose.isPano,
sequenceId: pose.sequenceId,
capturedAt: pose.capturedAt,
title: pose.title,
},
{
providerId: 'kartaview',
imageId: 'flat1',
position: { lon: -83.04, lat: 42.33 },
bearing: 90,
tilt: 0,
isPano: false,
sequenceId: 's1',
capturedAt: Date.UTC(2016, 7, 23),
title: null,
},
);
assert.equal(pose.externalUrl, PHOTOS.flat1.urls.full);
assert.equal(loads[0].url, PHOTOS.flat1.urls.view);
assert.equal(loads[0].crossOrigin, false, 'an <img> needs no CORS');
await settle();
assert.match(
loads[1].url,
/^https:\/\/cdn\.kartaview\.org\/.*rs:fit:2560:2560/,
);
assert.equal(picture.src, loads[1].url, 'upgraded to the sharp version');
assert.equal(viewer.supportsRenderModes(), true);
viewer.setRenderMode('fill');
assert.equal(picture.style.objectFit, 'cover');
});
test('a missing 1280 px rendition falls back to the proxy-shrunk full photo', async () => {
const { viewer, host, loads } = setup({ failLoads: ['/lth/'] });
await viewer.mount(host);
await viewer.open('flat1');
assert.match(loads[1].url, /rs:fit:2560:2560/);
assert.equal(parts(host).picture.hidden, false);
});
test('a 360° photo shows on the panorama, preview first; dragging turns the bearing', async () => {
const { viewer, poses, host, loads, renderers } = setup();
await viewer.mount(host);
await viewer.open('pano1');
const { picture, canvas } = parts(host);
assert.equal(canvas.hidden, false);
assert.equal(picture.hidden, true);
assert.match(loads[0].url, /rs:fit:1024:512/);
assert.equal(loads[0].crossOrigin, true, 'WebGL textures need CORS');
assert.equal(poses.at(-1).isPano, true);
assert.equal(poses.at(-1).bearing, 150);
assert.equal(viewer.supportsRenderModes(), false, 'no frame to fit');
await settle();
assert.match(renderers[0].images.at(-1), /rs:fit:4096:2048/);
// Drag left by a quarter of the width: the view turns right.
const frames = [];
globalThis.requestAnimationFrame = (callback) => {
frames.push(callback);
return frames.length;
};
try {
canvas.fire('pointerdown', {
button: 0,
pointerId: 1,
clientX: 200,
clientY: 100,
});
canvas.fire('pointermove', { pointerId: 1, clientX: 100, clientY: 100 });
canvas.fire('pointerup', { pointerId: 1 });
frames.forEach((callback) => callback());
} finally {
delete globalThis.requestAnimationFrame;
}
const turned = poses.at(-1).bearing;
assert.ok(turned > 150 && turned < 360, `bearing ${turned} turned right`);
});
test('without WebGL, or when the panorama fails, a 360° photo shows its front view', async () => {
const noGl = setup({ rendererThrows: true });
await noGl.viewer.mount(noGl.host);
await noGl.viewer.open('pano1');
assert.equal(parts(noGl.host).picture.hidden, false);
assert.equal(noGl.loads[0].url, PHOTOS.pano1.urls.view);
assert.equal(noGl.poses.at(-1).isPano, false);
await settle();
assert.equal(
noGl.loads.length,
1,
'the equirectangular image never replaces it',
);
const broken = setup({ failLoads: ['cdn.kartaview.org'] });
await broken.viewer.mount(broken.host);
await broken.viewer.open('pano1');
assert.equal(parts(broken.host).picture.hidden, false);
assert.equal(broken.poses.at(-1).imageId, 'pano1');
});
test('‹ › and the arrow keys step along the sequence; the end disables the button', async () => {
const { viewer, poses, host, stepped } = setup({
steps: { 'flat1:1': 'flat2' },
});
await viewer.mount(host);
await viewer.open('flat1');
const { root, prev, next } = parts(host);
next.fire('click');
await settle();
await settle();
assert.equal(poses.at(-1).imageId, 'flat2');
assert.deepEqual(stepped, ['flat2']);
root.fire('keydown', { key: 'ArrowRight' });
await settle();
await settle();
assert.equal(next.disabled, true, 'flat2 is the last photo');
root.fire('keydown', { key: 'ArrowLeft', metaKey: true });
await settle();
assert.equal(poses.at(-1).imageId, 'flat2', 'modified arrows are not ours');
assert.equal(prev.disabled, false);
});
test('a newer open wins; close hides the photo; unmount tears down the panorama', async () => {
const { viewer, poses, host, renderers } = setup();
await viewer.mount(host);
const first = viewer.open('pano1');
const second = viewer.open('flat1');
await Promise.all([first, second]);
assert.deepEqual(
poses.map((pose) => pose.imageId),
['flat1'],
'the overtaken panorama never posed',
);
assert.equal(renderers.length, 0, 'nor built a WebGL context');
await viewer.open('pano1');
viewer.close();
const { picture, canvas, root } = parts(host);
assert.equal(canvas.hidden, true);
assert.equal(picture.hidden, true);
assert.equal(root.dataset.kind, '');
await assert.rejects(viewer.open('nope'), /no such photo/);
viewer.unmount();
assert.equal(host.children.length, 0);
assert.equal(renderers[0].destroyed, true);
await assert.rejects(viewer.open('flat1'), /not mounted/);
});