billboard not clamped to ground when terrain is enabled

Hello again,

I'm trying to do a very simple thing, I want to place a billboard (or a placemark in GE language) on a set of coordinates. It happens that these coordinates are on the top of a small mountain. But when the camera view changes, so does the position of the billboard. Alas the billboard is not clamped/fixed to the ground. I hope that I'm doing something wrong and you can give me an easy solution, but then again such a basic functionality shouldn't be so difficult.

To replicate the problem you can go to the Hello Word demo and add the following code:

  var terrainProvider = new Cesium.CesiumTerrainProvider({
    url : '//',
    requestVertexNormals: true
  viewer.terrainProvider = terrainProvider;

        position : Cesium.Cartesian3.fromDegrees(23.815, 37.955),
        billboard :{
            image : '../images/Cesium_Logo_overlay.png'

The coordinates are in Athens, Greece. Try to change the camera view and watch the cesium logo moving with you. I'm using Firefox 41.0.2.


Hello Nikos,

Billboards on terrain isn’t available from the Entity API yet. However, we do have it implemented if you use a BillboardCollection to add your billboards. You can use the heightReference property for your billboards. Here is an example:

var viewer = new Cesium.Viewer(‘cesiumContainer’);

var cesiumTerrainProviderMeshes = new Cesium.CesiumTerrainProvider({
url : ‘//
viewer.terrainProvider = cesiumTerrainProviderMeshes;
viewer.scene.globe.depthTestAgainstTerrain = true;

var ellipsoid = viewer.scene.globe.ellipsoid;
var billboardCollection = viewer.scene.primitives.add(new Cesium.BillboardCollection({
scene : viewer.scene

position : Cesium.Cartesian3.fromDegrees(-110.0, 30.0),
image : ‘…/images/facility.gif’,
heightReference : Cesium.HeightReference.CLAMP_TO_GROUND


We do plan on making this option available from the Entity API at some point, but I think we’re waiting until we can show other types of Vector data on terrain, such as polylines.



  • for more entity support, even ahead of clamping polyline primitives.

Polylines are not the main reason that Entity billboards and labels being clamped to ground are not supported yet. A lot of the work needed for them is actually already done in the entity-clamp-to-ground branch for them, it just needs to be finished up and validated. It will definitely cause inconsistency when trying to build an app with it though, here’s a bunch of caveats off of the top of my head:

  1. There are problems with the camera, since it ends up following/zooming to the entity at it’s specified position, not it’s terrain adjusted position. This I would want to fix before releasing.

  2. Neither PointPrimitive or Model support clamping to ground yet, so supporting them yet isn’t possible.

  3. The GroundPrimitive can’t be batched, meaning loading a data source with a lot of polygons that performs fine now may have major performance problems when clamped to terrain.

  4. Geometry outlines can’t be clamped to ground and neither can polylines or paths.

  5. No lines means that having a moving billboard clamped to ground will cause the line to not be clamped to ground, producing weird visual inconsistency.

I’m sure there are many more issues that I’m not thinking of. Trust me, I really want to support data on terrain at the Entity API level, but the underlying Primitive API simply isn’t there yet. If we can get billboards and labels with some caveats in some time soon, we will.

Thanks for the heads up Matt. I didnt realize there were so many issues so its good to know the team has everything in mind.


Is the billboard issue fixed in latest version of Cesium (v1.37)?


Things are working with billboards and clamping them to ground as far as I’m aware. This code works as expected:

terrainProvider = viewer.terrainProvider;

viewer.terrainProvider = new Cesium.CesiumTerrainProvider({

    url : '[]('


viewer.scene.globe.depthTestAgainstTerrain = true;


    position : Cesium.Cartesian3.fromDegrees(-122.1958, 46.1915),

    billboard : {

        image : '../images/facility.gif',

        heightReference : Cesium.HeightReference.CLAMP_TO_GROUND,