Problem Overview

In a React application using Cesium.js 1.135.0, billboard markers using the CLAMP_TO_GROUND setting were observed to become inaccurately positioned after camera movement or zoom operations.

Environment

  • Cesium.js: 1.135.0 (issue occurred) -> 1.134.0 (issue resolved)
  • Framework: Next.js 16.0.1 + React 19.2.0
  • Terrain Data: Cesium World Terrain (Cesium.Terrain.fromWorldTerrain())
  • Marker Settings:
    • clampToGround: true
    • heightReference: Cesium.HeightReference.CLAMP_TO_GROUND

Symptoms

  1. Click a specific marker to zoom in
  2. Change the camera viewpoint (rotate/pan)
  3. Markers in the distance appear floating above the terrain or displayed at inaccurate positions

This issue is thought to occur due to inconsistency between the high-resolution terrain data (LOD: Level of Detail) loaded when the camera moves closer and the low-resolution terrain data referenced by distant markers.

Investigation Process

Attempt 1: Explicit Camera Control

Attempted to use sampleTerrainMostDetailed to obtain terrain altitude when a marker is clicked and explicitly move the camera, but the issue was not resolved.

Attempt 2: Changing heightReference

Attempted to change heightReference from CLAMP_TO_GROUND to NONE and use disableDepthTestDistance, but this caused markers to not be correctly placed on the terrain, creating a different problem.

Attempt 3: Version Comparison

Confirmed that a verification HTML file (using Cesium 1.110.0) did not exhibit the same issue. Identified that the Cesium version was potentially the cause.

Solution

Downgrading Cesium.js from 1.135.0 to 1.134.0 resolved the issue.

npminstallcesium@1.134.0

Technical Background

CLAMP_TO_GROUND Behavior

Cesium’s CLAMP_TO_GROUND setting provides functionality to fix entities to the terrain surface. This feature depends on terrain tile LOD (Level of Detail), and different resolution terrain data is used depending on the camera position.

Theoretically, Cesium should recalculate entity positions in response to terrain tile updates, but there may be an issue with this recalculation mechanism in version 1.135.0.

Similar issues have been reported in the CesiumGS/cesium GitHub repository:

This issue discusses problems related to clampToGround behavior.

Code Comparison

When Issue Occurred (1.135.0)

C}}e))smmc.eiaaltnurrahtmkkmei.eepntGrrT(yeCSo(.ooiGdbJlzraisoeotlor:ualn:nSbD2dooac4:uato,rrantcdSfre.oiu:hugeer.aiccngeoyh.l)tloRorP=ea,o>fdse(i{rgteeinoocjnesoo=nf,fCse{estiuomc.cHuerisghwtiRtehfetreernrcaei.nCLLAOMDP_cThOa_nGgReOsUND

After Resolution (1.134.0)

The same code works correctly. Only the version was changed.

Conclusion

Cesium 1.135.0 appears to contain a regression related to the CLAMP_TO_GROUND functionality. Using version 1.134.0 is recommended at this time.

Since this issue may be fixed in future 1.135.x releases, it is advisable to periodically check Cesium’s release notes and related issues.

Additional Information

Workaround (if version change is not possible)

If you must use 1.135.0, the following workaround is possible (though it may not be a complete solution):

c}Co)encrs.}Psoeit)rtntuhs}e}esumea)n)-ctr.nmeteesans(pnSinnarpasltcccetttmtoCmaeiaaatiiiposepmdtrrrettlgislpPittthsyyertieloeoooe...aiuTessgggifbbtpomedi[rrrgoiiehn.rPtiaaahrllriCroi]ppptEllrc=aaso.hhhRabbasriinpiiiecooietntsocccfhaan=noMi.s...e(rrtgoofillhreddheirsnotoaeen..entatsrintinthditypDEogigcieigi.he=anithetishtpit>ctutygatiocah=udthbses.i{(deo=tlsifl(Ce,>Re.trece,NeDmiodasO{feaom(riNeppnCvtuErt(.aiomehegreg.nTnetwrCcetteeaaesiVsrprttai.ht=DylatieiunecsCs=e(r,iet>(prasaCoainin{esi)3ucsin.meitP=f.uir>rH=moooe.nv{miNJ)iRguudahmledtbiriRea,aernnf.DcsePaa(rOtreSetnI.ocTngeIor.VwaNE(pO_)hNI)iENcFsI)NITY

This method samples terrain altitude once and uses it as a fixed value, so it is not affected by LOD changes. However, it has the limitation of not supporting dynamic terrain changes.

Last updated: 2025-11-13 Test environment: macOS, Darwin 25.0.0