Merge origin/main into the renderer-contract branch: the procedural fleet models drawn through the renderer's model sets

Aircraft, military, local ADS-B, vessel, transit and rail models come from
the fleet model set, loaded up front and drawn life size through the draw
port's models sets; no layer touches the viewer or Cesium outside
src/render/cesium/. The models capability gains glTF bytes (gltf), a
per-axis stretch (axisScale), a colour for tinted parts (maskColor) and a
cut below the origin (clip: 'belowOrigin'), with conformance checks.

Main's rail layer and Data Library are ported to the ports; the CCTV
footprint probe keeps the globe-terrain clamp through the query port.
This commit is contained in:
Sameh Khamis committed 2026-11-13 14:14:42 -08:00
commit e3865f462f
533 files changed
+55738 -2518

No files matched your search

+738
View File
@@ -0,0 +1,738 @@
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;
/** 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;
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;
routeSet?.clear();
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 = [];
// Arc length (m) of each drawn vertex, so each segment knows the arc
// it spans, and the cumulative drawn length per path vertex, which
// the split's fraction is measured on.
const drawnS = [];
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 : step);
if (!repeat) {
positions.push(point);
drawnS.push(path.s[i]);
}
}
if (positions.length < 2) return;
routeSet ||= lineSet(`rail:${instance}:route`);
if (!routeSet) return;
routeSet.show = true;
const ahead = categoryColor(entry.category, 1);
const travelled = categoryColor(entry.category, ROUTE_TRAVELLED_ALPHA);
const midS = new Float64Array(positions.length - 1);
for (let j = 0; j < midS.length; j++)
midS[j] = (drawnS[j] + drawnS[j + 1]) / 2;
const item = {
id: 'route',
positions,
widthPx: ROUTE_AHEAD_WIDTH_PX,
mode: 'draped',
style: { kind: 'solid', color: ahead },
segmentColors: new Array(midS.length).fill(ahead),
pickable: false,
};
routeSet.set([item]);
state._route = {
id,
item,
ahead,
travelled,
midS,
path,
chordAt,
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,
/** Segments drawn travelled, and which way: `${direction}:${count}`. */
split: '1:0',
ground: port.clampState?.() !== 'overlay',
};
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();
}
/**
* Colour the segments behind the train travelled and the rest ahead: a
* segment is behind it when the middle of its arc is.
*/
function updateSplit() {
const route = state._route;
if (!route) return;
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;
// No position on the line yet: draw it all as ahead.
route.fraction = Number.isFinite(fraction) ? fraction : NaN;
const mids = route.midS;
let behind = 0;
if (Number.isFinite(fraction))
for (let j = 0; j < mids.length; j++)
if (route.direction > 0 ? mids[j] < s : mids[j] > s) behind += 1;
const direction = Number.isFinite(fraction) ? route.direction : 1;
const split = `${direction}:${behind}`;
if (split === route.split) return;
route.split = split;
const colors = route.item.segmentColors;
for (let j = 0; j < mids.length; j++) {
const travelled =
Number.isFinite(fraction) &&
(route.direction > 0 ? mids[j] < s : mids[j] > s);
colors[j] = travelled ? route.travelled : route.ahead;
}
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,
refreshStops,
cullStops,
onSelectionChanged,
hideAll,
releaseIdleFeeds,
destroy,
stats,
};
}