Add support for clamping Vector 3D Tile point features to Terrain or 3d Tiles

[gdiehlEB]

Fixes Issue #11544

Adds the global heightReference member as an option for Cesium3DTileset to support clamping Billboards and Labels of Vector 3D Tiles point features to Terrain or 3D Tiles.

TO-DO:

• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have update the inline documentation, and included code examples where relevant
• Review and revise inline documentation
• I have performed a self-review of my code

[gdiehlEB]

@ggetz when you have time can you provide some feedback for this implementation? Thanks again for all of your help.

[ggetz]

Thanks @gdiehlEB, we'll do so shortly!

[ggetz]

@gdiehlEB Before we can review the code here, you'll need to have Contributor License Agreement covering you or the organization you are contributing on behalf of. Please ask EB to submit one and that you are listed on it.

[gdiehlEB]

@gdiehlEB Before we can review the code here, you'll need to have Contributor License Agreement covering you or the organization you are contributing on behalf of. Please ask EB to submit one and that you are listed on it.

@ggetz the corporate CLA has been submitted.

[ggetz]

Thanks @gdiehlEB!

We can test this out more properly once #11604 has been merged into main.

In the meantime, I don't think it's ideal to pass in scene from the top-level of Cesium3DTileset. I wonder if there is a way we can pass that in at a lower level instead.

[gdiehlEB]

Thanks for the feedback @ggetz! I had the same thought and have been looking for an alternative to passing the scene in, but I couldn’t find anywhere that the viewer instance was already available to access. If the heightReference is just set when creating the Cesium3DTileset instance similar to classificationType that seemed like the place to pass in the scene ie:

const tileset = await Cesium.Cesium3DTileset.fromUrl('/Apps/SampleData/lineworks/vector-tile.json', {
//clamp polylines
  classificationType: Cesium.ClassificationType.TERRAIN,
//clamp point features
  heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
//not ideal
  scene: viewer.scene
});

There may be another way that I am missing though. I saw that in the clamping sandcastle the Entity API is used and provides access to the viewer so no clues there.

[ggetz]

Thanks for the update and you patience @gdiehlEB.

I had the same thought and have been looking for an alternative to passing the scene in, but I couldn’t find anywhere that the viewer instance was already available to access.

Thanks for taking a look. Unfortunately, this may be the case given how Billboard and Label collections currently need to be constructed. Let's move forward with the approached provided here.

[ggetz]

I have a few suggestions— Most of these are comment on documentation types and wording for clarity. The code is looking good otherwise!

[ggetz]

@gdiehlEB Would you be able to provide a working Sandcastle example for verification and testing purposes here?

[gdiehlEB]

@ggetz thank you for the feedback!

Would you be able to provide a working Sandcastle example for verification and testing purposes here?

Not seeing any publicly available vector tiles with points in the sandcastles or Ion Asset Depot, I will share tilesets I was using to test but they are from a customer site so I will send directly. Let me know if that works and if you need anything else.

sandcastle code:

const viewer = new Cesium.Viewer("cesiumContainer");
 const  worldTerrain = await Cesium.createWorldTerrainAsync();
  viewer.scene.terrainProvider = worldTerrain;

viewer.scene.screenSpaceCameraController.enableCollisionDetection = false;

const tileset = await Cesium.Cesium3DTileset.fromUrl('/Apps/SampleData/clamping-target/tileset.json', {
enableCollision: true,
});

const lineworks = await Cesium.Cesium3DTileset.fromUrl('/Apps/SampleData/lineworks/tileset.json', {
  classificationType: Cesium.ClassificationType.CESIUM_3D_TILE, //clamps lineworks to tileset, existing
  heightReference: Cesium.HeightReference.CLAMP_TO_3D_TILE, //clamps points, new
  scene: viewer.scene //required for heightReference
});

viewer.scene.primitives.add(tileset);
viewer.scene.primitives.add(lineworks);
  
viewer.zoomTo(tileset);

[ggetz]

Thanks @gdiehlEB! You can send data to [email protected] and we can test and verify the fix.

[ggetz]

The only other change needed here is an item describing the update in CHANGES.md.

[ggetz]

We were able to validate with the data you sent over @gdiehlEB! All looking good for this PR. Thank you!

[PradipSable07]

Question: Can we apply per-feature styling and heightReference (like vector 3D tiles) to photogrammetry 3D tiles or terrain layers?

Hi @ggetz Cesium Team 👋,

I’ve been working with different types of 3D Tiles data in CesiumJS and wanted to confirm some capabilities.

I know that vector 3D tilesets support:

• heightReference: Cesium.HeightReference.CLAMP_TO_3D_TILE
• Per-feature styling using Cesium3DTileStyle
• Metadata-based filtering or highlighting

However, I wanted to ask:

👉 Can similar features be applied to:

1. Photogrammetry 3D Tilesets

   • Is it possible to enable CLAMP_TO_3D_TILE or access individual building/mesh metadata?
   • Can we apply any runtime styling or highlighting?

2. Terrain + Raster Layers

   • Are there any plans or ways to treat parts of terrain or raster tiles as interactive features?
   • Can we style based on raster or elevation data in real time?

I would really appreciate clarity on whether those formats support such capabilities, or if it’s strictly limited to vector 3D tiles.

Thanks for all your amazing work on Cesium!

– pradip sable