Files
gods-eye-view/src/layers/rail/pathBinding.js
T
German Khokhlov ee5a6ab317 Turn a train that backs away steadily, however small each step
The direction now follows how far a train has come back from the farthest
point it reached, so a slow reversal of under 15 m per report still turns it,
while GPS jitter around one spot does not. Rail policy takes the 15 m figure
from pathBinding instead of repeating it.
2026-11-18 14:32:36 +04:00

297 lines
10 KiB
JavaScript

import { pointAtS, projectOnPath } from '../../data/railPaths.js';
/**
* Binding a train to its railway line and moving it along that line.
*
* A train is bound to one shape of its feed's path pack: the shape its trip
* names, else the route's shape its report lies on. Every later report is
* projected onto that shape near the arc the train was last seen at, so a
* report can never snap to the far side of a loop or to a parallel branch.
* A report that lands well off the line means the binding was wrong (a
* diversion, a short-turn shape, a mismatched trip): the train is moved to
* another of its route's shapes if one fits, else it is unbound and drawn
* with straight-line motion again.
*
* Between two reports the marker moves by arc length: both reports are
* projected onto the shape once per playback segment, and each frame only
* interpolates the arc and looks up the point.
*
* Pure: no Cesium, no DOM.
*/
/** A report farther than this from the bound line unbinds the train (m). */
export const PATH_OFF_TRACK_M = 150;
/** Fastest train the search window allows for (m/s, about 250 km/h). */
const PATH_MAX_SPEED_MPS = 70;
/** Window slack for report jitter and clock error (m). */
const PATH_WINDOW_SLACK_M = 300;
/** Widest hinted search; beyond it the whole shape is searched (m). */
const PATH_WINDOW_MAX_M = 50_000;
/**
* Among route shapes that fit a report about equally well, the longest wins:
* overlapping shapes are usually a full run and its short turns, and a short
* turn would unbind a train that runs past its end.
*/
const PATH_TIE_M = 10;
/**
* Half-width of the arc window a train can have moved in `dtMs`, or NaN when
* the gap is unknown or too long for a window to be meaningful.
* @param {number} dtMs
* @returns {number}
*/
export function pathWindowM(dtMs) {
if (!Number.isFinite(dtMs)) return NaN;
const window =
PATH_WINDOW_SLACK_M + (PATH_MAX_SPEED_MPS * Math.abs(dtMs)) / 1000;
return window > PATH_WINDOW_MAX_M ? NaN : window;
}
/**
* Arc a train must move before that says which way it runs (m): a standing
* train's GPS jitter, back and forth, stays within it.
*/
export const DIRECTION_MIN_M = 15;
/**
* Track one more arc position of a train. `turn.s` is the farthest arc it
* has reached the way it runs (where it was first seen while that is
* unknown); it turns once it is DIRECTION_MIN_M or more back from there,
* however small each step.
* @param {number} direction +1, -1 or 0.
* @param {{s: number}} turn Updated in place.
* @param {number} s
* @returns {number} The direction now.
*/
function steer(direction, turn, s) {
if (!Number.isFinite(s)) return direction;
if (!Number.isFinite(turn.s)) {
turn.s = s;
return direction;
}
const step = s - turn.s;
if (direction && step * direction >= 0) {
turn.s = s;
return direction;
}
if (Math.abs(step) < DIRECTION_MIN_M) return direction;
turn.s = s;
return Math.sign(step);
}
function createBinding(shapeIndex, path, via, s, fix) {
return {
shapeIndex,
path,
via,
/**
* Which way the drawn train runs along the shape: +1 along it, -1
* against it, 0 until two reports or a playback segment tell. Kept until
* a rebind, and while the train stands. Once a playback segment has told
* it (`directionPlayed`), only playback changes it: the newest reports
* run ahead of the drawn train, so a reversal they show turns it when
* playback reaches it.
*/
direction: 0,
directionPlayed: false,
/** How far the reports and the played segments have run (steer). */
reportTurn: { s },
playTurn: { s: NaN },
/** Arc and time of the newest report. */
fixS: s,
fixT: fix.t,
fixLat: fix.lat,
fixLon: fix.lon,
/** Arc and time last drawn. */
drawS: s,
drawT: fix.t,
/** Projections of the current playback segment's two reports. */
segment: {
fromSeq: -1,
toSeq: -1,
fromLat: NaN,
fromLon: NaN,
toLat: NaN,
toLon: NaN,
sFrom: NaN,
sTo: NaN,
ok: false,
},
};
}
/** The route shape a report fits best, preferring the longest near-tie. */
function bestRouteShape(pack, routeId, fix, accept) {
const candidates = [];
for (const index of pack.shapesForRoute(routeId)) {
const path = pack.pathAt(index);
const hit = projectOnPath(path, fix.lat, fix.lon);
if (!hit || hit.offsetM > PATH_OFF_TRACK_M) continue;
if (!accept(index, path)) continue;
candidates.push({ index, path, s: hit.s, offsetM: hit.offsetM });
}
if (!candidates.length) return null;
const nearest = Math.min(...candidates.map((c) => c.offsetM));
let best = null;
for (const candidate of candidates) {
if (candidate.offsetM > nearest + PATH_TIE_M) continue;
if (!best || candidate.path.length > best.path.length) best = candidate;
}
return best;
}
/**
* Bind a train to a shape from its feed's pack.
*
* The trip's own shape when the trip is in the pack and the report lies on it;
* otherwise the route shape the report lies nearest (within PATH_OFF_TRACK_M),
* which for a single-shape route is that shape.
*
* @param {object} pack From createRailPathPack.
* @param {{tripId?: string, routeId?: string}} ids
* @param {{t: number, lat: number, lon: number}} fix The newest report.
* @returns {object|null} A binding, or null to keep straight-line motion.
*/
export function bindTrainPath(pack, { tripId, routeId } = {}, fix) {
if (!pack || !fix || !Number.isFinite(fix.lat) || !Number.isFinite(fix.lon))
return null;
const trip = pack.shapeForTrip(tripId);
if (trip !== null) {
const path = pack.pathAt(trip);
const hit = projectOnPath(path, fix.lat, fix.lon);
if (hit && hit.offsetM <= PATH_OFF_TRACK_M)
return createBinding(trip, path, 'trip', hit.s, fix);
}
const best = bestRouteShape(pack, routeId, fix, (index) => index !== trip);
return best
? createBinding(best.index, best.path, 'route', best.s, fix)
: null;
}
/**
* Follow a new report on the bound shape.
* @param {object} binding
* @param {{t: number, lat: number, lon: number}} fix
* @returns {boolean} False when the report lies off the line: the binding is wrong.
*/
export function followFix(binding, fix) {
if (!binding || !fix) return false;
const hit = projectOnPath(
binding.path,
fix.lat,
fix.lon,
binding.fixS,
pathWindowM(fix.t - binding.fixT),
);
if (!hit || hit.offsetM > PATH_OFF_TRACK_M) return false;
if (!binding.directionPlayed)
binding.direction = steer(binding.direction, binding.reportTurn, hit.s);
binding.fixS = hit.s;
binding.fixT = fix.t;
binding.fixLat = fix.lat;
binding.fixLon = fix.lon;
return true;
}
/**
* After a report fell off the bound shape: another shape of the route that
* holds both the previous report and this one, or null for straight lines.
* @param {object} pack
* @param {{routeId?: string}} ids
* @param {object} binding The binding that no longer fits.
* @param {{t: number, lat: number, lon: number}} fix
* @returns {object|null}
*/
export function rebindTrainPath(pack, { routeId } = {}, binding, fix) {
if (!pack || !binding || !fix) return null;
const best = bestRouteShape(pack, routeId, fix, (index, path) => {
if (index === binding.shapeIndex) return false;
const previous = projectOnPath(path, binding.fixLat, binding.fixLon);
return !!previous && previous.offsetM <= PATH_OFF_TRACK_M;
});
return best
? createBinding(best.index, best.path, 'route', best.s, fix)
: null;
}
/** Project one playback report, near the last drawn arc when that is useful. */
function projectReport(binding, fix, hintS, hintT) {
const path = binding.path;
const window = pathWindowM(fix.t - hintT);
let hit = Number.isFinite(hintS)
? projectOnPath(path, fix.lat, fix.lon, hintS, window)
: null;
if (!hit || hit.offsetM > PATH_OFF_TRACK_M)
hit = projectOnPath(path, fix.lat, fix.lon);
return hit && hit.offsetM <= PATH_OFF_TRACK_M ? hit.s : NaN;
}
/**
* Where a bound train is drawn this frame.
*
* The playback segment's two reports are projected once per segment (the
* from-report reuses the previous segment's to-report when they are the same
* report); every frame interpolates the arc by the playback fraction and
* looks up that point.
*
* @param {object} binding
* @param {{fromSeq: number, toSeq: number, fraction: number}} sample Playback sample.
* @param {{from: {seq:number, t:number, lat:number, lon:number},
* to: {seq:number, t:number, lat:number, lon:number}}} segment The sample's two reports.
* @param {{lat?: number, lon?: number, bearingDeg?: number}} out
* @returns {boolean} False when the train should stay on its straight-line point.
*/
export function placeOnPath(binding, sample, segment, out) {
if (!binding || !sample || !segment || !(sample.fromSeq >= 0)) return false;
const { from, to } = segment;
if (from.seq !== sample.fromSeq || to.seq !== sample.toSeq) return false;
const cache = binding.segment;
if (
cache.fromSeq !== sample.fromSeq ||
cache.toSeq !== sample.toSeq ||
cache.fromLat !== from.lat ||
cache.fromLon !== from.lon ||
cache.toLat !== to.lat ||
cache.toLon !== to.lon
) {
const chained =
cache.ok &&
cache.toSeq === sample.fromSeq &&
cache.toLat === from.lat &&
cache.toLon === from.lon;
const sFrom = chained
? cache.sTo
: projectReport(binding, from, binding.drawS, binding.drawT);
const sTo =
sample.toSeq === sample.fromSeq
? sFrom
: Number.isFinite(sFrom)
? projectReport(binding, to, sFrom, from.t)
: NaN;
cache.fromSeq = sample.fromSeq;
cache.toSeq = sample.toSeq;
cache.fromLat = from.lat;
cache.fromLon = from.lon;
cache.toLat = to.lat;
cache.toLon = to.lon;
cache.sFrom = sFrom;
cache.sTo = sTo;
cache.ok = Number.isFinite(sFrom) && Number.isFinite(sTo);
if (cache.ok) {
const turn = binding.playTurn;
binding.direction = steer(binding.direction, turn, sFrom);
binding.direction = steer(binding.direction, turn, sTo);
if (binding.direction) binding.directionPlayed = true;
}
}
if (!cache.ok) return false;
const f = Number.isFinite(sample.fraction)
? Math.max(0, Math.min(1, sample.fraction))
: 1;
const s = cache.sFrom + (cache.sTo - cache.sFrom) * f;
if (!pointAtS(binding.path, s, out)) return false;
binding.drawS = s;
binding.drawT = from.t + (to.t - from.t) * f;
return true;
}