feat(rail): add a Rail layer with keyless live trains

Live trains from 30 keyless operator feeds: GPS positions from 29 and
Irish Rail's station reports, shown as the operators publish them. 28
work out of the box; Renfe long and medium distance and KTMB appear once
their pack is built, because their vehicles name no route.

Packs are opt-in (scripts/build-rail-paths.mjs): the operator's own
route lines, stop names, next stops and trip-update delays for live
trains. Nothing downloads when the app starts, no train is placed from a
timetable, and no request carries a deployer's key.
This commit is contained in:
Denis Groshev committed 2026-11-11 16:06:22 +01:00
1 parent 14db73f201
commit 830c080803
114 files changed
+26639 -26

No files matched your search

+577
View File
@@ -0,0 +1,577 @@
/**
* @module layers/rail/policy
* @description Constants and pure decisions for the Rail layer. No Cesium
* scene state, no network: everything here is exercised by node:test.
*
* Motion between reports is the Transit layer's delayed playback
* (src/layers/transit/movement.js over src/data/contactPlayback.js), so the
* report-age rules here are Transit's too.
*/
import { msg } from '../../i18n/marker.js';
import {
RAIL_CATEGORIES,
RAIL_POSITION_SOURCES,
} from '../../data/railFeeds.js';
import { displayMotion } from '../transit/movement.js';
import { FIX_FLAGS, readFix } from '../../data/contactPlayback.js';
import { roundHeadingDegrees } from '../../data/headingDegrees.js';
import {
stopClock,
stopLateMinutes,
stopName,
stopRoleIndices,
} from './stopLabels.js';
export const RAIL_SELECTED_OVERLAY_SOURCE_ID = 'rail-selected';
export const RAIL_SELECTED_OVERLAY_SOURCE_OPTIONS = Object.freeze({
cohortLimit: 1,
collisionCapacity: 0,
moving: true,
});
/** Poll interval (ms), matching the proxy's 15 s cache window. */
export const RAIL_POLL_MS = 15_000;
/**
* Feeds activate below this camera altitude, with hysteresis. Rail networks
* are regional, so the gate is Transit's: low enough that a whole-continent
* view does not poll every operator at once.
*/
export const ACTIVATION_ALTITUDE_M = 3_000_000;
export const ACTIVATION_ENTER_ALTITUDE_M = ACTIVATION_ALTITUDE_M - 150_000;
export const ACTIVATION_EXIT_ALTITUDE_M = ACTIVATION_ALTITUDE_M + 150_000;
export const CAMERA_DEBOUNCE_MS = 340;
export const CAMERA_PERCENTAGE_CHANGED = 0.05;
/** A feed already active stays active this far past its coverage edge. */
export const RANGE_SLACK_KM = 40;
export const MAX_TRAINS_TOTAL = 5_000;
/** A train a feed stops listing for this many polls in a row is removed. */
export const MISSED_POLLS_TO_DROP = 2;
/** A report older than this is not drawn (a frozen feed empties, it does not lie). */
export const TRAIN_MAX_FIX_AGE_MS = 10 * 60_000;
/** A feed whose operator has not answered for this long reads as stale. */
export const FEED_STALE_AFTER_MS = 90_000;
/** ...and for this long, its trains are removed. */
export const FEED_EVICT_AFTER_MS = 5 * 60_000;
/** A stamp this far ahead of the fetch is a clock fault, bounded by the fetch. */
export const FUTURE_STAMP_TOLERANCE_MS = 10_000;
/**
* Where a drawn train's position may come from: the operator's GPS, or the
* station or timing point its signalling last reported. No train is placed
* or moved from a timetable; between reports it only glides along its line
* behind real time, as Transit's vehicles do. Every source the registry
* knows (RAIL_POSITION_SOURCES) is a live one.
*/
export const RAIL_LIVE_POSITION_SOURCES = RAIL_POSITION_SOURCES;
/**
* Whether a feed (a registry or catalog entry) or a train record reports
* live positions. Without a stated source, GPS is meant.
* @param {string|null|undefined} source `feed.positions` or
* `record.positionSource`.
* @returns {boolean}
*/
export function isLiveRailPositionSource(source) {
return RAIL_LIVE_POSITION_SOURCES.includes(source ?? 'gps');
}
/**
* A feed catalog that fails is asked for again after CATALOG_RETRY_FIRST_MS,
* then twice as long after each failure in a row, up to CATALOG_RETRY_MAX_MS.
*/
export const CATALOG_RETRY_FIRST_MS = 30_000;
export const CATALOG_RETRY_MAX_MS = 10 * 60_000;
/**
* How long the catalog waits after its nth failure in a row (ms).
* @param {number} failures 1 after the first.
* @returns {number}
*/
export function railCatalogRetryDelayMs(failures) {
return Math.min(
CATALOG_RETRY_MAX_MS,
CATALOG_RETRY_FIRST_MS * 2 ** Math.max(0, failures - 1),
);
}
/**
* Floor cells a moving train reaches cold are warmed in batches: at most
* COLD_CELLS_PER_FLUSH per flush, COLD_CELL_FLUSH_MS after the first one is
* queued, and a cell asked for is not asked again for COLD_CELL_RETRY_MS. A
* long-distance train crosses a 0.001° cell (about 111 m) every few seconds.
*/
export const COLD_CELLS_PER_FLUSH = 64;
export const COLD_CELL_FLUSH_MS = 1_000;
/**
* Floor warming shares `/api/terrain/heights` with every other layer: 90
* requests a minute per client, 64 points each. Rail's budget refills at
* FLOOR_CELLS_PER_MINUTE cells a minute and holds at most FLOOR_CELLS_BURST,
* so no minute spends more than the two together (1,520 cells, about 24
* requests). It is spent only on trains within FLOOR_WARM_MAX_DIST_KM of the
* camera and on the selected trip's stops, the selected train first, then
* the nearest, so hundreds of trains in view (Paris, the Ruhr) cannot use up
* the limit and leave every layer without floors.
*/
export const FLOOR_CELLS_PER_MINUTE = 1_200;
export const FLOOR_CELLS_BURST = COLD_CELLS_PER_FLUSH * 5;
export const FLOOR_WARM_MAX_DIST_KM = 30;
export const COLD_CELL_RETRY_MS = 5_000;
/**
* Track heights on photorealistic tiles: the rendered mesh is sampled at
* points on the train's own line (where the draped line is the track bed
* or the deck), in buckets of 1/TRACK_SAMPLE_GRID degree (about 55 m),
* at most TRACK_SAMPLES_PER_FLUSH per flush, for trains within
* TRACK_SAMPLE_MAX_DIST_KM of a camera at most TRACK_SAMPLE_MAX_CAMERA_M
* above the floor there, and only while the tileset reports its tiles
* loaded: a higher camera, or tiles still streaming, reads coarse tiles,
* whose height under a viaduct is the valley's (the failure
* src/services/meshFloorSampler.js records). A sample is kept only within
* TRACK_PRIOR_BELOW_M / TRACK_PRIOR_ABOVE_M of the floor under it, and is
* read again after TRACK_SAMPLE_REFRESH_MS: the new reading replaces it
* when the camera is no higher than it was, or once the old one is
* TRACK_SAMPLE_MAX_AGE_MS old.
*/
export const TRACK_SAMPLE_GRID = 2000;
export const TRACK_SAMPLES_PER_FLUSH = 8;
export const TRACK_SAMPLE_RETRY_MS = 4_000;
export const TRACK_SAMPLE_MAX_CAMERA_M = 5_000;
export const TRACK_SAMPLE_MAX_DIST_KM = 8;
export const TRACK_PRIOR_BELOW_M = 25;
export const TRACK_PRIOR_ABOVE_M = 80;
export const TRACK_SAMPLE_REFRESH_MS = 30_000;
export const TRACK_SAMPLE_MAX_AGE_MS = 5 * 60_000;
/**
* A train's drawn height follows its target height no faster than a
* railway climbs: TRACK_MAX_GRADE of the distance it moved (lines rarely
* exceed 4%), plus TRACK_SETTLE_MPS while it stands, so a roof or overpass
* sampled under it is a bump, not a jump. It snaps to a better source (a
* real floor replacing a fallback, or any floor replacing the ellipsoid)
* and after a jump of more than TRACK_SNAP_M.
*/
export const TRACK_MAX_GRADE = 0.05;
export const TRACK_SETTLE_MPS = 0.5;
export const TRACK_SNAP_M = 2_000;
export const MARKER_PIXEL_SIZE = 18;
export const SELECTED_PIXEL_SIZE = 28;
export const SELECTED_CARD_REFRESH_MS = 250;
/** While a train is selected, every other train is drawn at this opacity. */
export const UNSELECTED_TRAIN_ALPHA = 0.35;
/**
* The faint route network is drawn in full below the first altitude, fades
* out above it and is not drawn at all above the second (m). Above that the
* lines are clutter at the scale of a whole region, and cost frames.
*/
export const NETWORK_FULL_BELOW_M = 150_000;
export const NETWORK_HIDDEN_ABOVE_M = 200_000;
/** The network's opacity, and its share of that while a train is selected. */
export const NETWORK_ALPHA = 0.4;
export const NETWORK_SELECTED_DIM = 0.4;
export const NETWORK_WIDTH_PX = 2;
/**
* A feed out of use this long gives back its network, path pack and parsed
* schedule pack; it loads them again when next used (ms).
*/
export const FEED_RELEASE_AFTER_MS = 10 * 60_000;
/** The selected train's line: the part ahead, and the part travelled. */
export const ROUTE_AHEAD_WIDTH_PX = 5;
export const ROUTE_TRAVELLED_ALPHA = 0.3;
/** How often the selected line's travelled/ahead split follows the train. */
export const ROUTE_SPLIT_INTERVAL_MS = 250;
/** How often the selected train's stops, labels and card are refreshed. */
export const STOP_REFRESH_MS = 1_000;
/**
* How long the follow camera glides to another feed's copy of the selected
* train when the selection moves to it (ms), so it neither jumps nor lets go.
*/
export const FOLLOW_HANDOVER_MS = 1_200;
/**
* Category palette. Warm to cool with distance served, and none of the colours
* the Transit modes, flights (white/cyan), military (amber) or vessels use, so
* a train never reads as a bus drawn by the other layer.
*/
export const RAIL_CATEGORY_COLORS = Object.freeze({
transit: '#FF7A59',
local: '#F2D04B',
regional: '#7BE495',
national: '#5AB8FF',
international: '#C58BFF',
});
/** Panel and card words for each category. */
export const RAIL_CATEGORY_LABELS = Object.freeze({
transit: msg('Urban rail'),
local: msg('Local rail'),
regional: msg('Regional rail'),
national: msg('National rail'),
international: msg('International rail'),
});
/** Card words for what runs on the track, shared with the Transit layer's. */
const RAIL_MODE_WORDS = Object.freeze({
rail: msg('Train'),
metro: msg('Subway'),
tram: msg('Tram'),
});
/** Default visibility: every category on. */
export const DEFAULT_RAIL_CATEGORY_VISIBILITY = Object.freeze(
Object.fromEntries(RAIL_CATEGORIES.map((category) => [category, true])),
);
/**
* Normalise requested category toggles against the current ones. Unknown keys
* are ignored and non-boolean values keep the current setting, so a malformed
* share link can hide nothing it did not name.
* @param {Record<string, unknown>} params
* @param {Record<string, boolean>} [current]
* @returns {Record<string, boolean>}
*/
export function normalizeRailCategories(
params,
current = DEFAULT_RAIL_CATEGORY_VISIBILITY,
) {
const next = {};
for (const category of RAIL_CATEGORIES) {
next[category] =
typeof params?.[category] === 'boolean'
? params[category]
: current[category] !== false;
}
return next;
}
/**
* Stable key for a train across polls. Prefixed so it can never equal a
* Transit vehicle key for the same physical train in a shared pick registry.
* @param {string} feedId
* @param {string} trainId
* @returns {string}
*/
export function railTrainKey(feedId, trainId) {
return `rail:${feedId}:${trainId}`;
}
/**
* When a report was made, in ms: the train's own stamp, else the fetch time.
* @param {object} record
* @param {number|null} [fetchedAtMs]
* @returns {number}
*/
export function trainReportTimeMs(record, fetchedAtMs = null) {
const seconds = Number(record?.timestamp);
if (Number.isFinite(seconds) && seconds > 0) return seconds * 1000;
if (Number.isFinite(fetchedAtMs)) return fetchedAtMs;
return Date.now();
}
/**
* Age of a report in ms (never negative). An unstamped record is aged from
* the snapshot's fetch time, never from now.
* @param {object} record
* @param {number} nowMs
* @param {number|null} [fetchedAtMs]
* @returns {number}
*/
export function trainFixAgeMs(record, nowMs, fetchedAtMs = null) {
const seconds = Number(record?.timestamp);
if (Number.isFinite(seconds) && seconds > 0)
return Math.max(0, nowMs - seconds * 1000);
if (Number.isFinite(fetchedAtMs)) return Math.max(0, nowMs - fetchedAtMs);
return 0;
}
/** Whether a report is too old to draw. */
export function isStaleTrainFix(record, nowMs, fetchedAtMs = null) {
return trainFixAgeMs(record, nowMs, fetchedAtMs) > TRAIN_MAX_FIX_AGE_MS;
}
/** The movement module's speed ceilings are keyed by Transit mode names. */
export function playbackModeFor(railMode) {
return railMode === 'metro'
? 'subway'
: railMode === 'tram'
? 'tram'
: 'rail';
}
/** Two reports closer than this are one place: a parked train's jitter (m). */
export const FOLLOW_MIN_MOVE_M = 15;
const lastFix = {};
const priorFix = {};
/** How far apart a track's last two reports are (m), 0 with fewer. */
function lastReportsApartM(track) {
if (!track || track.count < 2) return 0;
const to = readFix(track, track.count - 1, lastFix);
const from = readFix(track, track.count - 2, priorFix);
if (from.epoch !== to.epoch || to.flags & FIX_FLAGS.BREAK) return 0;
const kx = 111_320 * Math.cos((((from.lat + to.lat) / 2) * Math.PI) / 180);
const dLon = ((((to.lon - from.lon + 180) % 360) + 360) % 360) - 180;
return Math.hypot(dLon * kx, (to.lat - from.lat) * 111_320);
}
/**
* Whether the camera follows a train once it is selected, as it follows a
* tracked aircraft: its reports are recent, and it is moving on its playback
* now, waits at a stop with its next move already reported, or is between
* reports (playback waiting for the next one) after its last two reports
* moved it. Any other train (parked, known from a single report, or not
* heard from lately) gets one fly-to.
* @param {{sample?: object, track?: object}|null} entry Runtime entry with
* playback state.
* @returns {boolean}
*/
export function railTrainFollowable(entry) {
const sample = entry?.sample;
if (!sample || displayMotion(entry, 0).word === 'NO FIX') return false;
if (sample.phase === 'playing' && sample.segmentSpeedMps > 0) return true;
if (
sample.phase === 'playing' &&
sample.motion === 'stopped' &&
Number.isFinite(sample.nextMotionT) &&
sample.nextMotionT > sample.displayT
)
return true;
return lastReportsApartM(entry.track) >= FOLLOW_MIN_MOVE_M;
}
/**
* The follow camera's offset from the train in east-north-up metres: the
* shared world-focus framing for a train (its range and pitch) seen along the
* camera's current heading, so taking the train does not swing the view round.
* @param {{rangeM: number, pitchDeg: number}} framing
* @param {number} headingRad
* @returns {{x: number, y: number, z: number}}
*/
export function railFollowOffset(framing, headingRad) {
const heading = Number.isFinite(headingRad) ? headingRad : 0;
const pitch = (framing.pitchDeg * Math.PI) / 180;
const across = framing.rangeM * Math.cos(pitch);
return {
x: -Math.sin(heading) * across,
y: -Math.cos(heading) * across,
z: -Math.sin(pitch) * framing.rangeM,
};
}
// Tools and the server may import this module, so no catalogue here: the
// layer passes the UI's t().
function englishText(text, values) {
return String(text).replace(/\{(\w+)\}/g, (match, key) =>
values && key in values ? String(values[key]) : match,
);
}
/** Card words for where a train's position comes from. */
const RAIL_POSITION_SOURCE_WORDS = Object.freeze({
gps: msg('Live GPS'),
event: msg('Estimated from station reports'),
});
/** The card never grows past this many detail lines. */
export const RAIL_CARD_MAX_LINES = 6;
/**
* The card's title: the route when the feed names one, else the trip's
* headsign, else the vehicle's own label, else its id.
* @param {object} record
* @param {string|null} headsign
* @param {(text: string, values?: object) => string} t
* @returns {string}
*/
function railCardTitle(record, headsign, t) {
const to = headsign ? t('To {headsign}', { headsign }) : '';
if (record.routeId) {
const route = t('Route {route}', { route: record.routeId });
return `🚆 ${to ? `${route} · ${to}` : route}`;
}
if (to) return `🚆 ${to}`;
const label =
typeof record.label === 'string' && record.label.trim()
? record.label.trim()
: '';
if (label && label !== record.id) return `🚆 ${label}`;
return `🚆 ${t('Vehicle {vehicle}', { vehicle: label || record.id })}`;
}
/** "Next Yonkers 14:32 T−4 (+3 min late)" / "Prev Riverdale 14:24 T+3". */
function stopLine(stop, which, t) {
const values = {
stop: stopName(stop),
time: stopClock(stop),
relative: stop.relative || '',
};
const line = (
which === 'next'
? t('Next {stop} {time} {relative}', values)
: t('Prev {stop} {time} {relative}', values)
)
.replace(/\s+/g, ' ')
.trim();
const late = which === 'next' ? stopLateMinutes(stop) : 0;
return late > 0
? `${line} ${t('(+{minutes} min late)', { minutes: late })}`
: line;
}
/**
* Card copy for the selected train. The status words, report-age wording and
* "shown behind" note are the Transit card's, so they read the same.
*
* With the trip's stops (see stopLabels.js for the stop shape) the card names
* the next and previous stops; the card stays within RAIL_CARD_MAX_LINES by
* dropping its least useful lines first.
*
* @param {object} feed Registry entry.
* @param {object} record Train record from the snapshot.
* @param {number} nowMs
* @param {number|null} [fetchedAtMs]
* @param {object|null} [entry] Runtime entry with playback state.
* @param {(text: string, values?: object) => string} [t]
* @param {{stops?: object[]|null, headsign?: string|null}|null} [trip] The
* trip's stops and headsign from the feed's schedule pack, when known.
* @returns {{title: string, details: string[]}}
*/
export function buildRailSelectionCopy(
feed,
record,
nowMs,
fetchedAtMs = null,
entry = null,
t = englishText,
trip = null,
) {
const headsign =
(typeof trip?.headsign === 'string' && trip.headsign.trim()) ||
(typeof record.headsign === 'string' && record.headsign.trim()) ||
null;
const title = railCardTitle(record, headsign, t);
const category = t(RAIL_CATEGORY_LABELS[record.category] || 'Train');
const mode = t(RAIL_MODE_WORDS[record.mode] || RAIL_MODE_WORDS.rail);
/** Lines with a rank: when the card is too long, the highest ranks go. */
const lines = [];
const add = (rank, text) => lines.push({ rank, text });
add(0, `${category} · ${mode} · ${feed.name} · ${feed.region}`);
const shown = entry ? displayMotion(entry, nowMs) : null;
const motion =
shown?.word === 'STOPPED'
? t('Stopped', { context: 'vehicle motion' })
: shown?.word === 'NO FIX'
? t('No recent fix')
: shown?.word === 'WAITING'
? t('Waiting for update')
: shown
? t('Moving')
: '';
const sourceWord = RAIL_POSITION_SOURCE_WORDS[record.positionSource];
const source = sourceWord ? t(sourceWord) : '';
if (motion || source)
add(1, motion && source ? `${motion} · ${source}` : motion || source);
const stops = Array.isArray(trip?.stops) ? trip.stops : [];
const roles = stopRoleIndices(stops);
if (roles.next >= 0) add(2, stopLine(stops[roles.next], 'next', t));
if (roles.previous >= 0)
add(3, stopLine(stops[roles.previous], 'previous', t));
const haveStops = roles.next >= 0 || roles.previous >= 0;
const ageS = Math.round(
(Number.isFinite(entry?.sample?.latestReportAgeMs)
? entry.sample.latestReportAgeMs
: trainFixAgeMs(record, nowMs, fetchedAtMs)) / 1000,
);
const reported =
ageS < 90
? t('Reported {seconds} s ago', { seconds: ageS })
: t('Reported {minutes} min ago', { minutes: Math.floor(ageS / 60) });
const ownTime =
Number.isFinite(record.timestamp) &&
record.timestamp > 0 &&
(!record.timestampSource || record.timestampSource === 'vehicle');
const lagS = Number.isFinite(entry?.sample?.actualDelayMs)
? Math.max(0, Math.round(entry.sample.actualDelayMs / 1000))
: null;
add(
4,
(ownTime ? reported : t('{reported} (feed time)', { reported })) +
(lagS === null
? ''
: ` · ${t('shown {seconds} s behind', { seconds: lagS })}`),
);
const reportedMotion = [];
if (Number.isFinite(record.speedMps))
reportedMotion.push(
t('reported {speed} km/h', { speed: Math.round(record.speedMps * 3.6) }),
);
if (Number.isFinite(record.bearing))
reportedMotion.push(
t('reported hdg {heading}°', {
heading: roundHeadingDegrees(record.bearing),
}),
);
if (reportedMotion.length) add(7, reportedMotion.join(' · '));
// The feed's own stop id says less than the schedule pack's stop names.
if (!haveStops) {
if (record.status === 'STOPPED_AT' && record.stopId)
add(8, t('Last report: stopped at stop {stop}', { stop: record.stopId }));
else if (record.status === 'INCOMING_AT' && record.stopId)
add(
8,
t('Last report: arriving at stop {stop}', { stop: record.stopId }),
);
else if (record.status === 'IN_TRANSIT_TO' && record.stopId)
add(8, t('Last report: next stop {stop}', { stop: record.stopId }));
}
if (record.mode === 'metro')
add(5, t('Shown at street level · depth not in the feed'));
add(
6,
`${t('Vehicle {vehicle}', { vehicle: record.id })}${record.label && record.label !== record.id ? ` · ${record.label}` : ''}`,
);
// Past the limit, the highest ranks go; the rest keep their order.
const kept = lines
.map((line, order) => ({ ...line, order }))
.sort((a, b) => a.rank - b.rank || a.order - b.order)
.slice(0, RAIL_CARD_MAX_LINES)
.sort((a, b) => a.order - b.order);
return { title, details: kept.map((line) => line.text) };
}
/**
* Shared-host card for the selected train.
* @param {string} key
* @param {object|(() => object|null)} position Cartesian, or a getter the host
* calls on every paint so the card follows the marker.
* @param {{title: string, details: string[]}} copy
* @param {string} category
* @returns {object|null}
*/
export function createRailSelectedOverlayEntry(key, position, copy, category) {
if (!key || !position) return null;
return {
id: String(key),
position,
variant: 'selected',
selected: true,
protected: true,
paintLane: 'selected',
collisionGroup: 'ambient-card',
priority: Number.MAX_SAFE_INTEGER,
title: copy.title,
details: copy.details,
accent: RAIL_CATEGORY_COLORS[category] || RAIL_CATEGORY_COLORS.local,
interactive: false,
anchorRadiusPx: 9,
minAnchorGapPx: 11,
verticalOnly: true,
placement: 'above',
edgeFade: 'keyhole',
horizonCull: true,
terrainOcclusion: false,
};
}