mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-18 17:22:19 +00:00
Trim the doc text this PR adds (README, CHANGELOG, CURRENT-STATE, KNOWN-ISSUES, SECURITY, DATA_SOURCES, .env.example, the CI job comment), drop code comments that restate the code, cut design-note JSDoc to a line or two, and drop review tags from test names. Comments only; no code changes. Also: README key count (seven keys, two metered), CURRENT-STATE's gate paragraph (CI runs a production build with a dummy token), the stacked doc above meshBoxInRange and the orphaned inMeshRange line in coverage.js, and a duplicate ALPR row in DATA_SOURCES that a merge had brought back. Co-Authored-By: Claude Opus 5.5 <[email protected]>
232 lines
6.8 KiB
JavaScript
232 lines
6.8 KiB
JavaScript
import { MAPILLARY_PROVIDER_ID, mapillaryImageUrl } from './policy.js';
|
|
|
|
/**
|
|
* Viewer adapter: lazy-loads MapillaryJS into the core's host and emits a
|
|
* provider-neutral pose on every image, view or position change.
|
|
* @returns {import('../../registry.js').ViewerAdapter}
|
|
*/
|
|
export function createMapillaryViewer({ source, render } = {}) {
|
|
let viewer = null;
|
|
let Library = null;
|
|
let container = null;
|
|
let pendingOpen = null;
|
|
let prewarming = null;
|
|
/** In-flight viewer construction, so pre-warm and open never build two. */
|
|
let creating = null;
|
|
/** Bumped by `unmount`, so a construction it overtook builds nothing. */
|
|
let generation = 0;
|
|
let renderMode = 'letterbox';
|
|
/** Metadata of the image on screen; pov/position events reuse it. */
|
|
let current = null;
|
|
const listeners = new Set();
|
|
|
|
function requestRender() {
|
|
render?.governorRequestRender?.('mapillary-viewer');
|
|
}
|
|
|
|
function libraryRenderMode(mode) {
|
|
const { RenderMode } = Library || {};
|
|
if (!RenderMode) return undefined;
|
|
return mode === 'fill' ? RenderMode.Fill : RenderMode.Letterbox;
|
|
}
|
|
|
|
async function ensureLibrary() {
|
|
if (Library) return Library;
|
|
// Lazy CSS: Vite applies it before the import resolves, so the viewer is
|
|
// styled from its first frame without ~90 KB of render-blocking CSS.
|
|
const [library] = await Promise.all([
|
|
import('mapillary-js'),
|
|
import('mapillary-js/dist/mapillary.css'),
|
|
]);
|
|
Library = library;
|
|
return Library;
|
|
}
|
|
|
|
function emit(pose) {
|
|
for (const listener of [...listeners]) {
|
|
try {
|
|
listener(pose);
|
|
} catch {
|
|
/* listener errors are the core's to log */
|
|
}
|
|
}
|
|
}
|
|
|
|
/** Read MapillaryJS image metadata into the neutral pose shape. */
|
|
function describe(image) {
|
|
return {
|
|
imageId: String(image.id),
|
|
isPano: image.cameraType === 'spherical',
|
|
capturedAt: image.capturedAt ?? null,
|
|
sequenceId: image.sequenceId ?? null,
|
|
altitude: Number.isFinite(image.computedAltitude)
|
|
? image.computedAltitude
|
|
: Number.isFinite(image.originalAltitude)
|
|
? image.originalAltitude
|
|
: null,
|
|
creator: image.creatorUsername || null,
|
|
};
|
|
}
|
|
|
|
async function publishPose(image) {
|
|
if (!viewer) return;
|
|
try {
|
|
const [lngLat, pov] = await Promise.all([
|
|
viewer.getPosition(),
|
|
viewer.getPointOfView(),
|
|
]);
|
|
// Closed (or never opened) while the pose was in flight: a late
|
|
// `image` event must not bring the photo back.
|
|
if (pendingOpen === null) return;
|
|
if (image) current = describe(image);
|
|
if (!current || !viewer) return;
|
|
emit({
|
|
providerId: MAPILLARY_PROVIDER_ID,
|
|
...current,
|
|
position: { lon: lngLat.lng, lat: lngLat.lat },
|
|
bearing: Number.isFinite(pov?.bearing) ? pov.bearing : null,
|
|
tilt: Number.isFinite(pov?.tilt) ? pov.tilt : 0,
|
|
externalUrl: mapillaryImageUrl(current.imageId),
|
|
});
|
|
requestRender();
|
|
} catch {
|
|
/* viewer torn down mid-flight */
|
|
}
|
|
}
|
|
|
|
function ensureViewer(host) {
|
|
if (viewer && container === host) return viewer;
|
|
if (creating?.container === host) return creating.promise;
|
|
const promise = createViewer(host).finally(() => {
|
|
if (creating?.promise === promise) creating = null;
|
|
});
|
|
creating = { container: host, promise };
|
|
return promise;
|
|
}
|
|
|
|
async function createViewer(host) {
|
|
const built = generation;
|
|
destroyViewer();
|
|
const { Viewer } = await ensureLibrary();
|
|
// Unmounted (layer off) while the library loaded: a viewer built now
|
|
// would hold a WebGL context nobody releases.
|
|
if (built !== generation) throw new Error('Mapillary viewer was unmounted');
|
|
viewer = new Viewer({
|
|
accessToken: source.token,
|
|
container: host,
|
|
component: {
|
|
cover: false,
|
|
bearing: true,
|
|
zoom: true,
|
|
attribution: true,
|
|
},
|
|
// The panel's ResizeObserver resizes the viewer, and skips it while it
|
|
// is hidden (0x0); MapillaryJS's own window tracking would resize a
|
|
// hidden viewer and ask for a tile at z=NaN.
|
|
trackResize: false,
|
|
renderMode: libraryRenderMode(renderMode),
|
|
});
|
|
container = host;
|
|
viewer.on('image', (event) => publishPose(event.image));
|
|
viewer.on('pov', () => publishPose(null));
|
|
viewer.on('position', () => publishPose(null));
|
|
return viewer;
|
|
}
|
|
|
|
function destroyViewer() {
|
|
if (viewer) {
|
|
try {
|
|
viewer.remove();
|
|
} catch {
|
|
/* already removed */
|
|
}
|
|
}
|
|
viewer = null;
|
|
container = null;
|
|
current = null;
|
|
}
|
|
|
|
return {
|
|
async mount(host) {
|
|
if (!host) throw new Error('Street Level viewer has no host element');
|
|
await ensureViewer(host);
|
|
},
|
|
|
|
/** Resolves once the image is on screen and its first pose was emitted. */
|
|
async open(imageId) {
|
|
const id = String(imageId);
|
|
if (!container) throw new Error('Mapillary viewer is not mounted');
|
|
pendingOpen = id;
|
|
const instance = await ensureViewer(container);
|
|
if (pendingOpen !== id) return;
|
|
const image = await instance.moveTo(id);
|
|
if (pendingOpen !== id) return;
|
|
await publishPose(image);
|
|
},
|
|
|
|
close() {
|
|
pendingOpen = null;
|
|
current = null;
|
|
// A playing sequence would keep stepping through (and downloading)
|
|
// images in the hidden viewer.
|
|
try {
|
|
viewer?.getComponent('sequence')?.stop();
|
|
} catch {
|
|
/* sequence component not available */
|
|
}
|
|
},
|
|
|
|
unmount() {
|
|
pendingOpen = null;
|
|
// The next mount builds afresh rather than joining a stale build.
|
|
generation++;
|
|
creating = null;
|
|
destroyViewer();
|
|
},
|
|
|
|
resize() {
|
|
try {
|
|
viewer?.resize();
|
|
} catch {
|
|
/* no-op */
|
|
}
|
|
},
|
|
|
|
/** Build the viewer ahead of the first image. Safe to call repeatedly. */
|
|
async prewarm(host) {
|
|
if (!host) return;
|
|
// An in-flight prewarm may give up (layer toggled mid-download): wait
|
|
// for it, then build if it did not.
|
|
if (prewarming) await prewarming;
|
|
if (viewer) return;
|
|
const run = (async () => {
|
|
try {
|
|
await ensureLibrary();
|
|
if (!viewer) await ensureViewer(host);
|
|
} catch {
|
|
/* the real open reports errors */
|
|
}
|
|
})();
|
|
prewarming = run;
|
|
await run;
|
|
if (prewarming === run) prewarming = null;
|
|
},
|
|
|
|
/** Show the whole image ('letterbox') or crop it to the frame ('fill'). */
|
|
setRenderMode(mode) {
|
|
renderMode = mode === 'fill' ? 'fill' : 'letterbox';
|
|
try {
|
|
const value = libraryRenderMode(renderMode);
|
|
if (viewer && value !== undefined) viewer.setRenderMode(value);
|
|
} catch {
|
|
/* viewer not ready */
|
|
}
|
|
},
|
|
|
|
onPose(listener) {
|
|
listeners.add(listener);
|
|
return () => listeners.delete(listener);
|
|
},
|
|
};
|
|
}
|