mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
screenProjectedRotation, perspectiveProjectedRotation, horizonOccluder and cameraPoseSignature read a Cesium scene or camera, so they move unchanged to src/render/cesium/iconOrientation.js, where the CCTV, radio and transit rendering (still Cesium-bound) load them. src/data/iconOrientation.js keeps the label backdrop test and the rotation deadband, and leaves the Cesium allow-list. Local ADS-B computes its rotation from the camera port's axes with courseScreenRotation directly, the same answer without a stand-in scene. The ./aircraft package entry re-exports src/data/iconOrientation.js, so it no longer carries the four moved helpers or the PERSPECTIVE_* constants.
192 lines
7.2 KiB
JavaScript
192 lines
7.2 KiB
JavaScript
/**
|
||
* @module render/cesium/iconOrientation
|
||
* @description The icon orientation and horizon helpers that read a Cesium
|
||
* scene or camera: the camera-basis course rotation, the exact perspective
|
||
* rotation for surface contacts, the shared horizon occluder and the camera
|
||
* pose signature. Why the course is projected the way it is, and the
|
||
* engine-free pieces (`skyBackdropFactor`, `stabilizeScreenRotation`), are
|
||
* in `src/data/iconOrientation.js` and `src/data/screenRotation.js`.
|
||
*/
|
||
import * as Cesium from 'cesium';
|
||
import { poseSignature } from '../camera/poseSignature.js';
|
||
import { courseScreenRotation } from '../../data/screenRotation.js';
|
||
|
||
const _scratchEnu = new Cesium.Matrix4();
|
||
const _scratchForward = new Cesium.Cartesian3();
|
||
const _scratchWorldForward = new Cesium.Cartesian3();
|
||
|
||
/**
|
||
* Computes the billboard rotation (radians, CCW-positive, for
|
||
* alignedAxis = Cartesian3.ZERO) that points an icon along its real-world
|
||
* course in the stable camera-basis approximation described in
|
||
* `src/data/iconOrientation.js`; the
|
||
* scene's camera axes in `screenRotation.js`'s `courseScreenRotation`.
|
||
*
|
||
* @param {Cesium.Scene} scene - The scene (projection source).
|
||
* @param {Cesium.Cartesian3} position - Entity world position.
|
||
* @param {number} courseDeg - Course/track in degrees clockwise from north.
|
||
* @param {number|null} previous - Rotation to keep when projection is
|
||
* unavailable (off-screen/behind camera/degenerate).
|
||
* @returns {number|null} Rotation in radians, or `previous` when unknown.
|
||
*/
|
||
export function screenProjectedRotation(
|
||
scene,
|
||
position,
|
||
courseDeg,
|
||
previous = null,
|
||
) {
|
||
const camera = scene?.camera;
|
||
return courseScreenRotation(
|
||
camera && { right: camera.rightWC, up: camera.upWC },
|
||
position,
|
||
courseDeg,
|
||
previous,
|
||
);
|
||
}
|
||
|
||
const _occluder = new Cesium.EllipsoidalOccluder(
|
||
Cesium.Ellipsoid.WGS84,
|
||
new Cesium.Cartesian3(),
|
||
);
|
||
|
||
/**
|
||
* Returns the shared horizon occluder, updated to the camera's position.
|
||
* With the Cesium globe hidden (Google 3D tiles provide the planet) nothing
|
||
* writes far-side depth, so billboards must be horizon-culled manually.
|
||
* Call once per tick, then test points with occluder.isPointVisible(pos).
|
||
*
|
||
* @param {Cesium.Camera} camera - The scene camera.
|
||
* @returns {Cesium.EllipsoidalOccluder}
|
||
*/
|
||
export function horizonOccluder(camera) {
|
||
_occluder.cameraPosition = camera.positionWC;
|
||
return _occluder;
|
||
}
|
||
|
||
/**
|
||
* Cheap camera pose signature for "did the camera move" gating of rotation
|
||
* passes (position quantized to ~10m, angles to ~0.06 deg).
|
||
* @param {Cesium.Camera} camera - The scene camera.
|
||
* @returns {string}
|
||
*/
|
||
export function cameraPoseSignature(camera) {
|
||
return poseSignature({
|
||
position: camera.positionWC,
|
||
heading: camera.heading,
|
||
pitch: camera.pitch,
|
||
roll: camera.roll,
|
||
});
|
||
}
|
||
|
||
/**
|
||
* Meters ahead used by the exact projection below. Short on purpose: the point
|
||
* of a perspective projection is that it is LOCAL to the contact, and a two
|
||
* kilometre probe on a bus at six hundred metres would sample a part of the
|
||
* frustum the vehicle is nowhere near.
|
||
*/
|
||
const NEAR_PROBE_M = 30;
|
||
const _scratchProbe = new Cesium.Cartesian3();
|
||
const _scratchWindowAt = new Cesium.Cartesian2();
|
||
const _scratchWindowAhead = new Cesium.Cartesian2();
|
||
|
||
/**
|
||
* Billboard rotation for a SURFACE contact, projected exactly — perspective
|
||
* division included — instead of through the camera-basis approximation.
|
||
*
|
||
* `screenProjectedRotation` above deliberately projects the course vector onto
|
||
* the camera's right/up basis, which is orthographic: exact at the viewport
|
||
* centre and an approximation away from it. That is the right trade for
|
||
* aircraft, where the alternative loses continuity through a tracked orbit and
|
||
* the contacts are far enough away for the error to be small.
|
||
*
|
||
* It is the wrong trade for street-level vehicles. A probe with a real Cesium
|
||
* camera at 600 m and −45° pitch, on a northbound contact 350 m right of
|
||
* centre, put the orthographic answer at 0° where the true screen direction of
|
||
* travel was 22.5°. At that pitch and that range the vehicles fill the frame
|
||
* away from the centre, and every one of them points visibly wrong.
|
||
*
|
||
* So this projects two nearby world points through the actual view-projection
|
||
* and reads the angle between them on screen. When either point cannot be
|
||
* projected — behind the camera, off the frustum, degenerate — it falls back to
|
||
* the camera-basis answer rather than inventing one.
|
||
*
|
||
* @param {Cesium.Scene} scene The scene (projection source).
|
||
* @param {Cesium.Cartesian3} position Entity world position.
|
||
* @param {number} courseDeg Course in degrees clockwise from north.
|
||
* @param {number|null} previous Rotation to keep when projection is unavailable.
|
||
* @returns {number|null} Rotation in radians, or the fallback.
|
||
*/
|
||
export function perspectiveProjectedRotation(
|
||
scene,
|
||
position,
|
||
courseDeg,
|
||
previous = null,
|
||
) {
|
||
if (!scene?.camera || !position || !Number.isFinite(courseDeg)) {
|
||
return previous;
|
||
}
|
||
const courseRad = Cesium.Math.toRadians(courseDeg);
|
||
Cesium.Cartesian3.fromElements(
|
||
Math.sin(courseRad) * NEAR_PROBE_M,
|
||
Math.cos(courseRad) * NEAR_PROBE_M,
|
||
0,
|
||
_scratchForward,
|
||
);
|
||
const enu = Cesium.Transforms.eastNorthUpToFixedFrame(
|
||
position,
|
||
Cesium.Ellipsoid.WGS84,
|
||
_scratchEnu,
|
||
);
|
||
Cesium.Matrix4.multiplyByPointAsVector(
|
||
enu,
|
||
_scratchForward,
|
||
_scratchWorldForward,
|
||
);
|
||
Cesium.Cartesian3.add(position, _scratchWorldForward, _scratchProbe);
|
||
|
||
const at = Cesium.SceneTransforms.worldToWindowCoordinates(
|
||
scene,
|
||
position,
|
||
_scratchWindowAt,
|
||
);
|
||
const ahead = Cesium.SceneTransforms.worldToWindowCoordinates(
|
||
scene,
|
||
_scratchProbe,
|
||
_scratchWindowAhead,
|
||
);
|
||
if (!at || !ahead) {
|
||
return screenProjectedRotation(scene, position, courseDeg, previous);
|
||
}
|
||
const dx = ahead.x - at.x;
|
||
const dy = ahead.y - at.y;
|
||
const separation = Math.hypot(dx, dy);
|
||
// Window y grows downward; rotation 0 = icon pointing screen-up.
|
||
const exact = Math.atan2(-dx, -dy);
|
||
if (separation >= PERSPECTIVE_BLEND_MAX_PX) return exact;
|
||
// Below a pixel or so of separation the exact answer is dominated by
|
||
// projection noise, and above it the camera-basis answer is the wrong one
|
||
// by up to twenty-odd degrees. A hard cutoff between the two flipped a
|
||
// sprite by 23° for a 20 m change of camera altitude; the two answers are
|
||
// blended across the band instead, the short way round, so the rotation is
|
||
// continuous through it.
|
||
const basis = screenProjectedRotation(scene, position, courseDeg, previous);
|
||
if (!Number.isFinite(basis)) return exact;
|
||
if (separation <= PERSPECTIVE_BLEND_MIN_PX) return basis;
|
||
const weight =
|
||
(separation - PERSPECTIVE_BLEND_MIN_PX) /
|
||
(PERSPECTIVE_BLEND_MAX_PX - PERSPECTIVE_BLEND_MIN_PX);
|
||
const delta = Math.atan2(Math.sin(exact - basis), Math.cos(exact - basis));
|
||
return basis + delta * weight;
|
||
}
|
||
|
||
/**
|
||
* Probe separations (px) between which the exact and camera-basis answers
|
||
* are blended. At or below the floor the camera-basis answer is used alone;
|
||
* at or above the ceiling the exact one.
|
||
*/
|
||
export const PERSPECTIVE_BLEND_MIN_PX = 0.5;
|
||
export const PERSPECTIVE_BLEND_MAX_PX = 3;
|
||
|
||
/** Exported for tests: how far ahead the exact projection probes. */
|
||
export const PERSPECTIVE_PROBE_M = NEAR_PROBE_M;
|