feat(geo): add src/geo, Cesium's vector maths without Cesium

An engine-neutral port of the CesiumJS 1.138 core maths gev uses: angle
maths, the WGS84 ellipsoid and geodetic coordinates, 2D/3D vectors, 3x3/4x4
matrices, quaternions and local east-north-up / heading-pitch-roll frames.
Formulas and operation order match Cesium, so outputs are bit-identical
(golden tests pin the centre, pole, -0 and quaternion branches).

- Values are plain-data instances of module-private constructors (own
  enumerable fields only), so geo's hot functions keep their own V8 hidden
  classes; matrices are plain column-major arrays Cesium accepts.
- Cesium's debug argument checks are ported with the same conditions, order
  and DeveloperError messages, gated on DEBUG (src/geo/debug.js): on in Node
  and the dev server, folded away by vite build, as Cesium's Build strips
  them. A release-parity test compares DEBUG=false geo with Build/Cesium.
- The import-direction check forbids cesium and @cesium/* in src/geo;
  CODE-BOUNDARIES.md and THIRD_PARTY_NOTICES.md document the port.
This commit is contained in:
German Khokhlov committed 2026-10-15 00:15:20 +04:00
1 parent 132b9e96dc
commit 4a92ed8377
29 files changed
+4470 -6

No files matched your search

+142
View File
@@ -0,0 +1,142 @@
// src/geo/cartographic.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import * as cartographic from './cartographic.js';
const close = (a, b, tol, label) =>
assert.ok(
Math.abs(a - b) <= tol * Math.max(1, Math.abs(b)),
`${label}: ${a} vs ${b}`,
);
test('fromDegrees and fromRadians equal Cesium', () => {
for (const [lon, lat, h] of [
[0, 0, 0],
[-73.9857, 40.7484, 381],
[139.76, 35.68, -20],
[180, -90, 1e4],
]) {
const ours = cartographic.fromDegrees(lon, lat, h);
const theirs = Cesium.Cartographic.fromDegrees(lon, lat, h);
assert.deepEqual(
{ ...ours },
{
longitude: theirs.longitude,
latitude: theirs.latitude,
height: theirs.height,
},
);
}
});
test('fromCartesian and toCartesian equal Cesium, including the centre case', () => {
for (const [x, y, z] of [
[1334762.2, -4654869.1, 4137287.9],
[6378137, 0, 0],
[0.01, 0, 0],
]) {
const ours = cartographic.fromCartesian({ x, y, z });
const theirs = Cesium.Cartographic.fromCartesian(
new Cesium.Cartesian3(x, y, z),
);
if (theirs === undefined) {
assert.equal(ours, undefined);
continue;
}
close(ours.longitude, theirs.longitude, 1e-12, 'lon');
close(ours.latitude, theirs.latitude, 1e-12, 'lat');
close(ours.height, theirs.height, 1e-9, 'h');
const back = cartographic.toCartesian(ours);
const cBack = Cesium.Cartographic.toCartesian(theirs);
for (const k of ['x', 'y', 'z']) close(back[k], cBack[k], 1e-12, k);
}
});
test('result objects are reused', () => {
const out = cartographic.create();
assert.equal(cartographic.fromDegrees(1, 2, 3, out), out);
assert.equal(cartographic.clone(out).longitude, out.longitude);
});
const POLAR_RADIUS = 6356752.3142451793;
const sameFields = (ours, theirs, keys, label) => {
for (const k of keys) {
assert.ok(
Object.is(ours[k], theirs[k]),
`${label}.${k}: ${ours[k]} vs ${theirs[k]}`,
);
}
};
test('fromCartesian is undefined at the exact centre, as in Cesium', () => {
for (const [x, y, z] of [
[0, 0, 0],
[-0, -0, -0],
]) {
assert.equal(
Cesium.Cartographic.fromCartesian(new Cesium.Cartesian3(x, y, z)),
undefined,
);
assert.equal(cartographic.fromCartesian({ x, y, z }), undefined);
}
});
test('fromCartesian and toCartesian equal Cesium bit for bit at the poles and the antimeridian', () => {
for (const [x, y, z, label] of [
[0, 0, POLAR_RADIUS, 'north pole'],
[0, 0, -POLAR_RADIUS, 'south pole'],
[-6378137, 0, 0, 'antimeridian, y = +0'],
[-6378137, -0, 0, 'antimeridian, y = -0'],
[-6378137, -0, -0, 'antimeridian, y = z = -0'],
]) {
const ours = cartographic.fromCartesian({ x, y, z });
const theirs = Cesium.Cartographic.fromCartesian(
new Cesium.Cartesian3(x, y, z),
);
sameFields(ours, theirs, ['longitude', 'latitude', 'height'], label);
sameFields(
cartographic.toCartesian(ours),
Cesium.Cartographic.toCartesian(theirs),
['x', 'y', 'z'],
`${label} back`,
);
}
// atan2 keeps the sign of a zero y: +π on one side of the antimeridian, -π on the other.
assert.equal(
cartographic.fromCartesian({ x: -6378137, y: 0, z: 0 }).longitude,
Math.PI,
);
assert.equal(
cartographic.fromCartesian({ x: -6378137, y: -0, z: 0 }).longitude,
-Math.PI,
);
});
// layers/streetLevel/view.js passes a Cesium Ellipsoid (scene.globe.ellipsoid),
// which has no public `centerToleranceSquared`; geo then reads Cesium's private
// `_centerToleranceSquared`. This pins that coupling to a Cesium private field:
// if a Cesium upgrade renames it, the centre case below stops matching.
test('fromCartesian with a Cesium Ellipsoid equals Cesium, including the centre', () => {
const ellipsoid = Cesium.Ellipsoid.WGS84;
assert.equal(ellipsoid.centerToleranceSquared, undefined);
assert.equal(typeof ellipsoid._centerToleranceSquared, 'number');
for (const [x, y, z, label] of [
[0, 0, 0, 'centre'],
[0.1, 0.1, 0.1, 'inside the centre tolerance'],
[6378137, 0, 0, 'equator'],
[1334000, -4654000, 4138000, 'mid-latitude'],
[0, 0, POLAR_RADIUS + 500, 'above the north pole'],
]) {
const ours = cartographic.fromCartesian({ x, y, z }, ellipsoid);
const theirs = Cesium.Cartographic.fromCartesian(
new Cesium.Cartesian3(x, y, z),
ellipsoid,
);
if (theirs === undefined) {
assert.equal(ours, undefined, label);
continue;
}
sameFields(ours, theirs, ['longitude', 'latitude', 'height'], label);
}
});