feat(extensions): TerrainExtension GlobeView support by charlieforward9 · Pull Request #10251 · visgl/deck.gl

charlieforward9 · 2026-04-19T19:34:41Z

Summary

Makes _TerrainExtension draped rendering work on GlobeView as well as MapView.

Why

Terrain cover and height-map textures are 2D render targets. The previous implementation derived their bounds and UVs from the live viewport common space; on GlobeView that space is globe cartesian, which is not a stable 2D sampling basis for those textures.

Change

Uses an absolute WebMercator texture basis for terrain cover and height-map FBOs in both map and globe modes.
Adds shared projection helpers for Mercator reference bounds.
Updates terrain cover and height-map bounds to avoid mixing globe-cartesian viewport bounds with Mercator layer bounds.
Converts globe terrain positions directly to Mercator world coordinates in the shader for terrain sampling.
Includes only the minimal TerrainLayer/tile traversal preview fixes needed to validate the extension on GlobeView.
Adds a MapView/GlobeView toggle to the terrain-extension website example.

Validation

MapView with TerrainExtension and TerrainLayer source remains unchanged.
GlobeView with TerrainExtension and TerrainLayer source renders draped layers and terrain preview correctly.
Projection toggles no longer reuse stale terrain tiles incorrectly.
Focused checks cover test/modules/extensions/terrain, test/modules/geo-layers/terrain-layer.spec.ts, and test/modules/geo-layers/tileset-2d/utils.spec.ts.

Merge Notes

Approved by Felix after follow-up cleanup. #10250 remains the broader TerrainLayer globe grid/tessellator work; this PR intentionally keeps only the minimal preview plumbing needed for the extension change.

Note

Medium Risk
Touches GPU terrain shaders, FBO coordinate logic, and tiled terrain on globe; MapView behavior is intended to stay the same but projection switching and elevation sampling are easy to get wrong.

Overview
TerrainExtension now supports GlobeView by building terrain height-map and cover FBOs in a fixed Web Mercator texture space instead of the live viewport’s globe cartesian common space, so draped/offset layers can sample the same targets when switching between map and globe.

Shared projection-utils helpers (lngLatToMercatorCommon, getMercatorReferenceViewport) drive bounds for HeightMapBuilder and TerrainCover: on globe, layer bounds stay Mercator and viewport intersection is skipped where globe bounds would be invalid. The terrain shader maps globe positions to Mercator for UVs, writes radial height on the globe, and applies sampled elevation along the surface normal.

Supporting globe validation: TerrainLayer uses GlobeViewport for tile overlap clamping and LNGLAT meshes when bounds look like degrees; OSM tile traversal culls tiles behind the horizon on globe. Docs note Map/Globe usage and tesselator: 'grid' for TerrainLayer on globe; the terrain-extension example adds a MapView/GlobeView toggle and related render tweaks.

^{Reviewed by Cursor Bugbot for commit c520bde. Bugbot is set up for automated code reviews on this repo. Configure here.}

Make TerrainExtension's draped rendering (height-map and terrain-cover FBOs) work on GlobeView as well as MapView. The existing implementation packed layer bounds into the live viewport's common space, which on GlobeView is sphere cartesian — incomparable with screen-space bounds, and invalid as a UV basis for the draped sampler. All bounds are now expressed in ABSOLUTE Web Mercator common space, regardless of the active projection. The FBO is rendered via a WebMercatorViewport in both cases, so the cover/height-map texture is projection-invariant and a projection toggle no longer requires re-rendering. Changes: - projection-utils: new `MERCATOR_REFERENCE_VIEWPORT` plus helpers `lngLatToMercatorCommon` and `getMercatorReferenceViewport` so other modules can compute bounds in the shared absolute-Mercator basis. - terrain-cover, height-map-builder: project layer bounds through the Mercator reference viewport; on globe, skip the viewport-bounds intersection in `getRenderBounds` (which would yield sphere cartesian coords) and use full layer bounds. - shader-module: compute `terrainMercPos` per-fragment by unprojecting globe cartesian back to lng/lat and forward-projecting through project_mercator_, so USE_HEIGHT_MAP / USE_COVER samples against the absolute-Mercator bounds uniform on any projection. The project module's helpers are VS-only, so the value is passed via varying; terrain meshes are fine enough that interpolation error is negligible. Bounds uniform is packed as absolute Mercator (no commonOrigin subtract), since the shader computes absolute xy itself. Example updated with a GlobeView toggle so the terrain-extension demo exercises both projections (requires TerrainLayer's grid tesselator from the companion geo-layers PR. EOF )

felixpalmer · 2026-04-22T12:40:48Z

 if (terrain.mode == TERRAIN_MODE_USE_HEIGHT_MAP) {
-  vec3 anchor = geometry.worldPosition;
-  anchor.z = 0.0;
-  vec3 anchorCommon = project_position(anchor);


OK, so if I understand correctly you're basically forcing project_position() to internally take the following branch:

if (project.projectionMode == PROJECTION_MODE_WEB_MERCATOR) {

A natural question that comes to mind is that if we are going to hardcode a projection, then why Mercator? Sure it works well for MapView but it doesn't fit the other views.

Perhaps related, I have been feeling that if we extend layers to take a "deformation" when generating geometry, such as a deformation UV grid for BitmapLayer than we could generalize that to support any projection.

felixpalmer · 2026-04-22T12:46:34Z

-        // Convert bounds to the common space, as [minX, minY, width, height]
+        // Pack bounds as [minX, minY, width, height]
        bounds: bounds
-          ? [


I worry this will introduce precision issues

felixpalmer · 2026-04-22T12:47:53Z

    const targetLayer = this.targetLayer;
    let shouldRedraw = false;

+    // Bounds are computed in ABSOLUTE Mercator common space — NOT the live


Could we try to use a cartesian space? Seems like a closer match to the spherical coordinates

ibgreen · 2026-04-28T12:06:31Z

-      // Recalculate cached bounds
+      // Recalculate cached bounds.
+      // Use a Mercator reference viewport so layer bounds live in ABSOLUTE
+      // Mercator common space — same rationale as terrain-cover.ts. On


Should we add mercator common space as a supported coordinateSystem?
Something like first class support for EPSG: 3857?
Or that is not helpful?

ibgreen · 2026-04-28T12:09:37Z

 if (terrain.mode == TERRAIN_MODE_USE_HEIGHT_MAP) {
-  vec3 anchor = geometry.worldPosition;
-  anchor.z = 0.0;
-  vec3 anchorCommon = project_position(anchor);


Perhaps related, I have been feeling that if we extend layers to take a "deformation" when generating geometry, such as a deformation UV grid for BitmapLayer than we could generalize that to support any projection.

felixpalmer

@charlieforward9 I've done a pass a tidied a few things:

Neater terrain_globe_to_mercator equations
More succinct comments
Revert removal of commonOrigin offset in bounds. This way the existing behavior isn't changed, only globeview support is added

Could you check that I haven't broken anything? Otherwise looks good to merge!

coveralls · 2026-05-12T12:06:15Z

coverage: 83.394% (+0.008%) from 83.386% — cr/feat/terrain-extension-globe into master

charlieforward9 · 2026-05-12T16:02:22Z

Confirmed locally: the TerrainExtension example loads tiles with the Mapbox token, and the View selector is now in the example controls. CI is green.

felixpalmer

Tested with new globe controls, works nicely

…xtension-globe # Conflicts: # modules/geo-layers/src/terrain-layer/terrain-layer.ts

chrisgervang

Observations as I've been reviewing this.

The elevation "jump" that we see at zoom level 12 when using MapView seems unrelated to this PR. It doesn't jump on GlobeView
I observe that the attempt to use flat lighting with material: false on the TerrainLayer isn't working on MapView at all zooms, or GlobeView when zoom less than 12. GlobeView with zoom greater than 12 does have flat lighting. Likely unrelated to this PR and something to follow up on.
The drape effect only supports one view, so side-by-side comparisons don't render the GeoJsonLayer. This is a preexisting limitation

Remaining Issue: the offset isn't working on GlobeView when zoom is less than 12.

parameters: { depthCompare: 'always' }is obfuscating a bug on GlobeView when zoom is less than 12. Notice how the flag isn't actually offset at zoom 11.9?

Zoom 11.9

Zoom 12.1

Proposed fix left in comments

chrisgervang · 2026-06-10T23:04:34Z

    float terrainZ = texture(terrain_map, texCoords).r;
-    geometry.position.z += terrainZ;
+    if (project.projectionMode == PROJECTION_MODE_GLOBE) {
+      geometry.position.xyz += normalize(geometry.position.xyz) * terrainZ;


Suggested change

geometry.position.xyz += normalize(geometry.position.xyz) * terrainZ;

// Height map is written in Mercator common space (units = TILE_SIZE / EARTH_CIRCUMFERENCE / cos(lat))

// Convert to globe radial units (units = GLOBE_RADIUS / EARTH_RADIUS)

terrainZ *= cos(radians(geometry.worldPosition.y)) * PI;

geometry.position.xyz += normalize(geometry.position.xyz) * terrainZ;

Result

Verified locally in the terrain-extension example on GlobeView.

chrisgervang

Tested again, looks good!

chrisgervang · 2026-06-11T03:25:50Z

      iconAtlas: `${DATA_URL_BASE}/flag-icons.png`,
      iconMapping: `${DATA_URL_BASE}/flag-icons.json`,
+      parameters: {
+        cullMode: 'none',


General commentary: It's not obvious that billboarded layers need cullMode: 'none' to work on GlobeView.

I think it'd be good practice to add a remark on layer docs that need this until deck offers an automatic solution.

Kinda related to #10262 @ibgreen

charlieforward9 added 2 commits April 19, 2026 14:59

fix(extensions): lint — template literals + remove unnecessary assertion

59cd841

charlieforward9 linked an issue Apr 19, 2026 that may be closed by this pull request

Tracker: GlobeView graduation #9199

Open

25 tasks

fix(extensions): prettier formatting

34d4813

charlieforward9 mentioned this pull request Apr 19, 2026

[Bug] Deck with Maplibre Globe synchronization issue #9466

Open

7 tasks

charlieforward9 self-assigned this Apr 19, 2026

This was referenced Apr 19, 2026

[Bug] Rendering artifacts when using ScatterplotLayer with Maplibre Interleaved mode + Globe projection #10206

Open

wrapLongitude problem with trips-layer #5631

Open

This was linked to issues Apr 20, 2026

[Bug] TerrainLayer zooming, TerrainExtension draping #9851

Closed

[Bug] Cannot dynamically alternate between terrain ON/OFF #8450

Closed

This was referenced Apr 20, 2026

[Feat] geojson onto 3D terrain #6644

Closed

[Feat] Multi view terrain extension #9474

Open

felixpalmer requested a review from Pessimistress April 22, 2026 12:31

felixpalmer requested changes Apr 22, 2026

View reviewed changes

fix(extensions): address terrain globe review

b3d4ecf

charlieforward9 requested a review from felixpalmer April 23, 2026 18:31

charlieforward9 mentioned this pull request Apr 27, 2026

Tracker: GlobeView graduation #9199

Open

25 tasks

ibgreen reviewed Apr 28, 2026

View reviewed changes

felixpalmer added 4 commits May 12, 2026 12:53

Tidy terrain_globe_to_mercator

92f63bb

Reduce comments

444afe7

Keep same behavior for non-globe case

5a6627e

Tidy

20765c0

felixpalmer approved these changes May 12, 2026

View reviewed changes

felixpalmer reviewed May 12, 2026

View reviewed changes

Comment thread examples/website/terrain-extension/app.tsx Outdated

Add back casts

408bc0a

chore(examples): move terrain view toggle to controls

abeed1a

Merge branch 'master' into cr/feat/terrain-extension-globe

7dd49ce

charlieforward9 requested a review from felixpalmer May 12, 2026 16:07

charlieforward9 removed a link to an issue May 13, 2026

Tracker: GlobeView graduation #9199

Open

25 tasks

Merge branch 'master' into cr/feat/terrain-extension-globe

95b48f3

felixpalmer approved these changes May 14, 2026

View reviewed changes

charlieforward9 added 4 commits May 14, 2026 11:59

Merge branch 'master' into cr/feat/terrain-extension-globe

9352f89

Merge remote-tracking branch 'upstream/master' into cr/feat/terrain-e…

6f4e2b2

…xtension-globe # Conflicts: # modules/geo-layers/src/terrain-layer/terrain-layer.ts

Merge branch 'master' into cr/feat/terrain-extension-globe

0d3cbe2

Merge branch 'master' into cr/feat/terrain-extension-globe

5aafcb7

charlieforward9 mentioned this pull request Jun 8, 2026

[codex] Improve effect handling for mesh-backed layers #10352

Closed

Merge branch 'master' into cr/feat/terrain-extension-globe

c2a667e

chrisgervang reviewed Jun 10, 2026

View reviewed changes

Comment thread modules/extensions/src/terrain/terrain-cover.ts Outdated

Comment thread modules/extensions/src/terrain/height-map-builder.ts Outdated

fix(terrain): address globe review feedback

b4f4a44

chrisgervang reviewed Jun 10, 2026

View reviewed changes

Comment thread examples/website/terrain-extension/app.tsx Outdated

Comment thread examples/website/terrain-extension/app.tsx Outdated

charlieforward9 added 3 commits June 10, 2026 15:45

chore(example): remove unnecessary icon terrain offset

03d9af3

chore(example): remove terrain view toggle

7e0522b

chore(example): show terrain in default globe view

aca1243

chrisgervang reviewed Jun 10, 2026

View reviewed changes

fix(terrain): correct height map unit conversion for globe offset mode

600cb82

Verified locally in the terrain-extension example on GlobeView.

chrisgervang approved these changes Jun 11, 2026

View reviewed changes

Merge branch 'master' into cr/feat/terrain-extension-globe

c520bde

chrisgervang reviewed Jun 11, 2026

View reviewed changes

chrisgervang merged commit 148eb40 into master Jun 11, 2026
6 checks passed

chrisgervang deleted the cr/feat/terrain-extension-globe branch June 11, 2026 03:26

-      geometry.position.xyz += normalize(geometry.position.xyz) * terrainZ;
+      // Height map is written in Mercator common space (units = TILE_SIZE / EARTH_CIRCUMFERENCE / cos(lat))
+      // Convert to globe radial units (units = GLOBE_RADIUS / EARTH_RADIUS)
+      terrainZ *= cos(radians(geometry.worldPosition.y)) * PI;
+      geometry.position.xyz += normalize(geometry.position.xyz) * terrainZ;

Conversation

charlieforward9 commented Apr 19, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Change

Validation

Merge Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixpalmer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coveralls commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

charlieforward9 commented May 12, 2026

Uh oh!

felixpalmer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisgervang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisgervang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

charlieforward9 commented Apr 19, 2026 •

edited by cursor Bot

Loading

coveralls commented May 12, 2026 •

edited

Loading