Merge upstream/main (KartaView #1121 merged) into pr/panoramax

KartaView's later viewer changes are carried into the shared
photoViewer.js: the camera bearing (`bearingOf`), redrawing the same
photo after a GPU reset through `onReopen`, no pose while a lost context
recovers, the 2,560 px flat version only once the viewer outgrows
1,280 px, `refreshPose`, and one sharper-panorama load at a time with a
second look once it lands. Its tile cache's `keyOf` and `clear` move to
the shared tileCache.js. KartaView gets `onEscape` beside `onReopen`.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Said TurkseverandClaude Opus 5.5 committed 2026-10-14 15:52:21 +01:00
commit da0d370fa3
43 files changed
+3299 -178

No files matched your search

@@ -6,6 +6,7 @@ import {
kartaViewZoomFor,
} from './index.js';
import {
FILTERED_OUT_MESSAGE,
NO_COVERAGE_HINT,
SEQUENCE_PAGE_SIZE,
TOO_HIGH_HINT,
@@ -36,13 +37,23 @@ function photoRecord(id, { metres = 0, seq = '14010', index = 0 } = {}) {
};
}
/** KartaView's shotDate for `ms` ago. */
const shotAgo = (ms) =>
new Date(Date.now() - ms).toISOString().replace('T', ' ').slice(0, 23);
/**
* A source over `sequences` (id → indexes present, in page order: KartaView
* pages follow photo ids, which only roughly follow the index), recording
* calls. Photos whose id is in `archived` answer 409.
*/
function fakeSource({ nearest = [], sequences = {}, archived = [] } = {}) {
const calls = { nearest: 0, photo: [], pages: [], probes: [] };
const calls = {
nearest: 0,
nearestFilters: [],
photo: [],
pages: [],
probes: [],
};
return {
calls,
probeImage: async (url) => {
@@ -50,8 +61,9 @@ function fakeSource({ nearest = [], sequences = {}, archived = [] } = {}) {
return !archived.some((id) => url.includes(`/${id}.jpg`));
},
getTile: async () => ({ lines: [] }),
nearestPhotos: async () => {
nearestPhotos: async ({ filter }) => {
calls.nearest++;
calls.nearestFilters.push(filter);
return nearest;
},
getPhoto: async (id) => {
@@ -80,12 +92,13 @@ function fakeSource({ nearest = [], sequences = {}, archived = [] } = {}) {
}
function fakeContext({ filter = { pano: 'all', sinceMs: null } } = {}) {
const actions = { opened: [], nearest: [], instance: null };
// `actions.filter` is the resolved filter now; a test may change it.
const actions = { opened: [], nearest: [], instance: null, filter };
return {
actions,
context: {
services: {},
getFilter: () => filter,
getFilter: () => actions.filter,
isActive: () => true,
groundCaster: null,
meshSampler: null,
@@ -105,11 +118,12 @@ function fakeContext({ filter = { pano: 'all', sinceMs: null } } = {}) {
};
}
function setup(sourceOptions, contextOptions) {
function setup(sourceOptions, contextOptions, { readMask } = {}) {
const source = fakeSource(sourceOptions);
const loads = [];
const definition = createKartaViewProvider({
source,
readMask,
viewerOptions: {
load: async (url) => {
loads.push(url);
@@ -128,12 +142,17 @@ function setup(sourceOptions, contextOptions) {
const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
test('KartaView registers keyless, off by default, with no filters and its own wording', () => {
test('KartaView registers keyless, off by default, with Mapillary’s 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.deepEqual(definition.filters, ['pano', 'since']);
assert.equal(
definition.sinceBasis,
'upload',
'SINCE is KartaView’s upload date',
);
assert.equal(
definition.highlightsSequence,
false,
@@ -195,6 +214,46 @@ test('the nearest photo is the closest within 50 m, and opening it asks nothing
);
});
test('the nearest photo passes the imagery filter by its upload date, as KartaView filters; none passing says so', async () => {
const since = Date.now() - 86_400_000;
const filter = { pano: 'pano', sinceMs: since };
const pano = (id, metres, uploaded) => ({
...photoRecord(id, { metres }),
projection: 'SPHERE',
fieldOfView: '360',
shotDate: '2016-08-23 20:17:47.000',
dateAdded: uploaded,
});
// Both taken in 2016; only the second was uploaded since yesterday.
const { instance, source } = setup(
{
nearest: [
pano('stale', 5, '2016-08-24 04:01:07'),
pano('fresh', 20, shotAgo(3_600_000).slice(0, 19)),
],
},
{ filter },
);
const at = { lat: 42.3314, lon: -83.0458 };
assert.equal(await instance.nearestImage(at), 'fresh');
assert.deepEqual(source.calls.nearestFilters, [filter]);
const stale = setup(
{ nearest: [pano('stale', 5, '2016-08-24 04:01:07')] },
{ filter },
);
await assert.rejects(stale.instance.nearestImage(at), {
message: FILTERED_OUT_MESSAGE,
});
// Uploaded earlier on the cut-off's UTC day: KartaView's startDate keeps
// it, and so does the check.
const day = new Date(since).toISOString().slice(0, 10);
const sameDay = setup(
{ nearest: [pano('early', 5, `${day} 00:00:01`)] },
{ filter },
);
assert.equal(await sameDay.instance.nearestImage(at), 'early');
});
test('a cone opens its photo; a line opens the photo nearest the click', () => {
const { instance, actions } = setup();
actions.instance = null;
@@ -617,34 +676,73 @@ test('the cones re-centre when ‹ › walk off the page they were drawn from',
);
});
test('a leftover imagery filter hides no cones: flat, undated photos still draw', async (t) => {
test('the imagery filter thins the cones by each photo’s upload date and projection', async (t) => {
const env = await mounted(
{ sequences: { s: [0, 1, 2, 3] } },
{ filter: { pano: 'pano', sinceMs: Date.now() - 86_400_000 } },
);
// Undated records: no capture time to pass a "since" filter with.
const undated = (record) => ({ ...record, shotDate: '', dateAdded: '' });
// 0 and 1: 360° photos uploaded an hour ago (taken in 2016, as all);
// 2 and 3: flat ones uploaded in 2016.
const shaped = (record) =>
Number(record.sequenceIndex) < 2
? {
...record,
projection: 'SPHERE',
fieldOfView: '360',
dateAdded: shotAgo(3_600_000).slice(0, 19),
}
: { ...record, dateAdded: '2016-08-24 04:01:07' };
const getPhoto = env.source.getPhoto;
env.source.getPhoto = async (id) => undated(await getPhoto(id));
env.source.getPhoto = async (id) => shaped(await getPhoto(id));
const getPage = env.source.getSequencePhotos;
env.source.getSequencePhotos = async (...args) => {
const page = await getPage(...args);
return { ...page, photos: page.photos.map(undated) };
return { ...page, photos: page.photos.map(shaped) };
};
const cones = await withCones(t, env);
await env.instance.viewer.open('s-1');
await env.instance.selectSequence('s');
assert.ok(await until(() => !env.instance.sequenceStats().loading));
assert.equal(env.instance.sequenceStats().images, 4);
assert.equal(cones.count(), 4, 'every cone drawn');
assert.equal(env.instance.sequenceStats().images, 4, 'the drive is whole');
assert.equal(cones.count(), 2, 'the 360° photos uploaded since yesterday');
assert.deepEqual(cones(), [0, 1]);
env.actions.filter = { pano: 'flat', sinceMs: null };
env.instance.setFilter();
assert.deepEqual(cones(), [2, 3], 'the flat ones');
env.actions.filter = { pano: 'all', sinceMs: null };
env.instance.setFilter();
assert.equal(cones.count(), 4, 'every cone, unfiltered');
});
/**
* The provider drawing coverage on a stand-in viewer above one z14 tile.
* `lines` are the tile's tracks as [lon, lat] pairs; `getTile` may be held.
*/
function coverageSetup(t, { lines = [], filter, height = 900 } = {}) {
const env = setup({}, { filter });
function coverageSetup(
t,
{ lines = [], filter, height = 900, drawnRows = () => [] } = {},
) {
// A filtered tile's mask: 512 px square, drawn on the rows
// `drawnRows(query)` lists as [from, to].
const env = setup(
{},
{ filter },
{
readMask: async ({ query }) => {
const alpha = new Uint8Array(512 * 512);
for (const [from, to] of drawnRows(query))
alpha.fill(255, from * 512, (to + 1) * 512);
return { width: 512, height: 512, alpha };
},
},
);
const masks = [];
let maskHold = null;
env.source.getTileMask = async (tile, query) => {
masks.push(query);
await maskHold;
return { query };
};
const centre = tileCentre(-83.0458, 42.3314);
const viewer = coverageViewer(
{ lon: centre.lon, lat: centre.lat, height },
@@ -671,6 +769,15 @@ function coverageSetup(t, { lines = [], filter, height = 900 } = {}) {
viewer,
centre,
tiles,
masks,
holdMasks() {
let release;
maskHold = new Promise((resolve) => (release = resolve));
return () => {
maskHold = null;
release();
};
},
holdTiles() {
let release;
hold = new Promise((resolve) => (release = resolve));
@@ -682,20 +789,59 @@ function coverageSetup(t, { lines = [], filter, height = 900 } = {}) {
};
}
test('a leftover imagery filter hides no KartaView line', async (t) => {
const { instance, viewer, centre } = coverageSetup(t, {
filter: { pano: 'pano', sinceMs: Date.now() - 86_400_000 },
lines: [
[
[-83.0458 - 0.001, 42.3314],
[-83.0458 + 0.001, 42.3314],
],
],
test('a filter thins the lines to those its PNG mask draws; without one they all show', async (t) => {
const { lon, lat } = tileCentre(-83.0458, 42.3314);
// Across the tile's middle row (mask row ~256), and a quarter up (~130).
const across = (at) => [
[lon - 0.001, at],
[lon + 0.001, at],
];
const env = coverageSetup(t, {
filter: { pano: 'pano', sinceMs: null },
lines: [across(lat), across(lat + 0.004)],
// 360° photos lie on the middle line only.
drawnRows: (query) => (query === 'fieldOfView=360' ? [[254, 258]] : []),
});
assert.ok(centre);
instance.activate(viewer);
assert.ok(await until(() => instance.coverageStats().count === 1));
assert.equal(instance.coverageStats().hint, '');
env.instance.activate(env.viewer);
assert.ok(await until(() => env.instance.coverageStats().count === 1));
assert.deepEqual(env.masks, ['fieldOfView=360']);
// Unfiltered: every line, and the tile's lines are not asked for again.
env.actions.filter = { pano: 'all', sinceMs: null };
env.instance.setFilter();
assert.ok(await until(() => env.instance.coverageStats().count === 2));
assert.equal(env.tiles.length, 1, 'the segments are kept');
// SINCE a day: uploaded since yesterday (UTC) — none here. The lines
// drawn now stay on the globe while KartaView draws the filtered tile.
const since = Date.now() - 86_400_000;
const release = env.holdMasks();
env.actions.filter = { pano: 'all', sinceMs: since };
env.instance.setFilter();
assert.ok(await until(() => env.instance.coverageStats().loading));
assert.ok(
env.viewer.scene.groundPrimitives.items.size > 0,
'the unfiltered lines show meanwhile',
);
release();
assert.ok(
await until(
() =>
!env.instance.coverageStats().loading &&
env.instance.coverageStats().count === 0,
),
);
assert.equal(
env.masks.at(-1),
`startDate=${new Date(since).toISOString().slice(0, 10)}`,
);
assert.equal(env.instance.coverageStats().hint, NO_COVERAGE_HINT);
assert.ok(
await until(() => env.viewer.scene.groundPrimitives.items.size === 0),
'and go once it is in',
);
// The same filter again asks KartaView for nothing.
env.instance.setFilter();
for (let i = 0; i < 5; i++) await settle();
assert.equal(env.masks.length, 2);
});
test('coverage hints: zoom in from too high, “no photos” only once an empty view has loaded', async (t) => {
@@ -714,7 +860,7 @@ test('coverage hints: zoom in from too high, “no photos” only once an empty
assert.equal(env.instance.coverageStats().hint, NO_COVERAGE_HINT);
});
test('a coverage tile loaded a moment ago is not asked for again', async (t) => {
test('coverage tiles are kept while KartaView is on and dropped once it is switched off', async (t) => {
const env = coverageSetup(t, {
lines: [
[
@@ -725,11 +871,14 @@ test('a coverage tile loaded a moment ago is not asked for again', async (t) =>
});
env.instance.activate(env.viewer);
assert.ok(await until(() => env.instance.coverageStats().count === 1));
// Off and on again (or a pan away and back): drawn from the kept tile.
env.instance.refreshCoverage();
assert.ok(await until(() => env.instance.coverageStats().count === 1));
assert.equal(env.tiles.length, 1, 'kept while on');
// Switched off: the decoded lines are not kept, so on again asks again.
env.instance.deactivate();
env.instance.activate(env.viewer);
assert.ok(await until(() => env.instance.coverageStats().count === 1));
assert.equal(env.tiles.length, 1);
assert.equal(env.tiles.length, 2);
});
test('a photo no page lists steps to the photos either side of its index', async () => {
@@ -767,3 +916,214 @@ test('Esc in the docked viewer clears the selected drive and is consumed; with n
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) },
});
const asked = [];
env.source.getSequenceCount = async (id) => {
asked.push(id);
return 2385;
};
await withCones(t, env);
await env.instance.viewer.open('s-3');
await env.instance.selectSequence('s');
assert.ok(
await until(() => env.instance.sequenceStats().images === 2385),
`images: ${env.instance.sequenceStats().images}`,
);
// Asked once per drive.
env.instance.clearSequence();
await env.instance.viewer.open('s-30');
await env.instance.selectSequence('s');
assert.ok(await until(() => env.instance.sequenceStats().images === 2385));
assert.deepEqual(asked, ['s']);
});
test('after a GPU reset the photo is drawn again by the viewer, not through the core; a failure is reported', async () => {
const source = fakeSource();
const record = {
...photoRecord('pano', { seq: 'p', index: 0 }),
projection: 'SPHERE',
fieldOfView: '360',
filepathProc: '2022/10/6/wrapped_proc/pano.jpg',
};
source.getPhoto = async () => record;
const view = { yaw: 0, pitch: 0, fov: 80 };
let failLoads = false;
const definition = createKartaViewProvider({
source,
viewerOptions: {
load: async (url) => {
if (failLoads)
throw new Error('The KartaView photo could not be loaded');
return { src: url };
},
createRenderer: () => ({
setImage() {},
setView: (next) => Object.assign(view, next),
getView: () => ({ ...view }),
resize() {},
clear() {},
destroy() {},
}),
},
});
const { context, actions } = fakeContext();
const errors = [];
context.actions.reportError = (message) => errors.push(message);
const instance = definition.create(context);
actions.instance = instance;
const host = fakeHost();
await instance.viewer.mount(host);
const poses = [];
instance.viewer.onPose((pose) => poses.push(pose.imageId));
await instance.viewer.open('pano');
const canvas = () => host.children[0].children[1];
const kind = () => host.children[0].dataset.kind;
canvas().fire('webglcontextlost');
assert.equal(kind(), '', 'cleared while it is drawn again');
assert.ok(await until(() => kind() === 'pano'), 'drawn again');
assert.ok(poses.length >= 2);
assert.deepEqual(actions.opened, [], 'the core (and its lookup) left alone');
failLoads = true;
canvas().fire('webglcontextlost');
assert.ok(await until(() => errors.length === 1));
assert.match(errors[0], /could not be loaded/);
});
test('the marker is KartaView’s own cone, and it points along the drive, not at a wrong compass', async () => {
const env = setup({
sequences: { s: Array.from({ length: 10 }, (_, i) => i) },
});
assert.deepEqual(env.definition.marker, {
kind: 'view-cone',
color: '#635bff',
});
// Photos run east (photoRecord puts index i at 5·i m east); the compass says 200°.
const getPhoto = env.source.getPhoto;
env.source.getPhoto = async (id) => ({
...(await getPhoto(id)),
heading: '200',
});
const getPage = env.source.getSequencePhotos;
env.source.getSequencePhotos = async (...args) => {
const page = await getPage(...args);
return {
...page,
photos: page.photos.map((record) => ({ ...record, heading: '200' })),
};
};
const host = fakeHost();
await env.instance.viewer.mount(host);
const bearings = [];
env.instance.viewer.onPose((pose) => bearings.push(pose.bearing));
await env.instance.viewer.open('s-4');
assert.equal(bearings[0], 200, 'the compass until the drive is known');
assert.ok(
await until(() => Math.abs(bearings.at(-1) - 90) < 1),
`then along the drive: ${bearings}`,
);
});
/** Hold `seq`'s page `page` until the returned function is called. */
function holdPage(source, seq, page) {
const getPage = source.getSequencePhotos;
let release;
const gate = new Promise((resolve) => (release = resolve));
source.getSequencePhotos = async (id, options) => {
if (id === seq && options.page === page) await gate;
return getPage(id, options);
};
return () => release();
}
test('a photo opened while the cones first load is the one they centre on', async (t) => {
const size = SEQUENCE_PAGE_SIZE;
const env = await mounted({
sequences: { s: Array.from({ length: size * 5 }, (_, i) => i) },
});
const cones = await withCones(t, env);
const release = holdPage(env.source, 's', 1);
await env.instance.viewer.open('s-10');
const selected = env.instance.selectSequence('s');
// A line click further along the drive while page 1 is still loading:
// nothing is drawn yet for its re-centre to move.
await env.instance.viewer.open(`s-${size * 4 + 10}`);
release();
await selected;
assert.ok(
await until(
() => !env.instance.sequenceStats().loading && cones.count() > 0,
),
);
assert.ok(
cones()[0] <= size * 4 + 10 && cones()[1] >= size * 4 + 10,
`around the newer photo, not the first: ${cones()}`,
);
});
test('a sequence page that lands while a lost GPU context recovers still draws its cones', async (t) => {
const env = setup({ sequences: { p: [0, 1, 2, 3] } });
const sphere = (record) => ({
...record,
projection: 'SPHERE',
fieldOfView: '360',
filepathProc: `2022/10/6/wrapped_proc/${record.id}.jpg`,
});
const getPhoto = env.source.getPhoto;
env.source.getPhoto = async (id) => sphere(await getPhoto(id));
const getPage = env.source.getSequencePhotos;
env.source.getSequencePhotos = async (...args) => {
const page = await getPage(...args);
return { ...page, photos: page.photos.map(sphere) };
};
const release = holdPage(env.source, 'p', 1);
let holdImages = false;
let releaseImage = null;
const view = { yaw: 0, pitch: 0, fov: 80 };
const definition = createKartaViewProvider({
source: env.source,
viewerOptions: {
load: async (url) => {
if (holdImages) await new Promise((r) => (releaseImage = r));
return { src: url };
},
createRenderer: () => ({
setImage() {},
setView: (next) => Object.assign(view, next),
getView: () => ({ ...view }),
resize() {},
clear() {},
destroy() {},
}),
},
});
const { context, actions } = fakeContext();
const errors = [];
context.actions.reportError = (message) => errors.push(message);
const instance = definition.create(context);
actions.instance = instance;
const cones = await withCones(t, { instance });
const host = fakeHost();
await instance.viewer.mount(host);
await instance.viewer.open('p-0');
// › to the next panorama; the GPU resets while it loads.
holdImages = true;
const opening = instance.viewer.open('p-1');
assert.ok(await until(() => releaseImage !== null));
host.children[0].children[1].fire('webglcontextlost');
const selected = instance.selectSequence('p');
release();
await selected;
assert.ok(
await until(() => !instance.sequenceStats().loading && cones.count() > 0),
'the page is drawn, not dropped',
);
releaseImage();
await opening;
assert.equal(host.children[0].dataset.kind, 'pano', 'p-1 shows');
// reportError(null) clears; nothing was reported.
assert.deepEqual(errors.filter(Boolean), []);
});