CesiumGS / CesiumGS/cesium

Follow-ups for draping imagery on 3D Tiles

Open
#12,643 11 comments 3 reactions 0 assignees View on GitHub
category - 3d tiles theme - 3D Tiles as Terrain type - enhancement
Dominant language
JavaScript
Stars
15.7k
Forks
3.9k
Avg merge
4d 6h
Merged PRs (30d)
34

Description

The functionality for [draping imagery on 3D Tiles](https://github.com/CesiumGS/cesium/issues/7591) had been requested several times. A first version of this has been implemented in a [pull request](https://github.com/CesiumGS/cesium/pull/12567) that has just been merged, meaning that the functionality will be part of the June 2025 release.

While the hope is that the current state already supports some of the most important use-cases, there are also some known limitations for that draping in the current state.

1. (Update: Extracted into https://github.com/CesiumGS/cesium/issues/12769 ) : There are issues with the computation of the texture coordinates when the tilesets cross the antimeridian.
- This is particularly noticable for global tilesets, causing the textures to look distorted in this area. The exact location of the issue (in the code... not on the globe) and possible solutions have to be identified and tested, but the hope is that this will only be a minor change that can happen soon in a follow-up PR
- Similarly, there are limits for the applicability near the north and south pole, for imagery using WebMercator projections. There is no silver bullet for solving that.
2. (Update: Fixed via https://github.com/CesiumGS/cesium/pull/12743 ) : The draping visualization is not updated when toggling `imageryLayer.show` between `true/false`. This should be an easy fix. As a workaround for now, setting `alpha=1.0` and `alpha=0.0` can achieve the desired effect.
3. Upsampling is not implemented.
- This means that objects that cover a large geographic area can only be covered with relatively low-resolution imagery. It also means that when using _multiple_ imageries, it can happen that the number of available texture units is exceeded, and some of the textures are omitted
- Some additional details and considerations can be found in the discussion of the pull request. A quick summary: When there is geometry that covers a large geographical area, and high-resolution imagery should be draped on that, then many textures have to be mapped to the geometry. Due to limitations of the graphics card, the number of textures that can be used "at once" is limited (to ~16 textures). This means that in order to drape these many textures, the geometry has to be split into smaller parts, so that each part only needs a few (less than 16) textures. There currently is no infrastructure for "splitting geometry" in CesiumJS, because once the geometry data is loaded, it is usually directly uploaded to the GPU.
4. Draping does not work for tilesets where the content uses the `CESIUM_primitive_outline` extension. The reason for that is, roughly speaking, that this extension causes the geometry of the glTF data to be modified to take into account the outline rendering information (modifying indices, duplicating vertices), and it's not clear how this can be aligned with the computation of the texture coordinates for the draping
5. The concept of a model being "ready" has to be reviewed. When a tileset with draped imagery is loaded, then the question is roughly: Should the tileset be displayed with its _original_ texture, which later (when the required imagery is loaded) is replaced with the imagery texture, **or** should the tileset _only_ be displayed when both the geometry _and_ the imagery are loded? Both approaches can cause ~"undesirable effects" for certain usage scenarios. Right now, there is the `asynchronouslyLoadImagery=false` option for the tileset constructor to offer both options, but some details have to be reviewed. For example, what this should mean when an imagery layer is added to a tileset that already _is_ visible.
- Update: One specific aspect of that is https://github.com/CesiumGS/cesium/issues/12709
6. Credit handling. Right now, the credits for the imagery are not displayed when the imagery is only draped on a tileset. The exact path for passing on these credits has to be determined. It might be possible to simply pass the credits from the imagery to the model.
7. Memory statistics: The model carries a bunch of statistics for the memory consumption, including that of textures. It is not clear where and how imagery textures should be accounted for. (And when the same imagery is also draped over _terrain_, then tracking that in the model as well might be misleading...)
8. The test coverage has to be improved. - A first set of ("integration-level") test cases has been created, and a first set of specs/unit tests has been added. But there have to be tests for more corner cases. Of course, this should _include_ a dedicated test at the antimeridian, but also tilesets with a mix of very large and very small objects, and other tests that aim at identifying limitations or drawbacks of the current approach. (A few profiling runs could also be worthwhile, but until now, the draping did not seem seem to have a significant performance impact)Further points will be added here, also based on the feedback from users who try out this new feature.

Contributor guide

Open the contributing guide

Research direction

Start with the merged pull request #12567 and the existing integration-level cases and specs/unit tests for draped imagery. Choose one limitation from this issue, first reproducing it with the relevant test setup; done means the selected behavior is addressed and a regression or corner-case test covers it, such as antimeridian handling or imagery visibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
computer-graphics, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.