Add bounds to range and autorange of cartesian, gl3d and radial axes

draftlogs/6547_add.md

@@ -0,0 +1,2 @@
+ - Add bounds to range and autorange of cartesian, gl3d and radial axes [[#6547](https://github.com/plotly/plotly.js/pull/6547)]
+

src/plots/cartesian/autorange.js

@@ -13,6 +13,7 @@ var getFromId = axIds.getFromId;
 var isLinked = axIds.isLinked;
 
 module.exports = {
+    applyAutorangeOptions: applyAutorangeOptions,
     getAutoRange: getAutoRange,
     makePadFn: makePadFn,
     doAutoRange: doAutoRange,
@@ -86,6 +87,12 @@ function getAutoRange(gd, ax) {
     if(ax.autorange === 'reversed') {
         axReverse = true;
         ax.autorange = true;
+    } else if(ax.autorange === 'min reversed') {
+        axReverse = true;
+        ax.autorange = 'min';
+    } else if(ax.autorange === 'max reversed') {
+        axReverse = true;
+        ax.autorange = 'max';
     }
 
     var rangeMode = ax.rangemode;
@@ -176,6 +183,10 @@ function getAutoRange(gd, ax) {
         ];
     }
 
+    newRange = applyAutorangeOptions(newRange, ax);
+
+    if(ax.limitRange) ax.limitRange();
+
     // maintain reversal
     if(axReverse) newRange.reverse();
 
@@ -209,7 +220,7 @@ function makePadFn(fullLayout, ax, max) {
         (ax.ticklabelposition || '').indexOf('inside') !== -1 ||
         (anchorAxis.ticklabelposition || '').indexOf('inside') !== -1
     ) {
-        var axReverse = ax.autorange === 'reversed';
+        var axReverse = ax.isReversed();
         if(!axReverse) {
             var rng = Lib.simpleMap(ax.range, ax.r2l);
             axReverse = rng[1] < rng[0];
@@ -623,3 +634,91 @@ function goodNumber(v) {
 
 function lessOrEqual(v0, v1) { return v0 <= v1; }
 function greaterOrEqual(v0, v1) { return v0 >= v1; }
+
+function applyAutorangeMinOptions(v, ax) {
+    var autorangeoptions = ax.autorangeoptions;
+    if(
+        autorangeoptions &&
+        autorangeoptions.minallowed !== undefined &&
+        hasValidMinAndMax(ax, autorangeoptions.minallowed, autorangeoptions.maxallowed)
+    ) {
+        return autorangeoptions.minallowed;
+    }
+
+    if(
+        autorangeoptions &&
+        autorangeoptions.clipmin !== undefined &&
+        hasValidMinAndMax(ax, autorangeoptions.clipmin, autorangeoptions.clipmax)
+    ) {
+        return Math.max(v, ax.d2l(autorangeoptions.clipmin));
+    }
+    return v;
+}
+
+function applyAutorangeMaxOptions(v, ax) {
+    var autorangeoptions = ax.autorangeoptions;
+
+    if(
+        autorangeoptions &&
+        autorangeoptions.maxallowed !== undefined &&
+        hasValidMinAndMax(ax, autorangeoptions.minallowed, autorangeoptions.maxallowed)
+    ) {
+        return autorangeoptions.maxallowed;
+    }
+
+    if(
+        autorangeoptions &&
+        autorangeoptions.clipmax !== undefined &&
+        hasValidMinAndMax(ax, autorangeoptions.clipmin, autorangeoptions.clipmax)
+    ) {
+        return Math.min(v, ax.d2l(autorangeoptions.clipmax));
+    }
+
+    return v;
+}
+
+function hasValidMinAndMax(ax, min, max) {
+    // in case both min and max are defined, ensure min < max
+    if(
+        min !== undefined &&
+        max !== undefined
+    ) {
+        min = ax.d2l(min);
+        max = ax.d2l(max);
+        return min < max;
+    }
+    return true;
+}
+
+// this function should be (and is) called before reversing the range
+// so range[0] is the minimum and range[1] is the maximum
+function applyAutorangeOptions(range, ax) {
+    if(!ax || !ax.autorangeoptions) return range;
+
+    var min = range[0];
+    var max = range[1];
+
+    var include = ax.autorangeoptions.include;
+    if(include !== undefined) {
+        var lMin = ax.d2l(min);
+        var lMax = ax.d2l(max);
+
+        if(!Lib.isArrayOrTypedArray(include)) include = [include];
+        for(var i = 0; i < include.length; i++) {
+            var v = ax.d2l(include[i]);
+            if(lMin >= v) {
+                lMin = v;
+                min = v;
+            }
+            if(lMax <= v) {
+                lMax = v;
+                max = v;
+            }
+        }
+    }
+
+    min = applyAutorangeMinOptions(min, ax);
+    max = applyAutorangeMaxOptions(max, ax);
+
+    return [min, max];
+}

src/plots/cartesian/autorange_options_defaults.js

@@ -0,0 +1,23 @@
+'use strict';
+
+module.exports = function handleAutorangeOptionsDefaults(coerce, autorange, range) {
+    var minRange, maxRange;
+    if(range) {
+        var isReversed = (
+            autorange === 'reversed' ||
+            autorange === 'min reversed' ||
+            autorange === 'max reversed'
+        );
+
+        minRange = range[isReversed ? 1 : 0];
+        maxRange = range[isReversed ? 0 : 1];
+    }
+
+    var minallowed = coerce('autorangeoptions.minallowed', maxRange === null ? minRange : undefined);
+    var maxallowed = coerce('autorangeoptions.maxallowed', minRange === null ? maxRange : undefined);
+
+    if(minallowed === undefined) coerce('autorangeoptions.clipmin');
+    if(maxallowed === undefined) coerce('autorangeoptions.clipmax');
+
+    coerce('autorangeoptions.include');
+};

src/plots/cartesian/axis_defaults.js

@@ -15,6 +15,7 @@ var handleTickLabelDefaults = require('./tick_label_defaults');
 var handlePrefixSuffixDefaults = require('./prefix_suffix_defaults');
 var handleCategoryOrderDefaults = require('./category_order_defaults');
 var handleLineGridDefaults = require('./line_grid_defaults');
+var handleAutorangeOptionsDefaults = require('./autorange_options_defaults');
 var setConvert = require('./set_convert');
 
 var DAY_OF_WEEK = require('./constants').WEEKDAY_PATTERN;
@@ -91,12 +92,19 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
 
     setConvert(containerOut, layoutOut);
 
-    var autorangeDflt = !containerOut.isValidRange(containerIn.range);
-    if(autorangeDflt && options.reverseDflt) autorangeDflt = 'reversed';
+    coerce('minallowed');
+    coerce('maxallowed');
+    var range = coerce('range');
+
+    var autorangeDflt = containerOut.getAutorangeDflt(range, options);
+
     var autoRange = coerce('autorange', autorangeDflt);
-    if(autoRange && (axType === 'linear' || axType === '-')) coerce('rangemode');
+    if(autoRange) {
+        handleAutorangeOptionsDefaults(coerce, autoRange, range);
+
+        if(axType === 'linear' || axType === '-') coerce('rangemode');
+    }
 
-    coerce('range');
     containerOut.cleanRange();
 
     handleCategoryOrderDefaults(containerIn, containerOut, coerce, options);

src/plots/cartesian/constraints.js

@@ -145,7 +145,12 @@ exports.handleDefaults = function(layoutIn, layoutOut, opts) {
             // special logic for coupling of range and autorange
             // if nobody explicitly specifies autorange, but someone does
             // explicitly specify range, autorange must be disabled.
-            if(attr === 'range' && val) {
+            if(attr === 'range' && val &&
+                axIn.range &&
+                axIn.range.length === 2 &&
+                axIn.range[0] !== null &&
+                axIn.range[1] !== null
+            ) {
                 hasRange = true;
             }
             if(attr === 'autorange' && val === null && hasRange) {

src/plots/cartesian/dragbox.js

@@ -565,6 +565,7 @@ function makeDragBox(gd, plotinfo, x, y, w, h, ns, ew) {
         if(xActive === 'ew' || yActive === 'ns') {
             var spDx = xActive ? -dx : 0;
             var spDy = yActive ? -dy : 0;
+
             if(matches.isSubplotConstrained) {
                 if(xActive && yActive) {
                     var frac = (dx / pw - dy / ph) / 2;
@@ -874,6 +875,13 @@ function makeDragBox(gd, plotinfo, x, y, w, h, ns, ew) {
                 if(sp._scene) {
                     var xrng = Lib.simpleMap(xa.range, xa.r2l);
                     var yrng = Lib.simpleMap(ya.range, ya.r2l);
+
+                    if(xa.limitRange) xa.limitRange();
+                    if(ya.limitRange) ya.limitRange();
+
+                    xrng = xa.range;
+                    yrng = ya.range;
+
                     sp._scene.update({range: [xrng[0], yrng[0], xrng[1], yrng[1]]});
                 }
             }
@@ -915,6 +923,14 @@ function makeDragBox(gd, plotinfo, x, y, w, h, ns, ew) {
                     clipDx = scaleAndGetShift(xa, xScaleFactor2);
                 }
 
+                if(xScaleFactor2 > 1 && (
+                    (xa.maxallowed !== undefined && editX === (xa.range[0] < xa.range[1] ? 'e' : 'w')) ||
+                    (xa.minallowed !== undefined && editX === (xa.range[0] < xa.range[1] ? 'w' : 'e'))
+                )) {
+                    xScaleFactor2 = 1;
+                    clipDx = 0;
+                }
+
                 if(editY2) {
                     yScaleFactor2 = yScaleFactor;
                     clipDy = ns || matches.isSubplotConstrained ? viewBox[1] : getShift(ya, yScaleFactor2);
@@ -931,6 +947,14 @@ function makeDragBox(gd, plotinfo, x, y, w, h, ns, ew) {
                     clipDy = scaleAndGetShift(ya, yScaleFactor2);
                 }
 
+                if(yScaleFactor2 > 1 && (
+                    (ya.maxallowed !== undefined && editY === (ya.range[0] < ya.range[1] ? 'n' : 's')) ||
+                    (ya.minallowed !== undefined && editY === (ya.range[0] < ya.range[1] ? 's' : 'n'))
+                )) {
+                    yScaleFactor2 = 1;
+                    clipDy = 0;
+                }
+
                 // don't scale at all if neither axis is scalable here
                 if(!xScaleFactor2 && !yScaleFactor2) {
                     continue;
@@ -1096,6 +1120,8 @@ function dragAxList(axList, pix) {
                     axi.l2r(axi._rl[1] - pix / axi._m)
                 ];
             }
+
+            if(axi.limitRange) axi.limitRange();
         }
     }
 }

src/plots/cartesian/layout_attributes.js

@@ -272,17 +272,69 @@ module.exports = {
     },
     autorange: {
         valType: 'enumerated',
-        values: [true, false, 'reversed'],
+        values: [true, false, 'reversed', 'min reversed', 'max reversed', 'min', 'max'],
         dflt: true,
         editType: 'axrange',
         impliedEdits: {'range[0]': undefined, 'range[1]': undefined},
         description: [
             'Determines whether or not the range of this axis is',
             'computed in relation to the input data.',
             'See `rangemode` for more info.',
-            'If `range` is provided, then `autorange` is set to *false*.'
+            'If `range` is provided and it has a value for both the',
+            ' lower and upper bound, `autorange` is set to *false*.',
+            'Using *min* applies autorange only to set the minimum.',
+            'Using *max* applies autorange only to set the maximum.',
+            'Using *min reversed* applies autorange only to set the minimum on a reversed axis.',
+            'Using *max reversed* applies autorange only to set the maximum on a reversed axis.',
+            'Using *reversed* applies autorange on both ends and reverses the axis direction.',
         ].join(' ')
     },
+    autorangeoptions: {
+        minallowed: {
+            valType: 'any',
+            editType: 'plot',
+            impliedEdits: {'range[0]': undefined, 'range[1]': undefined},
+            description: [
+                'Use this value exactly as autorange minimum.'
+            ].join(' ')
+        },
+        maxallowed: {
+            valType: 'any',
+            editType: 'plot',
+            impliedEdits: {'range[0]': undefined, 'range[1]': undefined},
+            description: [
+                'Use this value exactly as autorange maximum.'
+            ].join(' ')
+        },
+        clipmin: {
+            valType: 'any',
+            editType: 'plot',
+            impliedEdits: {'range[0]': undefined, 'range[1]': undefined},
+            description: [
+                'Clip autorange minimum if it goes beyond this value.',
+                'Has no effect when `autorangeoptions.minallowed` is provided.'
+            ].join(' ')
+        },
+        clipmax: {
+            valType: 'any',
+            editType: 'plot',
+            impliedEdits: {'range[0]': undefined, 'range[1]': undefined},
+            description: [
+                'Clip autorange maximum if it goes beyond this value.',
+                'Has no effect when `autorangeoptions.maxallowed` is provided.'
+            ].join(' ')
+        },
+        include: {
+            valType: 'any',
+            arrayOk: true,
+            editType: 'plot',
+            impliedEdits: {'range[0]': undefined, 'range[1]': undefined},
+            description: [
+                'Ensure this value is included in autorange.'
+            ].join(' ')
+        },
+        editType: 'plot'
+    },
     rangemode: {
         valType: 'enumerated',
         values: ['normal', 'tozero', 'nonnegative'],
@@ -317,7 +369,24 @@ module.exports = {
             'will be accepted and converted to strings.',
             'If the axis `type` is *category*, it should be numbers,',
             'using the scale where each category is assigned a serial',
-            'number from zero in the order it appears.'
+            'number from zero in the order it appears.',
+            'Leaving either or both elements `null` impacts the default `autorange`.',
+        ].join(' ')
+    },
+    minallowed: {
+        valType: 'any',
+        editType: 'plot',
+        impliedEdits: {'^autorange': false},
+        description: [
+            'Determines the minimum range of this axis.'
+        ].join(' ')
+    },
+    maxallowed: {
+        valType: 'any',
+        editType: 'plot',
+        impliedEdits: {'^autorange': false},
+        description: [
+            'Determines the maximum range of this axis.'
         ].join(' ')
     },
     fixedrange: {