Files
gods-eye-view/src/layers/rail/routeDisplay.js
T
Sameh Khamis 866a9816f2 Merge origin/main into the renderer seam
Brings in main up to f24abfc88: cockpit subject providers, the render
failure notice, aircraft drawn in their own mesh colours, airport ground
vehicles, and an aircraft with no ground track facing its true heading.

Under the seam:
- The render failure notice lives in the Cesium adapter
  (src/render/cesium/renderFailure.js) and is the application hook
  renderFailureNotice({allowReload, store}); its private Cesium fields
  (Event's raise queue, the widget's render loop flag) are read through
  internals.js. The inline panel's timer waits while the frame port reports
  the loop stopped, and goes on after a Retry.
- Ordinary aircraft models draw white with the 'highlight' colour blend
  through the draw port; tracked and emergency colours tint the mesh.
- Held trains and transit vehicles hide their route set and markers through
  the draw port; the fleet model test fakes answer loads through the fake
  draw port instead of Cesium's glTF loader.
- The Cockpit's subject view follows and places the camera through the
  camera port.
2026-11-14 09:59:55 -08:00

763 lines
24 KiB
JavaScript

import { drawOf } from '../../render/rendererOf.js';
import { cssColor } from '../../render/color.js';
import { fromDegrees } from '../../geo/ellipsoid.js';
import { distance } from '../../geo/vector.js';
import { classifyTrain, getRegisteredRailFeed } from '../../data/railFeeds.js';
import {
FEED_RELEASE_AFTER_MS,
NETWORK_ALPHA,
NETWORK_FULL_BELOW_M,
NETWORK_HIDDEN_ABOVE_M,
NETWORK_SELECTED_DIM,
NETWORK_WIDTH_PX,
RAIL_CATEGORY_COLORS,
ROUTE_AHEAD_WIDTH_PX,
ROUTE_SPLIT_INTERVAL_MS,
ROUTE_TRAVELLED_ALPHA,
STOP_REFRESH_MS,
} from './policy.js';
import {
networkAltitudeFade,
railNetworkLineSteps,
splitFraction,
} from './routeLines.js';
import {
RAIL_STOP_OVERLAY_SOURCE_ID,
RAIL_STOP_OVERLAY_SOURCE_OPTIONS,
createStopOverlayEntries,
selectStopLabels,
} from './stopLabels.js';
/** Longest slice of network building per task, so a frame is never held (ms). */
const NETWORK_SLICE_MS = 6;
/** The fade is applied in steps, so a slow zoom does not rewrite it per event. */
const FADE_STEP = 0.05;
/** A split that moved less than this share of the line is not redrawn. */
const SPLIT_EPSILON = 1e-5;
/** The selected line's dark rim, which keeps it legible over bright
* imagery: the outer 28% of its width at 22% of its colour. */
const ROUTE_RIM = Object.freeze({ shade: 0.22, widthFraction: 0.28 });
/** Arc a route-bound train must cover before its direction is trusted (m). */
const DIRECTION_EVIDENCE_M = 60;
const STOP_DOT_PX = 5;
const STOP_LABELLED_DOT_PX = 8;
const STOP_DOT_OUTLINE = Object.freeze(cssColor('rgba(10, 14, 20, 0.9)'));
/** Two drawn vertices closer than this are one (m), as the line drops repeats. */
const REPEAT_M = 1e-3;
/** Layers built so far, so each one's draw sets have ids of their own. */
let instances = 0;
/** A category's colour (0..1 channels) at `alpha`. */
function categoryColor(category, alpha) {
const rgba =
cssColor(RAIL_CATEGORY_COLORS[category] || RAIL_CATEGORY_COLORS.local) ||
cssColor(RAIL_CATEGORY_COLORS.local);
return [rgba[0], rgba[1], rgba[2], alpha];
}
/**
* Route lines for one Rail layer: the faint network of every active feed
* (built once per path pack), the selected train's line split where the train
* is, and the selected trip's stops as dots and labels.
*
* Every line is draped on the surface through the draw port: each feed's
* network a set per category, the selected line one set whose segments are
* coloured travelled or ahead, and the stops a set of dots.
*
* Nothing here runs per frame but the far-side test of the stops. The
* network's opacity follows the camera on camera events; the split and the
* stops follow the train on a timer that only runs while a train is
* selected.
*
* @param {object} context
* @returns {object}
*/
export function createRouteDisplay({
state,
services,
parts,
stops,
timetable,
}) {
const { governorRequestRender } = services.render;
const instance = (instances += 1);
/** feedId → when the feed was last seen in use (ms). */
const feedSeenAt = new Map();
/** Releases idle feeds while the layer is off. */
let releaseTimer = null;
/** The selected line's set and the stop dots' set, made on first use. */
let routeSet = null;
/** Route sets made, for ids of their own. */
let routeBuilds = 0;
let stopSet = null;
/** The stop dots drawn now, as pushed to their set. */
let stopItems = [];
let timer = null;
let ticks = 0;
/** The draw port, or null while the layer has no viewer. */
function draw() {
const viewer = state._viewer;
return viewer && !viewer.isDestroyed?.() ? drawOf(viewer) : null;
}
/** ECEF positions on the ellipsoid for a flat `[lat, lon, ...]` run, repeats dropped. */
function positionsOf(coords) {
const out = [];
for (let i = 0; i + 1 < coords.length; i += 2) {
const point = fromDegrees(coords[i + 1], coords[i], 0);
if (out.length && distance(out[out.length - 1], point) < REPEAT_M)
continue;
out.push(point);
}
return out;
}
/** A set of draped lines, never picked. */
function lineSet(id) {
return draw()?.lines({ id, pickable: false, show: false }) ?? null;
}
// ---------------------------------------------------------------------------
// Network
/**
* Start building a feed's network from its decoded pack, in slices between
* frames. Called once per pack by ingestion.
* @param {string} feedId
* @param {object} raw The pack's JSON body.
*/
function buildNetwork(feedId, raw) {
const previous = state._networks.get(feedId);
if (previous) dropNetwork(feedId);
const feed = getRegisteredRailFeed(feedId);
const categoryOf = (routeId) =>
feed ? classifyTrain(feed, routeId)?.category || null : null;
const network = {
feedId,
status: 'building',
steps: railNetworkLineSteps(raw, categoryOf),
timer: null,
layers: new Map(),
stats: null,
};
state._networks.set(feedId, network);
const slice = () => {
network.timer = null;
if (state._networks.get(feedId) !== network) return;
const started = performance.now();
for (;;) {
const next = network.steps.next();
if (next.done) {
network.steps = null;
finishNetwork(network, next.value);
return;
}
if (performance.now() - started > NETWORK_SLICE_MS) break;
}
network.timer = setTimeout(slice, 0);
};
network.timer = setTimeout(slice, 0);
}
function finishNetwork(network, result) {
network.status = 'ready';
network.stats = {
shapes: result.shapesIn,
pointsIn: result.pointsIn,
lines: result.lines.length,
points: result.pointsOut,
};
if (!draw()) return;
const byCategory = new Map();
for (const line of result.lines) {
if (!byCategory.has(line.category)) byCategory.set(line.category, []);
byCategory.get(line.category).push(positionsOf(line.coords));
}
for (const [category, runs] of byCategory) {
const style = { kind: 'solid', color: categoryColor(category, 0) };
const items = [];
for (const positions of runs) {
if (positions.length < 2) continue;
items.push({
id: String(items.length),
positions,
widthPx: NETWORK_WIDTH_PX,
mode: 'draped',
style,
pickable: false,
});
}
if (!items.length) continue;
const set = lineSet(
`rail:${instance}:network:${network.feedId}:${category}`,
);
if (!set) continue;
set.set(items);
network.layers.set(category, { set, items, category, alpha: -1 });
}
applyNetwork();
}
function dropNetwork(feedId) {
const network = state._networks.get(feedId);
if (!network) return;
clearTimeout(network.timer);
network.timer = null;
network.steps = null;
for (const layer of network.layers.values()) layer.set.dispose();
network.layers.clear();
state._networks.delete(feedId);
}
/**
* Show each feed's network while the feed is active, the category is on and
* the camera is low enough, at an opacity set by altitude and selection.
*/
function applyNetwork() {
const fade = state._networkFade;
const selected = state._selectedKey !== null;
let changed = false;
for (const network of state._networks.values()) {
// A feed held only for the selected train shows that train's line alone.
const active =
state._enabled &&
state._activeFeeds.has(network.feedId) &&
network.feedId !== state._heldFeedId;
for (const [category, layer] of network.layers) {
const alpha =
active && state._categories[category] !== false
? NETWORK_ALPHA * fade * (selected ? NETWORK_SELECTED_DIM : 1)
: 0;
const show = alpha > 0.001;
if (layer.set.show !== show) {
layer.set.show = show;
changed = true;
}
if (show && Math.abs(layer.alpha - alpha) > 0.001) {
const style = {
kind: 'solid',
color: categoryColor(layer.category, alpha),
};
for (const item of layer.items) item.style = style;
layer.set.upsert(layer.items);
layer.alpha = alpha;
changed = true;
}
}
}
if (changed) governorRequestRender('rail-network');
}
/** Camera moved: recompute the altitude fade, applying it only on a step. */
function onCamera() {
const altitude = parts.viewport.cameraAltitude();
const raw = networkAltitudeFade(
altitude,
NETWORK_FULL_BELOW_M,
NETWORK_HIDDEN_ABOVE_M,
);
const fade = Math.round(raw / FADE_STEP) * FADE_STEP;
if (fade === state._networkFade) return;
state._networkFade = fade;
applyNetwork();
}
// ---------------------------------------------------------------------------
// Selected route
/**
* The shape the selected train runs on: its binding, else its route's
* longest.
*/
function routeShapeFor(entry) {
const pack = state._pathPacks.get(entry.feedId)?.pack;
if (entry.path?.path)
return {
shapeIndex: entry.path.shapeIndex,
path: entry.path.path,
binding: entry.path,
};
const routeId = entry.record?.routeId;
if (!pack || !routeId) return null;
let best = null;
for (const index of pack.shapesForRoute(routeId)) {
const path = pack.pathAt(index);
if (path && (!best || path.length > best.path.length))
best = { shapeIndex: index, path, binding: null };
}
return best;
}
function dropRoute() {
if (!state._route) return;
// Let the set go: the next route's is made anew, on top of every line
// drawn before it (a feed's network loaded since), as each route's
// primitive was added when it was drawn.
routeSet?.dispose();
routeSet = null;
state._route = null;
}
/**
* Draw (or keep) the selected train's line. Rebuilt only when the train
* moves to another shape; the split recolours its segments.
*/
function syncRoute() {
const entry = state._trains.get(state._selectedKey);
const shape = entry && state._enabled ? routeShapeFor(entry) : null;
const port = shape ? draw() : null;
if (!shape || !port) {
if (state._route) {
dropRoute();
governorRequestRender('rail-route');
}
return;
}
const id = `${entry.key}\n${entry.feedId}\n${shape.shapeIndex}`;
if (state._route?.id !== id) {
dropRoute();
const { path } = shape;
const positions = [];
// The cumulative drawn length per path vertex, which the split's
// fraction is measured on: metres on the ground, as a draped line's
// texture runs; one per vertex where the scene draws it over the
// surface instead, as a polyline's does.
const ground = port.clampState?.() !== 'overlay';
const chordAt = new Float64Array(path.n);
for (let i = 0; i < path.n; i++) {
const point = fromDegrees(path.lon[i], path.lat[i], 0);
const last = positions[positions.length - 1];
const step = last ? distance(last, point) : 0;
const repeat = last && step < REPEAT_M;
if (i > 0)
chordAt[i] = chordAt[i - 1] + (repeat ? 0 : ground ? step : 1);
if (!repeat) positions.push(point);
}
if (positions.length < 2) return;
routeSet ||= lineSet(`rail:${instance}:route:${++routeBuilds}`);
if (!routeSet) return;
routeSet.show = true;
// Solid ahead of the train, dimmer behind, split where it is.
const item = {
id: 'route',
positions,
widthPx: ROUTE_AHEAD_WIDTH_PX,
mode: 'draped',
style: {
kind: 'split',
color: categoryColor(entry.category, 1),
behind: categoryColor(entry.category, ROUTE_TRAVELLED_ALPHA),
at: -1,
rim: ROUTE_RIM,
},
pickable: false,
};
routeSet.set([item]);
state._route = {
id,
item,
path,
chordAt,
ground,
binding: shape.binding,
// A trip's own shape runs the way the trip does; a route's shape may
// be drawn either way, so its direction is learnt from the train.
direction: shape.binding?.via === 'trip' ? 1 : 0,
firstS: shape.binding ? shape.binding.drawS : NaN,
fraction: NaN,
};
governorRequestRender('rail-route');
} else if (state._route.binding !== shape.binding) {
// Rebound to the same shape (a new trip on it): follow the new binding.
state._route.binding = shape.binding;
state._route.firstS = shape.binding ? shape.binding.drawS : NaN;
if (shape.binding?.via !== 'trip') state._route.direction = 0;
}
updateSplit();
}
/**
* Show the selected line unless a first-person view rides its train
* (cockpitSubject.js): from inside the train it would run up the middle of
* the view and under the eye.
*/
function applyHold() {
if (!state._route || !routeSet) return;
const shown = !(
state._cockpitSubjectKey !== null &&
state._cockpitSubjectKey === state._selectedKey
);
if (routeSet.show !== shown) {
routeSet.show = shown;
governorRequestRender('rail-route');
}
}
/** Move the travelled/ahead split to where the train is drawn now. */
function updateSplit() {
const route = state._route;
if (!route) return;
applyHold();
const binding = route.binding;
const s = binding ? binding.drawS : NaN;
if (route.direction === 0 && Number.isFinite(s)) {
const moved = s - route.firstS;
if (Math.abs(moved) >= DIRECTION_EVIDENCE_M)
route.direction = Math.sign(moved);
}
const fraction =
route.direction !== 0 && Number.isFinite(s)
? splitFraction(route.path, route.chordAt, s)
: NaN;
const style = route.item.style;
if (!Number.isFinite(fraction)) {
// No position on the line yet: draw it all as ahead.
route.fraction = NaN;
if (style.at === -1 && !style.reverse) return;
} else {
const reverse = route.direction < 0;
if (
Number.isFinite(route.fraction) &&
Math.abs(fraction - route.fraction) < SPLIT_EPSILON &&
Boolean(style.reverse) === reverse
)
return;
route.fraction = fraction;
}
const at = Number.isFinite(fraction) ? fraction : -1;
route.item = {
...route.item,
style: { ...style, at, reverse: at >= 0 && route.direction < 0 },
};
routeSet?.upsert([route.item]);
governorRequestRender('rail-route-split');
}
// ---------------------------------------------------------------------------
// Stops
function stopDots() {
stopSet ||=
draw()?.points({
id: `rail:${instance}:stops`,
blend: 'translucent',
pickable: false,
}) ?? null;
return stopSet;
}
function clearStops() {
stopItems = [];
stopSet?.clear();
state._trip = null;
state._stopsSignature = '';
state._stopLabelsSignature = '';
state._stopAnchors.clear();
state._overlayHost.setEntries(
RAIL_STOP_OVERLAY_SOURCE_ID,
[],
RAIL_STOP_OVERLAY_SOURCE_OPTIONS,
);
}
function anchorFor(stop) {
const key = `${stop.stopId ?? ''}\n${stop.lat}\n${stop.lon}`;
let anchor = state._stopAnchors.get(key);
if (!anchor) {
const { h, q } = parts.rendering.stopHeight(stop.lat, stop.lon);
anchor = {
lat: stop.lat,
lon: stop.lon,
h,
q,
position: fromDegrees(stop.lon, stop.lat, h),
};
state._stopAnchors.set(key, anchor);
}
return anchor.position;
}
/**
* Stops placed before their floor cell was warm stand on a fallback (the
* ellipsoid at worst, which is drawn over the terrain far off its station
* from a low camera): each refresh reads those again, and once one stands
* better its dot and label are drawn again there.
*/
function settleAnchors() {
let moved = false;
for (const anchor of state._stopAnchors.values()) {
if (anchor.q >= 2) continue;
const { h, q } = parts.rendering.stopHeight(anchor.lat, anchor.lon);
if (q < anchor.q || (q === anchor.q && Math.abs(h - anchor.h) < 1))
continue;
anchor.h = h;
anchor.q = q;
anchor.position = fromDegrees(anchor.lon, anchor.lat, h);
moved = true;
}
if (moved) {
state._stopsSignature = '';
state._stopLabelsSignature = '';
}
}
/**
* Hide the stop dots on the far side of the Earth. They are drawn over the
* terrain, and the selected trip is drawn at any distance (viewport.js), so
* the rendering pass hands over its horizon test every frame.
* @param {(position: object) => boolean} facesCamera
*/
function cullStops(facesCamera) {
if (!stopSet || !stopItems.length) return;
let changed = null;
for (const item of stopItems) {
const shown = facesCamera(item.pos);
if (item.show === shown) continue;
item.show = shown;
(changed ||= []).push(item);
}
if (changed) stopSet.upsert(changed);
}
/** Ask the provider for the selected trip's stops and redraw what changed. */
function refreshStops() {
const entry = state._trains.get(state._selectedKey);
if (!entry || !state._enabled || typeof stops?.stopsFor !== 'function') {
if (state._trip || state._stopsSignature) clearStops();
return;
}
let trip = null;
try {
trip = stops.stopsFor(
{
feedId: entry.feedId,
tripId: entry.record?.tripId || null,
routeId: entry.record?.routeId || null,
record: entry.record,
},
Date.now(),
);
} catch (error) {
console.warn('[Data:Rail] stops unavailable:', error?.message || error);
}
const list = Array.isArray(trip?.stops) ? trip.stops : [];
state._trip = list.length || trip?.headsign ? trip : null;
settleAnchors();
const { labels, dots } = selectStopLabels(list);
const color = categoryColor(entry.category, 1);
const passedColor = categoryColor(entry.category, 0.45);
const signature = `${entry.key}|${labels.map((l) => l.index).join(',')}|${dots
.map((d) => `${d.index}${d.passed ? 'p' : ''}`)
.join(',')}`;
if (signature !== state._stopsSignature) {
state._stopsSignature = signature;
const points = stopDots();
if (points) {
const items = [];
const add = (stop, passed, size) =>
items.push({
id: String(items.length),
pos: anchorFor(stop),
pixelSize: size,
color: passed ? passedColor : color,
outlineColor: STOP_DOT_OUTLINE,
outlineWidth: 1.5,
disableDepthTest: Infinity,
show: true,
});
for (const dot of dots) add(dot.stop, dot.passed, STOP_DOT_PX);
for (const label of labels)
add(label.stop, label.stop.state === 'passed', STOP_LABELLED_DOT_PX);
stopItems = items;
points.set(items);
}
governorRequestRender('rail-stops');
}
const entries = createStopOverlayEntries(entry.key, labels, anchorFor);
const text = JSON.stringify(
entries.map((item) => [item.id, item.title, item.details, item.accent]),
);
if (text !== state._stopLabelsSignature) {
state._stopLabelsSignature = text;
state._overlayHost.setEntries(
RAIL_STOP_OVERLAY_SOURCE_ID,
entries,
RAIL_STOP_OVERLAY_SOURCE_OPTIONS,
);
}
}
// ---------------------------------------------------------------------------
// Selection ticker
function tick() {
if (globalThis.document?.visibilityState === 'hidden') return;
if (!state._enabled || !state._selectedKey) {
stopTicker();
return;
}
ticks += 1;
syncRoute();
if ((ticks * ROUTE_SPLIT_INTERVAL_MS) % STOP_REFRESH_MS === 0) {
refreshStops();
parts.selection.refreshSelectedCard(false);
}
}
function startTicker() {
if (timer) return;
ticks = 0;
timer = setInterval(tick, ROUTE_SPLIT_INTERVAL_MS);
}
function stopTicker() {
clearInterval(timer);
timer = null;
}
/** A train was selected, or the selection was cleared. */
function onSelectionChanged() {
state._stopAnchors.clear();
state._stopsSignature = '';
state._stopLabelsSignature = '';
const entry = state._enabled ? state._trains.get(state._selectedKey) : null;
// The provider loads the feed's timetable and polls its delays while a
// train on it is selected.
stops?.onSelect?.(
entry
? {
feedId: entry.feedId,
tripId: entry.record?.tripId || null,
routeId: entry.record?.routeId || null,
record: entry.record,
}
: null,
);
if (state._selectedKey && state._enabled) {
syncRoute();
refreshStops();
startTicker();
} else {
stopTicker();
dropRoute();
clearStops();
}
applyNetwork();
governorRequestRender('rail-route');
}
/**
* Give back what a feed out of use for FEED_RELEASE_AFTER_MS holds: its
* faint network, its path pack and its parsed timetable. A feed in use
* (polled, or held for the selected train) keeps everything; a pack still
* loading is left to finish. Called on each poll tick, and once more while
* the layer is off.
* @param {number} nowMs
*/
function releaseIdleFeeds(nowMs) {
for (const feedId of state._activeFeeds.keys())
feedSeenAt.set(feedId, nowMs);
const held = new Set([
...state._networks.keys(),
...state._pathPacks.keys(),
...feedSeenAt.keys(),
]);
for (const feedId of held) {
if (state._activeFeeds.has(feedId)) continue;
const seen = feedSeenAt.get(feedId);
if (seen === undefined) {
feedSeenAt.set(feedId, nowMs);
continue;
}
if (nowMs - seen < FEED_RELEASE_AFTER_MS) continue;
if (state._pathPacks.get(feedId)?.status === 'loading') continue;
dropNetwork(feedId);
state._pathPacks.delete(feedId);
timetable?.forget?.(feedId);
feedSeenAt.delete(feedId);
}
}
/**
* Layer disabled: hide everything. Built networks stay for a quick return,
* and are released once they have been out of use FEED_RELEASE_AFTER_MS.
*/
function hideAll() {
stops?.onSelect?.(null);
stopTicker();
dropRoute();
clearStops();
applyNetwork();
releaseIdleFeeds(Date.now());
clearTimeout(releaseTimer);
releaseTimer = setTimeout(() => {
releaseTimer = null;
releaseIdleFeeds(Date.now());
}, FEED_RELEASE_AFTER_MS);
}
function destroy() {
hideAll();
clearTimeout(releaseTimer);
releaseTimer = null;
feedSeenAt.clear();
for (const feedId of [...state._networks.keys()]) dropNetwork(feedId);
routeSet?.dispose();
routeSet = null;
stopSet?.dispose();
stopSet = null;
stopItems = [];
state._overlayHost.clearSource(RAIL_STOP_OVERLAY_SOURCE_ID);
}
/** Counts for QA and the testing surface. */
function stats() {
const feeds = {};
for (const [feedId, network] of state._networks) {
feeds[feedId] = {
status: network.status,
primitives: network.layers.size,
shown: [...network.layers.values()].filter((l) => l.set.show).length,
...(network.stats || {}),
};
}
return {
fade: state._networkFade,
feeds,
route: state._route
? {
id: state._route.id,
vertices: state._route.path.n,
fraction: state._route.fraction,
direction: state._route.direction,
ground: state._route.ground,
}
: null,
stops: {
points: stopItems.length,
trip: state._trip ? state._trip.stops?.length || 0 : 0,
},
};
}
return {
buildNetwork,
dropNetwork,
applyNetwork,
onCamera,
syncRoute,
applyHold,
refreshStops,
cullStops,
onSelectionChanged,
hideAll,
releaseIdleFeeds,
destroy,
stats,
};
}