Example threejs terrain

[MichaelLangbein]

Launch Checklist

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
• Briefly describe the changes in this PR.
• Link to related issues.
• N/A Include before/after visuals or gifs if this PR includes visual changes.
• N/A Write tests for all new functionality.
• N/A Document any changes to public APIs.
• N/A Post benchmark scores.
• Add an entry to CHANGELOG.md under the ## main section.

Description

• Adds documentation: new example of using a three.js CustomLayer together with maplibre's terrain.
• Relates to this issue.
• Places a threejs scene on terrain by accounting for maplibre per default displaying all objects at the height of center - even if the objects themselves are located at a point on the terrain that lies higher or lower than center.
• It does so by simply translating the scene by sceneElevation - terrainCenterElevation.

Needs some review:

1. Is the sceneElevation - terrainCenterElevation approach suggested here really idiomatic?
2. Couldn't run generate-images as described here - is the provided image sufficient?

[codecov-commenter]

Codecov Report

Attention: 1 lines in your changes are missing coverage. Please review.

Comparison is base (b7b86c1) 75.60% compared to head (61adff5) 75.58%.
Report is 2 commits behind head on main.

Files	Patch %	Lines
src/source/load_tilejson.ts	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3429      +/-   ##
==========================================
- Coverage   75.60%   75.58%   -0.02%     
==========================================
  Files         242      242              
  Lines       19199    19188      -11     
  Branches     4257     4254       -3     
==========================================
- Hits        14515    14503      -12     
- Misses       4684     4685       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[HarelM]

Overall this looks good, I'm not familiar with three to fully understand this, but I think it's OK.

[neodescis]

The three.js part itself looks good. There is a lot more math here than in the old debug page I posted in the issue thread, but I do not know enough about it to know if this is all needed. @MichaelLangbein, do you think you could you take a look at the old debug page and help us understand the differences?

[MichaelLangbein]

The three.js part itself looks good. There is a lot more math here than in the old debug page I posted in the issue thread, but I do not know enough about it to know if this is all needed. @MichaelLangbein, do you think you could you take a look at the old debug page and help us understand the differences?

Sure thing, will do! I'll add some explaining comments some time after tonight. I can already say that there's not much change relative to the Debug-Page.

• I've attempted to make things a little simpler by removing a little of the rotation logic.
• I'm using a scene with two models in it to prove that the process works with objects at different elevations.
• That helper function calculateDistanceMercatorToMeters is just a quick-and-dirty way to get distances in threejs-scene coordinates from Mercator coordinates. It won't work if objects are far apart, which I will add as a comment.

The whole rest of the matrix math stems from the existing example in the docs, but I'll add some comments there, too.

[MichaelLangbein]

I've just stumbled across this helpful discussion on issue 1318.
But I wanted to make sure that my mental model was still correct. I believe that the graphic posted here is no longer correct. What the graphic calls altitude now is called cameraToCenterDistance (which is given in pixels). altitude today means the height of the camera over sea-level (given in meters). Am I correct?

[HarelM]

Not sure I know how to answer this question, can you clarify it a bit?

[MichaelLangbein]

Not sure I know how to answer this question, can you clarify it a bit?

This is my understanding of how the variables in map.projection are to be interpreted - it differs a little bit from the graphic shown here

[MichaelLangbein]

Alright, I've switched the code to use map.queryTerrainElevation, which did save me a few lines of calculations.
I've also added a bunch of comments explaining:

• the reasoning behind how the threejs-scene has been placed and transformed (which I think is now a little bit nicer than on my first attempt, because I'm now transforming the whole scene instead of each object individually)
• a few words about what queryTerrainElevation actually returns, particularly that it already returns the difference with the elevation of center.

[MichaelLangbein]

Hmm, sometimes the unit tests don't seem to pass. I haven't changed anything about maplibre itself - is this an actual error or just a CI issue?

[MichaelLangbein]

Thanks for merging! I guess this also closes issue 3427.

[neodescis]

Thank you @MichaelLangbein!