cesiumjs-spatial-math

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, and Cartesian4 are now ES6 classes. Calling new on a static factory method now throws -- new Cartesian3.fromArray([...]) and new Cartesian3.fromDegrees(...) are errors. Drop new for 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.