feat: add optional higher pitch option (#3384)

* feat: add optional higher pitch option

Signed-off-by: Ihor Dykhta <ihordykhta@Ihors-MacBook-Pro.local>

* tests, lint

Signed-off-by: Ihor Dykhta <ihordykhta@Ihors-MacBook-Pro.local>

* fall back to default - 60 for mapbox

Signed-off-by: Ihor Dykhta <ihordykhta@Ihors-MacBook-Pro.local>

---------

Signed-off-by: Ihor Dykhta <ihordykhta@Ihors-MacBook-Pro.local>
Co-authored-by: Ihor Dykhta <ihordykhta@Ihors-MacBook-Pro.local>

Author: igorDykhta

src/components/src/map-container.tsx

@@ -73,7 +73,9 @@ import {
   THROTTLE_NOTIFICATION_TIME,
   DEFAULT_PICKING_RADIUS,
   NO_MAP_ID,
-  EMPTY_MAPBOX_STYLE
+  EMPTY_MAPBOX_STYLE,
+  MAPBOX_MAX_PITCH,
+  MAP_LIB_OPTIONS
 } from '@kepler.gl/constants';
 
 import {DROPPABLE_MAP_CONTAINER_TYPE} from './common/dnd-layer-items';
@@ -1011,7 +1013,9 @@ export default function MapContainerFactory(
               isInteractive
                 ? {
                     doubleClickZoom: !isEditorDrawingMode,
-                    dragRotate: this.props.mapState.dragRotate
+                    dragRotate: this.props.mapState.dragRotate,
+                    maxPitch:
+                      this.props.mapState.maxPitch ?? getApplicationConfig().maxPitch
                   }
                 : false
             }
@@ -1177,8 +1181,13 @@ export default function MapContainerFactory(
         getApplicationConfig().baseMapLibraryConfig?.[baseMapLibraryName];
 
       const internalViewState = this.context?.getInternalViewState(index);
+      const configMaxPitch = mapState.maxPitch ?? getApplicationConfig().maxPitch;
+      const effectiveMaxPitch = baseMapLibraryName === MAP_LIB_OPTIONS.MAPBOX
+        ? Math.min(configMaxPitch, MAPBOX_MAX_PITCH)
+        : configMaxPitch;
       const mapProps = {
         ...internalViewState,
+        maxPitch: effectiveMaxPitch,
         preserveDrawingBuffer: this.props.isExport ?? false,
         mapboxAccessToken: currentStyle?.accessToken || mapboxApiAccessToken,
         // baseApiUrl: mapboxApiUrl,
@@ -1272,6 +1281,7 @@ export default function MapContainerFactory(
             <MapComponent
               key={`top-${baseMapLibraryName}`}
               viewState={internalViewState}
+              maxPitch={effectiveMaxPitch}
               mapStyle={mapStyle.topMapStyle}
               style={MAP_STYLE.top}
               mapboxAccessToken={mapProps.mapboxAccessToken}

src/components/src/map-view-state-context.tsx

@@ -10,6 +10,7 @@ type MapViewState = {
   zoom: number;
   bearing?: number;
   pitch?: number;
+  maxPitch?: number;
 };
 import {pickViewportPropsFromMapState} from '@kepler.gl/reducers';
 

src/constants/src/default-settings.ts

@@ -294,6 +294,9 @@ export const MAP_LIB_OPTIONS = {
   MAPLIBRE: 'maplibre' as const
 };
 
+/** Mapbox GL JS does not support pitch above 60 degrees */
+export const MAPBOX_MAX_PITCH = 60;
+
 export type BaseMapLibraryType = 'mapbox' | 'maplibre';
 
 export const NO_BASEMAP_ICON = `${BASEMAP_ICON_PREFIX}/NO_BASEMAP.png`;

src/reducers/src/map-state-updaters.ts

@@ -71,6 +71,7 @@ const mapStateUpdaters = null;
  * @property height Default: `800`
  * @property minZoom: `undefined`,
  * @property maxZoom: `undefined`,
+ * @property maxPitch: `undefined` (defaults to application config value, deck.gl default is 60)
  * @property maxBounds: `undefined`,
  * @property isSplit: `false`,
  * @property isViewportSynced: `true`,
@@ -89,6 +90,7 @@ export const INITIAL_MAP_STATE: MapState = {
   height: 800,
   minZoom: undefined,
   maxZoom: undefined,
+  maxPitch: undefined,
   maxBounds: undefined,
   isSplit: false,
   isViewportSynced: true,
@@ -466,6 +468,7 @@ export function pickViewportPropsFromMapState(state: MapState): Viewport {
     'dragRotate',
     'minZoom',
     'maxZoom',
+    'maxPitch',
     'maxBounds'
   ]);
 }

src/schemas/src/map-state-schema.ts

@@ -19,7 +19,8 @@ export const propertiesV1 = {
   isSplit: null,
   isViewportSynced: null,
   isZoomLocked: null,
-  splitMapViewports: null
+  splitMapViewports: null,
+  maxPitch: null
 };
 
 const mapStateSchema = {

src/types/reducers.d.ts

@@ -24,6 +24,7 @@ export type MapState = {
   height: number;
   minZoom?: number;
   maxZoom?: number;
+  maxPitch?: number;
   maxBounds?: Bounds;
   initialState?: any;
   scale?: number;
@@ -530,6 +531,8 @@ export type Viewport = {
   minZoom?: number;
   /**  Maximum allowed viewport zoom */
   maxZoom?: number;
+  /**  Maximum pitch angle in degrees */
+  maxPitch?: number;
   /**  Maximum geographical bounds, pan/zoom operations are constrained within those bounds */
   maxBounds?: Bounds;
   /** viewport transition duration use by geocoder panel **/

src/utils/src/application-config.ts

@@ -89,6 +89,10 @@ export type KeplerApplicationConfig = {
   // Image export config
   /** Whether to apply fix for uglify error in dom-to-image (should be true for webpack builds, false for Vite) */
   escapeXhtmlForWebpack?: boolean;
+
+  /** Maximum pitch angle in degrees. deck.gl defaults to 60; set higher (up to 85) for elevated perspectives.
+   *  Note: values above 60 may cause rendering artifacts with some basemap tile providers. */
+  maxPitch?: number;
 };
 
 const DEFAULT_APPLICATION_CONFIG: Required<KeplerApplicationConfig> = {
@@ -147,7 +151,9 @@ const DEFAULT_APPLICATION_CONFIG: Required<KeplerApplicationConfig> = {
 
   // Image export config
   // Default to true for webpack builds, false for other build tools (e.g., Vite)
-  escapeXhtmlForWebpack: isWebpackBuild()
+  escapeXhtmlForWebpack: isWebpackBuild(),
+
+  maxPitch: 60
 };
 
 const applicationConfig: Required<KeplerApplicationConfig> = DEFAULT_APPLICATION_CONFIG;

test/node/schemas/map-state-schema-test.js

@@ -26,7 +26,8 @@ test('#mapStateSchema -> v1 -> save load mapState', t => {
       'isSplit',
       'isViewportSynced',
       'isZoomLocked',
-      'splitMapViewports'
+      'splitMapViewports',
+      'maxPitch'
     ],
     'mapState should have all 6 entries'
   );
@@ -41,7 +42,8 @@ test('#mapStateSchema -> v1 -> save load mapState', t => {
     isSplit: false,
     isViewportSynced: true,
     isZoomLocked: false,
-    splitMapViewports: []
+    splitMapViewports: [],
+    maxPitch: undefined
   };
 
   t.deepEqual(msToSave, expected, 'save mapState should be current');