Compare commits

...
Author SHA1 Message Date
German Khokhlov ebf2686e2f Number the changelog fragment for #1786 2026-11-18 00:51:07 +04:00
German Khokhlov ec9d5c9e06 Describe the cockpit ride fixes and add their changelog entry 2026-11-17 19:30:47 +04:00
German Khokhlov a7d966ae7e Rail cockpit rides: no height on an unknown floor, a standing train keeps its direction
- railHeightM is null while the train is drawn on the ellipsoid (floor
  quality 0) instead of -1.5 m, so a view waits for the surface.
- An arc step between two reports tells which way a train runs only above
  15 m, the layer's parked-train jitter (FOLLOW_MIN_MOVE_M). GPS jitter of
  a standing train no longer flips the direction through the playback
  segments, which turned a ride 180 degrees every poll.
- drawDirection, a copy of direction, becomes a directionPlayed flag.
2026-11-17 19:30:47 +04:00
German Khokhlov 134138931f Transit cockpit rides: hide the held icon, end a hold with the layer, no ellipsoid height
- A held vehicle's icon is hidden through the renderer (setShown, then
  flushMarkers). The icon sets draw a marker only as last pushed, so the
  direct marker.show write left a parked vehicle's icon drawn under the
  view's eye.
- disable() ends the hold: turned off and on again, the vehicle shows and
  clicks and Escape reach the layer.
- Far above the ground a vehicle with no floor is drawn on the ellipsoid.
  Its snapshot now reports groundHeightM null there, as near the ground,
  instead of -1.5 m.
- The uneven-ground test also checks the snapshot mid-segment, where a
  blend of the two reports' floors would read about 55 m instead of 10 m.
2026-11-17 19:30:47 +04:00
10 changed files with 248 additions and 31 deletions

No files matched your search

@@ -0,0 +1,8 @@
- Fix rides on a Rail train or Transit vehicle for an application's Cockpit
subjects. A held parked vehicle no longer leaves its icon drawn under the
view, and turning Transit off ends a hold, so the vehicle shows again when
the layer is back on. A train or vehicle drawn on the ellipsoid while no
floor is known reports no height, so the view waits for the ground instead
of standing on the ellipsoid. A train standing at a platform keeps the way
it runs: GPS jitter of a few metres no longer turns the ride around
(German, @gekh, #1786).
+12 -7
View File
@@ -2768,8 +2768,9 @@ HUD view is.
The Rail layer offers a read API for such a view: `getSelectedTrain()` and
`getCockpitSubject()` (a snapshot of the train: where it is along its line,
which way it runs (`pathBinding.js` learns it), its rail height, speed as
reported or derived, position source, feed credit and stops, and
which way it runs (`pathBinding.js` learns it), its rail height (null while
no floor is known and it is drawn on the ellipsoid), speed as reported or
derived, position source, feed credit and stops, and
`selectedAtMs`, when the user last selected it by a click or `focusTrain`,
even again; null after a deselection and for a train only a hold selected),
`setCockpitSubject(key)` (its marker, 3D model and card hidden, the selection kept, its
@@ -2784,11 +2785,15 @@ offers the same for a vehicle (`getSelectedVehicle`, `getCockpitSubject`,
`setCockpitSubject`, `focusVehicle`): a held vehicle keeps playing when it is
out of the camera's view, and its sprite, 3D model, card, trail and detection
box are hidden; released, it is out of play until a visibility sweep finds it in
view. Its snapshot's `position.groundHeightM` is the floor where playback draws
it (the drawn marker's height while it is placed, else its segment's two
reports' floors at the playback fraction), not the newest report's, and null while that floor is unknown. Rail's `path.direction` is the
way the drawn train runs: once playback has placed it, a report that runs back
turns it only when playback reaches that report. `docs/APPLICATION.md` (Cockpit subjects) shows a minimal provider. `src/ui/cockpitSubjectView.test.mjs`,
view. Turning the layer off ends the hold. Its snapshot's
`position.groundHeightM` is the floor where playback draws it (the drawn
marker's height while it is placed, else its segment's two reports' floors at
the playback fraction), not the newest report's, and null while that floor is
unknown, also far above the ground, where such a vehicle is drawn on the
ellipsoid. Rail's `path.direction` is the way the drawn train runs: once
playback has placed it, a report that runs back turns it only when playback
reaches that report, and a step of at most 15 m between two reports (a standing
train's GPS jitter) keeps the direction it had. `docs/APPLICATION.md` (Cockpit subjects) shows a minimal provider. `src/ui/cockpitSubjectView.test.mjs`,
`src/cockpitSubjectProviders.test.mjs`, `src/cockpitProgress.test.mjs`,
`src/layers/rail/cockpitSubject.test.mjs` and the Transit lifecycle tests
cover them.
+4 -1
View File
@@ -205,7 +205,10 @@ export function createRailCockpitSubject({
finiteOrNull(drawn?.lat) ?? finiteOrNull(sample?.lat) ?? record.lat;
position.longitude =
finiteOrNull(drawn?.lon) ?? finiteOrNull(sample?.lon) ?? record.lon;
position.railHeightM = Number.isFinite(drawn?.h) ? drawn.h - liftM : null;
// Quality 0 is the ellipsoid a train is drawn on while no floor is
// known: no height, so a view waits for the surface.
position.railHeightM =
Number.isFinite(drawn?.h) && drawn.q > 0 ? drawn.h - liftM : null;
position.heightQuality = Number.isFinite(drawn?.q) ? drawn.q : 0;
position.atMs = finiteOrNull(drawn?.at);
+23 -1
View File
@@ -44,6 +44,13 @@ const PACK = Object.freeze({
routes: { R1: [0] },
});
/** A floor service that knows the ground everywhere, at 12 m. */
const WARM_GROUND = Object.freeze({
GROUND_FLOOR_LIFT_M: 1.5,
cachedGroundFloor: () => 12,
warmGroundFloor() {},
});
/** Two trains on the line, T1 running east and T2 west, a step a poll. */
async function onTheLine(t, options = {}) {
const app = harness(t, {
@@ -76,7 +83,7 @@ const T1 = railTrainKey('mbta-rail', 'T1');
const T2 = railTrainKey('mbta-rail', 'T2');
test('the selected train reads as a snapshot of its place, motion and sources', async (t) => {
const app = await onTheLine(t);
const app = await onTheLine(t, { ground: WARM_GROUND });
assert.equal(app.layer.getSelectedTrain(), null, 'nothing selected');
app.parts().selection.selectTrain(T1);
const view = app.layer.getSelectedTrain();
@@ -105,6 +112,7 @@ test('the selected train reads as a snapshot of its place, motion and sources',
assert.equal(view.provenance.positionSource, 'gps');
assert.equal(view.provenance.timestampSource, 'vehicle');
const drawn = app.entry(T1).drawnHeight;
assert.ok(view.position.heightQuality > 0, 'on a known floor');
assert.equal(view.position.railHeightM, drawn.h - 1.5);
assert.ok(Number.isFinite(view.position.latitude));
assert.ok(Array.isArray(view.stops));
@@ -129,6 +137,20 @@ const stopList = (...names) =>
state: 'upcoming',
}));
test('a train drawn on an unknown floor reports no rail height', async (t) => {
// The harness's floor service is always cold: the train is drawn on the
// ellipsoid, which is no floor for a view to stand on.
const app = await onTheLine(t);
app.parts().selection.selectTrain(T1);
const view = app.layer.getSelectedTrain();
assert.equal(view.position.heightQuality, 0, 'no floor is known');
assert.equal(
view.position.railHeightM,
null,
'an unknown floor is no height',
);
});
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, {
+15 -13
View File
@@ -47,8 +47,13 @@ export function pathWindowM(dtMs) {
return window > PATH_WINDOW_MAX_M ? NaN : window;
}
/** Arc moved between two reports before it says which way a train runs (m). */
const DIRECTION_MIN_M = 1;
/**
* Arc moved between two reports before it says which way a train runs (m).
* A standing train's GPS jitter, a few metres back and forth, stays under it
* (the same parked-train jitter as FOLLOW_MIN_MOVE_M, policy.js) and keeps
* the direction learnt.
*/
const DIRECTION_MIN_M = 15;
/** +1 or -1 for an arc step longer than DIRECTION_MIN_M, else `known`. */
function directionOf(step, known) {
@@ -65,13 +70,13 @@ function createBinding(shapeIndex, path, via, s, fix) {
/**
* 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. Once playback has placed the train, only playback changes
* it: the newest reports run ahead of the drawn train, so a reversal
* they show turns it when playback reaches it.
* 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,
/** The direction the last placed playback segment ran, 0 before one. */
drawDirection: 0,
directionPlayed: false,
/** Arc and time of the newest report. */
fixS: s,
fixT: fix.t,
@@ -159,7 +164,7 @@ export function followFix(binding, fix) {
pathWindowM(fix.t - binding.fixT),
);
if (!hit || hit.offsetM > PATH_OFF_TRACK_M) return false;
if (!binding.drawDirection)
if (!binding.directionPlayed)
binding.direction = directionOf(hit.s - binding.fixS, binding.direction);
binding.fixS = hit.s;
binding.fixT = fix.t;
@@ -253,11 +258,8 @@ export function placeOnPath(binding, sample, segment, out) {
cache.sTo = sTo;
cache.ok = Number.isFinite(sFrom) && Number.isFinite(sTo);
if (cache.ok) {
binding.drawDirection = directionOf(
sTo - sFrom,
binding.drawDirection || binding.direction || 0,
);
binding.direction = binding.drawDirection;
binding.direction = directionOf(sTo - sFrom, binding.direction);
if (binding.direction) binding.directionPlayed = true;
}
}
if (!cache.ok) return false;
+63 -2
View File
@@ -209,8 +209,9 @@ test('a binding learns which way its train runs, and keeps it through a stop', (
assert.equal(along.direction, 0, 'one report tells no direction');
assert.ok(followFix(along, fix(10_000, 700, 0)));
assert.equal(along.direction, 1);
// Standing still (under a metre) keeps what it learnt.
assert.ok(followFix(along, fix(20_000, 700.4, 0)));
// Standing at a stop, its reports jitter back a few metres: it keeps what
// it learnt.
assert.ok(followFix(along, fix(20_000, 690, 0)));
assert.equal(along.direction, 1);
const against = bindTrainPath(p, ids, fix(0, 1500, 0));
assert.ok(followFix(against, fix(10_000, 1200, 0)));
@@ -262,3 +263,63 @@ 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)));
// Playback runs the train east, 1000 m -> 1600 m: direction +1.
const out = {};
let seq = 0;
const play = (fromM, toM, t0) => {
const segment = {
from: { seq, ...fix(t0, fromM, 0) },
to: { seq: seq + 1, ...fix(t0 + 15_000, toM, 0) },
};
assert.ok(
placeOnPath(
binding,
{ fromSeq: seq, toSeq: seq + 1, fraction: 0.5 },
segment,
out,
),
);
seq += 1;
return binding.direction;
};
assert.equal(play(1000, 1600, 0), 1);
assert.equal(
binding.directionPlayed,
true,
'playback owns the direction now',
);
// At the platform: reports 3-5 m apart, back and forth, polled and played.
const learnt = [];
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], '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.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');
});
+14 -7
View File
@@ -84,12 +84,16 @@ export function createTransitCockpitSubject({ state, parts, services }) {
* or held), which near the ground follows the terrain between reports;
* else its segment's two reports' floors at the playback fraction. Null
* while either floor is unknown, as on cold terrain, so a view waits for
* the surface. Not `entry.heightM`, the floor at the newest report, which
* playback has not reached yet.
* the surface: far above the ground such a marker is drawn on the
* ellipsoid, which is no floor. Not `entry.heightM`, the floor at the
* newest report, which playback has not reached yet.
*/
function drawnFloorOf(entry) {
const segment = entry.segment;
if (!segment || entry.heightPending) return null;
const from = segment.from?.h;
const to = segment.to?.h;
if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
const placed =
entry.surfaceReady === true &&
entry.hasRendered &&
@@ -99,9 +103,6 @@ export function createTransitCockpitSubject({ state, parts, services }) {
const drawn = toCartographicRadians(entry.marker.position);
if (drawn) return drawn.height - liftM;
}
const from = segment.from?.h;
const to = segment.to?.h;
if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
const f = Number.isFinite(segment.fraction)
? Math.max(0, Math.min(1, segment.fraction))
: 1;
@@ -173,11 +174,17 @@ export function createTransitCockpitSubject({ state, parts, services }) {
return snapshot;
}
/** Show or hide a vehicle's sprite and trail for the hold. */
/**
* Show or hide a vehicle's sprite and trail for the hold. The sprite goes
* through the renderer (setShown, flushMarkers): its set draws a marker
* only as last pushed.
*/
function repaint(entry) {
if (!entry?.marker) return;
if (entry.key === state._cockpitSubjectKey) entry.marker.show = false;
if (entry.key === state._cockpitSubjectKey)
parts.rendering.setShown(entry, false);
else parts.rendering.placeSample(entry);
parts.rendering.flushMarkers();
parts.rendering.schedulePlayback(entry);
parts.trails.update();
state._detectRevision += 1;
+2
View File
@@ -165,6 +165,8 @@ export function createLifecycle({ state, services, parts }) {
state._visible.clear();
clearTimeout(state._cameraDebounceTimer);
state._cameraDebounceTimer = null;
// A hold ends with the layer (cockpitSubject.js).
state._cockpitSubjectKey = null;
parts.selection.clearSelection();
state._overlayHost.setVisible(TRANSIT_SELECTED_OVERLAY_SOURCE_ID, false);
parts.selection.removeClickHandler();
+106
View File
@@ -978,6 +978,34 @@ test('a held vehicle with no floor yet tells its view no height', async (t) => {
assert.equal(app.layer.getCockpitSubject().position.groundHeightM, null);
});
test('far above the ground, a held vehicle drawn on the ellipsoid tells its view no height', async (t) => {
// Above the height gate a vehicle with no floor is drawn on the ellipsoid
// at once, not held back; the ellipsoid is still no floor to stand a view
// on.
const app = harness(t, { altitude: 100_000, floorAt: () => undefined });
app.serve('mbta', () => ({
status: 200,
body: snapshot(
'mbta',
'MBTA',
[vehicle('bus-1', 42.36, -71.06, Date.now() / 1000)],
{ fetchedAt: Date.now() },
),
}));
app.layer.enable(app.viewer);
await app.layer.update();
app.settle();
const [entry] = app.vehicles();
assert.ok(app.layer.setCockpitSubject(entry.key) !== false);
app.frame();
assert.equal(entry.surfaceReady, true, 'it is drawn');
const drawnM = Cesium.Cartographic.fromCartesian(
entry.marker.position,
).height;
assert.ok(Math.abs(drawnM) < 1e-3, `on the ellipsoid, got ${drawnM} m`);
assert.equal(app.layer.getCockpitSubject().position.groundHeightM, null);
});
test('a vehicle waits for its floor rather than standing on the ellipsoid', async (t) => {
// The shared ground-floor system answers from the rendered mesh cell or the
// real DEM cell; until one of them is warm there is no honest height to draw
@@ -2125,6 +2153,11 @@ test('a segment climbs from the ground it left to the ground it reaches', async
Math.abs(height() - 11.5) < 3,
`at the corridor floor, got ${height().toFixed(1)} m`,
);
// The two reports' floors blended at the fraction would say about 55 m.
assert.ok(
Math.abs(floor() + 1.5 - height()) < 1,
`its snapshot stands on that floor too, got ${floor().toFixed(1)} m`,
);
app.run(TRANSIT_POLL_MS);
assert.ok(
Math.abs(height() - 101.5) < 1.5,
@@ -4880,3 +4913,76 @@ test('a held vehicle hides, keeps moving out of view, and lets go when it goes',
assert.equal(app.state()._cockpitSubjectKey, null);
assert.equal(app.layer.getCockpitSubject(), null);
});
test('turning Transit off ends a hold; on again, Escape deselects and the vehicle shows', async (t) => {
const app = harness(t);
const key = await busRunningNorth(app);
assert.equal(app.layer.setCockpitSubject(key), true);
app.layer.disable(app.viewer);
assert.equal(
app.state()._cockpitSubjectKey,
null,
'the hold ended with the layer',
);
// On again, without a release: the same bus is listed again.
app.layer.enable(app.viewer);
await app.layer.update();
app.settle();
app.run(TRANSIT_POLL_MS);
await app.layer.update();
app.settle();
assert.equal(app.layer.focusVehicle(key), true);
const [entry] = app.vehicles();
app.frame();
assert.equal(entry.marker.show, true, 'the vehicle is drawn, not held');
globalThis.document.dispatchEvent(
Object.assign(new Event('keydown'), { key: 'Escape' }),
);
assert.equal(app.state()._selectedKey, null, 'Escape deselects');
});
test('a held parked vehicle draws no icon; let go, it draws its icon again', async (t) => {
// A parked bus with no course: nothing moves or turns its icon, so only the
// hold itself can take the icon out of the set that draws it.
const app = harness(t);
app.serve('mbta', () => ({
status: 200,
body: snapshot(
'mbta',
'MBTA',
[vehicle('bus-1', 42.36, -71.06, reported(), { stopId: 'place-1' })],
{ fetchedAt: Date.now() },
),
}));
app.layer.enable(app.viewer);
await app.layer.update();
app.settle();
for (let i = 0; i < 3; i += 1) {
app.run(TRANSIT_POLL_MS);
await app.layer.update();
app.settle();
}
const key = 'mbta:bus-1';
const [entry] = app.vehicles();
const icon = () =>
app.markers('still').get(key) ?? app.markers('moving').get(key);
assert.equal(icon()?.show, true, 'drawn before the hold');
assert.equal(app.layer.setCockpitSubject(key), true);
// The view rides it for a while: frames, a sweep, a poll.
app.run(2_000, 16);
app.settle();
app.run(TRANSIT_POLL_MS);
await app.layer.update();
app.settle();
assert.equal(entry.marker.show, false, 'its marker is hidden');
assert.equal(
icon()?.show ?? false,
false,
'and so is the icon the set draws',
);
assert.equal(app.layer.setCockpitSubject(null), true);
app.advance(250);
app.settle();
assert.equal(icon()?.show, true, 'let go: drawn again');
});
+1
View File
@@ -1225,6 +1225,7 @@ export function createRendering({ state, services, parts }) {
setNameOf,
markerShown,
markDirty,
setShown,
flushMarkers,
removeMarker,
watchCamera,