Move the scene-reading icon orientation helpers into the Cesium adapter

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.
This commit is contained in:
Sameh Khamis committed 2026-11-08 05:49:05 -08:00
1 parent d8d6db4389
commit b6e94b8d93
14 files changed
+224 -206

No files matched your search

+1 -1
View File
@@ -1,7 +1,7 @@
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import test from 'node:test';
import { cameraPoseSignature } from '../../data/iconOrientation.js';
import { cameraPoseSignature } from '../cesium/iconOrientation.js';
import { poseSignature } from './poseSignature.js';
const pose = {
+191
View File
@@ -0,0 +1,191 @@
/**
* @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;
-1
View File
@@ -11,7 +11,6 @@
"src/data/detection.js",
"src/data/focusDeemphasis.js",
"src/data/geoImportPins.js",
"src/data/iconOrientation.js",
"src/input/dispatcher.js",
"src/input/sensorPick.js",
"src/layers/cctv/projection.js",