Files
gods-eye-view/src/data/modelVisualAnchor.js
T
Sameh Khamis 5f98f8bdf3 Aircraft drawn as far behind real time as their feed is late, along one curve their trail follows
Civil and military aircraft were drawn a fixed 30 s (15 s) behind real time
while anonymous feed reports arrive about 90 s old every 30 s, so every
contact dead reckoned about a minute past its newest report and snapped
when the next one landed (several km on a turn), and the tracked trail,
recorded from those drawn positions and patched as reports arrived, kinked.

- The display delay (data/displayDelay.js) is the 90th percentile of the
  newest 256 report lags plus 5 s, between the layer's floor (30 s, 15 s)
  and five minutes, slewed at most 0.2 s/s up and 0.05 s/s down. Icons,
  the renderer's live motion clock, labels, HUD, detection, the tracked
  camera and the trail read the one delay; following the world clock
  draws with none and deliveries leave it alone.
- Between two reports an aircraft flies a biarc (data/fixCurve.js) that
  passes through both and leaves each along its track, sent as contract
  arc segments; the trail is the reports joined along the same curve, so
  the icon sits on it. Nothing drawn between reports is kept.
- A report a coasting contact missed is eased onto from where it would
  have been that frame (at least 3 s, at most 30% over its speed, within
  20 s); over 5 km it jumps. Past its newest report a contact coasts
  straight on: a turn rate averaged over earlier reports outlived the turn.
- Forward synthetic fixes no longer block real reports older than them,
  and a history keeps 24 fixes.
- A feed simulation (testSupport/aircraftFeedSim.mjs) checks both layers
  against a 90 s late feed, a fallback switch, repeated reports, outages
  and the world clock.
2026-11-14 00:31:29 -08:00

290 lines
14 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Model-space anchors on the aircraft layers' fleet models: where brackets
* and readouts sit (a model's visual centre) and where a tracked trail
* attaches (its aft-belly point, measured per model in fleetTrailAnchors.js
* and handed to the layers with each model's spec by fleetModels.js).
*
* Values are native model units in raw glTF axes; the trail anchors are
* turned into the placed model's frame here (`gltfToPlacedAxes`), so the
* layer's ENU placement applies to them. A fleet model's visual centre is its
* origin. Callers supply the scale the model is drawn at (`modelDrawnScale`),
* which the placement does not carry and which the pixel floor may raise
* above `scale`.
*/
/**
* How a model's raw glTF axes land in its placed frame, as the renderer
* draws a glTF model (`ModelItem`: Y-up, turned to Z-up, nose along the
* frame's own axis): raw glTF `[x, y, z]` becomes `[z, x, y]` in the frame
* `orientation` places. modelScale.test.mjs pins it against the Cesium
* renderer's own axis correction.
* @param {readonly number[]} v Raw glTF `[x, y, z]`.
* @returns {number[]} `[x, y, z]` in the placed frame.
*/
export const gltfToPlacedAxes = (v) => [v[2] || 0, v[0] || 0, v[1] || 0];
/**
* World position of a model-local anchor, through the same chain the model
* is drawn with: its placement `matrix` (column-major, the frame the layer
* posed it in) after the glTF axis turn (`gltfToPlacedAxes`), at the scale
* it is drawn at.
*
* This exists because doing it by hand got it wrong. The anchors used to be
* stored after a single glTF Y-up -> Z-up step (`[x, y, z]` -> `[x, -z, y]`) and
* multiplied straight by the placement. That is only half of the turn: the
* full one maps raw glTF `[x, y, z]` -> `[z, x, y]`. The aircraft's
* longitudinal axis is raw glTF X, so the old conversion put the aft offset on
* the RENDERED model's lateral axis — a 90-degree disagreement. Because the
* placement carries the heading, both frames rotated together and the offset
* came out sideways in world space, flipping which side it appeared on as the
* course changed. Measured on the live rig at N/E/S/W plus a helicopter: the
* old path put 81.47 m of a civil airliner's anchor entirely on cross-track
* with 0 aft, at every heading; this path puts 81.47 m aft with 0 cross.
*
* The anchors are therefore stored in RAW glTF coordinates and turned here,
* so exactly one convention stands between the table and the world.
*
* @param {ArrayLike<number>|null|undefined} matrix Where the model is placed.
* @param {readonly number[]} nativeAnchor Raw glTF `[x, y, z]` native-unit offset.
* @param {number} scale The scale the model is drawn at (`modelDrawnScale`).
* @param {{x:number,y:number,z:number}} result Mutable Cartesian-like result.
* @returns {{x:number,y:number,z:number}|null} World position of the anchor.
*/
export function modelAnchorWorld(matrix, nativeAnchor, scale, result) {
if (!matrix || !nativeAnchor || !result) return null;
return modelVisualAnchor(
matrix,
gltfToPlacedAxes(nativeAnchor),
scale,
result,
);
}
/**
* The scale a model is drawn at, by the draw contract's pixel rule: `scale`
* (capped by `maxScale`), raised so its bounding sphere spans `minPixelSize`
* pixels at the sphere's distance from the eye (its depth along the view
* direction, less its radius), and capped by `maxScale` again.
* @param {object} options
* @param {number} [options.scale] The item's `scale` (default 1). An item
* that also has `scaleByDistance` or `maxPixelSize` is drawn at a scale
* this does not model; aircraft models use neither.
* @param {number} [options.minPixelSize]
* @param {number} [options.maxScale]
* @param {number} options.radiusM The model's bounding radius at scale 1.
* @param {{x:number,y:number,z:number}} options.center Where it is placed.
* @param {{position: object, direction: object, fovy: number}|null} options.pose
* The camera pose (`camera.pose()`).
* @param {number} options.viewportHeightPx Drawn viewport height, CSS pixels.
* @param {number} [options.viewportWidthPx] Drawn viewport width, CSS pixels.
* @param {number} [options.pixelRatio] Drawing-buffer pixels per CSS pixel
* (default 1): the sphere's drawn size is capped at the drawing buffer's
* larger side, in its own pixels.
* @returns {number}
*/
export function modelDrawnScale({
scale = 1,
minPixelSize = 0,
maxScale,
radiusM,
center,
pose,
viewportHeightPx,
viewportWidthPx = viewportHeightPx,
pixelRatio = 1,
}) {
const capped = (s) => (Number.isFinite(maxScale) ? Math.min(maxScale, s) : s);
if (
!(minPixelSize > 0) ||
!(radiusM > 0) ||
!center ||
!pose?.position ||
!pose.direction ||
!(pose.fovy > 0) ||
!(viewportHeightPx > 0)
)
return capped(scale);
const sphereRadius = radiusM * capped(scale);
const depth = Math.abs(
(center.x - pose.position.x) * pose.direction.x +
(center.y - pose.position.y) * pose.direction.y +
(center.z - pose.position.z) * pose.direction.z,
);
const distance = Math.max(0, depth - sphereRadius);
const metresPerPixel =
(2 * distance * Math.tan(pose.fovy / 2)) / viewportHeightPx;
if (!(metresPerPixel > 0)) return capped(scale);
const diameterPx = Math.min(
(2 * sphereRadius) / metresPerPixel,
Math.max(viewportWidthPx || 0, viewportHeightPx) *
(pixelRatio > 0 ? pixelRatio : 1),
);
const drawn =
diameterPx < minPixelSize
? (minPixelSize * metresPerPixel) / (2 * radiusM)
: scale;
return capped(drawn);
}
/**
* Where a trail head segment should START being drawn: the whole segment, a
* shortened piece of it, or nothing at all.
*
* The head segment bridges the last displayed trail point to the aft-belly
* anchor. On a moving contact that point is a poll interval behind, so the
* segment arrives from open air and terminates ON the hull, which is what it
* should do. On a PARKED one it sits where the aircraft is: the segment
* degenerates into a line from inside the model out to its own anchor — a stick
* through half the fuselage on an aeroplane going nowhere. Grounded tracking
* starts a trail unconditionally, so every parked selection drew one.
*
* Three earlier cuts were wrong, and each is recorded because the shape of the
* mistake matters:
*
* - Testing segment LENGTH against the radius hid real trail. With
* an airliner model's 34.41 m radius and 24.09 m tail anchor, a prior fix 58 m
* aft gives a 33.98 m segment — under the radius, so suppressed — even
* though ~23.6 m of it is in open air behind the aircraft. It also made the
* whole segment pop in at once on crossing ~58.4 m.
* - CLIPPING the segment at the envelope boundary and keeping only what lay
* OUTSIDE fixed the pop but broke the thing the trail is for: a bounding
* sphere encloses a lot of empty space around a slender airframe, so
* trimming at sphere entry stops the trail visibly SHORT of the aircraft it
* is attached to. The head end is never cut. That end is the whole point.
* - CONTAINMENT — the whole segment when the start is outside the envelope,
* nothing when it is inside — kept both of those ends honest but decided it
* with a BOOLEAN, and a boolean at a 34.41 m boundary is a 10.33 m flash.
* Moving the start from 34.40 m to 34.42 m turned the entire segment on at
* once, and a contact whose next fix landed back inside turned it off again.
* Nothing in the world changes by 10 m across 2 cm of travel.
*
* So the far end MOVES and the near end does not. The drawn start slides along
* the segment, from the anchor itself out to the segment's true start, over the
* shell between the two lengths the model already defines:
*
* - the ANCHOR'S OWN STATION, `|anchor − centre|`. Inside that, the last body
* point is no further from the aircraft's centre than its own attachment
* point is, so every millimetre of the segment would be drawn forward of
* the anchor, into the fuselage. Nothing is drawn. A parked contact sits at
* exactly zero here, which is the case this whole guard exists for.
* - the ENVELOPE, `radiusM`. At and beyond it the segment is drawn in full,
* bit-identical to the containment rule it replaces — so every contact that
* has moved more than its own size (any airborne contact: 30 s of flight is
* kilometres) is completely unaffected by any of this.
*
* Between them the visible length grows continuously from zero, so a contact
* creeping across the boundary reveals its trail a few centimetres at a time
* and an in/out/in flap costs a few centimetres each way instead of ten metres.
*
* Scale-free rather than tuned: both ends of that shell come from the model —
* `radiusM` carries the drawn scale, so it tracks whatever
* `minPixelSize` inflated the model to, and the station comes from the
* anchor being drawn to.
*
* @param {{x:number,y:number,z:number}} start Segment start (last trail point).
* @param {{x:number,y:number,z:number}|null} anchor Segment end, world space —
* the aft-belly attachment point actually being drawn to.
* @param {{x:number,y:number,z:number}|null} center Model origin, world space.
* @param {number} radiusM Rendered bounding radius (nativeRadiusM x drawn scale).
* @param {{x:number,y:number,z:number}} result Mutable Cartesian-like result.
* @returns {{x:number,y:number,z:number}|null} The point to draw FROM, or null
* when the segment should not be drawn. May be `start` itself.
*/
export function trailHeadStart(start, anchor, center, radiusM, result) {
if (!start) return null;
// No envelope to judge against (no model drawing this contact, a radius we
// cannot trust, or nowhere to put the answer) — draw it all rather than lose
// a real trail.
if (!anchor || !center || !result) return start;
if (!Number.isFinite(radiusM) || radiusM <= 0) return start;
const startD = Math.hypot(
start.x - center.x,
start.y - center.y,
start.z - center.z,
);
if (startD >= radiusM) return start;
const anchorD = Math.hypot(
anchor.x - center.x,
anchor.y - center.y,
anchor.z - center.z,
);
// A degenerate shell (an anchor at or outside the envelope — no shipped asset
// has one, since every anchor is a measured hull point) leaves nothing to
// ramp across; fall back to the containment verdict rather than divide by it.
if (!(radiusM > anchorD)) return null;
const revealed = (startD - anchorD) / (radiusM - anchorD);
if (revealed <= 0) return null;
result.x = anchor.x + (start.x - anchor.x) * revealed;
result.y = anchor.y + (start.y - anchor.y) * revealed;
result.z = anchor.z + (start.z - anchor.z) * revealed;
return result;
}
/**
* The live head line from the last trail report through `points` (on the
* way to the aircraft) to `head`, as drawn: points inside the model's
* envelope are left out, and the link into the model slides as
* `trailHeadStart` decides (nothing on a contact that has not moved).
* @param {{x:number,y:number,z:number}} start The last body report.
* @param {Array<{x:number,y:number,z:number}>} points Between it and the head.
* @param {{x:number,y:number,z:number}} head The aircraft's trail anchor.
* @param {{x:number,y:number,z:number}|null} center Model origin, or null.
* @param {number|null} radiusM Rendered bounding radius.
* @param {{x:number,y:number,z:number}} result Scratch for the slid start.
* @returns {Array<{x:number,y:number,z:number}>} Empty when nothing is drawn.
*/
export function trailHeadLine(start, points, head, center, radiusM, result) {
const outside = (p) =>
!center ||
!(radiusM > 0) ||
Math.hypot(p.x - center.x, p.y - center.y, p.z - center.z) >= radiusM;
const line = [start];
for (const p of points) if (outside(p)) line.push(p);
// On a contact that has not moved the last link runs from inside the model
// out to its own anchor — a line through the fuselage. The END never gives,
// so a moving trail still terminates on the tail; the START is what
// slides, from nothing on a parked contact out to the whole link once it
// has cleared its own envelope.
const from = trailHeadStart(line.pop(), head, center, radiusM, result);
if (!from)
return line.length ? [...line, { x: head.x, y: head.y, z: head.z }] : [];
line.push(from === result ? { x: from.x, y: from.y, z: from.z } : from);
line.push({ x: head.x, y: head.y, z: head.z });
return line;
}
/**
* Transform a model-local visual centre into world coordinates without
* allocating. `modelMatrix` continues to own the model origin (including
* ground snapping); bracket/readout and trail consumers supply their own
* model-local anchor.
* @param {ArrayLike<number>} modelMatrix The placement, column-major 4x4.
* @param {readonly number[]} nativeCenter Placed-frame native-unit offset.
* @param {number} scale The drawn scale, applied outside the placement.
* @param {{x:number,y:number,z:number}} result Mutable Cartesian-like result.
* @returns {{x:number,y:number,z:number}|null} World visual centre.
*/
export function modelVisualAnchor(modelMatrix, nativeCenter, scale, result) {
if (!modelMatrix || !result) return null;
const safeScale = Number.isFinite(scale) ? scale : 1;
const x = (nativeCenter?.[0] || 0) * safeScale;
const y = (nativeCenter?.[1] || 0) * safeScale;
const z = (nativeCenter?.[2] || 0) * safeScale;
result.x =
modelMatrix[0] * x +
modelMatrix[4] * y +
modelMatrix[8] * z +
modelMatrix[12];
result.y =
modelMatrix[1] * x +
modelMatrix[5] * y +
modelMatrix[9] * z +
modelMatrix[13];
result.z =
modelMatrix[2] * x +
modelMatrix[6] * y +
modelMatrix[10] * z +
modelMatrix[14];
return result;
}