Files
gods-eye-view/src/annotations/hybridAnnotationRenderer.js
T
Sameh Khamis a61d0f4c2a tighten the remaining voice outline review items
- One place-name key for server and tiles, so "St. Paul" and "Saint Paul"
  agree in Nominatim name checks.
- Tile street names: a lone letter is a direction only beside another name
  word ("E Street" is not "East Street"), and a trailing quadrant ("E St NW")
  may go unsaid in the ask.
- A building cut at the tile edge that is nearer the point than any whole
  one leaves the point instead of a farther neighbour standing in; an edge
  without a tile buffer counts as a cut, so a cut area never answers grounds.
- A batch building install re-judges only results that installed; a late
  timeout during caption conversion keeps the pending point drawn; a failed
  plain recaption keeps the old mark addressable.
- An interrupted Nominatim dispatch is reclaimed by the next lock owner ten
  minutes after the start its marker names; node:sqlite loads on first use
  without its experimental warning.
- PHOTON_URL accepts only https, which the page's connect-src allows.
- Shared OpenFreeMap tiles decode each layer when a consumer first selects
  it; outline selection reuses the shared ring area and simplification, and
  ground probes the shared ring centroid; the grounds word list lives once.
2026-11-02 08:50:05 -08:00

299 lines
11 KiB
JavaScript

import { recordWorkSlice } from '../sources/phaseTiming.js';
import { createWorldAnnotationRenderer } from './worldAnnotationRenderer.js';
import { createScreenAnnotationRenderer } from './screenAnnotationRenderer.js';
/**
* Hybrid annotation renderer (Direction C — the recommended production blend).
*
* Routes each mark to the renderer that does it best:
* - `area` footprints → WORLD-space, so the outline/fill drapes onto and
* conforms to the real 3D building/ground geometry (screen-space can only
* draw a flat polygon that ignores relief and building tops).
* - everything else (highlight / pin / arrow / label) → SCREEN-space SVG, for
* the hand-drawn "whiteboard" aesthetic: pulsing reticles, bowed arrows,
* and glassy callout cards with leader lines.
*
* The area's text label is also drawn as a SCREEN callout (the world drape is
* label-less) so every caption shares one consistent style.
*
* The hybrid surface honors add/update/remove/sync/destroy; update coordinates the
* one route change that spans both sub-renderers. `screen` passes options to the
* screen renderer (its store, in tests).
*/
export function createHybridAnnotationRenderer(
viewer,
{ screen: screenOptions } = {},
) {
const world = createWorldAnnotationRenderer(viewer);
const screen = createScreenAnnotationRenderer(viewer, screenOptions);
// anno.id -> { worldProxy?, screenProxy? } — proxies own the sub-renderer state.
const routed = new Map();
function add(anno, options = {}) {
const entry = {};
// Route the entry FIRST, then fill it in. A sub-renderer throw (WebGL loss
// mid-add) otherwise stranded whatever the earlier sub-renderer had already
// created: `routed` never learned the id, so remove() was a no-op and the
// engine's rollback could not reach the orphan — a re-annotate of the same
// geometry then stacked a second mark over it. Registered up front, the
// partial entry is addressable and remove() cleans exactly what exists.
routed.set(anno.id, entry);
if (anno.type === 'area' && anno.ring && anno.ring.length >= 3) {
// Drape the footprint in world space, but without its own label...
entry.worldProxy = liveProxy(anno, { label: null });
const completion = world.add(
entry.worldProxy,
worldOptions(anno, entry, options),
);
if (completion?.then) {
if (options.pendingVisible !== false) {
entry.screenProxy = liveProxy(anno, {
ring: null,
pendingOutline: true,
});
screen.add(entry.screenProxy);
}
return finishBuilding(anno, entry, completion, options);
}
// ...and place the caption as a screen-space callout at the centroid.
if (anno.label) {
entry.screenProxy = liveProxy(anno, { type: 'label', ring: null });
screen.add(entry.screenProxy);
}
} else if (
anno.type === 'route' &&
Array.isArray(anno.path) &&
anno.path.length >= 2
) {
// Drape the path on the tiles (world), caption it with a screen callout
// at the path midpoint.
entry.worldProxy = liveProxy(anno, { label: null });
world.add(entry.worldProxy);
if (anno.label) {
const mid = anno.path[Math.floor(anno.path.length / 2)];
entry.screenProxy = liveProxy(anno, {
type: 'label',
path: null,
anchor: { lon: mid.lon, lat: mid.lat, height: mid.height },
});
screen.add(entry.screenProxy);
}
} else {
entry.screenProxy = anno;
screen.add(anno);
}
}
/**
* Upgrade a pending area without replacing its existing screen-space group.
* World geometry is new, but the reticle's SVG group is converted in place to
* the centroid callout so there is no overlapping fade-out/fade-in pair.
*/
function update(anno, options = {}) {
const entry = routed.get(anno.id);
if (!entry) {
return add(anno, options);
}
if (anno.type !== 'area' || !anno.ring || anno.ring.length < 3) {
if (anno.outlineUnavailable && entry.screenProxy) {
entry.screenProxy = liveProxy(anno, { ring: null });
screen.update(entry.screenProxy);
}
return;
}
if (!entry.worldProxy) {
entry.worldProxy = liveProxy(anno, { label: null });
const completion = world.add(
entry.worldProxy,
worldOptions(anno, entry, options),
);
if (completion?.then) {
if (entry.screenProxy) {
const pending = liveProxy(anno, { ring: null, pendingOutline: true });
screen.update(pending);
entry.screenProxy = pending;
}
return finishBuilding(anno, entry, completion, options);
}
}
updateCaption(anno, entry);
}
function updateCaption(anno, entry) {
const screenProxy = liveProxy(anno, { type: 'label', ring: null });
if (entry.screenProxy) {
screen.update(screenProxy, { empty: !anno.label });
} else if (anno.label) {
// Publish before add: a partially created caption must remain removable.
entry.screenProxy = screenProxy;
screen.add(screenProxy);
}
entry.screenProxy = entry.screenProxy
? screenProxy
: anno.label
? screenProxy
: null;
}
function finishBuilding(anno, entry, completion, options) {
const workTrace = options.workTrace;
const proxy = entry.worldProxy;
return completion
.then((result) => {
const workStart = workTrace ? performance.now() : 0;
try {
if (
routed.get(anno.id) !== entry ||
entry.worldProxy !== proxy ||
options.signal?.aborted ||
!(options.isCurrent?.() ?? true)
) {
world.remove(proxy);
if (routed.get(anno.id) === entry) remove(anno);
if (workTrace) workTrace.rendererStatus = 'cancelled';
return { ...result, status: 'cancelled' };
}
if (result.status !== 'installed') {
world.remove(proxy);
entry.worldProxy = null;
if (workTrace) workTrace.rendererStatus = result.status;
return result;
}
if (performance.now() >= result.timing.deadlineMs) {
world.remove(proxy);
entry.worldProxy = null;
if (workTrace) workTrace.rendererStatus = 'timeout';
return { ...result, status: 'timeout' };
}
const at = performance.now();
try {
updateCaption(anno, entry);
} finally {
const ms = performance.now() - at;
result.timing.workMs += ms;
result.timing.lastSliceMs += ms;
result.timing.maxSliceMs = Math.max(
result.timing.maxSliceMs,
result.timing.lastSliceMs,
);
}
if (performance.now() >= result.timing.deadlineMs) {
world.remove(proxy);
entry.worldProxy = null;
if (options.pendingVisible === false) {
if (entry.screenProxy) screen.remove(entry.screenProxy);
entry.screenProxy = null;
} else {
// The caption conversion already reshaped the group; redraw the pending point.
const pending = liveProxy(anno, {
ring: null,
pendingOutline: true,
});
if (entry.screenProxy) screen.remove(entry.screenProxy);
entry.screenProxy = pending;
screen.add(pending);
}
if (workTrace) workTrace.rendererStatus = 'timeout';
return { ...result, status: 'timeout' };
}
if (workTrace) workTrace.rendererStatus = result.status;
return result;
} finally {
if (workTrace)
recordWorkSlice(workTrace, 'hybrid-complete', workStart);
}
})
.catch((error) => {
const workStart = workTrace ? performance.now() : 0;
try {
// A later caption throw must roll back the already installed world parts too.
if (routed.get(anno.id) === entry) {
try {
remove(anno);
} catch {
/* original error wins; failed routes stay addressable */
}
} else world.remove(proxy);
throw error;
} finally {
if (workTrace) {
workTrace.rendererStatus = 'failed';
recordWorkSlice(workTrace, 'hybrid-rollback', workStart);
}
}
});
}
function worldOptions(anno, entry, options) {
const proxy = entry.worldProxy;
return {
...options,
isCurrent: () =>
routed.get(anno.id) === entry &&
entry.worldProxy === proxy &&
(options.isCurrent?.() ?? true),
};
}
/**
* Release both routes. Tolerates PARTIAL state (only one sub-renderer got
* its content) and an absent id, so it doubles as the rollback path for a
* failed add.
*
* Both releases are ALWAYS attempted, each clears its own proxy as it
* succeeds, and the routing entry is dropped only once nothing is left to
* release. A release that throws therefore leaves the id still addressable,
* so a retry (or a later clear) can finish the job instead of the orphan
* becoming permanently unreachable. The failure is rethrown after both
* routes have had their turn.
*/
function remove(anno) {
const entry = routed.get(anno.id);
if (!entry) return;
let failure = null;
if (entry.worldProxy) {
try {
world.remove(entry.worldProxy);
entry.worldProxy = null;
} catch (error) {
failure = error; // keep the proxy: it still owns live geometry
}
}
if (entry.screenProxy) {
try {
screen.remove(entry.screenProxy);
entry.screenProxy = null;
} catch (error) {
failure = failure || error;
}
}
if (!entry.worldProxy && !entry.screenProxy) routed.delete(anno.id);
if (failure) throw failure;
}
function sync(annotations) {
world.sync(annotations);
screen.sync(annotations);
}
function destroy() {
world.destroy();
screen.destroy();
routed.clear();
}
return { add, update, remove, sync, destroy };
}
/**
* A proxy that inherits from `anno` via the prototype chain (so live fields the
* engine mutates each tick — `alpha`, `bornAt`, `expiring` — are read through),
* with a few own properties overridden. Sub-renderers store their own state
* (`_entities`, SVG refs) as own properties on the proxy, isolated per route.
*/
function liveProxy(anno, overrides) {
return Object.assign(Object.create(anno), overrides);
}