Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

feat: add optional higher pitch option (#3384)

Igor Dykhtaeadf5ae5ed06
diff --git a/src/components/src/map-container.tsx b/src/components/src/map-container.tsx
index 015b333a3..eee9a55a6 100644
--- a/src/components/src/map-container.tsx
+++ b/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}
diff --git a/src/components/src/map-view-state-context.tsx b/src/components/src/map-view-state-context.tsx
index 8711e5ffc..fbd96e56d 100644
--- a/src/components/src/map-view-state-context.tsx
+++ b/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';
diff --git a/src/constants/src/default-settings.ts b/src/constants/src/default-settings.ts
index ec325e17f..7fba971b9 100644
--- a/src/constants/src/default-settings.ts
+++ b/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`;
diff --git a/src/reducers/src/map-state-updaters.ts b/src/reducers/src/map-state-updaters.ts
index 0aeccd0c1..fdf357822 100644
--- a/src/reducers/src/map-state-updaters.ts
+++ b/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'
]);
}
diff --git a/src/schemas/src/map-state-schema.ts b/src/schemas/src/map-state-schema.ts
index d877751e8..f2c53ecd5 100644
--- a/src/schemas/src/map-state-schema.ts
+++ b/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 = {
diff --git a/src/types/reducers.d.ts b/src/types/reducers.d.ts
index 5cf3522d4..3c4427577 100644
--- a/src/types/reducers.d.ts
+++ b/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 **/
diff --git a/src/utils/src/application-config.ts b/src/utils/src/application-config.ts
index 2f252e772..e2cf2c303 100644
--- a/src/utils/src/application-config.ts
+++ b/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;
diff --git a/test/node/schemas/map-state-schema-test.js b/test/node/schemas/map-state-schema-test.js
index 2d3ad572c..9dbf0a659 100644
--- a/test/node/schemas/map-state-schema-test.js
+++ b/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');