cesiumjs-spatial-math
CesiumJS spatial math - Cartesian3, Cartographic, Matrix4, Quaternion, Transforms, Ellipsoid, BoundingSphere, projections, coordinate conversions. Use when converting between coordinate systems, computing positions on the ellipsoid, performing spatial intersection tests, building model matrices, or working with geographic projections.
CesiumGS · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add CesiumGS/cesiumjs-skills --skill cesiumjs-spatial-mathAbout this skill
name: cesiumjs-spatial-math description: "CesiumJS spatial math - Cartesian3, Cartographic, Matrix4, Quaternion, Transforms, Ellipsoid, BoundingSphere, projections, coordinate conversions. Use when converting between coordinate systems, computing positions on the ellipsoid, performing spatial intersection tests, building model matrices, or working with geographic projections."
CesiumJS Spatial Math & Transforms
Version baseline: CesiumJS v1.143 (2026-07-01)
Mathematical foundation for every CesiumJS application: coordinate types, unit conversions, ellipsoid geometry, reference frame transforms, bounding volumes, intersection tests, and projections.
Core Concepts
CesiumJS uses a right-handed Earth-Centered Earth-Fixed (ECEF) coordinate system:
- Cartesian3 -- ECEF (x, y, z) in meters. Internal representation for all 3D positions.
- Cartographic -- (longitude, latitude, height). Angles are radians, height in meters above ellipsoid.
All angular values in core math are radians. Use Math.toRadians() / Math.toDegrees(). Math types use a static-method-with-result pattern: pass a result parameter to reuse allocations.
Cartesian3 -- Positions and Vectors
import { Cartesian3, Math as CesiumMath } from "cesium";
// From lon/lat degrees -- most common entry point
const pos = Cartesian3.fromDegrees(-105.0, 40.0);
const elevated = Cartesian3.fromDegrees(-105.0, 40.0, 1500.0); // with height
// Batch creation: [lon, lat, lon, lat, ...]
const ring = Cartesian3.fromDegreesArray([-105, 40, -100, 40, -100, 35]);
// With heights: [lon, lat, h, lon, lat, h, ...]
const wall = Cartesian3.fromDegreesArrayHeights([-105, 40, 500, -100, 40, 1000]);
// From raw ECEF or from radians
const raw = new Cartesian3(-1275096.0, -4797180.0, 4075270.0);
const fromRad = Cartesian3.fromRadians(-1.8326, 0.6981, 1500.0);
// Constants
Cartesian3.ZERO; // (0,0,0)
Cartesian3.UNIT_X; // (1,0,0)
Cartesian3.UNIT_Y; // (0,1,0)
Cartesian3.UNIT_Z; // (0,0,1)
Breaking change (1.139, #8359):
Cartesian2,Cartesian3, andCartesian4are now ES6 classes. Callingnewon a static factory method now throws --new Cartesian3.fromArray([...])andnew Cartesian3.fromDegrees(...)are errors. Dropnewfor factory methods (Cartesian3.fromArray([...])); keep it only for the real constructor (new Cartesian3(x, y, z)). More classes are migrating to ES6 classes, so apply this rule everywhere.
Vector Operations
const a = new Cartesian3(1.0, 2.0, 3.0);
const b = new Cartesian3(4.0, 5.0, 6.0);
const r = new Cartesian3(); // reusable scratch
Cartesian3.add(a, b, r); // a + b
Cartesian3.subtract(a, b, r); // a - b
Cartesian3.multiplyByScalar(a, 2.0, r); // a * 2
Cartesian3.negate(a, r); // -a
Cartesian3.cross(a, b, r); // cross product
Cartesian3.normalize(a, r); // unit vector
Cartesian3.lerp(a, b, 0.5, r); // linear interpolation
Cartesian3.midpoint(a, b, r); // midpoint
const dot = Cartesian3.dot(a, b); // dot product
const len = Cartesian3.magnitude(a); // ||a||
const dist = Cartesian3.distance(a, b); // Euclidean distance
const distSq = Cartesian3.distanceSquared(a, b); // faster for comparisons
const angle = Cartesian3.angleBetween(a, b); // radians
Cartographic -- Geographic Coordinates
import { Cartographic, Cartesian3, Math as CesiumMath } from "cesium";
const carto = Cartographic.fromDegrees(-105.0, 40.0, 1500.0);
const cartoRad = Cartographic.fromRadians(-1.8326, 0.6981, 1500.0);
// Cartesian3 <-> Cartographic
const position = Cartesian3.fromDegrees(-105.0, 40.0, 1500.0);
const geo = Cartographic.fromCartesian(position);
const lonDeg = CesiumMath.toDegrees(geo.longitude); // -105.0
const latDeg = CesiumMath.toDegrees(geo.latitude); // 40.0
const backToCart = Cartographic.toCartesian(geo);
CesiumMath Utilities
import { Math as CesiumMath } from "cesium";
// Degree/radian conversion
const rad = CesiumMath.toRadians(90.0); // PI/2
const deg = CesiumMath.toDegrees(Math.PI); // 180
// Constants: PI, TWO_PI, PI_OVER_TWO, PI_OVER_FOUR, RADIANS_PER_DEGREE
// EPSILON1 (0.1) through EPSILON21 (1e-21)
const clamped = CesiumMath.clamp(value, 0.0, 1.0);
const interp = CesiumMath.lerp(0.0, 100.0, 0.5); // 50
const norm = CesiumMath.negativePiToPi(angle); // [-PI, PI]
const pos = CesiumMath.zeroToTwoPi(angle); // [0, 2*PI]
const safeLon = CesiumMath.convertLongitudeRange(angle); // [-PI, PI)
const eq = CesiumMath.equalsEpsilon(a, b, CesiumMath.EPSILON7); // float compare
Ellipsoid
import { Ellipsoid, Cartesian3, Cartographic } from "cesium";
// Built-in ellipsoids
Ellipsoid.WGS84; // Earth (default)
Ellipsoid.UNIT_SPHERE; // radius 1
Ellipsoid.MOON; // lunar sphere
Ellipsoid.MARS; // Mars (v1.133+)
// Change default (affects Ellipsoid.default everywhere)
Ellipsoid.default = Ellipsoid.MOON;
// Conversions on a specific ellipsoid
const cart = Ellipsoid.WGS84.cartographicToCartesian(
Cartographic.fromDegrees(-75.0, 40.0, 100.0),
);
const carto = Ellipsoid.WGS84.cartesianToCartographic(cart);
// Surface normal at a position
const normal = Ellipsoid.WGS84.geodeticSurfaceNormal(cart, new Cartesian3());
// Project point onto ellipsoid surface
const onSurface = Ellipsoid.WGS84.scaleToGeodeticSurface(cart, new Cartesian3());
Transforms -- Reference Frames
Transforms builds 4x4 matrices relating local frames to ECEF. The most commonly used function is eastNorthUpToFixedFrame.
East-North-Up (ENU)
ENU: X = east, Y = north, Z = up. Standard frame for placing models on the globe.
import { Cartesian3, Transforms, Matrix4 } from "cesium";
const origin = Cartesian3.fromDegrees(-105.0, 40.0);
const enuMatrix = Transforms.eastNorthUpToFixedFrame(origin);
// Columns: [east, north, up, origin] in ECEF