feat(cockpit): ride the selected vessel from its bridge

With no aircraft tracked, Cockpit can ride the selected AIS vessel. Entry
needs only Live AIS Vessels and a selected vessel; C, double-click and the
entry buttons (reading BRIDGE with a ship icon) enter it, while voice stays
aircraft-only.

The eye sits on the AIS position at a representative bridge height for the
vessel's type family, looks along true heading and moves along course over
ground. The last fix is dead-reckoned for up to 180 s between the layer's
refreshes, and on rivers and lakes the waterline is read from the rendered
surface around the ship rather than the geoid.

The bridge HUD shows speed and course over ground, a straight heading
tape, window mullions, the AIS destination as a reported voyage and a
heading-up radar of nearby ships (3 to 24 NM). The arrow keys look around,
Home or 0 looks ahead again. The vessel layer hides the ridden ship's
sprite and card, ignores scene clicks while held, and returns the camera
to the vessel's map view on exit.
This commit is contained in:
Denis Groshev committed 2026-11-07 19:52:30 +01:00
1 parent 52187c91d1
commit 72112ecb45
58 files changed
+5313 -137

No files matched your search

+221 -9
View File
@@ -7,6 +7,15 @@ import {
cockpitUiUpdateDue,
slewHeading,
} from '../cockpitMath.js';
import {
VESSEL_DEAD_RECKON_MAX_S,
VESSEL_WATERLINE_REFRESH_MS,
deadReckonVesselFix,
vesselCameraProfile,
vesselWaterlineM,
waterlineProbePoints,
} from '../cockpitSubjects.js';
import { easeLook } from '../cockpitLook.js';
import {
COCKPIT_HEADING_SLEW_DPS,
COCKPIT_FORWARD_OFFSET_M,
@@ -44,6 +53,10 @@ export function update() {
}
const nowMs = performance.now();
if (this.subjectKind === 'vessel') {
updateVessel.call(this, nowMs);
return;
}
const info = this.readAircraftInfo();
// Adopt a newly selected track before the camera cadence gate. A context
@@ -86,17 +99,208 @@ export function update() {
placeCamera.call(this, target, info, nowMs, dtSec, AIRCRAFT_CAMERA_PROFILE);
}
/**
* The surface the ridden ship floats on: the layer's geoid sea surface, or
* the water read off the rendered scene when that sits higher (a river or
* lake above sea level). The read runs in the background every
* VESSEL_WATERLINE_REFRESH_MS. The full-detail read can take many seconds
* from cold tiles, so a new ship's first read starts from the tiles already
* on screen; until any read lands the sea surface stands. Only one
* full-detail read runs at a time (each is nine picks Cesium traverses
* every frame until it settles): while one is still running, a refresh
* reads the loaded tiles instead, and the slow read applies whenever it
* lands unless a newer one has.
* @param {{latitude: number, longitude: number}} [at] Where to read the
* water: the dead-reckoned position the camera rides.
* @returns {number} Ellipsoidal metres.
*/
function vesselSurfaceM(info, nowMs, at = info) {
const seaM = Number.isFinite(info.seaSurfaceHeightM)
? info.seaSurfaceHeightM
: 0;
const scene = this.viewer.scene;
let read =
this.vesselWaterline?.mmsi === info.mmsi ? this.vesselWaterline : null;
if (
typeof scene?.sampleHeightMostDetailed === 'function' &&
(!read || nowMs - read.sampledMs >= VESSEL_WATERLINE_REFRESH_MS)
) {
const probes = waterlineProbePoints(at.latitude, at.longitude).map(
({ lat, lon }) => Cesium.Cartographic.fromDegrees(lon, lat),
);
if (!read) {
read = {
mmsi: info.mmsi,
heightM: loadedWaterlineM(scene, probes, seaM),
sampledMs: nowMs,
// Full-detail reads by number: the last started, the last applied.
startedSeq: 0,
landedSeq: 0,
inFlight: false,
};
this.vesselWaterline = read;
} else {
read.sampledMs = nowMs;
if (read.inFlight) {
const loadedM = loadedWaterlineM(scene, probes, seaM);
if (Number.isFinite(loadedM)) read.heightM = loadedM;
}
}
if (!read.inFlight) readWaterline.call(this, read, scene, probes, seaM);
}
return read && Number.isFinite(read.heightM)
? Math.max(seaM, read.heightM)
: seaM;
}
/** Start one full-detail water read for `read`; its answer lands on it. */
function readWaterline(read, scene, probes, seaM) {
const seq = ++read.startedSeq;
read.inFlight = true;
Promise.resolve()
.then(() => scene.sampleHeightMostDetailed(probes))
.then(
(samples) => {
if (this.vesselWaterline !== read) return;
read.inFlight = false;
// However late it lands, it applies unless a newer read has.
if (seq <= read.landedSeq) return;
read.landedSeq = seq;
read.heightM = vesselWaterlineM(
seaM,
(samples || []).map((sample) => sample?.height),
);
},
() => {
if (this.vesselWaterline === read) read.inFlight = false;
},
);
}
/**
* The waterline from the tiles already loaded, read at once: a first answer
* while the full-detail read loads. Null when the scene cannot sample or no
* probe met loaded geometry: nothing sampled is no answer, not the sea, so it
* never undoes a river height a full read set.
*/
function loadedWaterlineM(scene, probes, seaM) {
if (typeof scene.sampleHeight !== 'function') return null;
if (scene.sampleHeightSupported === false) return null;
try {
const heights = probes.map((probe) => scene.sampleHeight(probe));
if (!heights.some(Number.isFinite)) return null;
return vesselWaterlineM(seaM, heights);
} catch {
return null;
}
}
/**
* Drive the bridge camera from the selected vessel. The vessel layer redraws
* a ship only when its feed refreshes, so the target is the last fix advanced
* along course over ground; the shared anchor smoothing then absorbs the
* correction each new fix brings.
*/
function updateVessel(nowMs) {
// Tracking an aircraft from the bridge clears the vessel selection; end the
// bridge and leave Cesium tracking with that aircraft.
if (this.viewer.trackedEntity?.position) {
this.exit({ restoreTracking: false });
return;
}
const info = this.readVesselInfo();
if (!info || info.mmsi !== this.subjectId) {
this.exit({ restoreTracking: false });
return;
}
if (
!cockpitUiUpdateDue(
nowMs,
this.lastCameraUpdateMs,
COCKPIT_CAMERA_UPDATE_MS,
)
)
return;
this.lastCameraUpdateMs = nowMs;
const fix = deadReckonVesselFix(
{
latitude: info.latitude,
longitude: info.longitude,
courseDeg: info.motionCourse,
speedMps: info.velocityMps,
fixEpochMs: info.fixEpochMs,
receivedAtMs: info.receivedAtMs,
feedEpochMs: info.feedEpochMs,
},
Date.now(),
);
const target = Cesium.Cartesian3.fromDegrees(
fix.longitude,
fix.latitude,
// Read the water where the ship is now, not at its last report.
vesselSurfaceM.call(this, info, nowMs, fix),
Cesium.Ellipsoid.WGS84,
this.scratchTarget,
);
// The target advances in wall-clock time, so the anchor must too: the
// aircraft path's 0.1 s step cap would leave a slow-frame or hitching bridge
// falling ever further behind its own ship.
const dtSec = Math.min(
VESSEL_DEAD_RECKON_MAX_S,
Math.max(0, (nowMs - this.lastFrameMs) / 1000),
);
this.lastFrameMs = nowMs;
if (Number.isFinite(info.track)) {
this.heading = slewHeading(
this.heading ?? info.track,
info.track,
COCKPIT_HEADING_SLEW_DPS * dtSec,
);
}
// Past the projection limit the target stops advancing; hold on it rather
// than let the inertial anchor sail on alone.
const projectionExpired =
Number.isFinite(fix.ageSec) && fix.ageSec > VESSEL_DEAD_RECKON_MAX_S;
// The look eases on its own clock: the anchor's step is capped differently.
this.lookView = easeLook(
this.lookView,
this.lookTarget,
nowMs - (this.lookLastMs || nowMs),
);
this.lookLastMs = nowMs;
// A ship reporting neither course nor heading has no direction to move
// in: its anchor stays on the fix, as the dead reckoning does.
const ridden = Number.isFinite(info.motionCourse)
? info
: { ...info, velocityMps: 0 };
placeCamera.call(
this,
target,
projectionExpired ? { ...ridden, stale: true } : ridden,
nowMs,
dtSec,
vesselCameraProfile(info),
this.lookView,
);
}
/**
* Place the camera for one update: advance the inertial anchor, clamp it and
* the eye against the rendered surface, and look along the slewed heading.
* @param {Cesium.Cartesian3} target Authoritative subject position.
* @param {object} info Subject info.
* @param {object} info Subject info; `motionCourse` (when present) is the
* direction the subject moves, otherwise it moves where it faces.
* @param {number} nowMs Frame time.
* @param {number} dtSec Seconds since the previous camera update.
* @param {{forwardM: number, upM: number, pitchDeg: number,
* minClearanceM: number}} profile Eye offsets for the subject kind.
* @param {?{yawDeg: number, pitchDeg: number}} [look] A bridge view turned
* off the bow: yaw relative to the heading and absolute pitch. It turns
* only the view; the eye and its motion keep the heading and course.
* Aircraft pass none and look along the heading at the profile pitch.
*/
function placeCamera(target, info, nowMs, dtSec, profile) {
function placeCamera(target, info, nowMs, dtSec, profile, look = null) {
if (!this.cockpitAnchorValid) {
Cesium.Cartesian3.clone(target, this.cockpitAnchor);
this.cockpitAnchorValid = true;
@@ -110,7 +314,15 @@ function placeCamera(target, info, nowMs, dtSec, profile) {
// 15/30-second interpolation and per-frame cache without exposing its
// sample-boundary corrections to the camera.
const headingRad = Cesium.Math.toRadians(this.heading ?? 0);
const pitchRad = Cesium.Math.toRadians(profile.pitchDeg);
const courseRad = Number.isFinite(info.motionCourse)
? Cesium.Math.toRadians(info.motionCourse)
: headingRad;
const pitchRad = Cesium.Math.toRadians(
look ? look.pitchDeg : profile.pitchDeg,
);
const viewHeadingRad = look
? Cesium.Math.toRadians((this.heading ?? 0) + look.yawDeg)
: headingRad;
const speedMps = Number.isFinite(info.velocityMps)
? Math.max(0, info.velocityMps)
: 0;
@@ -126,8 +338,8 @@ function placeCamera(target, info, nowMs, dtSec, profile) {
Cesium.Ellipsoid.WGS84,
this.scratchEnu,
);
this.scratchLocal.x = Math.sin(headingRad);
this.scratchLocal.y = Math.cos(headingRad);
this.scratchLocal.x = Math.sin(courseRad);
this.scratchLocal.y = Math.cos(courseRad);
this.scratchLocal.z = 0;
Cesium.Matrix4.multiplyByPointAsVector(
this.scratchEnu,
@@ -296,8 +508,8 @@ function placeCamera(target, info, nowMs, dtSec, profile) {
);
Cesium.Cartesian3.normalize(this.scratchHorizontal, this.scratchHorizontal);
this.scratchLocal.x = Math.sin(headingRad) * Math.cos(pitchRad);
this.scratchLocal.y = Math.cos(headingRad) * Math.cos(pitchRad);
this.scratchLocal.x = Math.sin(viewHeadingRad) * Math.cos(pitchRad);
this.scratchLocal.y = Math.cos(viewHeadingRad) * Math.cos(pitchRad);
this.scratchLocal.z = Math.sin(pitchRad);
Cesium.Matrix4.multiplyByPointAsVector(
this.scratchEnu,
@@ -306,8 +518,8 @@ function placeCamera(target, info, nowMs, dtSec, profile) {
);
Cesium.Cartesian3.normalize(this.scratchForward, this.scratchForward);
this.scratchLocal.x = -Math.sin(headingRad) * Math.sin(pitchRad);
this.scratchLocal.y = -Math.cos(headingRad) * Math.sin(pitchRad);
this.scratchLocal.x = -Math.sin(viewHeadingRad) * Math.sin(pitchRad);
this.scratchLocal.y = -Math.cos(viewHeadingRad) * Math.sin(pitchRad);
this.scratchLocal.z = Math.cos(pitchRad);
Cesium.Matrix4.multiplyByPointAsVector(
this.scratchEnu,