fix(geo-layers): Pass zoomOffset through TerrainLayer to child TileLayer. (#10382)

asford · chrisgervang · commit 379d83d0755b · 2026-06-25T10:13:50.000-07:00
diff --git a/examples/website/map-tile/app.tsx b/examples/website/map-tile/app.tsx
@@ -57,6 +57,7 @@ export default function App({
   maxZoom = 7,
   visibleMinZoom,
   visibleMaxZoom = 7,
+  zoomOffset = 0,
   useExtent = false
 }: {
   showBorder?: boolean;
@@ -66,6 +67,7 @@ export default function App({
   maxZoom?: number;
   visibleMinZoom?: number;
   visibleMaxZoom?: number;
+  zoomOffset?: number;
   useExtent?: boolean;
 }) {
   const [zoom, setZoom] = useState(INITIAL_VIEW_STATE.zoom);
@@ -95,6 +97,7 @@ export default function App({
     tileSize: 512,
     visibleMinZoom,
     visibleMaxZoom,
+    zoomOffset,
     extent: useExtent ? FRANCE_EXTENT : undefined,
     renderSubLayers: props => {
       const [[west, south], [east, north]] = props.tile.boundingBox;
diff --git a/examples/website/terrain/app.tsx b/examples/website/terrain/app.tsx
@@ -2,12 +2,13 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import React from 'react';
-import {createRoot} from 'react-dom/client';
 import {DeckGL} from '@deck.gl/react';
+import React, {useCallback, useState} from 'react';
+import {createRoot} from 'react-dom/client';
 
-import {TerrainLayer, TerrainLayerProps} from '@deck.gl/geo-layers';
 import type {MapViewState} from '@deck.gl/core';
+import {_GlobeView as GlobeView, MapView} from '@deck.gl/core';
+import {TerrainLayer, TerrainLayerProps} from '@deck.gl/geo-layers';
 
 // Set your mapbox token here
 const MAPBOX_TOKEN = process.env.MapboxAccessToken; // eslint-disable-line
@@ -36,29 +37,58 @@ const ELEVATION_DECODER: TerrainLayerProps['elevationDecoder'] = {
 export default function App({
   texture = SURFACE_IMAGE,
   wireframe = false,
-  initialViewState = INITIAL_VIEW_STATE
+  globeView = false,
+  zoomOffset = 0,
+  minZoom = 0,
+  maxZoom = 14,
+  visibleMinZoom = 0,
+  visibleMaxZoom = 14,
+  initialViewState = INITIAL_VIEW_STATE,
+  onZoomChange
 }: {
   texture?: string;
   wireframe?: boolean;
+  globeView?: boolean;
+  zoomOffset?: number;
+  minZoom?: number;
+  maxZoom?: number;
+  visibleMinZoom?: number;
+  visibleMaxZoom?: number;
   initialViewState?: MapViewState;
+  onZoomChange?: (zoom: number) => void;
 }) {
+  const [viewState, setViewState] = useState(initialViewState);
+  const onViewStateChange = useCallback(
+    ({viewState: vs}) => {
+      setViewState(vs);
+      onZoomChange?.(vs.zoom);
+    },
+    [onZoomChange]
+  );
+
   const layer = new TerrainLayer({
     id: 'terrain',
-    minZoom: 0,
-    maxZoom: 23,
-    strategy: 'no-overlap',
+    minZoom,
+    maxZoom,
+    visibleMinZoom,
+    visibleMaxZoom,
+    refinementStrategy: 'best-available',
     elevationDecoder: ELEVATION_DECODER,
     elevationData: TERRAIN_IMAGE,
     texture,
     wireframe,
+    zoomOffset,
     color: [255, 255, 255],
     pickable: '3d'
   });
 
   return (
     <DeckGL
-      initialViewState={initialViewState}
+      views={globeView ? new GlobeView() : new MapView()}
+      viewState={viewState}
+      onViewStateChange={onViewStateChange}
       controller={true}
+      parameters={{cull: true}}
       layers={[layer]}
       getTooltip={info => {
         if (info.picked && info.coordinate && info.coordinate.length === 3) {
diff --git a/modules/geo-layers/src/terrain-layer/terrain-layer.ts b/modules/geo-layers/src/terrain-layer/terrain-layer.ts
@@ -6,7 +6,9 @@ import {
   Color,
   CompositeLayer,
   CompositeLayerProps,
+  COORDINATE_SYSTEM,
   DefaultProps,
+  _GlobeViewport as GlobeViewport,
   Layer,
   LayersList,
   log,
@@ -15,7 +17,6 @@ import {
   UpdateParameters
 } from '@deck.gl/core';
 import {SimpleMeshLayer} from '@deck.gl/mesh-layers';
-import {COORDINATE_SYSTEM} from '@deck.gl/core';
 import type {MeshAttributes} from '@loaders.gl/schema';
 import {TerrainWorkerLoader} from '@loaders.gl/terrain';
 import TileLayer, {TileLayerProps} from '../tile-layer/tile-layer';
@@ -26,7 +27,7 @@ import type {
   TileLoadProps,
   ZRange
 } from '../tileset-2d/index';
-import {Tile2DHeader, urlType, getURLFromTemplate, URLTemplate} from '../tileset-2d/index';
+import {getURLFromTemplate, Tile2DHeader, URLTemplate, urlType} from '../tileset-2d/index';
 
 const DUMMY_DATA = [1];
 
@@ -295,7 +296,8 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
       onTileError,
       maxCacheSize,
       maxCacheByteSize,
-      refinementStrategy
+      refinementStrategy,
+      zoomOffset
     } = this.props;
 
     if (this.state.isTiled) {
@@ -311,7 +313,9 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
               elevationData: urlTemplateToUpdateTrigger(elevationData),
               texture: urlTemplateToUpdateTrigger(texture),
               meshMaxError,
-              elevationDecoder
+              elevationDecoder,
+              projectionMode: this.context.viewport.projectionMode,
+              zoomOffset
             }
           },
           onViewportLoad: this.onViewportLoad.bind(this),
@@ -326,7 +330,8 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
           onTileError,
           maxCacheSize,
           maxCacheByteSize,
-          refinementStrategy
+          refinementStrategy,
+          zoomOffset
         }
       );
     }
diff --git a/test/modules/geo-layers/terrain-layer-loading.spec.ts b/test/modules/geo-layers/terrain-layer-loading.spec.ts
@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {test, expect} from 'vitest';
-import {MapView} from '@deck.gl/core';
+import {COORDINATE_SYSTEM, _GlobeView as GlobeView, MapView} from '@deck.gl/core';
 import {TerrainLayer} from '@deck.gl/geo-layers';
 import {testInitializeLayerAsync} from '@deck.gl/test-utils/vitest';
 import {TruncatedConeGeometry} from '@luma.gl/engine';
@@ -26,6 +26,12 @@ const TEST_VIEWPORT = new MapView().makeViewport({
   viewState: {longitude: 0, latitude: 0, zoom: 0}
 });
 
+const TEST_GLOBE_VIEWPORT = new GlobeView().makeViewport({
+  width: 100,
+  height: 100,
+  viewState: {longitude: 0, latitude: 0, zoom: 0}
+});
+
 function createTestMesh() {
   const mesh = new TruncatedConeGeometry({
     topRadius: 1,
@@ -125,3 +131,86 @@ test('TerrainLayer#isLoaded waits for elevation and texture in tiled mode', asyn
   expect(layer.isLoaded, 'tiled terrain layer is loaded after both resources resolve').toBe(true);
   handle?.finalize();
 });
+
+test('TerrainLayer fetches tiles at correct zoom levels for different zoomOffset values', async () => {
+  // Create a viewport at zoom 3 to test various zoomOffset values
+  const viewportZoom3 = new MapView().makeViewport({
+    width: 100,
+    height: 100,
+    viewState: {longitude: 0, latitude: 0, zoom: 3}
+  });
+
+  const testCases = [
+    {zoomOffset: -1, expectedZ: 2, description: 'zoomOffset: -1 (lower detail)'},
+    {zoomOffset: 0, expectedZ: 3, description: 'zoomOffset: 0 (normal)'},
+    {zoomOffset: 1, expectedZ: 4, description: 'zoomOffset: +1 (higher detail)'}
+  ];
+
+  for (const testCase of testCases) {
+    const fetchedUrls: {elevation: string[]; texture: string[]} = {
+      elevation: [],
+      texture: []
+    };
+
+    const layer = new TerrainLayer({
+      id: `terrain-zoom-offset-${testCase.zoomOffset}`,
+      elevationData: 'https://example.com/elevation/{z}/{x}/{y}.png',
+      texture: 'https://example.com/texture/{z}/{x}/{y}.png',
+      zoomOffset: testCase.zoomOffset,
+      minZoom: 0,
+      maxZoom: 6,
+      fetch: (url, {propName}) => {
+        if (propName === 'elevationData') {
+          fetchedUrls.elevation.push(url);
+        } else if (propName === 'texture') {
+          fetchedUrls.texture.push(url);
+        }
+        return Promise.resolve(createTestMesh());
+      }
+    });
+
+    const handle = await testInitializeLayerAsync({
+      layer,
+      viewport: viewportZoom3,
+      finalize: false
+    });
+
+    await sleep();
+
+    // Verify tiles are fetched at the expected zoom level for both elevation and texture
+    const expectedZoomPath = `/${testCase.expectedZ}/`;
+    expect(
+      fetchedUrls.elevation.some(url => url.includes(expectedZoomPath)),
+      `${testCase.description}: elevation tiles fetched at z=${testCase.expectedZ}`
+    ).toBe(true);
+    expect(
+      fetchedUrls.texture.some(url => url.includes(expectedZoomPath)),
+      `${testCase.description}: texture tiles fetched at z=${testCase.expectedZ}`
+    ).toBe(true);
+
+    handle?.finalize();
+  }
+});
+
+test('TerrainLayer renders tiled Martini meshes in lng/lat coordinates on GlobeView', async () => {
+  const layer = new TerrainLayer({
+    id: 'terrain-tiled-globe',
+    elevationData: 'https://example.com/elevation/{z}/{x}/{y}.png',
+    minZoom: 0,
+    maxZoom: 0,
+    fetch: () => Promise.resolve(createTestMesh())
+  });
+
+  const handle = await testInitializeLayerAsync({
+    layer,
+    viewport: TEST_GLOBE_VIEWPORT,
+    finalize: false
+  });
+
+  const tileLayer = layer.getSubLayers()[0];
+  const meshLayer = tileLayer.getSubLayers()[0];
+  expect(meshLayer.props.coordinateSystem, 'Globe terrain mesh uses lng/lat').toBe(
+    COORDINATE_SYSTEM.LNGLAT
+  );
+  handle?.finalize();
+});
diff --git a/website/src/examples/terrain-layer.js b/website/src/examples/terrain-layer.js
@@ -2,9 +2,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import React, {Component} from 'react';
-import {MAPBOX_STYLES, GITHUB_TREE} from '../constants/defaults';
+import {Component} from 'react';
 import App from 'website-examples/terrain/app';
+import {GITHUB_TREE, MAPBOX_STYLES} from '../constants/defaults';
 
 import {makeExample} from '../components';
 
@@ -62,6 +62,7 @@ class TerrainDemo extends Component {
   static code = `${GITHUB_TREE}/examples/website/terrain`;
 
   static parameters = {
+    globeView: {displayName: 'Globe View', type: 'checkbox', value: false},
     location: {
       displayName: 'Location',
       type: 'select',
@@ -74,7 +75,51 @@ class TerrainDemo extends Component {
       options: Object.keys(SURFACE_IMAGES),
       value: 'Satellite'
     },
-    wireframe: {displayName: 'Wireframe', type: 'checkbox', value: false}
+    wireframe: {displayName: 'Wireframe', type: 'checkbox', value: false},
+    minZoom: {
+      displayName: 'Min Zoom',
+      type: 'range',
+      value: 0,
+      step: 1,
+      min: 0,
+      max: 19,
+      accentColor: '#0275ff'
+    },
+    maxZoom: {
+      displayName: 'Max Zoom',
+      type: 'range',
+      value: 14,
+      step: 1,
+      min: 0,
+      max: 19,
+      accentColor: '#0275ff'
+    },
+    visibleMinZoom: {
+      displayName: 'Visible Min Zoom',
+      type: 'range',
+      value: 0,
+      step: 1,
+      min: 0,
+      max: 19,
+      accentColor: '#1a2b4a'
+    },
+    visibleMaxZoom: {
+      displayName: 'Visible Max Zoom',
+      type: 'range',
+      value: 19,
+      step: 1,
+      min: 0,
+      max: 19,
+      accentColor: '#1a2b4a'
+    },
+    zoomOffset: {
+      displayName: 'Zoom Offset',
+      type: 'range',
+      value: 0,
+      min: -2,
+      max: 2,
+      step: 1
+    }
   };
 
   static mapStyle = MAPBOX_STYLES.BLANK;
@@ -99,13 +144,32 @@ class TerrainDemo extends Component {
             <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>
           </div>
         </p>
+        <div className="layout">
+          <div className="stat col-1-2">
+            Viewport Zoom<b>{meta.zoom != null ? meta.zoom.toFixed(1) : '-'}</b>
+          </div>
+        </div>
       </div>
     );
   }
 
+  _onZoomChange = zoom => {
+    this.props.onStateChange({zoom});
+  };
+
   render() {
     const {params, data, ...otherProps} = this.props;
-    const {location, surface, wireframe} = params;
+    const {
+      location,
+      surface,
+      wireframe,
+      globeView,
+      minZoom,
+      maxZoom,
+      visibleMinZoom,
+      visibleMaxZoom,
+      zoomOffset
+    } = params;
 
     const initialViewState = LOCATIONS[location.value];
     initialViewState.pitch = 45;
@@ -118,6 +182,13 @@ class TerrainDemo extends Component {
           initialViewState={initialViewState}
           texture={SURFACE_IMAGES[surface.value]}
           wireframe={wireframe.value}
+          globeView={globeView.value}
+          minZoom={minZoom.value}
+          maxZoom={maxZoom.value}
+          visibleMinZoom={visibleMinZoom.value}
+          visibleMaxZoom={visibleMaxZoom.value}
+          zoomOffset={zoomOffset.value}
+          onZoomChange={this._onZoomChange}
         />
       </div>
     );
diff --git a/website/src/examples/tile-layer.js b/website/src/examples/tile-layer.js
