Snap to integer zoom level

src/ui/camera.ts

@@ -96,6 +96,31 @@ export type JumpToOptions = CameraOptions & {
     padding?: PaddingOptions;
 }
 
+/**
+ * The options object related to the {@link Map#shouldSnapToIntegerZoom} method
+ */
+export type SnapToIntegerZoomOptions = {
+    /**
+     * Whether snaps to integer zoom levels when box zooming.
+     */
+    boxZoom: boolean;
+
+    /**
+     * Whether snaps to integer zoom levels when double click zooming.
+     */
+    clickZoom: boolean;
+
+    /**
+     * Whether snaps to integer zoom levels when scroll zooming.
+     */
+    scrollZoom: boolean;
+
+    /**
+     * Whether snaps to integer zoom levels when tap zooming.
+     */
+    tapZoom: boolean;
+}
+
 /**
  * A options object for the {@link Map#cameraForBounds} method
  */
@@ -113,6 +138,11 @@ export type CameraForBoundsOptions = CameraOptions & {
      * The maximum zoom level to allow when the camera would transition to the specified bounds.
      */
     maxZoom?: number;
+
+    /**
+     * Whether the map should snap to integer zoom levels during the transition.
+     */
+    shouldSnapToIntegerZoom?: boolean;
 }
 
 /**
@@ -728,7 +758,8 @@ export abstract class Camera extends Evented {
             return undefined;
         }
 
-        const zoom = Math.min(tr.scaleZoom(tr.scale * Math.min(scaleX, scaleY)), options.maxZoom);
+        const floatZoom = Math.min(tr.scaleZoom(tr.scale * Math.min(scaleX, scaleY)), options.maxZoom);
+        const zoom = options.shouldSnapToIntegerZoom ? Math.round(floatZoom) : floatZoom;
 
         // Calculate center: apply the zoom, the configured offset, as well as offset that exists as a result of padding.
         const offset = Point.convert(options.offset);

src/ui/handler/box_zoom.ts

@@ -135,7 +135,11 @@ export class BoxZoomHandler implements Handler {
         } else {
             this._map.fire(new Event('boxzoomend', {originalEvent: e}));
             return {
-                cameraAnimation: map => map.fitScreenCoordinates(p0, p1, this._tr.bearing, {linear: true})
+                cameraAnimation: map => map.fitScreenCoordinates(p0, p1, this._tr.bearing,
+                    {
+                        linear: true,
+                        shouldSnapToIntegerZoom: this._map.shouldSnapToIntegerZoom('boxZoom')
+                    })
             };
         }
     }

src/ui/handler/click_zoom.ts

@@ -27,9 +27,10 @@ export class ClickZoomHandler implements Handler {
         e.preventDefault();
         return {
             cameraAnimation: (map: Map) => {
+                const floatZoomTarget = this._tr.zoom + (e.shiftKey ? -1 : 1);
                 map.easeTo({
                     duration: 300,
-                    zoom: this._tr.zoom + (e.shiftKey ? -1 : 1),
+                    zoom: map.shouldSnapToIntegerZoom('clickZoom') ? Math.round(floatZoomTarget) : floatZoomTarget,
                     around: this._tr.unproject(point)
                 }, {originalEvent: e});
             }

src/ui/handler/scroll_zoom.ts

@@ -154,7 +154,9 @@ export class ScrollZoomHandler implements Handler {
         if (this._map.cooperativeGestures.isEnabled() && !e[this._map.cooperativeGestures._bypassKey]) {
             return;
         }
+
         let value = e.deltaMode === WheelEvent.DOM_DELTA_LINE ? e.deltaY * 40 : e.deltaY;
+
         const now = browser.now(),
             timeDelta = now - (this._lastWheelEventTime || 0);
 
@@ -170,11 +172,13 @@ export class ScrollZoomHandler implements Handler {
 
         } else if (timeDelta > 400) {
             // This is likely a new scroll action.
-            this._type = null;
-            this._lastValue = value;
+            if (!this._map.shouldSnapToIntegerZoom('scrollZoom')) {
+                this._type = null;
+                this._lastValue = value;
 
-            // Start a timeout in case this was a singular event, and dely it by up to 40ms.
-            this._timeout = setTimeout(this._onTimeout, 40, e);
+                // Start a timeout in case this was a singular event, and dely it by up to 40ms.
+                this._timeout = setTimeout(this._onTimeout, 40, e);
+            }
 
         } else if (!this._type) {
             // This is a repeating event, but we don't know the type of event just yet.
@@ -193,6 +197,24 @@ export class ScrollZoomHandler implements Handler {
         // Slow down zoom if shift key is held for more precise zooming
         if (e.shiftKey && value) value = value / 4;
 
+        if (this._map.shouldSnapToIntegerZoom('scrollZoom') && value !== 0) {
+            const pos = DOM.mousePos(this._map.getCanvas(), e);
+            e.preventDefault();
+            let zoomTarget = value > 100 ? this._map.getZoom() - 2 :
+                value > 0 ? this._map.getZoom() - 1 :
+                    value > -100 ? this._map.getZoom() + 1 :
+                        value < -100 ? this._map.getZoom() + 2 : 0;
+
+            zoomTarget = Math.round(zoomTarget);
+
+            this._map.easeTo({
+                duration: 200,
+                zoom: zoomTarget,
+                around: this._tr.unproject(pos)
+            }, {originalEvent: e});
+            return;
+        }
+
         // Only fire the callback if we actually know what type of scrolling device the user uses.
         if (this._type) {
             this._lastWheelEvent = e;
@@ -283,6 +305,7 @@ export class ScrollZoomHandler implements Handler {
 
         const targetZoom = typeof this._targetZoom === 'number' ?
             this._targetZoom : tr.zoom;
+
         const startZoom = this._startZoom;
         const easing = this._easing;
 

src/ui/handler/tap_zoom.ts

@@ -55,11 +55,13 @@ export class TapZoomHandler implements Handler {
             e.preventDefault();
             setTimeout(() => this.reset(), 0);
             return {
-                cameraAnimation: (map: Map) => map.easeTo({
-                    duration: 300,
-                    zoom: tr.zoom + 1,
-                    around: tr.unproject(zoomInPoint)
-                }, {originalEvent: e})
+                cameraAnimation: (map: Map) => {
+                    map.easeTo({
+                        duration: 300,
+                        zoom: map.shouldSnapToIntegerZoom('tapZoom') ? Math.round(tr.zoom + 1) : tr.zoom + 1,
+                        around: tr.unproject(zoomInPoint)
+                    }, {originalEvent: e});
+                }
             };
         } else if (zoomOutPoint) {
             this._active = true;
@@ -68,7 +70,7 @@ export class TapZoomHandler implements Handler {
             return {
                 cameraAnimation: (map: Map) => map.easeTo({
                     duration: 300,
-                    zoom: tr.zoom - 1,
+                    zoom: map.shouldSnapToIntegerZoom('tapZoom') ? Math.round(tr.zoom - 1) : tr.zoom - 1,
                     around: tr.unproject(zoomOutPoint)
                 }, {originalEvent: e})
             };

src/ui/map.ts

@@ -37,7 +37,7 @@ import type {LngLatBoundsLike} from '../geo/lng_lat_bounds';
 import type {AddLayerObject, FeatureIdentifier, StyleOptions, StyleSetterOptions} from '../style/style';
 import type {MapDataEvent} from './events';
 import type {StyleImage, StyleImageInterface, StyleImageMetadata} from '../style/style_image';
-import type {PointLike} from './camera';
+import type {PointLike, SnapToIntegerZoomOptions} from './camera';
 import type {ScrollZoomHandler} from './handler/scroll_zoom';
 import type {BoxZoomHandler} from './handler/box_zoom';
 import type {AroundCenterOptions, TwoFingersTouchPitchHandler} from './handler/two_fingers_touch';
@@ -61,6 +61,8 @@ import type {QueryRenderedFeaturesOptions, QuerySourceFeatureOptions} from '../s
 
 const version = packageJSON.version;
 
+export type SnapToIntegerZoomType = keyof SnapToIntegerZoomOptions;
+
 /**
  * The {@link Map} options object.
  */
@@ -146,6 +148,13 @@ export type MapOptions = {
      * @defaultValue 22
      */
     maxZoom?: number | null;
+
+    /**
+     * Zooming options related to restricting to integer levels.
+     * Useful for raster tiles.
+     */
+    snapToIntegerZoomOptions?: SnapToIntegerZoomOptions | null;
+
     /**
      * The minimum pitch of the map (0-85). Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the MapLibre project.
      * @defaultValue 0
@@ -350,6 +359,7 @@ const defaultOptions = {
 
     minZoom: defaultMinZoom,
     maxZoom: defaultMaxZoom,
+    snapToIntegerZoomOptions: {},
 
     minPitch: defaultMinPitch,
     maxPitch: defaultMaxPitch,
@@ -473,6 +483,7 @@ export class Map extends Camera {
     _overridePixelRatio: number | null;
     _maxCanvasSize: [number, number];
     _terrainDataCallback: (e: MapStyleDataEvent | MapSourceDataEvent) => void;
+    _snapToIntegerZoomOptions: SnapToIntegerZoomOptions;
 
     /**
      * @internal
@@ -580,6 +591,7 @@ export class Map extends Camera {
         this._overridePixelRatio = options.pixelRatio;
         this._maxCanvasSize = options.maxCanvasSize;
         this.transformCameraUpdate = options.transformCameraUpdate;
+        this._snapToIntegerZoomOptions = options.snapToIntegerZoomOptions;
 
         this._imageQueueHandle = ImageRequest.addThrottleControl(() => this.isMoving());
 
@@ -1008,6 +1020,11 @@ export class Map extends Camera {
         } else throw new Error('maxZoom must be greater than the current minZoom');
     }
 
+    setSnapToIntegerZoom(snap: SnapToIntegerZoomOptions): Map {
+        this._snapToIntegerZoomOptions = snap;
+        return this;
+    }
+
     /**
      * Returns the map's maximum allowable zoom level.
      *
@@ -1019,6 +1036,21 @@ export class Map extends Camera {
      */
     getMaxZoom(): number { return this.transform.maxZoom; }
 
+    shouldSnapToIntegerZoom(type: SnapToIntegerZoomType): boolean {
+        switch (type) {
+            case 'boxZoom':
+                return this._snapToIntegerZoomOptions.boxZoom;
+            case 'scrollZoom':
+                return this._snapToIntegerZoomOptions.scrollZoom;
+            case 'tapZoom':
+                return this._snapToIntegerZoomOptions.tapZoom;
+            case 'clickZoom':
+                return this._snapToIntegerZoomOptions.clickZoom;
+            default:
+                return false;
+        }
+    }
+
     /**
      * Sets or clears the map's minimum pitch.
      * If the map's current pitch is lower than the new minimum,

test/build/min.test.ts

@@ -29,7 +29,7 @@ describe('test min build', () => {
 
         // Need to be very frugal when it comes to minified script.
         // Most changes should increase less than 1k.
-        const increaseQuota = 1024;
+        const increaseQuota = 1600;
 
         // decreasement means optimizations, so more generous (4k) but still
         // need to make sure not a big bug that resulted in a big loss.