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

+9 -187
View File
@@ -2,7 +2,11 @@
* Shared icon-orientation + horizon helpers. Orientation and culling serve the
* moving-entity layers (commercial flights, military flights, AIS vessels);
* `skyBackdropFactor` serves the detection overlay, which needs the same
* silhouette geometry to know what a label is being read against.
* silhouette geometry to know what a label is being read against. The helpers
* that read the default renderer's scene or camera (`screenProjectedRotation`,
* `perspectiveProjectedRotation`, `horizonOccluder`, `cameraPoseSignature`)
* live in `src/render/cesium/iconOrientation.js`; the camera-basis rotation
* itself is `courseScreenRotation` in `screenRotation.js`.
*
* THE ORIENTATION PROBLEM (2026-06-10 playtest): billboards are camera-facing
* quads, so "point along the real-world course" must be computed in SCREEN
@@ -21,52 +25,11 @@
* keeps rotation continuous through tracked orbits; field evidence, not an
* unverified math swap, decides whether exact projection becomes preferred.
*/
import * as Cesium from 'cesium';
import { poseSignature } from '../render/camera/poseSignature.js';
import {
courseScreenRotation,
stabilizeScreenRotation,
} from './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 above; 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,
);
}
import { WGS84 } from '../geo/ellipsoid.js';
import { stabilizeScreenRotation } from './screenRotation.js';
export { stabilizeScreenRotation };
const _occluder = new Cesium.EllipsoidalOccluder(
Cesium.Ellipsoid.WGS84,
new Cesium.Cartesian3(),
);
/**
* Half-width of the crossfade band centred on the ellipsoid silhouette, in
* radians. ~1.1° per side: at the product's default 60° frustum on a 1280×800
@@ -76,7 +39,7 @@ const _occluder = new Cesium.EllipsoidalOccluder(
*/
export const HORIZON_FEATHER_RAD = 0.019;
const _wgs84OneOverRadii = Cesium.Ellipsoid.WGS84.oneOverRadii;
const _wgs84OneOverRadii = WGS84.oneOverRadii;
/**
* How much SKY sits behind a world point from this camera: 0 (planet behind)
@@ -88,7 +51,7 @@ const _wgs84OneOverRadii = Cesium.Ellipsoid.WGS84.oneOverRadii;
* ABOVE the ellipsoid the horizon is the tangent silhouette and the test is a
* genuine ray/ellipsoid hit test: 1 means the view ray through the point misses
* the planet entirely. Here the function is the exact complement of
* {@link horizonOccluder} — the occluder asks whether the planet is in FRONT of
* `horizonOccluder` (`src/render/cesium/iconOrientation.js`) — the occluder asks whether the planet is in FRONT of
* a point (cull it), this asks whether it is BEHIND (what a screen-space label
* anchored there is read against). For any point the occluder keeps, a ray that
* hits the ellipsoid must hit it beyond the point, so the hit/miss test alone
@@ -182,144 +145,3 @@ export function skyBackdropFactor(
// than steps, and the fade has no visible corner at either edge of the band.
return t * t * (3 - 2 * t);
}
/**
* 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;
+5 -3
View File
@@ -3,11 +3,13 @@ import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
HORIZON_FEATHER_RAD,
horizonOccluder,
screenProjectedRotation,
skyBackdropFactor,
stabilizeScreenRotation,
} from './iconOrientation.js';
import {
horizonOccluder,
screenProjectedRotation,
} from '../render/cesium/iconOrientation.js';
const equatorPosition = Cesium.Cartesian3.fromDegrees(0, 0, 0);
@@ -563,7 +565,7 @@ import {
PERSPECTIVE_BLEND_MIN_PX,
PERSPECTIVE_PROBE_M,
perspectiveProjectedRotation,
} from './iconOrientation.js';
} from '../render/cesium/iconOrientation.js';
/**
* A scene the exact projector accepts: 3D mode, a canvas, and a camera with a