Keep a standing train's direction through jitter and missing bearings

- GPS jitter under 15 m at a standing train no longer turns it, in reports
  and in playback; a reversal needs at least 15 m of movement.
- A standing train keeps its operator's last bearing through reports that
  leave it out.
- Playback resets its turn point at a break, so a jump to a corrected
  position is not a reversal.
- A train bound while its line is still loading takes its direction from
  the movement it already made.
- A vehicle in view that leaves a Transit hold goes on from its own clock
  instead of rewinding.
- Tests cover the 15 m boundary, the late line, the hold release and the
  icon after Transit is turned back on; duplicate jitter tests are merged.
- FOLLOW_MIN_MOVE_M is gone; comments and CURRENT-STATE match the code.
This commit is contained in:
German Khokhlov committed 2026-11-18 20:49:15 +04:00
1 parent df4d76384c
commit 58afb169d1
10 files changed
+291 -127

No files matched your search

+4 -5
View File
@@ -173,16 +173,15 @@ export function createRailCockpitSubject({
/**
* Which way the train runs along its shape: as its binding learnt it from
* successive reports, else from its reported bearing against the line's
* bearing there; 0 while neither tells. Not the drawn course: until the
* binding tells, the train has not moved past GPS jitter, and a course
* drawn between such reports is that jitter.
* successive reports, else from its operator's last reported bearing
* against the line's bearing there; 0 while neither tells. Not the drawn
* course: before the binding tells, that course is GPS jitter.
*/
function directionOf(entry) {
const binding = entry.path;
if (binding.direction === 1 || binding.direction === -1)
return binding.direction;
const course = finiteOrNull(entry.record?.bearing);
const course = finiteOrNull(binding.bearingDeg);
const point = pointAtS(binding.path, binding.drawS, scratch);
if (course === null || !Number.isFinite(point?.bearingDeg)) return 0;
const turn = Math.abs(((course - point.bearingDeg + 540) % 360) - 180);
+42 -2
View File
@@ -162,8 +162,8 @@ test('a train on a known floor at sea level reports a rail height of 0 m', async
});
test('a train first seen standing takes no direction from its GPS jitter', async (t) => {
// Neither reports 13 m apart nor the course drawn between them say which way
// it runs; an operator's bearing does.
// Reports 13 m apart, and the course drawn between them, do not tell which
// way it runs; an operator's bearing does.
const app = harness(t, { paths: { 'mbta-rail': PACK }, at: BOSTON });
let jitterM = 0;
app.feeds.set('mbta-rail', () => [
@@ -184,6 +184,46 @@ test('a train first seen standing takes no direction from its GPS jitter', async
assert.deepEqual(seen, Array(6).fill([0, -1]));
});
test('a standing train keeps its operator’s bearing through reports that leave it out', async (t) => {
const app = harness(t, { paths: { 'mbta-rail': PACK }, at: BOSTON });
let bearing = 270;
app.feeds.set('mbta-rail', () => [
train('T1', LAT, LON0 + 1000 / KX, { bearing }),
]);
await app.enable();
const seen = [];
for (const next of [270, 270, 270, null, null, null]) {
bearing = next;
app.run(RAIL_POLL_MS);
await app.poll();
app.parts().selection.selectTrain(T1);
seen.push(app.layer.getSelectedTrain().path.direction);
}
assert.deepEqual(seen, Array(6).fill(-1));
});
test('a train bound standing, its line late, runs the way its earlier reports went', async (t) => {
t.mock.method(console, 'warn', () => {});
const paths = { 'mbta-rail': 503 };
const app = harness(t, { paths, at: BOSTON });
let eastM = 1600;
app.feeds.set('mbta-rail', () => [train('T1', LAT, LON0 + eastM / KX)]);
await app.enable();
// No line yet: it runs 300 m west, with no bearing, and stands.
for (const next of [1500, 1400, 1300, 1300, 1300, 1300, 1300, 1300]) {
eastM = next;
app.run(RAIL_POLL_MS);
await app.poll();
}
assert.equal(app.entry(T1).path, null, 'not bound yet');
paths['mbta-rail'] = PACK;
const slot = app.state()._pathPacks.get('mbta-rail');
app.run(Math.max(0, slot.retryAt - Date.now()));
await app.poll();
app.parts().selection.selectTrain(T1);
assert.equal(app.layer.getSelectedTrain().path.direction, -1);
});
test('a snapshot read again while nothing changed is the one read before', async (t) => {
let list = stopList('Alpha', 'Bravo', 'Charlie');
const app = await onTheLine(t, {
+26 -1
View File
@@ -23,7 +23,12 @@ import {
railTrainKey,
trainReportTimeMs,
} from './policy.js';
import { bindTrainPath, followFix, rebindTrainPath } from './pathBinding.js';
import {
bindTrainPath,
followFix,
rebindTrainPath,
recallDirection,
} from './pathBinding.js';
import { scheduleRetryDelayMs } from './schedules.js';
import { createDuplicateFilter } from './dedupe.js';
@@ -220,6 +225,23 @@ export function createIngestion({ state, services, parts, source }) {
entry.path = rebindTrainPath(pack, ids, entry.path, fix);
}
/**
* A track's reports before `newest`, newest first, back to the start of
* its run of playback (a new epoch or a break).
*/
function earlierFixes(track, newest) {
const fixes = [];
let later = newest;
for (let i = track.count - 2; i >= 0; i--) {
if (later.flags & FIX_FLAGS.BREAK) break;
const fix = readFix(track, i);
if (fix.epoch !== later.epoch) break;
fixes.push(fix);
later = fix;
}
return fixes;
}
/** Bind the trains a feed already shows once its pack arrives. */
function bindFeedTrains(feedId) {
const newest = {};
@@ -228,6 +250,9 @@ export function createIngestion({ state, services, parts, source }) {
if (!entry.track?.count) continue;
readFix(entry.track, entry.track.count - 1, newest);
followPath(entry, entry.record, newest);
// It may have run, and stopped, before its line came.
if (entry.path)
recallDirection(entry.path, earlierFixes(entry.track, newest));
parts.rendering.schedulePlayback(entry);
}
governorRequestRender('rail-paths');
+46 -27
View File
@@ -1,3 +1,4 @@
import { FIX_FLAGS } from '../../data/contactPlayback.js';
import { pointAtS, projectOnPath } from '../../data/railPaths.js';
/**
@@ -48,32 +49,19 @@ export function pathWindowM(dtMs) {
}
/**
* 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.
* Arc a train must move before it tells which way it runs (m); a standing
* train's GPS jitter 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.
* The direction after one more arc position `s`: once `s` is DIRECTION_MIN_M
* or more from `turn.s`, the sign of that move, and `turn.s` moves to `s`.
*/
function steer(direction, turn, s) {
if (!Number.isFinite(s)) return direction;
if (!Number.isFinite(turn.s)) {
turn.s = s;
return direction;
}
if (!Number.isFinite(turn.s)) turn.s = s;
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);
@@ -86,17 +74,19 @@ function createBinding(shapeIndex, path, via, s, fix) {
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.
* against it, 0 until it has moved DIRECTION_MIN_M (steer, or
* recallDirection). 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). */
/** steer() turn points: one for the reports, one for the played segments. */
reportTurn: { s },
playTurn: { s: NaN },
/** The newest operator bearing its reports gave (deg), NaN before one. */
bearingDeg: Number.isFinite(fix.bearingDeg) ? fix.bearingDeg : NaN,
/** Arc and time of the newest report. */
fixS: s,
fixT: fix.t,
@@ -149,7 +139,7 @@ function bestRouteShape(pack, routeId, fix, accept) {
*
* @param {object} pack From createRailPathPack.
* @param {{tripId?: string, routeId?: string}} ids
* @param {{t: number, lat: number, lon: number}} fix The newest report.
* @param {{t: number, lat: number, lon: number, bearingDeg?: number}} fix The newest report.
* @returns {object|null} A binding, or null to keep straight-line motion.
*/
export function bindTrainPath(pack, { tripId, routeId } = {}, fix) {
@@ -171,7 +161,7 @@ export function bindTrainPath(pack, { tripId, routeId } = {}, fix) {
/**
* Follow a new report on the bound shape.
* @param {object} binding
* @param {{t: number, lat: number, lon: number}} fix
* @param {{t: number, lat: number, lon: number, bearingDeg?: number}} fix
* @returns {boolean} False when the report lies off the line: the binding is wrong.
*/
export function followFix(binding, fix) {
@@ -186,6 +176,7 @@ export function followFix(binding, fix) {
if (!hit || hit.offsetM > PATH_OFF_TRACK_M) return false;
if (!binding.directionPlayed)
binding.direction = steer(binding.direction, binding.reportTurn, hit.s);
if (Number.isFinite(fix.bearingDeg)) binding.bearingDeg = fix.bearingDeg;
binding.fixS = hit.s;
binding.fixT = fix.t;
binding.fixLat = fix.lat;
@@ -214,6 +205,32 @@ export function rebindTrainPath(pack, { routeId } = {}, binding, fix) {
: null;
}
/**
* Which way a train just bound standing ran before: the newest of its
* earlier reports (newest first) DIRECTION_MIN_M or more along the line
* from its newest one tells. Stops at the first report off the line.
* @param {object} binding Just made, from the newest report.
* @param {Array<{t: number, lat: number, lon: number}>} earlier
*/
export function recallDirection(binding, earlier) {
if (!binding || binding.direction) return;
for (const fix of earlier) {
const hit = projectOnPath(
binding.path,
fix.lat,
fix.lon,
binding.fixS,
pathWindowM(binding.fixT - fix.t),
);
if (!hit || hit.offsetM > PATH_OFF_TRACK_M) return;
const step = binding.fixS - hit.s;
if (Math.abs(step) >= DIRECTION_MIN_M) {
binding.direction = Math.sign(step);
return;
}
}
}
/** Project one playback report, near the last drawn arc when that is useful. */
function projectReport(binding, fix, hintS, hintT) {
const path = binding.path;
@@ -236,7 +253,7 @@ function projectReport(binding, fix, hintS, hintT) {
*
* @param {object} binding
* @param {{fromSeq: number, toSeq: number, fraction: number}} sample Playback sample.
* @param {{from: {seq:number, t:number, lat:number, lon:number},
* @param {{from: {seq:number, t:number, lat:number, lon:number, flags?: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.
@@ -279,6 +296,8 @@ export function placeOnPath(binding, sample, segment, out) {
cache.ok = Number.isFinite(sFrom) && Number.isFinite(sTo);
if (cache.ok) {
const turn = binding.playTurn;
// A break is a corrected position, not a move: steer on from there.
if (from.flags & FIX_FLAGS.BREAK) turn.s = sFrom;
binding.direction = steer(binding.direction, turn, sFrom);
binding.direction = steer(binding.direction, turn, sTo);
if (binding.direction) binding.directionPlayed = true;
+81 -45
View File
@@ -1,5 +1,6 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { FIX_FLAGS } from '../../data/contactPlayback.js';
import { createRailPathPack } from '../../data/railPaths.js';
import {
PATH_OFF_TRACK_M,
@@ -264,53 +265,41 @@ test('a report that runs back turns the drawn train only when playback does', ()
assert.equal(binding.direction, -1);
});
test('jitter segments played back at a standing train keep the direction it learnt', () => {
const p = pack();
const ids = { tripId: 'full', routeId: 'main' };
const binding = bindTrainPath(p, ids, fix(0, 1000, 0));
assert.ok(followFix(binding, fix(15_000, 1600, 0)));
let seq = 0;
const play = (fromM, toM, t0) => {
const { sample, segment } = playback(
seq,
seq + 1,
fix(t0, fromM, 0),
fix(t0 + 15_000, toM, 0),
0.5,
test('a jump to a corrected position in a new playback epoch is no reversal', () => {
const binding = bindTrainPath(
pack(),
{ tripId: 'full', routeId: 'main' },
fix(0, 1000, 0),
);
const play = (seq, from, to) =>
placeOnPath(
binding,
{ fromSeq: seq, toSeq: seq + 1, fraction: 0.5 },
{ from: { seq, ...from }, to: { seq: seq + 1, ...to } },
{},
);
assert.ok(placeOnPath(binding, sample, segment, {}));
seq += 1;
return binding.direction;
};
// It runs east, then stands at the platform: reports 3-5 m apart, back and
// forth, polled and played.
const learnt = [play(1000, 1600, 0)];
let t0 = 15_000;
for (const [fromM, toM] of [
[1600, 1597],
[1597, 1600],
[1600, 1596],
[1596, 1601],
]) {
assert.ok(followFix(binding, fix(t0 + 15_000, toM, 0)));
learnt.push(play(fromM, toM, t0));
t0 += 15_000;
}
assert.deepEqual(learnt, [1, 1, 1, 1, 1], 'from the played-back segments');
});
test('GPS jitter in the newest reports before playback keeps the direction', () => {
const p = pack();
const ids = { tripId: 'full', routeId: 'main' };
const binding = bindTrainPath(p, ids, fix(0, 1000, 0));
assert.ok(followFix(binding, fix(15_000, 1600, 0)));
assert.ok(play(0, fix(0, 1000, 0), fix(60_000, 1600, 0)));
assert.equal(binding.direction, 1);
const learnt = [];
[1597, 1600, 1596, 1601].forEach((eastM, i) => {
assert.ok(followFix(binding, fix(30_000 + i * 15_000, eastM, 0)));
learnt.push(binding.direction);
});
assert.deepEqual(learnt, [1, 1, 1, 1], 'from the newest reports');
// The source puts it back at 1400 m: a new epoch whose first report is a
// break, and no segment is played from 1600 m to there.
const epoch = { epoch: 1 };
assert.ok(
play(
5,
{ ...fix(70_000, 1400, 0), ...epoch, flags: FIX_FLAGS.BREAK },
{ ...fix(85_000, 1400, 0), ...epoch },
),
);
assert.equal(binding.direction, 1, 'standing there, it keeps its way');
// From there, a real move back still turns it.
assert.ok(
play(
6,
{ ...fix(85_000, 1400, 0), ...epoch },
{ ...fix(100_000, 1380, 0), ...epoch },
),
);
assert.equal(binding.direction, -1);
});
/** The direction after each played segment, `[fromM, toM]` 15 s apart. */
@@ -351,6 +340,30 @@ test('a train that moves under 15 m a report still tells its direction', () => {
);
});
test('a train turns 15 m back from where it ran to, not 14.9 m', () => {
const p = pack();
const ids = { tripId: 'full', routeId: 'main' };
for (const [backM, want, label] of [
[1100, -1, '15 m back'],
[1100.1, 1, '14.9 m back'],
]) {
const reports = bindTrainPath(p, ids, fix(0, 1000, 0));
const learnt = [1115, backM].map((eastM, i) => {
assert.ok(followFix(reports, fix((i + 1) * 15_000, eastM, 0)));
return reports.direction;
});
assert.deepEqual(learnt, [1, want], `${label}, from the newest reports`);
assert.deepEqual(
playDirections(bindTrainPath(p, ids, fix(0, 1000, 0)), [
[1000, 1115],
[1115, backM],
]),
[1, want],
`${label}, from the played-back segments`,
);
}
});
test('GPS jitter of up to 14 m at a standing train keeps its direction', () => {
const p = pack();
const ids = { tripId: 'full', routeId: 'main' };
@@ -372,4 +385,27 @@ test('GPS jitter of up to 14 m at a standing train keeps its direction', () => {
[1, 1, 1, 1, 1],
'from the played-back segments',
);
// On both sides of where it stopped: 8 m either way, 16 m from end to end.
const both = bindTrainPath(p, ids, fix(0, 600, 0));
assert.deepEqual(
[1000, 1008, 1000, 992, 1000, 1008].map((eastM, i) => {
assert.ok(followFix(both, fix((i + 1) * 15_000, eastM, 0)));
return both.direction;
}),
[1, 1, 1, 1, 1, 1],
'both sides, from the newest reports',
);
assert.deepEqual(
playDirections(bindTrainPath(p, ids, fix(0, 600, 0)), [
[600, 1000],
[1000, 1008],
[1008, 1000],
[1000, 992],
[992, 1000],
[1000, 1008],
]),
[1, 1, 1, 1, 1, 1],
'both sides, from the played-back segments',
);
});
+1 -4
View File
@@ -295,9 +295,6 @@ export function playbackModeFor(railMode) {
: 'rail';
}
/** Two reports closer than this are one place: a parked train's jitter (m). */
export const FOLLOW_MIN_MOVE_M = DIRECTION_MIN_M;
const lastFix = {};
const priorFix = {};
@@ -334,7 +331,7 @@ export function railTrainFollowable(entry) {
sample.nextMotionT > sample.displayT
)
return true;
return lastReportsApartM(entry.track) >= FOLLOW_MIN_MOVE_M;
return lastReportsApartM(entry.track) >= DIRECTION_MIN_M;
}
/**