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

+49
View File
@@ -0,0 +1,49 @@
// Ported from CesiumJS 1.138 (Apache-2.0) — Cartesian2.js
//
// 2D vectors (screen coordinates) as plain-data {x, y} objects. With DEBUG on
// (development and tests; see debug.js) invalid arguments throw the same
// DeveloperError as Cesium's debug checks.
//
// Geo values are not Object.prototype objects, so src/app/stateChannel.js
// copyState and src/director/documentFields.js jsonTree reject them: copy
// the fields into a literal before putting one into product state or a
// scene document.
import { DEBUG } from './debug.js';
import { Check } from './check.js';
// Values are instances of a module-private constructor rather than object
// literals: every `{x, y}` literal in the process shares one V8 hidden
// class, and code elsewhere that builds such literals would make geo's hot
// functions polymorphic. The instances still look like plain data: own
// enumerable fields only, no prototype methods or getters.
function Vector2(x, y) {
this.x = x;
this.y = y;
}
/** A vector (Cesium's `new Cartesian2(x, y)`). */
export function create(x, y) {
return new Vector2(x ?? 0.0, y ?? 0.0);
}
/** Copies a vector; `undefined` when there is none. */
export function clone(cartesian, result) {
if (cartesian == null) return undefined;
if (result == null) return create(cartesian.x, cartesian.y);
result.x = cartesian.x;
result.y = cartesian.y;
return result;
}
/** The distance between two points. */
export function distance(left, right) {
if (DEBUG) {
Check.typeOf.object('left', left);
Check.typeOf.object('right', right);
}
const x = left.x - right.x;
const y = left.y - right.y;
return Math.sqrt(x * x + y * y);
}