mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
src/globe/navara builds the GlobeEngine on a Navara 0.2.1 ThreeView. The engine keeps the camera pose in src/geo values and pushes it to Navara's setCamera in degrees (Cesium's heading/pitch/roll convention, S4); whatever Navara moves itself (user input, its flyTo arc) is read back from the drawn camera each frame. Projection, picks against the ellipsoid and the view rectangle are geo math on that pose, with Navara's fov kept on Cesium's 60° across the wider side. - flights: Navara flyTo in ms with mapped easings, cancelFlight via an empty setCamera, user input cancels a flight as in Cesium - events: moveStart/moveEnd (500 ms still)/changed from the pose - render: forceUpdate and animation (render on demand, S5) - surface: S2 CPU ray over 3D-tile meshes, Navara terrain fallback - maps: OSM/Esri raster, Re:Earth or ion quantized-mesh terrain, Google 3D tiles with a browser key and Google's logo - input: DOM pointer events with ScreenSpaceEventHandler semantics - the three private Navara members used live in internals.js, pinned to 0.2.1 by a test index.js builds the product view (MSAA 4, native pixel ratio, preserved drawing buffer, effects=minimal) for a dynamic import. The contract QA script gains --engine=navara on a dev-only harness page: 46/46 contract and 4/4 Navara checks; Cesium stays 53/53.
445 lines
16 KiB
JavaScript
445 lines
16 KiB
JavaScript
// Camera math for the Navara engine, on src/geo only: Cesium's heading/pitch/
|
||
// roll convention, the perspective projection and picks of a camera given as
|
||
// { position, direction, up, fovy, width, height } (Earth-fixed metres, unit
|
||
// vectors, vertical fov in radians, CSS pixels), Cesium's view rectangle and
|
||
// horizon test, and the Navara setCamera pose (degrees). Ported from the S4
|
||
// spike (src/bench/cameraConvention.js) and the contract's fake engine; the
|
||
// projection matches what Navara draws because the engine keeps Navara's
|
||
// camera on the same pose and fov.
|
||
|
||
import * as geo from '../../geo/index.js';
|
||
|
||
const { cartesian2, cartesian3, cartographic, math, matrix4 } = geo;
|
||
const WGS84 = geo.ellipsoid.WGS84;
|
||
const RADII = WGS84.radii;
|
||
const MAXIMUM_RADIUS = Math.max(RADII.x, RADII.y, RADII.z);
|
||
// The near/far planes of viewProjection (only its z row depends on them).
|
||
const NEAR = 1;
|
||
const FAR = 1e9;
|
||
// Cesium's MINIMUM_ZOOM (range for a radius-0 sphere) and the camera
|
||
// controller's default zoom distances.
|
||
const ZERO_RADIUS_SPHERE_RANGE = 100;
|
||
const MINIMUM_ZOOM_DISTANCE = 1;
|
||
const MAXIMUM_ZOOM_DISTANCE = Infinity;
|
||
// Cesium's default PerspectiveFrustum fov, across the wider canvas side.
|
||
const CESIUM_FOV = Math.PI / 3;
|
||
|
||
const copy3 = (value) => cartesian3.create(value.x, value.y, value.z);
|
||
const scaled = (vector, scalar) =>
|
||
cartesian3.multiplyByScalar(vector, scalar, cartesian3.create());
|
||
const sum = (...vectors) =>
|
||
vectors.reduce(
|
||
(total, vector) => cartesian3.add(total, vector, total),
|
||
cartesian3.create(),
|
||
);
|
||
const unit = (vector) => cartesian3.normalize(vector, cartesian3.create());
|
||
const cross = (left, right) =>
|
||
cartesian3.cross(left, right, cartesian3.create());
|
||
|
||
/** An angle in [0, 2π), as Cesium's camera reports heading and roll. */
|
||
export function wrapAngle(angle) {
|
||
const value = math.zeroToTwoPi(angle);
|
||
return value < 1e-12 || math.TWO_PI - value < 1e-12 ? 0 : value;
|
||
}
|
||
|
||
function localAxes(position) {
|
||
const frame = geo.transforms.eastNorthUpToFixedFrame(position, WGS84);
|
||
return {
|
||
east: cartesian3.create(frame[0], frame[1], frame[2]),
|
||
north: cartesian3.create(frame[4], frame[5], frame[6]),
|
||
up: cartesian3.create(frame[8], frame[9], frame[10]),
|
||
};
|
||
}
|
||
const combine = (axes, e, n, u) =>
|
||
sum(scaled(axes.east, e), scaled(axes.north, n), scaled(axes.up, u));
|
||
const toLocal = (axes, vector) => ({
|
||
e: cartesian3.dot(vector, axes.east),
|
||
n: cartesian3.dot(vector, axes.north),
|
||
u: cartesian3.dot(vector, axes.up),
|
||
});
|
||
|
||
/**
|
||
* Direction and up for heading/pitch/roll (radians) in the local frame at
|
||
* `position`, as Cesium's setView builds them: heading 0 looks north and turns
|
||
* clockwise, positive pitch looks up, positive roll tilts up to the right.
|
||
*/
|
||
export function orientationVectors(position, heading, pitch, roll) {
|
||
const axes = localAxes(position);
|
||
const cosPitch = Math.cos(pitch);
|
||
const direction = combine(
|
||
axes,
|
||
Math.sin(heading) * cosPitch,
|
||
Math.cos(heading) * cosPitch,
|
||
Math.sin(pitch),
|
||
);
|
||
const levelRight = combine(axes, Math.cos(heading), -Math.sin(heading), 0);
|
||
const levelUp = cross(levelRight, direction);
|
||
const up = sum(
|
||
scaled(levelUp, Math.cos(roll)),
|
||
scaled(levelRight, Math.sin(roll)),
|
||
);
|
||
return { direction: unit(direction), up: unit(up) };
|
||
}
|
||
|
||
/**
|
||
* Cesium's camera heading/pitch/roll getters: heading and roll in [0, 2π);
|
||
* within 1e-3 of straight up or down roll is 0 and heading follows `up`.
|
||
*/
|
||
export function headingPitchRoll(position, direction, up) {
|
||
const axes = localAxes(position);
|
||
const d = toLocal(axes, direction);
|
||
const u = toLocal(axes, up);
|
||
const r = toLocal(axes, cross(direction, up));
|
||
const vertical = Math.abs(Math.abs(d.u) - 1) <= 1e-3;
|
||
const raw = vertical
|
||
? Math.atan2(u.n, u.e) - math.PI_OVER_TWO
|
||
: Math.atan2(d.n, d.e) - math.PI_OVER_TWO;
|
||
return {
|
||
heading: wrapAngle(math.TWO_PI - math.zeroToTwoPi(raw)),
|
||
pitch: math.PI_OVER_TWO - Math.acos(math.clamp(d.u, -1, 1)),
|
||
roll: vertical ? 0 : wrapAngle(Math.atan2(-r.u, u.u)),
|
||
};
|
||
}
|
||
|
||
/**
|
||
* The Navara setCamera/flyTo pose for a camera pose: the eye's longitude,
|
||
* latitude and ellipsoid height, and the same heading/pitch/roll in degrees
|
||
* (Navara 0.2.1 uses Cesium's convention, S4), heading in [0, 360) and roll
|
||
* in (−180, 180].
|
||
*/
|
||
export function navaraPose(position, direction, up) {
|
||
const place = cartographic.fromCartesian(position, WGS84);
|
||
const angles = headingPitchRoll(position, direction, up);
|
||
let roll = math.toDegrees(angles.roll);
|
||
if (roll > 180) roll -= 360;
|
||
return {
|
||
lng: math.toDegrees(place.longitude),
|
||
lat: math.toDegrees(place.latitude),
|
||
height: place.height,
|
||
heading: math.toDegrees(angles.heading),
|
||
pitch: math.toDegrees(angles.pitch),
|
||
roll,
|
||
};
|
||
}
|
||
|
||
/** Cesium's vertical fov for a canvas: 60° across the wider side. */
|
||
export function cesiumFovy(width, height) {
|
||
return width > height
|
||
? 2 * Math.atan(Math.tan(CESIUM_FOV / 2) * (height / width))
|
||
: CESIUM_FOV;
|
||
}
|
||
|
||
const aspectOf = (camera) => camera.width / camera.height;
|
||
const rightOf = (camera) => unit(cross(camera.direction, camera.up));
|
||
|
||
/** Window position (CSS px) of a world point; undefined behind the camera. */
|
||
export function projectToWindow(camera, position, result) {
|
||
const offset = cartesian3.subtract(
|
||
position,
|
||
camera.position,
|
||
cartesian3.create(),
|
||
);
|
||
const depth = cartesian3.dot(offset, camera.direction);
|
||
if (!(depth > 0)) return undefined;
|
||
const tangent = Math.tan(camera.fovy / 2);
|
||
const ndcX =
|
||
cartesian3.dot(offset, rightOf(camera)) /
|
||
(depth * tangent * aspectOf(camera));
|
||
const ndcY = cartesian3.dot(offset, camera.up) / (depth * tangent);
|
||
const x = ((ndcX + 1) / 2) * camera.width;
|
||
const y = ((1 - ndcY) / 2) * camera.height;
|
||
if (!result) return cartesian2.create(x, y);
|
||
result.x = x;
|
||
result.y = y;
|
||
return result;
|
||
}
|
||
|
||
/** World → clip matrix consistent with projectToWindow (column-major). */
|
||
export function viewProjection(camera, result = matrix4.create()) {
|
||
const f = 1 / Math.tan(camera.fovy / 2);
|
||
const rows = [
|
||
[rightOf(camera), f / aspectOf(camera)],
|
||
[camera.up, f],
|
||
];
|
||
const D = camera.direction;
|
||
const P = camera.position;
|
||
for (const [row, [axis, scale]] of rows.entries()) {
|
||
result[row] = axis.x * scale;
|
||
result[4 + row] = axis.y * scale;
|
||
result[8 + row] = axis.z * scale;
|
||
result[12 + row] = -cartesian3.dot(axis, P) * scale;
|
||
}
|
||
// Eye z is −direction·(p − position); clip.w = −z_eye.
|
||
const A = (FAR + NEAR) / (NEAR - FAR);
|
||
const B = (2 * FAR * NEAR) / (NEAR - FAR);
|
||
result[2] = -D.x * A;
|
||
result[6] = -D.y * A;
|
||
result[10] = -D.z * A;
|
||
result[14] = cartesian3.dot(D, P) * A + B;
|
||
result[3] = D.x;
|
||
result[7] = D.y;
|
||
result[11] = D.z;
|
||
result[15] = -cartesian3.dot(D, P);
|
||
return result;
|
||
}
|
||
|
||
/** The unit ray from the eye through a window position (CSS px). */
|
||
export function pickRay(camera, screen) {
|
||
const tangent = Math.tan(camera.fovy / 2);
|
||
const ndcX = (2 * screen.x) / camera.width - 1;
|
||
const ndcY = 1 - (2 * screen.y) / camera.height;
|
||
const direction = sum(
|
||
camera.direction,
|
||
scaled(rightOf(camera), ndcX * tangent * aspectOf(camera)),
|
||
scaled(camera.up, ndcY * tangent),
|
||
);
|
||
return { origin: copy3(camera.position), direction: unit(direction) };
|
||
}
|
||
|
||
/** Nearest intersection of a ray with the WGS84 ellipsoid, if any. */
|
||
export function intersectEllipsoid(origin, direction) {
|
||
const o = [origin.x / RADII.x, origin.y / RADII.y, origin.z / RADII.z];
|
||
const d = [
|
||
direction.x / RADII.x,
|
||
direction.y / RADII.y,
|
||
direction.z / RADII.z,
|
||
];
|
||
const a = d[0] * d[0] + d[1] * d[1] + d[2] * d[2];
|
||
const b = 2 * (o[0] * d[0] + o[1] * d[1] + o[2] * d[2]);
|
||
const c = o[0] * o[0] + o[1] * o[1] + o[2] * o[2] - 1;
|
||
const discriminant = b * b - 4 * a * c;
|
||
if (discriminant < 0) return undefined;
|
||
const root = Math.sqrt(discriminant);
|
||
const nearest = (-b - root) / (2 * a);
|
||
const t = nearest > 0 ? nearest : (-b + root) / (2 * a);
|
||
if (!(t > 0)) return undefined;
|
||
return sum(origin, scaled(direction, t));
|
||
}
|
||
|
||
/** Cesium's camera.pickEllipsoid for a window position. */
|
||
export function pickEllipsoid(camera, screen) {
|
||
return intersectEllipsoid(camera.position, pickRay(camera, screen).direction);
|
||
}
|
||
|
||
/** Cesium's EllipsoidalOccluder.isPointVisible from `eye`. */
|
||
export function horizonVisible(eye, position) {
|
||
const camera = cartesian3.create(
|
||
eye.x / RADII.x,
|
||
eye.y / RADII.y,
|
||
eye.z / RADII.z,
|
||
);
|
||
const limbSquared = cartesian3.magnitudeSquared(camera) - 1;
|
||
const target = cartesian3.create(
|
||
position.x / RADII.x,
|
||
position.y / RADII.y,
|
||
position.z / RADII.z,
|
||
);
|
||
const vt = cartesian3.subtract(target, camera, cartesian3.create());
|
||
const vtDotVc = -cartesian3.dot(vt, camera);
|
||
const occluded =
|
||
limbSquared < 0
|
||
? vtDotVc > 0
|
||
: vtDotVc > limbSquared &&
|
||
(vtDotVc * vtDotVc) / cartesian3.magnitudeSquared(vt) > limbSquared;
|
||
return !occluded;
|
||
}
|
||
|
||
// Cesium's computeHorizonQuad: four limb points around the eye's nadir, in the
|
||
// corner order upper-left, lower-left, lower-right, upper-right.
|
||
function horizonQuad(position) {
|
||
const q = cartesian3.create(
|
||
position.x / RADII.x,
|
||
position.y / RADII.y,
|
||
position.z / RADII.z,
|
||
);
|
||
const qMagnitude = cartesian3.magnitude(q);
|
||
const qUnit = unit(q);
|
||
let east;
|
||
let north;
|
||
if (cartesian3.equalsEpsilon(qUnit, cartesian3.UNIT_Z, math.EPSILON10)) {
|
||
east = cartesian3.create(0, 1, 0);
|
||
north = cartesian3.create(0, 0, 1);
|
||
} else {
|
||
east = unit(cross(cartesian3.UNIT_Z, qUnit));
|
||
north = unit(cross(qUnit, east));
|
||
}
|
||
const center = scaled(qUnit, 1 / qMagnitude);
|
||
const offset =
|
||
Math.sqrt(Math.max(0, cartesian3.magnitudeSquared(q) - 1)) / qMagnitude;
|
||
const point = (n, e) => {
|
||
const p = sum(center, scaled(north, n * offset), scaled(east, e * offset));
|
||
return cartesian3.create(p.x * RADII.x, p.y * RADII.y, p.z * RADII.z);
|
||
};
|
||
return [point(1, -1), point(-1, -1), point(-1, 1), point(1, 1)];
|
||
}
|
||
|
||
// Cesium's Rectangle.fromCartographicArray, including the antimeridian case.
|
||
function rectangleFromCartographics(points) {
|
||
let west = Infinity;
|
||
let east = -Infinity;
|
||
let westOverIDL = Infinity;
|
||
let eastOverIDL = -Infinity;
|
||
let south = Infinity;
|
||
let north = -Infinity;
|
||
for (const { longitude, latitude } of points) {
|
||
west = Math.min(west, longitude);
|
||
east = Math.max(east, longitude);
|
||
south = Math.min(south, latitude);
|
||
north = Math.max(north, latitude);
|
||
const adjusted = longitude >= 0 ? longitude : longitude + math.TWO_PI;
|
||
westOverIDL = Math.min(westOverIDL, adjusted);
|
||
eastOverIDL = Math.max(eastOverIDL, adjusted);
|
||
}
|
||
if (east - west > eastOverIDL - westOverIDL) {
|
||
west = westOverIDL > Math.PI ? westOverIDL - math.TWO_PI : westOverIDL;
|
||
east = eastOverIDL > Math.PI ? eastOverIDL - math.TWO_PI : eastOverIDL;
|
||
}
|
||
return { west, south, east, north };
|
||
}
|
||
|
||
// Whether the sphere around the Earth is wholly outside the view frustum.
|
||
function globeOutsideFrustum(camera) {
|
||
const toCentre = cartesian3.negate(camera.position, cartesian3.create());
|
||
const D = camera.direction;
|
||
const tanY = Math.tan(camera.fovy / 2);
|
||
const tanX = tanY * aspectOf(camera);
|
||
const R = rightOf(camera);
|
||
const U = camera.up;
|
||
const planes = [
|
||
[D, NEAR],
|
||
[unit(sum(scaled(R, -1), scaled(D, tanX))), 0],
|
||
[unit(sum(R, scaled(D, tanX))), 0],
|
||
[unit(sum(scaled(U, -1), scaled(D, tanY))), 0],
|
||
[unit(sum(U, scaled(D, tanY))), 0],
|
||
];
|
||
return planes.some(
|
||
([normal, offset]) =>
|
||
cartesian3.dot(normal, toCentre) - offset < -MAXIMUM_RADIUS,
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Cesium's Camera.computeViewRectangle (radians): undefined when the globe is
|
||
* outside the frustum, the whole globe when fewer than two canvas corners
|
||
* hit it, west > east across the antimeridian, opened to a pole the corners
|
||
* walk around.
|
||
*/
|
||
export function viewRectangle(camera) {
|
||
if (globeOutsideFrustum(camera)) return undefined;
|
||
const horizon = horizonQuad(camera.position);
|
||
let hits = 0;
|
||
const points = [
|
||
[0, 0],
|
||
[0, camera.height],
|
||
[camera.width, camera.height],
|
||
[camera.width, 0],
|
||
].map(([x, y], index) => {
|
||
const hit = pickEllipsoid(camera, cartesian2.create(x, y));
|
||
if (hit) hits++;
|
||
return cartographic.fromCartesian(hit ?? horizon[index], WGS84);
|
||
});
|
||
if (hits < 2)
|
||
return {
|
||
west: -Math.PI,
|
||
south: -math.PI_OVER_TWO,
|
||
east: Math.PI,
|
||
north: math.PI_OVER_TWO,
|
||
};
|
||
const rectangle = rectangleFromCartographics(points);
|
||
let travelled = 0;
|
||
let last = points[3].longitude;
|
||
for (const { longitude } of points) {
|
||
const step = Math.abs(longitude - last);
|
||
travelled += step > Math.PI ? math.TWO_PI - step : step;
|
||
last = longitude;
|
||
}
|
||
if (math.equalsEpsilon(Math.abs(travelled), math.TWO_PI, 1e-9)) {
|
||
rectangle.west = -Math.PI;
|
||
rectangle.east = Math.PI;
|
||
if (points[0].latitude >= 0) rectangle.north = math.PI_OVER_TWO;
|
||
else rectangle.south = -math.PI_OVER_TWO;
|
||
}
|
||
return rectangle;
|
||
}
|
||
|
||
/**
|
||
* Where a {west, south, east, north} destination is seen from, looking
|
||
* straight down: above the rectangle's centre, high enough for its wider
|
||
* side to fill the view (with a margin for curvature). Cesium fits the
|
||
* corners exactly; this framing is within a few percent of it.
|
||
*/
|
||
export function rectangleViewPosition(
|
||
{ west, south, east, north },
|
||
fovy,
|
||
aspect,
|
||
) {
|
||
const lonSpan = east >= west ? east - west : east + math.TWO_PI - west;
|
||
const longitude = math.negativePiToPi(west + lonSpan / 2);
|
||
const latitude = (south + north) / 2;
|
||
const tanY = Math.tan(fovy / 2);
|
||
const radius = WGS84.maximumRadius;
|
||
const widest =
|
||
south * north <= 0
|
||
? 1
|
||
: Math.cos(Math.min(Math.abs(south), Math.abs(north)));
|
||
const across =
|
||
1.05 *
|
||
Math.max(
|
||
(radius * widest * lonSpan) / 2 / (tanY * aspect),
|
||
(radius * (north - south)) / 2 / tanY,
|
||
);
|
||
return cartesian3.fromRadians(longitude, latitude, across, WGS84);
|
||
}
|
||
|
||
// The camera offset from a target for a HeadingPitchRange, in the target frame.
|
||
function offsetFromHeadingPitchRange(heading, pitch, range) {
|
||
const p = math.clamp(pitch, -math.PI_OVER_TWO, math.PI_OVER_TWO);
|
||
const cosPitch = Math.cos(p);
|
||
return cartesian3.create(
|
||
-Math.sin(heading) * cosPitch * range,
|
||
-Math.cos(heading) * cosPitch * range,
|
||
-Math.sin(p) * range,
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Cesium's lookAtTransform pose: the camera at `offset` in `frame`
|
||
* (a HeadingPitchRange or a Cartesian position), looking at the frame origin
|
||
* with the frame's +Z as up.
|
||
*/
|
||
export function lookAtFrame(frame, offset) {
|
||
const local =
|
||
'heading' in offset
|
||
? offsetFromHeadingPitchRange(offset.heading, offset.pitch, offset.range)
|
||
: copy3(offset);
|
||
const localDirection = unit(cartesian3.negate(local, cartesian3.create()));
|
||
let localRight = cross(localDirection, cartesian3.UNIT_Z);
|
||
if (cartesian3.magnitudeSquared(localRight) < math.EPSILON10)
|
||
localRight = copy3(cartesian3.UNIT_X);
|
||
localRight = unit(localRight);
|
||
const localUp = unit(cross(localRight, localDirection));
|
||
const vector = (value) =>
|
||
unit(matrix4.multiplyByPointAsVector(frame, value, cartesian3.create()));
|
||
return {
|
||
position: matrix4.multiplyByPoint(frame, local, cartesian3.create()),
|
||
direction: vector(localDirection),
|
||
up: vector(localUp),
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Cesium's flyToBoundingSphere default range: 100 m for a radius-0 sphere,
|
||
* otherwise the distance that fits the sphere in view, clamped to the
|
||
* camera controller's zoom distances.
|
||
*/
|
||
export function sphereRange(radius, fovy, aspect) {
|
||
if (radius === 0) return ZERO_RADIUS_SPHERE_RANGE;
|
||
const tanPhi = Math.tan(fovy / 2);
|
||
const tanTheta = aspect * tanPhi;
|
||
return math.clamp(
|
||
Math.max(radius / tanTheta, radius / tanPhi),
|
||
MINIMUM_ZOOM_DISTANCE,
|
||
MAXIMUM_ZOOM_DISTANCE,
|
||
);
|
||
}
|