Tile Refinement Modification for Vector Tiles

[xuanhuang1]

Feature

I encountered what I thought was a bug but turns to be potentially a mismatch between runtime traversal behavior and the newly generated vector tiles. Had a discussion with @ggetz @lilleyse and @jaadelgren and it seems to be a persisting JS traversal implementation issue to some extend, but just visually more noticeable with vector tiles due to its heavy feature elimination at LOD generation.

The Sep 1 vector tile release will depend on this feature implementation.

Feature Requested:
Add a special path in the traversal logic to

1. identify vector tiles through the 3DTILES_content_gltf_vector extension
2. use unconditional refinement to resolve refinement traversal on empty tiles as planned with 3D Tiles 2.0 already

Problem description:
An example with a large, uneven vector data of global river as polylines. Notice that a couple tiles at the entering point of Yangzi river near Shanghai refuse to refine before suddenly jumping to a much deeper LOD.

Screencast.from.2026-08-04.17-30-09.mp4

This happen when there is a tile (of actual geometry content) with one of its children empty all the way until maybe >3 levels down, where the leave contains a bit of actual geometry that got simplified & discarded in tiling once moving to the coarser LOD. This should be somewhat an edge case for other meshes? Anyhow due to the extensive feature removal this structure is fairly common for large vector data, say for land features that have bits here and there on small islands. See the red arrow in the chart for a tree branch illustration.

Related issue: #9356 (comment). A previous attempt #11843 to resolve, which made some assumptions about how far the empty tile chain will be in the tileset.

AI acknowledgment

• I used AI to generate this feature request.
• (If the above is checked) I have reviewed the AI-generated content before submitting.

[mzschwartz5]

I'm wondering if this is as simple as adding:

if (tile.hasEmptyContent) {
  return true;
}

to Cesium3DTilesetTraversal.canTraverse. This is what Cesium3DTilesetMostDetailedTraversal.canTraverse already does. As you can see in the video below, with the same dataset as in the issue description, the region of interest loads in appropriately now. However, I also noticed that a region in the upper-left (ish) area of the screen is loading at a very high detail immediately. (I imagine this is just an area with many levels of empty tiles that are now being traversed straight through to the high LOD leaves).

I'll do more testing on other tilesets tomorrow, but hopefully this works and remains a surgical change.

vector-tileset-lods.mov

[xuanhuang1]

@mzschwartz5 Yes the previously problematic area seems to be fixed now. That dense little area does look strange though - I'd expect those to be empty (/to be displayed in around same LOD level as its siblings) until zoomed in.

If I understand correctly, that is cause by the implementation logic here as:
traverse all empty tiles until fetch renderable content

For comparison, what I did locally for the sanity test was:
allow refinement to resolve when hitting empty tile
which restricts the traversal depth still, guided by current SSE

There are visual artifacts with the second method too. There are some sudden blinking happening, I assume because now tile is allowed to render prematurely (e.g. when content is not fully streamed in yet)?

So yeah not if if either method is correct as the final solution.

(Note this video is showing a smaller region dataset, so the issue doesn't happen at the exact same location)
https://github.com/user-attachments/assets/facee7cf-a154-494a-87ad-865cfc2796bc

[mzschwartz5]

@xuanhuang1 It might be helpful to see the same dataset in cesium-native (where this bug doesn't exist, right?). Just so I can see what the desired end-behavior looks like.

Is that something that you could easily set up?

[xuanhuang1]

@xuanhuang1 It might be helpful to see the same dataset in cesium-native (where this bug doesn't exist, right?)

Is that something that you could easily set up?

That I have no idea of... I don't think it has been tested in native. @j9liu are you aware of anything like this in native's traversal/refinement implementation?

[mzschwartz5]

I'm going to be honest: I don't understand (yet) exactly what this setting does or why it helps so much here. I reverted my code change, so this is the base code as on main -- the only change I made was to add skipLevelOfDetail: true to the tileset options. Et voilà:

skipLevelOfDetail.mov

The original region loads in properly, as does the overly-dense region in my last video.

[mzschwartz5]

(Offline, we discussed not wanting to rely on skip traversal, due in part to a history of tricky spots with that setting. Also, we don't want to require users to turn it on to be able to render vector data properly. However, knowing that skip traversal works allowed me to compare it to the base traversal to identify the gap causing this bug).

To summarize my findings: the main issue is that base traversal won't refine a tile until all of its children resolve, and an empty child that's already met its SSE reports back as unresolved, which blocks its content-bearing siblings from ever rendering. #11843 tried to address this by introducing short-circuit logic to prevent empty children from blocking siblings (root.hasEmptyContent || allDescendantsLoaded), but this short-circuit is bypassed at implicit subtree boundaries, where the traversal encounters a "placeholder" tile (hasEmptyContent = false, hasImplicitContent = true) instead of the empty tile.

My proposal is to gate on hasRenderableContent, which is false only for genuinely empty tiles. Those empty descendants no longer flip allDescendantsLoaded to false, so executeEmptyTraversal returns true and refinement proceeds. Content tiles and not-yet-loaded placeholders keep hasRenderableContent = true, so they still block refinement until their content streams in.

// was: if (!traverse && !tile.contentAvailable)
if (!traverse && tile.hasRenderableContent && !tile.contentAvailable) {
    allDescendantsLoaded = false;
}

Demo of code change in action, with base traversal:

traversalFixed.mov

[ggetz]

@mzschwartz5 This was the last time the empty tile refinement was altered: #11843. The PR description links to an issue detail a use case we should confirm doesn't have any regressions.

[xuanhuang1]

(Offline, we discussed not wanting to rely on skip traversal, due in part to a history of tricky spots with that setting. Also, we don't want to require users to turn it on to be able to render vector data properly. However, knowing that skip traversal works allowed me to compare it to the base traversal to identify the gap causing this bug).

To summarize my findings: the main issue is that base traversal won't refine a tile until all of its children resolve, and an empty child that's already met its SSE reports back as unresolved, which blocks its content-bearing siblings from ever rendering. #11843 tried to address this by introducing short-circuit logic to prevent empty children from blocking siblings (root.hasEmptyContent || allDescendantsLoaded), but this short-circuit is bypassed at implicit subtree boundaries, where the traversal encounters a "placeholder" tile (hasEmptyContent = false, hasImplicitContent = true) instead of the empty tile.

My proposal is to gate on hasRenderableContent, which is false only for genuinely empty tiles. Those empty descendants no longer flip allDescendantsLoaded to false, so executeEmptyTraversal returns true and refinement proceeds. Content tiles and not-yet-loaded placeholders keep hasRenderableContent = true, so they still block refinement until their content streams in.

// was: if (!traverse && !tile.contentAvailable)
if (!traverse && tile.hasRenderableContent && !tile.contentAvailable) {
allDescendantsLoaded = false;
}
Demo of code change in action, with base traversal:

traversalFixed.mov

Can confirm visually this is the expected behavior. Nice work!