Files
gods-eye-view/src/layers/transit/movement.js
T
Sameh Khamis 46f7b74c8c chore: drop unused exports from modules QA harnesses load
QA harnesses import some modules in the page by path, for example
import('/src/data/radio.js'). Those calls name exactly which bindings
they use, and every other export of these modules has no importer:

- src/data/radio.js: 20 aliases of radio layer methods and two
  re-exported altitude constants. The radio layer keeps the methods.
- src/layers/transit/movement.js: tuning constants and course helpers
  used only inside the module lose `export`; FIX_HISTORY_MAX,
  DISPLAY_LAG_MIN_MS, DISPLAY_LAG_RESET_MS, FIX_NOISE_M, STOPPED_FIXES
  and courseBetween, which nothing reads, are deleted.
- src/overlays/worldOverlay.js, src/splitFlap.js,
  src/data/contactPlayback.js and src/voice/cloudVoiceAuth.js: helpers
  and constants used only locally lose `export`.
2026-10-22 19:07:46 -07:00

287 lines
9.5 KiB
JavaScript

/** Transit admission and orientation policy; storage and clocks are portable. */
import {
createTrack,
createSample,
createFixSample,
insertFix,
advance,
readFix,
correctHeight,
setTimeOffsetMs,
} from '../../data/contactPlayback.js';
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
*/
function speedCeilingMps(mode, inferred = false) {
if (inferred) return MODE_MAX_SPEED_MPS.unknown;
return MODE_MAX_SPEED_MPS[mode] ?? MODE_MAX_SPEED_MPS.unknown;
}
/**
* 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.
*/
const COURSE_MIN_TRAVEL_M = 12;
/** Maximum display-course change per second (deg). A bus is not a gyroscope. */
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.
*/
const COURSE_STEP_MAX_S = 0.25;
/**
* 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.
*/
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);
}
/**
* Shortest signed difference between two courses, in degrees (-180, 180].
* @param {number} from
* @param {number} to
* @returns {number}
*/
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);
}
}
function displayCourse(entry, nowMs) {
if (!entry) return null;
const target = Number.isFinite(entry.sample?.segmentCourseDeg)
? entry.sample.segmentCourseDeg
: null;
if (target === null) {
if (Number.isFinite(entry.courseDeg)) return entry.courseDeg;
return Number.isFinite(entry.record?.bearing) ? entry.record.bearing : 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',
};
}