Skip to content

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

[feat] Add minZoom, maxZoom, maxBounds (#2124)

Igor Dykhtaa438383b8f3f
diff --git a/src/reducers/src/map-state-updaters.ts b/src/reducers/src/map-state-updaters.ts
index 8994efc57..b6dd498b9 100644
--- a/src/reducers/src/map-state-updaters.ts
+++ b/src/reducers/src/map-state-updaters.ts
@@ -18,9 +18,14 @@
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
-import {getCenterAndZoomFromBounds} from '@kepler.gl/utils';
+import geoViewport from '@mapbox/geo-viewport';
+import booleanWithin from '@turf/boolean-within';
+import bboxPolygon from '@turf/bbox-polygon';
+import {fitBounds} from '@math.gl/web-mercator';
+
+import {getCenterAndZoomFromBounds, validateBounds, MAPBOX_TILE_SIZE} from '@kepler.gl/utils';
import {MapStateActions, ReceiveMapConfigPayload, ActionTypes} from '@kepler.gl/actions';
-import {MapState} from '@kepler.gl/types';
+import {MapState, Bounds} from '@kepler.gl/types';
/**
* Updaters for `mapState` reducer. Can be used in your root reducer to directly modify kepler.gl's state.
@@ -86,7 +91,10 @@ export const INITIAL_MAP_STATE: MapState = {
dragRotate: false,
width: 800,
height: 800,
- isSplit: false
+ isSplit: false,
+ minZoom: undefined,
+ maxZoom: undefined,
+ maxBounds: undefined
};
/* Updaters */
@@ -98,10 +106,26 @@ export const INITIAL_MAP_STATE: MapState = {
export const updateMapUpdater = (
state: MapState,
action: MapStateActions.UpdateMapUpdaterAction
-): MapState => ({
- ...state,
- ...(action.payload || {})
-});
+): MapState => {
+ let newMapState = {
+ ...state,
+ ...(action.payload || {})
+ };
+
+ // Make sure zoom level doesn't go bellow minZoom if defined
+ if (newMapState.minZoom && newMapState.zoom < newMapState.minZoom) {
+ newMapState.zoom = newMapState.minZoom;
+ }
+ // Make sure zoom level doesn't go above maxZoom if defined
+ if (newMapState.maxZoom && newMapState.zoom > newMapState.maxZoom) {
+ newMapState.zoom = newMapState.maxZoom;
+ }
+ // Limit viewport update based on maxBounds
+ if (newMapState.maxBounds && validateBounds(newMapState.maxBounds)) {
+ newMapState = updateViewportBasedOnBounds(state, newMapState);
+ }
+ return newMapState;
+};
/**
* Fit map viewport to bounds
@@ -233,3 +257,58 @@ export function getMapDimForSplitMap(isSplit, state) {
width
};
}
+
+function updateViewportBasedOnBounds(state: MapState, newMapState: MapState) {
+ // Get the new viewport bounds
+ const viewportBounds = geoViewport.bounds(
+ [newMapState.longitude, newMapState.latitude],
+ newMapState.zoom,
+ [newMapState.width, newMapState.height],
+ MAPBOX_TILE_SIZE
+ );
+ // Generate turf Polygon from bounds for comparison
+ const viewportBoundsPolygon = bboxPolygon(viewportBounds);
+ // @ts-ignore
+ const newStateMaxBounds: Bounds = newMapState.maxBounds;
+ // @ts-ignore
+ const maxBoundsPolygon = bboxPolygon(newStateMaxBounds);
+
+ // If maxBounds has changed reset the viewport to snap to bounds
+ const hasMaxBoundsChanged =
+ !state.maxBounds || !state.maxBounds.every((val, idx) => val === newStateMaxBounds[idx]);
+ if (hasMaxBoundsChanged) {
+ // Check if the newMapState viewport is within maxBounds
+ if (!booleanWithin(viewportBoundsPolygon, maxBoundsPolygon)) {
+ const {latitude, longitude, zoom} = fitBounds({
+ width: newMapState.width,
+ height: newMapState.width,
+ bounds: [
+ [newStateMaxBounds[0], newStateMaxBounds[1]],
+ [newStateMaxBounds[2], newStateMaxBounds[3]]
+ ]
+ });
+
+ newMapState = {
+ ...newMapState,
+ latitude,
+ longitude,
+ // For marginal or invalid bounds, zoom may be NaN. Make sure to provide a valid value in order
+ // to avoid corrupt state and potential crashes as zoom is expected to be a number
+ ...(Number.isFinite(zoom) ? {zoom} : {})
+ };
+ }
+ return newMapState;
+ }
+
+ // Check if the newMapState viewport is within maxBounds
+ if (!booleanWithin(viewportBoundsPolygon, maxBoundsPolygon)) {
+ newMapState = {
+ ...newMapState,
+ longitude: state.longitude,
+ latitude: state.latitude,
+ zoom: state.zoom
+ };
+ }
+
+ return newMapState;
+}
diff --git a/src/types/reducers.d.ts b/src/types/reducers.d.ts
index f3137c1b5..849348932 100644
--- a/src/types/reducers.d.ts
+++ b/src/types/reducers.d.ts
@@ -10,6 +10,9 @@ export type MapState = {
width: number;
height: number;
isSplit: boolean;
+ minZoom?: number;
+ maxZoom?: number;
+ maxBounds?: Bounds;
initialState?: any;
scale?: number;
};
@@ -399,6 +402,12 @@ export type Viewport = {
longitude?: number;
/** Whether to enable drag and rotate map into perspective viewport */
dragRotate?: boolean;
+ /** Minimum allowed viewport zoom */
+ minZoom?: number;
+ /** Maximum allowed viewport zoom */
+ maxZoom?: number;
+ /** Maximum geographical bounds, pan/zoom operations are constrained within those bounds */
+ maxBounds?: Bounds;
};
export type MapStyles = {
diff --git a/src/utils/src/index.ts b/src/utils/src/index.ts
index e999e3114..3270ecbd6 100644
--- a/src/utils/src/index.ts
+++ b/src/utils/src/index.ts
@@ -106,7 +106,7 @@ export {
unobserveDimensions,
default as useDimensions
} from './observe-dimensions';
-export {validateBounds, getCenterAndZoomFromBounds, normalizeEvent} from './projection-utils';
+export {validateBounds, getCenterAndZoomFromBounds, normalizeEvent, MAPBOX_TILE_SIZE} from './projection-utils';
export {validateToken} from './mapbox-utils';
export {
getDefaultLayerGroupVisibility,
diff --git a/src/utils/src/projection-utils.ts b/src/utils/src/projection-utils.ts
index 5ba7393f1..8518b3d54 100644
--- a/src/utils/src/projection-utils.ts
+++ b/src/utils/src/projection-utils.ts
@@ -23,7 +23,7 @@ import geoViewport from '@mapbox/geo-viewport';
import WebMercatorViewport from 'viewport-mercator-project';
import Console from 'global/console';
-const MAPBOX_TILE_SIZE = 512;
+export const MAPBOX_TILE_SIZE = 512;
function isLat(num) {
return Number.isFinite(num) && num <= 90 && num >= -90;
diff --git a/test/node/reducers/map-state-test.js b/test/node/reducers/map-state-test.js
index 28daca3e8..912ec6b35 100644
--- a/test/node/reducers/map-state-test.js
+++ b/test/node/reducers/map-state-test.js
@@ -75,6 +75,150 @@ test('#mapStateReducer -> UPDATE_MAP', t => {
t.end();
});
+// eslint-disable-next-line max-statements
+test('#mapStateReducer -> UPDATE_MAP - minZoom/maxZoom', t => {
+ let mapUpdate = {
+ zoom: 9,
+ maxZoom: 12
+ };
+ let expectedState = {...InitialMapState, ...mapUpdate};
+ let newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'If zoom < maxZoom - zoom should stay the same');
+
+ mapUpdate = {
+ zoom: 14,
+ maxZoom: 12
+ };
+ expectedState = {...InitialMapState, ...mapUpdate, ...{zoom: mapUpdate.maxZoom}};
+ newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'If zoom > maxZoom - zoom should be equal to maxZoom');
+
+ mapUpdate = {
+ zoom: 15,
+ minZoom: 12
+ };
+ expectedState = {...InitialMapState, ...mapUpdate};
+ newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'If zoom > minZoom - zoom should stay the same');
+
+ mapUpdate = {
+ zoom: 9,
+ minZoom: 12
+ };
+ expectedState = {...InitialMapState, ...mapUpdate, ...{zoom: mapUpdate.minZoom}};
+ newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'If zoom < minZoom - zoom should be equal to minZoom');
+
+ mapUpdate = {
+ zoom: 9,
+ minZoom: 3,
+ maxZoom: 15
+ };
+ expectedState = {...InitialMapState, ...mapUpdate};
+ newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'If minZoom < zoom < maxZoom - zoom should stay the same');
+
+ mapUpdate = {
+ zoom: 9,
+ minZoom: 9,
+ maxZoom: 9
+ };
+ expectedState = {...InitialMapState, ...mapUpdate};
+ newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(
+ newState,
+ expectedState,
+ 'If minZoom === zoom === maxZoom - zoom should stay the same'
+ );
+
+ mapUpdate = {
+ zoom: 15,
+ minZoom: 3,
+ maxZoom: 12
+ };
+ expectedState = {...InitialMapState, ...mapUpdate, ...{zoom: mapUpdate.maxZoom}};
+ newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(
+ newState,
+ expectedState,
+ 'If minZoom < maxZoom < zoom - zoom should be equal to maxZoom'
+ );
+
+ mapUpdate = {
+ zoom: 3,
+ minZoom: 6,
+ maxZoom: 12
+ };
+ expectedState = {...InitialMapState, ...mapUpdate, ...{zoom: mapUpdate.minZoom}};
+ newState = reducer(undefined, updateMap(mapUpdate));
+ t.deepEqual(
+ newState,
+ expectedState,
+ 'If zoom < minZoom < maxZoom - zoom should be equal to minZoom'
+ );
+
+ t.end();
+});
+
+test('#mapStateReducer -> UPDATE_MAP - maxBounds', t => {
+ let state = {
+ ...InitialMapState,
+ latitude: 37.685430657228906,
+ longitude: -122.20643775128097,
+ zoom: 5,
+ width: 640,
+ height: 480
+ };
+ let mapUpdate = {
+ maxBounds: [-122.47705311445556, 37.52481163037179, -121.93582238810639, 37.846049684086026]
+ };
+ let expectedState = {
+ ...state,
+ ...mapUpdate,
+ ...{
+ latitude: 37.68560457001023,
+ longitude: -122.20643775128097,
+ zoom: 9.699465540852673
+ }
+ };
+ let newState = reducer(state, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'maxBounds is snapped to the viewport');
+
+ state = {
+ ...InitialMapState,
+ latitude: 37.685430657228906,
+ longitude: -122.20643775128097,
+ zoom: 9,
+ width: 640,
+ height: 480,
+ maxBounds: [-122.47705311445556, 37.52481163037179, -121.93582238810639, 37.846049684086026]
+ };
+ mapUpdate = {
+ zoom: 12
+ };
+ expectedState = {...state, ...mapUpdate};
+ newState = reducer(state, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'Viewport is within maxBounds - zoomed in');
+
+ state = {
+ ...InitialMapState,
+ latitude: 37.685430657228906,
+ longitude: -122.20643775128097,
+ zoom: 9,
+ width: 640,
+ height: 480,
+ maxBounds: [-122.47705311445556, 37.52481163037179, -121.93582238810639, 37.846049684086026]
+ };
+ mapUpdate = {
+ zoom: 8
+ };
+ expectedState = {...state};
+ newState = reducer(state, updateMap(mapUpdate));
+ t.deepEqual(newState, expectedState, 'Viewport is outside the maxBounds - zoomed out');
+
+ t.end();
+});
+
test('#mapStateReducer -> TOGGLE_PERSPECTIVE', t => {
const newState = reducer(undefined, {});
t.equal(newState.dragRotate, false, 'dragRotate should default to false');