Files
gods-eye-view/src/geo/ellipsoid.js
T
Sameh Khamis e32988ae5e Match Cesium's fromDegrees exactly and keep toEcef in the stub
fromRadians divides by gamma as Cesium does, so geodetic to ECEF is now
bit for bit Cesium's, and the test checks it exactly. Its tests also
cover three height bands, points inside the Earth and NaN input. toEcef
reads the renderer contract's Position, so it moves to the stub's maths.
The ellipsoid docs pair each conversion with Cesium's.
2026-11-05 14:28:10 -08:00

152 lines
5.3 KiB
JavaScript

/**
* @module geo/ellipsoid
* @description The WGS84 ellipsoid: geodetic and Earth-centred, Earth-fixed
* (ECEF) conversions, surface normals and projection onto the surface. The
* formulas follow the default renderer's step for step, so they agree with
* it to floating-point noise.
*
* Into ECEF, positions are arguments (`fromDegrees(lon, lat, height)`,
* `fromRadians` likewise); out of it, objects (`toLonLatH` gives
* `{lon, lat, height}` in degrees, `toCartographicRadians` the same in
* radians). Cesium's `Cartographic.fromDegrees(lon, lat, h)` is plain
* `{lon: toRadians(lon), lat: toRadians(lat), height: h}`; for its ECEF
* point, use `fromDegrees`.
*
* NaN in gives NaN fields out, never a throw (Cesium's debug build throws).
* The Earth's centre, and points so near it that their squares round to
* zero, answer null, as Cesium answers undefined.
*/
import {
add,
dot,
magnitude,
normalize,
scale,
sub,
toDegrees,
toRadians,
vec,
} from './vector.js';
export const WGS84 = Object.freeze({
radii: Object.freeze({ x: 6378137.0, y: 6378137.0, z: 6356752.3142451793 }),
radiiSquared: Object.freeze({
x: 6378137.0 * 6378137.0,
y: 6378137.0 * 6378137.0,
z: 6356752.3142451793 * 6356752.3142451793,
}),
oneOverRadii: Object.freeze({
x: 1 / 6378137.0,
y: 1 / 6378137.0,
z: 1 / 6356752.3142451793,
}),
oneOverRadiiSquared: Object.freeze({
x: 1 / (6378137.0 * 6378137.0),
y: 1 / (6378137.0 * 6378137.0),
z: 1 / (6356752.3142451793 * 6356752.3142451793),
}),
});
const EPSILON12 = 1e-12;
const CENTER_TOLERANCE_SQUARED = 0.1;
export function geodeticSurfaceNormal(p) {
const o = WGS84.oneOverRadiiSquared;
return normalize(vec(p.x * o.x, p.y * o.y, p.z * o.z));
}
function geodeticSurfaceNormalCartographic(lon, lat) {
const cosLat = Math.cos(lat);
return normalize(
vec(cosLat * Math.cos(lon), cosLat * Math.sin(lon), Math.sin(lat)),
);
}
/** Geodetic radians and metres to ECEF. */
export function fromRadians(lon, lat, height = 0) {
const n = geodeticSurfaceNormalCartographic(lon, lat);
const r = WGS84.radiiSquared;
let k = vec(r.x * n.x, r.y * n.y, r.z * n.z);
const gamma = Math.sqrt(dot(n, k));
k = vec(k.x / gamma, k.y / gamma, k.z / gamma);
return add(k, scale(n, height));
}
/** Geodetic degrees and metres to ECEF. */
export const fromDegrees = (lon, lat, height = 0) =>
fromRadians(toRadians(lon), toRadians(lat), height);
/** The point on the ellipsoid along the geodetic normal, or null at the centre. */
export function scaleToGeodeticSurface(p) {
const { x: positionX, y: positionY, z: positionZ } = p;
const oneOverRadiiX = WGS84.oneOverRadii.x;
const oneOverRadiiY = WGS84.oneOverRadii.y;
const oneOverRadiiZ = WGS84.oneOverRadii.z;
const x2 = positionX * positionX * oneOverRadiiX * oneOverRadiiX;
const y2 = positionY * positionY * oneOverRadiiY * oneOverRadiiY;
const z2 = positionZ * positionZ * oneOverRadiiZ * oneOverRadiiZ;
const squaredNorm = x2 + y2 + z2;
const ratio = Math.sqrt(1.0 / squaredNorm);
const intersection = scale(p, ratio);
if (squaredNorm < CENTER_TOLERANCE_SQUARED)
return Number.isFinite(ratio) ? intersection : null;
const oneOverRadiiSquaredX = WGS84.oneOverRadiiSquared.x;
const oneOverRadiiSquaredY = WGS84.oneOverRadiiSquared.y;
const oneOverRadiiSquaredZ = WGS84.oneOverRadiiSquared.z;
const gradient = vec(
intersection.x * oneOverRadiiSquaredX * 2.0,
intersection.y * oneOverRadiiSquaredY * 2.0,
intersection.z * oneOverRadiiSquaredZ * 2.0,
);
let lambda = ((1.0 - ratio) * magnitude(p)) / (0.5 * magnitude(gradient));
let correction = 0.0;
let func, denominator, xMultiplier, yMultiplier, zMultiplier;
let xMultiplier2, yMultiplier2, zMultiplier2;
let xMultiplier3, yMultiplier3, zMultiplier3;
do {
lambda -= correction;
xMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredX);
yMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredY);
zMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredZ);
xMultiplier2 = xMultiplier * xMultiplier;
yMultiplier2 = yMultiplier * yMultiplier;
zMultiplier2 = zMultiplier * zMultiplier;
xMultiplier3 = xMultiplier2 * xMultiplier;
yMultiplier3 = yMultiplier2 * yMultiplier;
zMultiplier3 = zMultiplier2 * zMultiplier;
func = x2 * xMultiplier2 + y2 * yMultiplier2 + z2 * zMultiplier2 - 1.0;
denominator =
x2 * xMultiplier3 * oneOverRadiiSquaredX +
y2 * yMultiplier3 * oneOverRadiiSquaredY +
z2 * zMultiplier3 * oneOverRadiiSquaredZ;
const derivative = -2.0 * denominator;
correction = func / derivative;
} while (Math.abs(func) > EPSILON12);
return vec(
positionX * xMultiplier,
positionY * yMultiplier,
positionZ * zMultiplier,
);
}
/** ECEF to geodetic `{lon, lat}` radians and `height` metres, or null at the centre. */
export function toCartographicRadians(p) {
const surface = scaleToGeodeticSurface(p);
if (!surface) return null;
const n = geodeticSurfaceNormal(surface);
const h = sub(p, surface);
return {
lon: Math.atan2(n.y, n.x),
lat: Math.asin(n.z),
height: Math.sign(dot(h, p)) * magnitude(h),
};
}
/** ECEF to `{lon, lat}` degrees and `height` metres. */
export function toLonLatH(p) {
const c = toCartographicRadians(p);
if (!c) return null;
return { lon: toDegrees(c.lon), lat: toDegrees(c.lat), height: c.height };
}