Cesium Errors Coordinates

Cesium Errors : Coordinates

Overview

Almost every CesiumJS placement bug comes from confusing two coordinate types or two angle units. CesiumJS uses ONE position type internally and a small set of factories to build it. Reading the rules below removes the whole class of "my thing is in the wrong place" failures.

Core facts:

• Cartesian3 is an Earth-Centered, Earth-Fixed (ECEF) position in METERS. It

is NOT longitude, latitude, height. Its x, y, z are geocentric.

• Cartographic stores longitude and latitude in RADIANS plus height in

meters. The constructor and the fields are radians, NOT degrees.

• The fromDegrees factories are the bridge from human degrees to either type.

When to Use

• An entity, model, or primitive does not appear, or appears far from where it

should.

• Geometry renders at the center of the Earth or shoots off into space.
• A position logs as (NaN, NaN, NaN) or a height logs as NaN.
• A point sits underground or floats above terrain.
• A model points the wrong way or is tilted.
• GeoJSON or a polygon draws at sea level instead of on the terrain.

The Two Type Rules

ALWAYS know which type an API wants. Mixing them is the single most common coordinate bug.

| You have | You want a Cartesian3 | You want a Cartographic | |----------|-------------------------|---------------------------| | degrees lon, lat, height | Cartesian3.fromDegrees(lon, lat, height) | Cartographic.fromDegrees(lon, lat, height) | | radians lon, lat, height | Cartesian3.fromRadians(lon, lat, height) | new Cartographic(lon, lat, height) | | a Cartesian3 | already have it | Cartographic.fromCartesian(cartesian3) | | a Cartographic | Cartographic.toCartesian(carto) or ellipsoid.cartographicToCartesian(carto) | already have it |

• ALWAYS pass a Cartesian3 to entity.position, model.position,

camera.flyTo({ destination }), and primitive modelMatrix builders.

• NEVER pass a Cartographic where a Cartesian3 is expected. It has no x,

y, z in meters and silently misplaces or breaks the geometry.

The Units Rule

Cartographic longitude and latitude are RADIANS. HeadingPitchRoll values are RADIANS. The fromDegrees factories are the only place degrees are accepted.

• ALWAYS use Cartesian3.fromDegrees(...) when your data is in degrees.
• NEVER write new Cartographic(-75.0, 40.0). Those numbers are read as

radians, which is roughly 4297 and 2292 degrees, producing a wild position.

• ALWAYS convert with Cesium.Math.toRadians(deg) when an API needs radians

and you have degrees.

The Argument Order Rule

Every CesiumJS coordinate factory takes LONGITUDE FIRST, then latitude, then height: (longitude, latitude, height).

• This is the opposite of the common "lat, lon" spoken order and of many other

mapping libraries.

• NEVER pass (latitude, longitude). A point meant for Amsterdam

(4.9, 52.4) passed as (52.4, 4.9) lands in a different hemisphere.

NaN Positions

A Cartesian3 with any NaN component renders nothing and produces no error.

• Symptom : geometry silently absent; logging the position shows NaN.
• Root cause : Cartesian3.fromDegrees received undefined, a string, or

a NaN argument, often from unparsed input or a missing object field.

• Prevention : validate inputs are finite numbers before calling a factory.

ALWAYS Number.isFinite(value) on each coordinate from external data.

• Recovery : log the raw arguments at the factory call; trace the NaN

back to the source field or parse step.

Height, Terrain, and Ground Clamping

Height 0 is the WGS84 ellipsoid surface, not the terrain surface. With world terrain loaded, ellipsoid height 0 can sit far above or below the ground.

• ALWAYS set heightReference to clamp an entity to the surface instead of

guessing a height: HeightReference.CLAMP_TO_GROUND (terrain and 3D Tiles), CLAMP_TO_TERRAIN, or RELATIVE_TO_GROUND.

• A clamped entity needs a position whose longitude and latitude are correct;

its height is then ignored.

• To read an actual terrain height, ALWAYS await an async sampler. Reading a

height before terrain tiles load returns the ellipsoid height 0.

const carto = Cesium.Cartographic.fromDegrees(4.9, 52.4);
const [sampled] = await Cesium.sampleTerrainMostDetailed(
  viewer.terrainProvider,
  [carto]
);
const groundPosition = Cesium.Cartographic.toCartesian(sampled);

GeoJSON Floats at Sea Level

GeoJsonDataSource.load defaults clampToGround to false. Polygons and lines then draw at ellipsoid height 0, which floats or sinks over terrain.

• ALWAYS pass { clampToGround: true } to drape GeoJSON on the surface.
• This is a default, not a bug; it must be opted into.

HeadingPitchRoll Conventions

HeadingPitchRoll orients a model or camera. All three values are RADIANS.

| Value | Meaning | Sign convention | |-------|---------|-----------------| | heading | rotation about the local up axis | 0 faces north, increases clockwise (toward east) | | pitch | rotation about the local east axis | 0 is level; negative looks down by convention | | roll | rotation about the local forward axis | 0 is upright |

• A model placed only with a position but no orientation defaults to an

east-north-up frame; it is not "facing the camera".

• NEVER pass degrees to HeadingPitchRoll. Convert with Cesium.Math.toRadians.
• To place AND orient a model, build a modelMatrix with

Transforms.headingPitchRollToFixedFrame(origin, hpr). See cesium-impl-aec-georef.

Common Mistakes

| Mistake | Consequence | Fix | |---------|-------------|-----| | new Cartographic(-75, 40) with degree numbers | Position thousands of degrees off | Use Cartesian3.fromDegrees or Cartographic.fromDegrees | | Passing a Cartographic to entity.position | Geometry misplaced or absent | Convert with Cartographic.toCartesian | | (latitude, longitude) argument order | Point in the wrong hemisphere | Order is (longitude, latitude, height) | | Height 0 expecting the terrain surface | Geometry above or below the ground | Set heightReference or sample terrain | | GeoJSON without clampToGround: true | Polygons float at sea level | Pass { clampToGround: true } | | undefined field into fromDegrees | NaN position, nothing renders | Validate inputs with Number.isFinite | | Degrees passed to HeadingPitchRoll | Model wildly rotated | Convert with Cesium.Math.toRadians |

Red Flags : STOP

• new Cartographic( followed by numbers larger than about 7 in magnitude.
• A coordinate factory called with a value straight from JSON.parse with no

finite-number check.

• entity.position or model.position assigned something that is not the

result of a Cartesian3 factory.

• A polygon or line DataSource loaded without clampToGround while terrain

is enabled.

Reference Files

• references/methods.md : verified signatures for Cartesian3,

Cartographic, the fromDegrees and fromRadians factories, Cesium.Math.toRadians, sampleTerrainMostDetailed, and HeightReference.

• references/examples.md : correct placement, degree-to-radian conversion,

terrain height sampling, ground-clamped GeoJSON, and oriented model placement.

• references/anti-patterns.md : each coordinate failure with symptom, root

cause, prevention, and recovery.

Related Skills

• cesium-core-coordinates : the full coordinate-system reference.
• cesium-syntax-entity : entity.position and heightReference.
• cesium-syntax-datasources : GeoJSON clampToGround.
• cesium-impl-aec-georef : Transforms and modelMatrix orientation.
• cesium-syntax-terrain : loading a terrain provider before sampling.

Sources

Verified via WebFetch on 2026-05-20 against the CesiumJS API Reference (https://cesium.com/learn/cesiumjs/ref-doc/) : Cartesian3, Cartographic, Math, HeightReference, HeadingPitchRoll, sampleTerrainMostDetailed, GeoJsonDataSource.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/CesiumJS-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.