static axis scalewith/scaleratio constraints

alexcjohnson · alexcjohnson · commit d9a8ab7bff60 · 2017-03-28T00:59:24.000-04:00
all constraints are satisfied on initial plot, but not yet on zooms
diff --git a/src/plot_api/plot_api.js b/src/plot_api/plot_api.js
@@ -32,6 +32,7 @@ var manageArrays = require('./manage_arrays');
 var helpers = require('./helpers');
 var subroutines = require('./subroutines');
 var cartesianConstants = require('../plots/cartesian/constants');
+var enforceAxisConstraints = require('../plots/cartesian/constraints');
 
 
 /**
@@ -256,18 +257,20 @@ Plotly.plot = function(gd, data, layout, config) {
         return Lib.syncOrAsync([
             Registry.getComponentMethod('shapes', 'calcAutorange'),
             Registry.getComponentMethod('annotations', 'calcAutorange'),
-            doAutoRange,
+            doAutoRangeAndConstraints,
             Registry.getComponentMethod('rangeslider', 'calcAutorange')
         ], gd);
     }
 
-    function doAutoRange() {
+    function doAutoRangeAndConstraints() {
         if(gd._transitioning) return;
 
         var axList = Plotly.Axes.list(gd, '', true);
         for(var i = 0; i < axList.length; i++) {
             Plotly.Axes.doAutoRange(axList[i]);
         }
+
+        enforceAxisConstraints(gd);
     }
 
     // draw ticks, titles, and calculate axis scaling (._b, ._m)
diff --git a/src/plots/cartesian/constraint_defaults.js b/src/plots/cartesian/constraint_defaults.js
@@ -0,0 +1,128 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+
+'use strict';
+
+var Lib = require('../../lib');
+var id2name = require('./axis_ids').id2name;
+
+
+module.exports = function handleConstraintDefaults(containerIn, containerOut, coerce, counterAxes, layoutOut) {
+    var constraintGroups = layoutOut._axisConstraintGroups;
+
+    if(!containerIn.scalewith) return;
+
+    var constraintOpts = getConstraintOpts(constraintGroups, containerOut._id, counterAxes, layoutOut);
+
+    var scalewith = Lib.coerce(containerIn, containerOut, {
+        scalewith: {
+            valType: 'enumerated',
+            values: constraintOpts.linkableAxes
+        }
+    }, 'scalewith');
+
+    if(scalewith) {
+        var scaleratio = coerce('scaleratio');
+        // TODO: I suppose I could do attribute.min: Number.MIN_VALUE to avoid zero,
+        // but that seems hacky. Better way to say "must be a positive number"?
+        // Of course if you use several super-tiny values you could eventually
+        // force a product of these to zero and all hell would break loose...
+        // Likewise with super-huge values.
+        if(!scaleratio) scaleratio = containerOut.scaleratio = 1;
+
+        updateConstraintGroups(constraintGroups, constraintOpts.thisGroup,
+            containerOut._id, scalewith, scaleratio);
+    }
+    else if(counterAxes.indexOf(containerIn.scalewith) !== -1) {
+        Lib.warn('ignored ' + containerOut._name + '.scalewith: "' +
+            containerIn.scalewith + '" to avoid an infinite loop ' +
+            'and possibly inconsistent scaleratios.');
+    }
+};
+
+function getConstraintOpts(constraintGroups, thisID, counterAxes, layoutOut) {
+    // If this axis is already part of a constraint group, we can't
+    // scalewith any other axis in that group, or we'd make a loop.
+    // Filter counterAxes to enforce this, also matching axis types.
+
+    var thisType = layoutOut[id2name(thisID)].type;
+
+    var i, j, idj;
+    for(i = 0; i < constraintGroups.length; i++) {
+        if(constraintGroups[i][thisID]) {
+            var thisGroup = constraintGroups[i];
+
+            var linkableAxes = [];
+            for(j = 0; j < counterAxes.length; j++) {
+                idj = counterAxes[j];
+                if(!thisGroup[idj] && layoutOut[id2name(idj)].type === thisType) {
+                    linkableAxes.push(idj);
+                }
+            }
+            return {linkableAxes: linkableAxes, thisGroup: thisGroup};
+        }
+    }
+
+    return {linkableAxes: counterAxes, thisGroup: null};
+}
+
+
+/*
+ * Add this axis to the axis constraint groups, which is the collection
+ * of axes that are all constrained together on scale.
+ *
+ * constraintGroups: a list of objects. each object is
+ * {axis_id: scale_within_group}, where scale_within_group is
+ * only important relative to the rest of the group, and defines
+ * the relative scales between all axes in the group
+ *
+ * thisGroup: the group the current axis is already in
+ * thisID: the id if the current axis
+ * scalewith: the id of the axis to scale it with
+ * scaleratio: the ratio of this axis to the scalewith axis
+ */
+function updateConstraintGroups(constraintGroups, thisGroup, thisID, scalewith, scaleratio) {
+    var i, j, groupi, keyj, thisGroupIndex;
+
+    if(thisGroup === null) {
+        thisGroup = {};
+        thisGroup[thisID] = 1;
+        thisGroupIndex = constraintGroups.length;
+        constraintGroups.push(thisGroup);
+    }
+    else {
+        thisGroupIndex = constraintGroups.indexOf(thisGroup);
+    }
+
+    var thisGroupKeys = Object.keys(thisGroup);
+
+    // we know that this axis isn't in any other groups, but we don't know
+    // about the scalewith axis. If it is, we need to merge the groups.
+    for(i = 0; i < constraintGroups.length; i++) {
+        groupi = constraintGroups[i];
+        if(i !== thisGroupIndex && groupi[scalewith]) {
+            var baseScale = groupi[scalewith];
+            for(j = 0; j < thisGroupKeys.length; j++) {
+                keyj = thisGroupKeys[j];
+                groupi[keyj] = baseScale * scaleratio * thisGroup[keyj];
+            }
+            constraintGroups.splice(thisGroupIndex, 1);
+            return;
+        }
+    }
+
+    // otherwise, we insert the new scalewith axis as the base scale (1)
+    // in its group, and scale the rest of the group to it
+    if(scaleratio !== 1) {
+        for(j = 0; j < thisGroupKeys.length; j++) {
+            thisGroup[thisGroupKeys[j]] *= scaleratio;
+        }
+    }
+    thisGroup[scalewith] = 1;
+}
diff --git a/src/plots/cartesian/constraints.js b/src/plots/cartesian/constraints.js
@@ -0,0 +1,67 @@
+/**
+* Copyright 2012-2017, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+
+'use strict';
+
+var id2name = require('./axis_ids').id2name;
+
+var ALMOST_EQUAL = 1 - 1e-6;
+
+
+module.exports = function enforceAxisConstraints(gd) {
+    var fullLayout = gd._fullLayout;
+    var layout = gd.layout;
+    var constraintGroups = fullLayout._axisConstraintGroups;
+
+    var i, j, axisID, ax, normScale;
+
+    for(i = 0; i < constraintGroups.length; i++) {
+        var group = constraintGroups[i];
+        var axisIDs = Object.keys(group);
+
+        var minScale = Infinity;
+        var maxScale = 0;
+        var normScales = {};
+        var axes = {};
+
+        // find the (normalized) scale of each axis in the group
+        for(j = 0; j < axisIDs.length; j++) {
+            axisID = axisIDs[j];
+            axes[axisID] = ax = fullLayout[id2name(axisID)];
+
+            // set axis scale here so we can use _m rather than
+            // having to calculate it from length and range
+            ax.setScale();
+
+            // abs: inverted scales still satisfy the constraint
+            normScales[axisID] = normScale = Math.abs(ax._m) / group[axisID];
+            minScale = Math.min(minScale, normScale);
+            maxScale = Math.max(maxScale, normScale);
+        }
+
+        // Do we have a constraint mismatch? Give a small buffer for rounding errors
+        if(minScale > ALMOST_EQUAL * maxScale) continue;
+
+        // now increase any ranges we need to until all normalized scales are equal
+        for(j = 0; j < axisIDs.length; j++) {
+            axisID = axisIDs[j];
+            normScale = normScales[axisID];
+            if(normScale > minScale) {
+                ax = axes[axisID];
+                var rangeLinear = [ax.r2l(ax.range[0]), ax.r2l(ax.range[1])];
+                var center = (rangeLinear[0] + rangeLinear[1]) / 2;
+                var newHalfSpan = (center - rangeLinear[0]) * normScale / minScale;
+                ax.range = layout[id2name(axisID)].range = [
+                    ax.l2r(center - newHalfSpan),
+                    ax.l2r(center + newHalfSpan)
+                ];
+            }
+        }
+    }
+};
diff --git a/src/plots/cartesian/layout_attributes.js b/src/plots/cartesian/layout_attributes.js
@@ -98,7 +98,6 @@ module.exports = {
             'number from zero in the order it appears.'
         ].join(' ')
     },
-
     fixedrange: {
         valType: 'boolean',
         dflt: false,
@@ -108,6 +107,42 @@ module.exports = {
             'If true, then zoom is disabled.'
         ].join(' ')
     },
+    // scalewith: not used directly, just put here for reference
+    // values are any opposite-letter axis id
+    scalewith: {
+        valType: 'enumerated',
+        values: [
+            constants.idRegex.x.toString(),
+            constants.idRegex.y.toString()
+        ],
+        role: 'info',
+        description: [
+            'If set to an opposite-letter axis id (e.g. `x2`, `y`), the range of this axis',
+            'changes together with the range of the corresponding opposite-letter axis.',
+            'such that the scale of pixels per unit is in a constant ratio.',
+            'Both axes are still zoomable, but when you zoom one, the other will',
+            'zoom the same amount, keeping a fixed midpoint.',
+            'Autorange will also expand about the midpoints to satisfy the constraint.',
+            'You can chain these, ie `yaxis: {scalewith: *x*}, xaxis2: {scalewith: *y*}`',
+            'but you can only link axes of the same `type`.',
+            'Loops (`yaxis: {scalewith: *x*}, xaxis: {scalewith: *y*}` or longer) are redundant',
+            'and the last constraint encountered will be ignored to avoid possible',
+            'inconsistent constraints via `scaleratio`.'
+        ].join(' ')
+    },
+    scaleratio: {
+        valType: 'number',
+        min: 0,
+        dflt: 1,
+        role: 'info',
+        description: [
+            'If this axis is linked to another by `scalewith`, this determines the pixel',
+            'to unit scale ratio. For example, if this value is 10, then every unit on',
+            'this axis spans 10 times the number of pixels as a unit on the linked axis.',
+            'Use this for example to create an elevation profile where the vertical scale',
+            'is exaggerated a fixed amount with respect to the horizontal.'
+        ].join(' ')
+    },
     // ticks
     tickmode: {
         valType: 'enumerated',
@@ -430,7 +465,7 @@ module.exports = {
         ],
         role: 'info',
         description: [
-            'If set to an opposite-letter axis id (e.g. `xaxis2`, `yaxis`), this axis is bound to',
+            'If set to an opposite-letter axis id (e.g. `x2`, `y`), this axis is bound to',
             'the corresponding opposite-letter axis.',
             'If set to *free*, this axis\' position is determined by `position`.'
         ].join(' ')
diff --git a/src/plots/cartesian/layout_defaults.js b/src/plots/cartesian/layout_defaults.js
@@ -18,6 +18,7 @@ var constants = require('./constants');
 var layoutAttributes = require('./layout_attributes');
 var handleTypeDefaults = require('./type_defaults');
 var handleAxisDefaults = require('./axis_defaults');
+var handleConstraintDefaults = require('./constraint_defaults');
 var handlePositionDefaults = require('./position_defaults');
 var axisIds = require('./axis_ids');
 
@@ -184,6 +185,8 @@ module.exports = function supplyLayoutDefaults(layoutIn, layoutOut, fullData) {
 
         handleAxisDefaults(axLayoutIn, axLayoutOut, coerce, defaultOptions, layoutOut);
 
+        handleConstraintDefaults(axLayoutIn, axLayoutOut, coerce, counterAxes, layoutOut);
+
         var positioningOptions = {
             letter: axLetter,
             counterAxes: counterAxes,
diff --git a/test/image/baselines/axes_scalewith.png b/test/image/baselines/axes_scalewith.png
diff --git a/test/image/mocks/axes_scalewith.json b/test/image/mocks/axes_scalewith.json
@@ -0,0 +1,15 @@
+{
+  "data":[
+    {"x": [0,1,1,0,0,1,1,2,2,3,3,2,2,3], "y": [0,0,1,1,3,3,2,2,3,3,1,1,0,0]},
+    {"x": [0,1,2,3], "y": [1,2,4,8], "yaxis":"y2"}
+  ],
+  "layout":{
+    "width": 600,
+    "height":600,
+    "title": "fixed-ratio axes",
+    "xaxis": {"nticks": 10, "title": "shared X axis"},
+    "yaxis": {"scalewith": "x", "domain": [0, 0.45], "title": "1:1"},
+    "yaxis2": {"scalewith": "x", "scaleratio": 0.2, "domain": [0.55,1], "title": "1:5"},
+    "showlegend": false
+  }
+}
diff --git a/test/jasmine/tests/axes_test.js b/test/jasmine/tests/axes_test.js
