feat: Add min/max scale limits for geo plots

draftlogs/7371_add.md

@@ -0,0 +1 @@
+ - Add `minscale`, `maxscale` geo plot attributes [[#7371](https://github.com/plotly/plotly.js/pull/7371)]

src/components/modebar/buttons.js

@@ -546,9 +546,22 @@ function handleGeo(gd, ev) {
 
         if(attr === 'zoom') {
             var scale = geoLayout.projection.scale;
+            var minscale = geoLayout.projection.minscale;
+            var maxscale = geoLayout.projection.maxscale === -1 ? Infinity : geoLayout.projection.maxscale;
+            var max = Math.max(minscale, maxscale);
+            var min = Math.min(minscale, maxscale);
             var newScale = (val === 'in') ? 2 * scale : 0.5 * scale;
 
-            Registry.call('_guiRelayout', gd, id + '.projection.scale', newScale);
+            // make sure the scale is within the min/max bounds
+            if (newScale > max) {
+                newScale = max;
+            } else if (newScale < min) {
+                newScale = min;
+            }
+
+            if (newScale !== scale) {
+                Registry.call('_guiRelayout', gd, id + '.projection.scale', newScale);
+            }
         }
     }
 

src/plots/geo/geo.js

@@ -484,7 +484,10 @@ proto.updateFx = function(fullLayout, geoLayout) {
 
     if(dragMode === 'pan') {
         bgRect.node().onmousedown = null;
-        bgRect.call(createGeoZoom(_this, geoLayout));
+        var zoom = createGeoZoom(_this, geoLayout)
+        bgRect.call(zoom);
+        // Trigger zoom transition to account for initial min/max scale values
+        if (geoLayout.projection.minscale > 0 && !d3.event) zoom.event(bgRect);
         bgRect.on('dblclick.zoom', zoomReset);
         if(!gd._context._scrollZoom.geo) {
             bgRect.on('wheel.zoom', null);
@@ -709,6 +712,15 @@ function getProjection(geoLayout) {
 
     projection.precision(constants.precision);
 
+    // https://d3js.org/d3-zoom#zoom_scaleExtent
+    projection.scaleExtent = () => {
+        var minscale = projLayout.minscale;
+        var maxscale = projLayout.maxscale === -1 ? Infinity : projLayout.maxscale;
+        var max = Math.max(minscale, maxscale);
+        var min = Math.min(minscale, maxscale);
+        return [100 * min, 100 * max];
+    };
+
     if(geoLayout._isSatellite) {
         projection.tilt(projLayout.tilt).distance(projLayout.distance);
     }

src/plots/geo/layout_attributes.js

@@ -177,6 +177,26 @@ var attrs = module.exports = overrideAll({
                 'that fits the map\'s lon and lat ranges. '
             ].join(' ')
         },
+        minscale: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            description: [
+                'Minimal zoom level of the map view.',
+                'A minscale of *0.5* (50%) corresponds to a zoom level',
+                'where the map has half the size of base zoom level.'
+            ].join(' ')
+        },
+        maxscale: {
+            valType: 'number',
+            min: 0,
+            dflt: -1,
+            description: [
+                'Maximal zoom level of the map view.',
+                'A maxscale of *2* (200%) corresponds to a zoom level',
+                'where the map is twice as big as the base layer.'
+            ].join(' ')
+        },
     },
     center: {
         lon: {

src/plots/geo/layout_defaults.js

@@ -161,6 +161,8 @@ function handleGeoDefaults(geoLayoutIn, geoLayoutOut, coerce, opts) {
     }
 
     coerce('projection.scale');
+    coerce('projection.minscale');
+    coerce('projection.maxscale');
 
     show = coerce('showland', !visible ? false : undefined);
     if(show) coerce('landcolor');

src/plots/geo/zoom.js

@@ -32,6 +32,7 @@ module.exports = createGeoZoom;
 function initZoom(geo, projection) {
     return d3.behavior.zoom()
         .translate(projection.translate())
+        .scaleExtent(projection.scaleExtent())
         .scale(projection.scale());
 }
 
@@ -132,16 +133,21 @@ function zoomNonClipped(geo, projection) {
     function handleZoomstart() {
         d3.select(this).style(zoomstartStyle);
 
-        mouse0 = d3.mouse(this);
+        var rect = this.getBBox()
+        mouse0 = d3.event.sourceEvent
+            ? d3.mouse(this)
+            : [rect.x + rect.width / 2, rect.y + rect.height / 2];
         rotate0 = projection.rotate();
         translate0 = projection.translate();
         lastRotate = rotate0;
         zoomPoint = position(mouse0);
     }
 
     function handleZoom() {
-        mouse1 = d3.mouse(this);
-
+        var rect = this.getBBox()
+        mouse1 = d3.event.sourceEvent
+            ? d3.mouse(this)
+            : [rect.x + rect.width / 2, rect.y + rect.height / 2];
         if(outside(mouse0)) {
             zoom.scale(projection.scale());
             zoom.translate(projection.translate());
@@ -210,7 +216,10 @@ function zoomClipped(geo, projection) {
     zoom.on('zoomstart', function() {
         d3.select(this).style(zoomstartStyle);
 
-        var mouse0 = d3.mouse(this);
+        var rect = this.getBBox()
+        var mouse0 = d3.event.sourceEvent
+            ? d3.mouse(this)
+            : [rect.x + rect.width / 2, rect.y + rect.height / 2];
         var rotate0 = projection.rotate();
         var lastRotate = rotate0;
         var translate0 = projection.translate();
@@ -219,7 +228,10 @@ function zoomClipped(geo, projection) {
         zoomPoint = position(projection, mouse0);
 
         zoomOn.call(zoom, 'zoom', function() {
-            var mouse1 = d3.mouse(this);
+            var rect = this.getBBox()
+            var mouse1 = d3.event.sourceEvent
+                ? d3.mouse(this)
+                : [rect.x + rect.width / 2, rect.y + rect.height / 2];
 
             projection.scale(view.k = d3.event.scale);
 

test/jasmine/tests/geo_test.js

@@ -2730,6 +2730,83 @@ describe('Test geo zoom/pan/drag interactions:', function() {
         })
         .then(done, done.fail);
     });
+
+    describe('minscale and maxscale', () => {
+        const defaultConfig = {
+            layout: {
+                dragmode: 'pan',
+                geo: { projection: {} },
+                height: 500,
+                width: 700
+            }
+        }
+        let gd;
+
+        beforeEach(() => { gd = createGraphDiv(); });
+
+        afterEach(destroyGraphDiv);
+
+        const allTests = [
+            {
+                name: 'non-clipped',
+                mock: require('../../image/mocks/geo_winkel-tripel')
+            },
+            {
+                name: 'clipped',
+                mock: require('../../image/mocks/geo_orthographic')
+            },
+            {
+                name: 'scoped',
+                mock: require('../../image/mocks/geo_europe-bubbles')
+            }
+        ];
+
+        allTests.forEach(({ mock, name }) => {
+            it(`${name} maxscale`, done => {
+                const fig = Lib.extendDeep({}, mock, defaultConfig);
+                fig.layout.geo.projection.maxscale = 1.2;
+
+                Plotly
+                    .newPlot(gd, fig)
+                    // Zoom in far enough to hit limit
+                    .then(() => scroll([200, 250], [-200, -200]))
+                    .then(() => {
+                        const maxScale = gd._fullLayout.geo._subplot.projection.scaleExtent()[1];
+                        expect(gd._fullLayout.geo._subplot.projection.scale()).toEqual(maxScale);
+                    })
+                    .then(done, done.fail);
+            });
+
+            it(`${name} minscale`, done => {
+                const fig = Lib.extendDeep({}, mock, defaultConfig);
+                fig.layout.geo.projection.minscale = 0.8;
+
+                Plotly
+                    .newPlot(gd, fig)
+                    // Zoom out far enough to hit limit
+                    .then(() => scroll([200, 250], [1000, 1000]))
+                    .then(() => {
+                        const minScale = gd._fullLayout.geo._subplot.projection.scaleExtent()[0];
+                        expect(gd._fullLayout.geo._subplot.projection.scale()).toEqual(minScale);
+                    })
+                    .then(done, done.fail);
+            });
+
+            it(`${name} minscale greater than 1`, done => {
+                const fig = Lib.extendDeep({}, mock, defaultConfig);
+                fig.layout.geo.projection.minscale = 3;
+
+                Plotly
+                    .newPlot(gd, fig)
+                    // The limit should already be hit during plot creation
+                    .then(() => {
+                        const minScale = gd._fullLayout.geo._subplot.projection.scaleExtent()[0];
+                        expect(gd._fullLayout.geo._subplot.projection.scale()).toEqual(minScale);
+                    })
+                    .then(done, done.fail);
+            });
+        });
+    });
 });
 
 describe('Test geo interactions update marker angles:', function() {

test/plot-schema.json

@@ -2373,6 +2373,20 @@
       "valType": "number"
      },
      "editType": "plot",
+     "maxscale": {
+      "description": "Maximal zoom level of the map view. A maxscale of *2* (200%) corresponds to a zoom level where the map is twice as big as the base layer.",
+      "dflt": -1,
+      "editType": "plot",
+      "min": 0,
+      "valType": "number"
+     },
+     "minscale": {
+      "description": "Minimal zoom level of the map view. A minscale of *0.5* (50%) corresponds to a zoom level where the map has half the size of base zoom level.",
+      "dflt": 0,
+      "editType": "plot",
+      "min": 0,
+      "valType": "number"
+     },
      "parallels": {
       "description": "For conic projection types only. Sets the parallels (tangent, secant) where the cone intersects the sphere.",
       "editType": "plot",