mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-17 08:42:21 +00:00
feat(transit): live public-transit vehicles from open GTFS-Realtime feeds (#587)
Supersedes #218 by @spcpza, ported onto the current component layout with fixes from review. Verified before merge: format, package boundaries, unit suite, build, and the browser tracking suite; a browser harness for the change where one applies; adversarial review applied. Contributor: @spcpza. His original commit is the base of this branch, and his own re-port onto main (2026-09-15, `5b69011`) was consulted while finishing the height work. That port reads every vehicle's surface from the app's shared ground-floor system (`cachedGroundFloor` / `warmGroundFloor` / `GROUND_FLOOR_LIFT_M`) rather than sampling the scene per layer, keeps a vehicle hidden until its cell answers, warms a bounded batch per poll on a timer instead of per frame, and renders at the ellipsoid above the altitude gate. That is the sounder primitive — one floor system for the app, with the rooftop-versus-street question already settled against a datum-correct DEM prior — and this branch's height work was rebuilt on it, replacing a bespoke cell cache, ground prior and rooftop rule written here. Credit for that direction is his. Future work (not in this PR), both written up in docs/CURRENT-STATE.md: - Readable route names. The realtime feeds carry only `route_id`; `route_short_name` / `route_long_name` live in each operator's static GTFS `routes.txt`, and headsigns in `trips.txt`. Doing it properly wants a server-side metadata loader beside the transit proxy with fixed registered static sources, bounded indexes built once and persisted, a slow conditional refresh, and a versioned route dictionary the browser caches. Shipped here: ids are never rewritten, and a cut one carries an ellipsis instead of reading as a typo. - Below-ground rendering. Subway vehicles are drawn on the surface directly above themselves, because the feeds carry no depth and a train nobody can see is not worth drawing; the card says so plainly. Real treatment wants OSM tunnel geometry per city and a ghosted sprite tethered to the surface. The owner recorded it and left it. Round four and after (2026-09-15). The owner tested round three under FLIR and NVG, and then asked for the design to be taken further: elegant in performance, beautiful on camera, trails with a cache for public transport, Cesium-native, and a core other moving layers can adopt. Codex Astra reviewed the plan (it confirmed the speed fault: a glide started from the drawn position at receipt time but spanned the gap between report times, so with MBTA reporting every ~10 s against a 15 s poll every second glide ran at 1.5x; it rejected a queued-segment patch), then wrote the design, then implemented it in commit-sized passes with adversarial review between them and real-browser harness runs by the integrator. What this PR now contains beyond the contributor's original port: - Delayed playback in a contact-agnostic core (`src/data/contactPlayback.js`): each vehicle keeps a typed, bounded fix history and a display clock that runs at one second per second through it, a feed-derived lag behind real time, holding at its newest fix rather than extrapolating and never sprinting to catch up. Marker, course, motion word, card and trail all read the same displayed sample. The clock has an explicit time-offset and seek API so a rewind is a later feature, not a rewrite; flights and vessels are untouched. - A selected-vehicle trail (`src/data/contactTrailRenderer.js`, `src/layers/transit/trails.js`): the retained history drawn with batched Cesium primitives, clipped at display time so the head is exactly the sprite, faded by age, in the mode colour (white under sensor presets), on the same surface path as the marker. - Bounded proxy-side history (`server/providers/transitHistory.js`): fifteen minutes and at most 128 fixes per vehicle with hard byte ceilings, MBTA only for now (opt-in per feed), served by a small endpoint that never fetches upstream, so a selected trail survives a browser reload while the server keeps running. - Scene work bounded to what is visible and moving, an occluder, cached DETECT candidates, holds on the render loop only while something visible moves. - Sensor presets: white-hot haloed sprites under NVG/FLIR/noir (black-hot inverts), saturated mode colours under CRT, per-mode bracket tiers in every theme, the selected card keeping its mode colour. - A discriminating browser harness (`scripts/qa-transit.mjs`) that samples postRender frames, reads the real card anchor, and measures fleet budgets at 800 and 3,000 vehicles. Not built, recorded as follow-ups: curated route display names (lowest priority per the owner), fleet-wide tails, route snapping, a rewind UI, adoption of the playback core by flights and vessels. Verified at merge (2026-09-15 morning): unit suite 3,896 passing, build clean, format and boundary gates clean, tracking regression 109/109, browser harness keyless 200 pass / 0 fail (13 sensor checks unexercised because the live view offered fewer than six isolated sprites; every judged sprite passed), keyed on Google 3D tiles 198 pass with the per-frame allocation gate as the only failure. Follow-ups recorded: the keyed build's playback sampler still allocates per frame (CPU and frame time stay within budget; the 3,000-vehicle metro view sits at a 27.6 ms frame interval against a 25 ms budget), the shared detection overlay's per-paint allocation, friendlier route names, fleet-wide tails, a rewind UI, and adopting the playback core for vessels and flights. Co-authored-by: spcpza <[email protected]>
This commit is contained in:
1 parent
1ad565c8af
commit
76c20be277
78 files changed
+19842
-186
No files matched your search
@@ -0,0 +1,313 @@
|
||||
/** Transit admission and orientation policy; storage and clocks are portable. */
|
||||
import {
|
||||
createTrack,
|
||||
createSample,
|
||||
createFixSample,
|
||||
insertFix,
|
||||
advance,
|
||||
readFix,
|
||||
correctHeight,
|
||||
setTimeOffsetMs,
|
||||
} from '../../data/contactPlayback.js';
|
||||
export const FIX_HISTORY_MAX = 128;
|
||||
export const DISPLAY_LAG_MIN_MS = 25_000;
|
||||
export const DISPLAY_LAG_RESET_MS = 90_000;
|
||||
export const MODE_MAX_SPEED_MPS = Object.freeze({
|
||||
bus: 36, // ~130 km/h — a coach on a motorway
|
||||
tram: 28, // ~100 km/h — interurban light rail
|
||||
subway: 42, // ~150 km/h
|
||||
rail: 111, // ~400 km/h — high-speed services exist on some feeds
|
||||
ferry: 25, // ~90 km/h — fast catamarans
|
||||
unknown: 56, // ~200 km/h
|
||||
});
|
||||
|
||||
/**
|
||||
* The ceiling a fix is judged against. A mode a feed DEFAULTED to is a guess
|
||||
* about a fleet, not a fact about a vehicle: TransLink publishes rail in a
|
||||
* feed whose default is bus, and a bus ceiling refused its 140 km/h services
|
||||
* as impossible and placed them instead of animating them. An inferred mode
|
||||
* gets the permissive ceiling; only a mode the route id actually established
|
||||
* gets its own.
|
||||
* @param {string} mode
|
||||
* @param {boolean} [inferred] Whether the mode came from a feed default.
|
||||
* @returns {number} m/s
|
||||
*/
|
||||
export function speedCeilingMps(mode, inferred = false) {
|
||||
if (inferred) return MODE_MAX_SPEED_MPS.unknown;
|
||||
return MODE_MAX_SPEED_MPS[mode] ?? MODE_MAX_SPEED_MPS.unknown;
|
||||
}
|
||||
|
||||
/** Position deadband is disabled: even a short reported crawl is played. */
|
||||
export const FIX_NOISE_M = 0;
|
||||
|
||||
/**
|
||||
* Displacement (m) a glide must cover before its direction is worth believing.
|
||||
* Below this the course derived from it is noise; the last good one is held.
|
||||
*/
|
||||
export const COURSE_MIN_TRAVEL_M = 12;
|
||||
|
||||
/** Maximum display-course change per second (deg). A bus is not a gyroscope. */
|
||||
export const COURSE_MAX_RATE_DEG_PER_S = 120;
|
||||
/**
|
||||
* Longest stretch of elapsed time (s) one evaluation may spend. The limiter
|
||||
* used to bank the time since the course last CHANGED, so a vehicle that held
|
||||
* north for thirty seconds had thirty seconds of allowance and snapped through
|
||||
* a corner in one step. Elapsed time is now measured since the course was last
|
||||
* EVALUATED, and capped here so that even a first look after a long idle
|
||||
* sweeps visibly instead of snapping.
|
||||
*/
|
||||
export const COURSE_STEP_MAX_S = 0.25;
|
||||
|
||||
/**
|
||||
* Consecutive fixes at the same place before a vehicle is called STOPPED.
|
||||
* One is not enough: a fifteen-second gap between identical fixes is also what
|
||||
* a vehicle waiting at a light looks like, and so is a feed that repeated
|
||||
* itself.
|
||||
*/
|
||||
export const STOPPED_FIXES = 2;
|
||||
|
||||
/**
|
||||
* How long after its newest fix a vehicle stops being described as travelling.
|
||||
*
|
||||
* "En route" means the last two fixes are in different places, which is a fact
|
||||
* about the past. A bus that reported movement and then went quiet for three
|
||||
* minutes is not en route — we simply do not know what it is doing, and saying
|
||||
* otherwise is the same overreach as reading STOPPED off a stale status. Ninety
|
||||
* seconds matches the threshold at which a whole feed reads as gone quiet.
|
||||
*/
|
||||
export const MOTION_UNKNOWN_AFTER_MS = 90_000;
|
||||
|
||||
const EARTH_M_PER_DEG = 111_320;
|
||||
|
||||
/**
|
||||
* Metres between two lat/lon points, flat-earth. Over the few hundred metres a
|
||||
* surface vehicle covers between fixes this is exact to well under a metre.
|
||||
* @param {{lat:number, lon:number}} a
|
||||
* @param {{lat:number, lon:number}} b
|
||||
* @returns {number}
|
||||
*/
|
||||
export function fixDistanceM(a, b) {
|
||||
if (!a || !b) return 0;
|
||||
const dLat = (b.lat - a.lat) * EARTH_M_PER_DEG;
|
||||
const dLon =
|
||||
(b.lon - a.lon) * EARTH_M_PER_DEG * Math.cos((a.lat * Math.PI) / 180);
|
||||
return Math.hypot(dLat, dLon);
|
||||
}
|
||||
|
||||
/**
|
||||
* Course in degrees clockwise from north, from one point to another.
|
||||
* @param {{lat:number, lon:number}} from
|
||||
* @param {{lat:number, lon:number}} to
|
||||
* @returns {number} 0-360
|
||||
*/
|
||||
export function courseBetween(from, to) {
|
||||
const dLat = (to.lat - from.lat) * EARTH_M_PER_DEG;
|
||||
const dLon =
|
||||
(to.lon - from.lon) *
|
||||
EARTH_M_PER_DEG *
|
||||
Math.cos((from.lat * Math.PI) / 180);
|
||||
const deg = (Math.atan2(dLon, dLat) * 180) / Math.PI;
|
||||
return (deg + 360) % 360;
|
||||
}
|
||||
|
||||
/**
|
||||
* Shortest signed difference between two courses, in degrees (-180, 180].
|
||||
* @param {number} from
|
||||
* @param {number} to
|
||||
* @returns {number}
|
||||
*/
|
||||
export function courseDelta(from, to) {
|
||||
let delta = ((to - from + 540) % 360) - 180;
|
||||
if (delta === -180) delta = 180;
|
||||
return delta;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a displacement between two fixes could have been travelled.
|
||||
* @param {string} mode
|
||||
* @param {number} meters
|
||||
* @param {number} seconds
|
||||
* @param {boolean} [inferred] The mode is a feed default, not a route fact.
|
||||
* @returns {boolean} False when the implied speed is impossible for the mode.
|
||||
*/
|
||||
export function displacementPlausible(mode, meters, seconds, inferred = false) {
|
||||
if (!(meters > 0)) return true;
|
||||
const ceiling = speedCeilingMps(mode, inferred);
|
||||
// Below a second of separation the implied speed is dominated by clock
|
||||
// resolution, so judge those against a flat displacement instead.
|
||||
if (!(seconds >= 1)) return meters <= ceiling;
|
||||
return meters / seconds <= ceiling;
|
||||
}
|
||||
|
||||
export function initializePlayback(entry, budget, feedLag) {
|
||||
entry.track = createTrack({
|
||||
budget,
|
||||
policy: {
|
||||
feedLag,
|
||||
courseMinTravelM: COURSE_MIN_TRAVEL_M,
|
||||
staleMs: MOTION_UNKNOWN_AFTER_MS,
|
||||
accept: (a, b) =>
|
||||
displacementPlausible(
|
||||
b.admissionMode ?? entry.mode,
|
||||
fixDistanceM(a, b),
|
||||
(b.t - a.t) / 1000,
|
||||
b.admissionModeInferred ?? entry.modeInferred,
|
||||
),
|
||||
},
|
||||
});
|
||||
entry.sample = createSample();
|
||||
entry.segment = {
|
||||
from: createFixSample(),
|
||||
to: createFixSample(),
|
||||
fraction: NaN,
|
||||
};
|
||||
entry.clocks = { wallNowMs: NaN, monoNowMs: NaN };
|
||||
// Inspection only. Scene animation reads the typed store into owned scratch.
|
||||
Object.defineProperty(entry, 'playT', {
|
||||
configurable: true,
|
||||
get: () => entry.sample.displayT,
|
||||
});
|
||||
Object.defineProperty(entry, 'lagTarget', {
|
||||
configurable: true,
|
||||
get: () => entry.track.targetDelayMs,
|
||||
});
|
||||
Object.defineProperty(entry, 'fixes', {
|
||||
configurable: true,
|
||||
get() {
|
||||
return Array.from({ length: entry.track.count }, (_, i) =>
|
||||
readFix(entry.track, i),
|
||||
);
|
||||
},
|
||||
});
|
||||
}
|
||||
export function recordFix(entry, fix, observation = {}) {
|
||||
const context = observation.context;
|
||||
let epoch = entry.currentEpoch || 1;
|
||||
if (context) {
|
||||
const previous = entry.track.epochs.get(epoch);
|
||||
if (
|
||||
previous &&
|
||||
(previous.trip !== context.trip ||
|
||||
previous.route !== context.route ||
|
||||
previous.mode !== context.mode)
|
||||
)
|
||||
epoch = Math.max(0, ...entry.track.epochs.keys()) + 1;
|
||||
}
|
||||
const result = insertFix(
|
||||
entry.track,
|
||||
{
|
||||
...fix,
|
||||
epoch,
|
||||
admissionMode: context?.mode,
|
||||
admissionModeInferred: observation.modeInferred,
|
||||
},
|
||||
observation,
|
||||
);
|
||||
if (result.accepted) {
|
||||
const latest = readFix(
|
||||
entry.track,
|
||||
entry.track.count - 1,
|
||||
entry.track.latest,
|
||||
);
|
||||
entry.currentEpoch = latest.epoch;
|
||||
if (context) entry.track.epochs.set(latest.epoch, context);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
export function updatePlayback(entry, wallNowMs, monoNowMs) {
|
||||
entry.clocks.wallNowMs = wallNowMs;
|
||||
entry.clocks.monoNowMs = monoNowMs;
|
||||
advance(entry.track, entry.clocks, entry.sample);
|
||||
entry.resets = entry.track.resets;
|
||||
const segment = entry.segment;
|
||||
readFix(
|
||||
entry.track,
|
||||
entry.sample.fromSeq - entry.track.baseSeq,
|
||||
segment.from,
|
||||
);
|
||||
readFix(entry.track, entry.sample.toSeq - entry.track.baseSeq, segment.to);
|
||||
segment.fraction = entry.sample.fraction;
|
||||
return entry.sample;
|
||||
}
|
||||
export function syncPlayback(entry, wallNowMs, monoNowMs = performance.now()) {
|
||||
entry.clocks.wallNowMs = wallNowMs;
|
||||
entry.clocks.monoNowMs = monoNowMs;
|
||||
const resets = entry.track.resets;
|
||||
const reason = entry.track.resetReason;
|
||||
setTimeOffsetMs(entry.track, 0, entry.clocks);
|
||||
if (entry.hasRendered) entry.track.resetReason = 're-entry';
|
||||
else {
|
||||
entry.track.resets = resets;
|
||||
entry.track.resetReason = reason;
|
||||
}
|
||||
updatePlayback(entry, wallNowMs, monoNowMs);
|
||||
}
|
||||
export function playbackPosition(entry) {
|
||||
if (!entry?.track) return null;
|
||||
return {
|
||||
lat: entry.sample.lat,
|
||||
lon: entry.sample.lon,
|
||||
settled: entry.sample.phase !== 'playing',
|
||||
};
|
||||
}
|
||||
export function attachFloorToPlace(entry, fix, heightM) {
|
||||
if (!entry.track || !Number.isFinite(heightM)) return;
|
||||
const scratch = {};
|
||||
for (let i = 0; i < entry.track.count; i++) {
|
||||
readFix(entry.track, i, scratch);
|
||||
if (scratch.lat === fix.lat && scratch.lon === fix.lon)
|
||||
correctHeight(entry.track, scratch.seq, heightM);
|
||||
}
|
||||
}
|
||||
export function displayCourse(entry, nowMs) {
|
||||
if (!entry) return null;
|
||||
const target = Number.isFinite(entry.sample?.segmentCourseDeg)
|
||||
? entry.sample.segmentCourseDeg
|
||||
: null;
|
||||
if (target === null) return entry.courseDeg ?? null;
|
||||
if (entry.courseDeg === null || !Number.isFinite(entry.courseEvalAt)) {
|
||||
return target;
|
||||
}
|
||||
|
||||
// Rate-limit, the way the aircraft display course does: a fix arriving from
|
||||
// around a corner should sweep, not snap. Time since the last EVALUATION,
|
||||
// capped, so idle time is never banked into one big turn.
|
||||
const elapsedS = Math.min(
|
||||
COURSE_STEP_MAX_S,
|
||||
Math.max(0, (nowMs - entry.courseEvalAt) / 1000),
|
||||
);
|
||||
const allowed = COURSE_MAX_RATE_DEG_PER_S * elapsedS;
|
||||
const delta = courseDelta(entry.courseDeg, target);
|
||||
if (Math.abs(delta) <= allowed) return target;
|
||||
return (entry.courseDeg + Math.sign(delta) * allowed + 360) % 360;
|
||||
}
|
||||
|
||||
/**
|
||||
* Evaluate the display course and write it back — the ONE writer both the
|
||||
* poll and the rotation pass go through, so the limiter sees every look.
|
||||
* @param {object} entry
|
||||
* @param {number} nowMs
|
||||
* @returns {boolean} Whether the course changed.
|
||||
*/
|
||||
export function applyDisplayCourse(entry, nowMs) {
|
||||
const course = displayCourse(entry, nowMs);
|
||||
entry.courseEvalAt = nowMs;
|
||||
if (course === entry.courseDeg) return false;
|
||||
entry.courseDeg = course;
|
||||
entry.courseAt = nowMs;
|
||||
return true;
|
||||
}
|
||||
|
||||
export function displayMotion(entry, nowMs) {
|
||||
if (!entry) return { moving: false, word: '' };
|
||||
const sample = entry.sample;
|
||||
if (!sample) return { moving: false, word: 'WAITING' };
|
||||
if (sample.latestReportAgeMs > MOTION_UNKNOWN_AFTER_MS)
|
||||
return { moving: false, word: 'NO FIX' };
|
||||
if (sample.phase !== 'playing') return { moving: false, word: 'WAITING' };
|
||||
if (sample.motion === 'stopped') return { moving: false, word: 'STOPPED' };
|
||||
return {
|
||||
moving: sample.motion === 'moving',
|
||||
word: sample.motion === 'moving' ? 'EN ROUTE' : 'WAITING',
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user