package.src.plots.cartesian.constraints.js Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of plotly.js Show documentation
Show all versions of plotly.js Show documentation
The open source javascript graphing library that powers plotly
The newest version!
'use strict';
var Lib = require('../../lib');
var autorange = require('./autorange');
var id2name = require('./axis_ids').id2name;
var layoutAttributes = require('./layout_attributes');
var scaleZoom = require('./scale_zoom');
var setConvert = require('./set_convert');
var ALMOST_EQUAL = require('../../constants/numerical').ALMOST_EQUAL;
var FROM_BL = require('../../constants/alignment').FROM_BL;
exports.handleDefaults = function(layoutIn, layoutOut, opts) {
var axIds = opts.axIds;
var axHasImage = opts.axHasImage;
// sets of axes linked by `scaleanchor` OR `matches` along with the
// scaleratios compounded together, populated in handleConstraintDefaults
var constraintGroups = layoutOut._axisConstraintGroups = [];
// similar to _axisConstraintGroups, but only matching axes
var matchGroups = layoutOut._axisMatchGroups = [];
var i, group, axId, axName, axIn, axOut, attr, val;
for(i = 0; i < axIds.length; i++) {
axName = id2name(axIds[i]);
axIn = layoutIn[axName];
axOut = layoutOut[axName];
handleOneAxDefaults(axIn, axOut, {
axIds: axIds,
layoutOut: layoutOut,
hasImage: axHasImage[axName]
});
}
// save matchGroup on each matching axis
function stash(groups, stashAttr) {
for(i = 0; i < groups.length; i++) {
group = groups[i];
for(axId in group) {
layoutOut[id2name(axId)][stashAttr] = group;
}
}
}
stash(matchGroups, '_matchGroup');
// If any axis in a constraint group is fixedrange, they all get fixed
// This covers matches axes, as they're now in the constraintgroup too
// and have not yet been removed (if the group is *only* matching)
for(i = 0; i < constraintGroups.length; i++) {
group = constraintGroups[i];
for(axId in group) {
axOut = layoutOut[id2name(axId)];
if(axOut.fixedrange) {
for(var axId2 in group) {
var axName2 = id2name(axId2);
if((layoutIn[axName2] || {}).fixedrange === false) {
Lib.warn(
'fixedrange was specified as false for axis ' +
axName2 + ' but was overridden because another ' +
'axis in its constraint group has fixedrange true'
);
}
layoutOut[axName2].fixedrange = true;
}
break;
}
}
}
// remove constraint groups that simply duplicate match groups
i = 0;
while(i < constraintGroups.length) {
group = constraintGroups[i];
for(axId in group) {
axOut = layoutOut[id2name(axId)];
if(axOut._matchGroup && Object.keys(axOut._matchGroup).length === Object.keys(group).length) {
constraintGroups.splice(i, 1);
i--;
}
break;
}
i++;
}
// save constraintGroup on each constrained axis
stash(constraintGroups, '_constraintGroup');
// make sure `matching` axes share values of necessary attributes
// Precedence (base axis is the one that doesn't list a `matches`, ie others
// all point to it):
// (1) explicitly defined value in the base axis
// (2) explicitly defined in another axis (arbitrary order)
// (3) default in the base axis
var matchAttrs = [
'constrain',
'range',
'autorange',
'rangemode',
'rangebreaks',
'categoryorder',
'categoryarray'
];
var hasRange = false;
var hasDayOfWeekBreaks = false;
function setAttrVal() {
val = axOut[attr];
if(attr === 'rangebreaks') {
hasDayOfWeekBreaks = axOut._hasDayOfWeekBreaks;
}
}
for(i = 0; i < matchGroups.length; i++) {
group = matchGroups[i];
// find 'matching' range attrs
for(var j = 0; j < matchAttrs.length; j++) {
attr = matchAttrs[j];
val = null;
var baseAx;
for(axId in group) {
axName = id2name(axId);
axIn = layoutIn[axName];
axOut = layoutOut[axName];
if(!(attr in axOut)) {
continue;
}
if(!axOut.matches) {
baseAx = axOut;
// top priority: explicit value in base axis
if(attr in axIn) {
setAttrVal();
break;
}
}
if(val === null && attr in axIn) {
// second priority: first explicit value in another axis
setAttrVal();
}
}
// 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 &&
axIn.range &&
axIn.range.length === 2 &&
axIn.range[0] !== null &&
axIn.range[1] !== null
) {
hasRange = true;
}
if(attr === 'autorange' && val === null && hasRange) {
val = false;
}
if(val === null && attr in baseAx) {
// fallback: default value in base axis
val = baseAx[attr];
}
// but we still might not have a value, which is fine.
if(val !== null) {
for(axId in group) {
axOut = layoutOut[id2name(axId)];
axOut[attr] = attr === 'range' ? val.slice() : val;
if(attr === 'rangebreaks') {
axOut._hasDayOfWeekBreaks = hasDayOfWeekBreaks;
setConvert(axOut, layoutOut);
}
}
}
}
}
};
function handleOneAxDefaults(axIn, axOut, opts) {
var axIds = opts.axIds;
var layoutOut = opts.layoutOut;
var hasImage = opts.hasImage;
var constraintGroups = layoutOut._axisConstraintGroups;
var matchGroups = layoutOut._axisMatchGroups;
var axId = axOut._id;
var axLetter = axId.charAt(0);
var splomStash = ((layoutOut._splomAxes || {})[axLetter] || {})[axId] || {};
var thisID = axOut._id;
var isX = thisID.charAt(0) === 'x';
// Clear _matchGroup & _constraintGroup so relinkPrivateKeys doesn't keep
// an old one around. If this axis is in a group we'll set this again later
axOut._matchGroup = null;
axOut._constraintGroup = null;
function coerce(attr, dflt) {
return Lib.coerce(axIn, axOut, layoutAttributes, attr, dflt);
}
// coerce the constraint mechanics even if this axis has no scaleanchor
// because it may be the anchor of another axis.
coerce('constrain', hasImage ? 'domain' : 'range');
Lib.coerce(axIn, axOut, {
constraintoward: {
valType: 'enumerated',
values: isX ? ['left', 'center', 'right'] : ['bottom', 'middle', 'top'],
dflt: isX ? 'center' : 'middle'
}
}, 'constraintoward');
// If this axis is already part of a constraint group, we can't
// scaleanchor any other axis in that group, or we'd make a loop.
// Filter axIds to enforce this, also matching axis types.
var thisType = axOut.type;
var i, idi;
var linkableAxes = [];
for(i = 0; i < axIds.length; i++) {
idi = axIds[i];
if(idi === thisID) continue;
var axi = layoutOut[id2name(idi)];
if(axi.type === thisType) {
linkableAxes.push(idi);
}
}
var thisGroup = getConstraintGroup(constraintGroups, thisID);
if(thisGroup) {
var linkableAxesNoLoops = [];
for(i = 0; i < linkableAxes.length; i++) {
idi = linkableAxes[i];
if(!thisGroup[idi]) linkableAxesNoLoops.push(idi);
}
linkableAxes = linkableAxesNoLoops;
}
var canLink = linkableAxes.length;
var matches, scaleanchor;
if(canLink && (axIn.matches || splomStash.matches)) {
matches = Lib.coerce(axIn, axOut, {
matches: {
valType: 'enumerated',
values: linkableAxes,
dflt: linkableAxes.indexOf(splomStash.matches) !== -1 ? splomStash.matches : undefined
}
}, 'matches');
}
// 'matches' wins over 'scaleanchor' - each axis can only specify one
// constraint, but you can chain matches and scaleanchor constraints by
// specifying them in separate axes.
var scaleanchorDflt = hasImage && !isX ? axOut.anchor : undefined;
if(canLink && !matches && (axIn.scaleanchor || scaleanchorDflt)) {
scaleanchor = Lib.coerce(axIn, axOut, {
scaleanchor: {
valType: 'enumerated',
values: linkableAxes.concat([false])
}
}, 'scaleanchor', scaleanchorDflt);
}
if(matches) {
axOut._matchGroup = updateConstraintGroups(matchGroups, thisID, matches, 1);
// Also include match constraints in the scale groups
var matchedAx = layoutOut[id2name(matches)];
var matchRatio = extent(layoutOut, axOut) / extent(layoutOut, matchedAx);
if(isX !== (matches.charAt(0) === 'x')) {
// We don't yet know the actual scale ratio of x/y matches constraints,
// due to possible automargins, so just leave a placeholder for this:
// 'x' means "x size over y size", 'y' means the inverse.
// in principle in the constraint group you could get multiple of these.
matchRatio = (isX ? 'x' : 'y') + matchRatio;
}
updateConstraintGroups(constraintGroups, thisID, matches, matchRatio);
} else if(axIn.matches && axIds.indexOf(axIn.matches) !== -1) {
Lib.warn('ignored ' + axOut._name + '.matches: "' +
axIn.matches + '" to avoid an infinite loop');
}
if(scaleanchor) {
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 = axOut.scaleratio = 1;
updateConstraintGroups(constraintGroups, thisID, scaleanchor, scaleratio);
} else if(axIn.scaleanchor && axIds.indexOf(axIn.scaleanchor) !== -1) {
Lib.warn('ignored ' + axOut._name + '.scaleanchor: "' +
axIn.scaleanchor + '" to avoid either an infinite loop ' +
'and possibly inconsistent scaleratios, or because this axis ' +
'declares a *matches* constraint.');
}
}
function extent(layoutOut, ax) {
var domain = ax.domain;
if(!domain) {
// at this point overlaying axes haven't yet inherited their main domains
// TODO: constrain: domain with overlaying axes is likely a bug.
domain = layoutOut[id2name(ax.overlaying)].domain;
}
return domain[1] - domain[0];
}
function getConstraintGroup(groups, thisID) {
for(var i = 0; i < groups.length; i++) {
if(groups[i][thisID]) {
return groups[i];
}
}
return null;
}
/*
* Add this axis to the axis constraint groups, which is the collection
* of axes that are all constrained together on scale (or matching).
*
* 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
* thatID: the id of the axis to scale it with
* scaleratio: the ratio of this axis to the thatID axis
*/
function updateConstraintGroups(constraintGroups, thisID, thatID, scaleratio) {
var i, j, groupi, keyj, thisGroupIndex;
var thisGroup = getConstraintGroup(constraintGroups, thisID);
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 thatID axis. If it is, we need to merge the groups.
for(i = 0; i < constraintGroups.length; i++) {
groupi = constraintGroups[i];
if(i !== thisGroupIndex && groupi[thatID]) {
var baseScale = groupi[thatID];
for(j = 0; j < thisGroupKeys.length; j++) {
keyj = thisGroupKeys[j];
groupi[keyj] = multiplyScales(baseScale, multiplyScales(scaleratio, thisGroup[keyj]));
}
constraintGroups.splice(thisGroupIndex, 1);
return;
}
}
// otherwise, we insert the new thatID 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++) {
var key = thisGroupKeys[j];
thisGroup[key] = multiplyScales(scaleratio, thisGroup[key]);
}
}
thisGroup[thatID] = 1;
}
// scales may be numbers or 'x1.3', 'yy4.5' etc to multiply by as-yet-unknown
// ratios between x and y plot sizes n times
function multiplyScales(a, b) {
var aPrefix = '';
var bPrefix = '';
var aLen, bLen;
if(typeof a === 'string') {
aPrefix = a.match(/^[xy]*/)[0];
aLen = aPrefix.length;
a = +a.substr(aLen);
}
if(typeof b === 'string') {
bPrefix = b.match(/^[xy]*/)[0];
bLen = bPrefix.length;
b = +b.substr(bLen);
}
var c = a * b;
// just two numbers
if(!aLen && !bLen) {
return c;
}
// one or more prefixes of the same type
if(!aLen || !bLen || aPrefix.charAt(0) === bPrefix.charAt(0)) {
return aPrefix + bPrefix + (a * b);
}
// x and y cancel each other out exactly - back to a number
if(aLen === bLen) {
return c;
}
// partial cancelation of prefixes
return (aLen > bLen ? aPrefix.substr(bLen) : bPrefix.substr(aLen)) + c;
}
function finalRatios(group, fullLayout) {
var size = fullLayout._size;
var yRatio = size.h / size.w;
var out = {};
var keys = Object.keys(group);
for(var i = 0; i < keys.length; i++) {
var key = keys[i];
var val = group[key];
if(typeof val === 'string') {
var prefix = val.match(/^[xy]*/)[0];
var pLen = prefix.length;
val = +val.substr(pLen);
var mult = prefix.charAt(0) === 'y' ? yRatio : (1 / yRatio);
for(var j = 0; j < pLen; j++) {
val *= mult;
}
}
out[key] = val;
}
return out;
}
exports.enforce = function enforce(gd) {
var fullLayout = gd._fullLayout;
var constraintGroups = fullLayout._axisConstraintGroups || [];
var i, j, group, axisID, ax, normScale, mode, factor;
// matching constraints are handled in the autorange code when autoranged,
// or in the supplyDefaults code when explicitly ranged.
// now we just need to handle scaleanchor constraints
// matches constraints that chain with scaleanchor constraints are included
// here too, but because matches has already been satisfied,
// any changes here should preserve that.
for(i = 0; i < constraintGroups.length; i++) {
group = finalRatios(constraintGroups[i], fullLayout);
var axisIDs = Object.keys(group);
var minScale = Infinity;
var maxScale = 0;
// mostly matchScale will be the same as minScale
// ie we expand axis ranges to encompass *everything*
// that's currently in any of their ranges, but during
// autorange of a subset of axes we will ignore other
// axes for this purpose.
var matchScale = Infinity;
var normScales = {};
var axes = {};
var hasAnyDomainConstraint = false;
// 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)];
if(ax._inputDomain) ax.domain = ax._inputDomain.slice();
else ax._inputDomain = ax.domain.slice();
if(!ax._inputRange) ax._inputRange = ax.range.slice();
// 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);
if(ax.constrain === 'domain' || !ax._constraintShrinkable) {
matchScale = Math.min(matchScale, normScale);
}
// this has served its purpose, so remove it
delete ax._constraintShrinkable;
maxScale = Math.max(maxScale, normScale);
if(ax.constrain === 'domain') hasAnyDomainConstraint = true;
}
// Do we have a constraint mismatch? Give a small buffer for rounding errors
if(minScale > ALMOST_EQUAL * maxScale && !hasAnyDomainConstraint) 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];
ax = axes[axisID];
mode = ax.constrain;
// even if the scale didn't change, if we're shrinking domain
// we need to recalculate in case `constraintoward` changed
if(normScale !== matchScale || mode === 'domain') {
factor = normScale / matchScale;
if(mode === 'range') {
scaleZoom(ax, factor);
} else {
// mode === 'domain'
var inputDomain = ax._inputDomain;
var domainShrunk = (ax.domain[1] - ax.domain[0]) /
(inputDomain[1] - inputDomain[0]);
var rangeShrunk = (ax.r2l(ax.range[1]) - ax.r2l(ax.range[0])) /
(ax.r2l(ax._inputRange[1]) - ax.r2l(ax._inputRange[0]));
factor /= domainShrunk;
if(factor * rangeShrunk < 1) {
// we've asked to magnify the axis more than we can just by
// enlarging the domain - so we need to constrict range
ax.domain = ax._input.domain = inputDomain.slice();
scaleZoom(ax, factor);
continue;
}
if(rangeShrunk < 1) {
// the range has previously been constricted by ^^, but we've
// switched to the domain-constricted regime, so reset range
ax.range = ax._input.range = ax._inputRange.slice();
factor *= rangeShrunk;
}
if(ax.autorange) {
/*
* range & factor may need to change because range was
* calculated for the larger scaling, so some pixel
* paddings may get cut off when we reduce the domain.
*
* This is easier than the regular autorange calculation
* because we already know the scaling `m`, but we still
* need to cut out impossible constraints (like
* annotations with super-long arrows). That's what
* outerMin/Max are for - if the expansion was going to
* go beyond the original domain, it must be impossible
*/
var rl0 = ax.r2l(ax.range[0]);
var rl1 = ax.r2l(ax.range[1]);
var rangeCenter = (rl0 + rl1) / 2;
var rangeMin = rangeCenter;
var rangeMax = rangeCenter;
var halfRange = Math.abs(rl1 - rangeCenter);
// extra tiny bit for rounding errors, in case we actually
// *are* expanding to the full domain
var outerMin = rangeCenter - halfRange * factor * 1.0001;
var outerMax = rangeCenter + halfRange * factor * 1.0001;
var getPadMin = autorange.makePadFn(fullLayout, ax, 0);
var getPadMax = autorange.makePadFn(fullLayout, ax, 1);
updateDomain(ax, factor);
var m = Math.abs(ax._m);
var extremes = autorange.concatExtremes(gd, ax);
var minArray = extremes.min;
var maxArray = extremes.max;
var newVal;
var k;
for(k = 0; k < minArray.length; k++) {
newVal = minArray[k].val - getPadMin(minArray[k]) / m;
if(newVal > outerMin && newVal < rangeMin) {
rangeMin = newVal;
}
}
for(k = 0; k < maxArray.length; k++) {
newVal = maxArray[k].val + getPadMax(maxArray[k]) / m;
if(newVal < outerMax && newVal > rangeMax) {
rangeMax = newVal;
}
}
var domainExpand = (rangeMax - rangeMin) / (2 * halfRange);
factor /= domainExpand;
rangeMin = ax.l2r(rangeMin);
rangeMax = ax.l2r(rangeMax);
ax.range = ax._input.range = (rl0 < rl1) ?
[rangeMin, rangeMax] : [rangeMax, rangeMin];
}
updateDomain(ax, factor);
}
}
}
}
};
exports.getAxisGroup = function getAxisGroup(fullLayout, axId) {
var matchGroups = fullLayout._axisMatchGroups;
for(var i = 0; i < matchGroups.length; i++) {
var group = matchGroups[i];
if(group[axId]) return 'g' + i;
}
return axId;
};
// For use before autoranging, check if this axis was previously constrained
// by domain but no longer is
exports.clean = function clean(gd, ax) {
if(ax._inputDomain) {
var isConstrained = false;
var axId = ax._id;
var constraintGroups = gd._fullLayout._axisConstraintGroups;
for(var j = 0; j < constraintGroups.length; j++) {
if(constraintGroups[j][axId]) {
isConstrained = true;
break;
}
}
if(!isConstrained || ax.constrain !== 'domain') {
ax._input.domain = ax.domain = ax._inputDomain;
delete ax._inputDomain;
}
}
};
function updateDomain(ax, factor) {
var inputDomain = ax._inputDomain;
var centerFraction = FROM_BL[ax.constraintoward];
var center = inputDomain[0] + (inputDomain[1] - inputDomain[0]) * centerFraction;
ax.domain = ax._input.domain = [
center + (inputDomain[0] - center) / factor,
center + (inputDomain[1] - center) / factor
];
ax.setScale();
}