Update quiver trace API

draftlogs/7710_add.md

@@ -1 +1 @@
-- Add `quiver` trace type to visualize vector fields using arrows [[#7710](https://github.com/plotly/plotly.js/pull/7710)], with thanks to @degzhaus for the contribution!
+- Add `quiver` trace type to visualize vector fields using arrows [[#7710](https://github.com/plotly/plotly.js/pull/7710), [#7945](https://github.com/plotly/plotly.js/issues/7945)], with thanks to @degzhaus for the contribution!

src/traces/quiver/attributes.js

@@ -14,62 +14,63 @@ var attrs = {
  valType: 'data_array',
  editType: 'calc+clearAxisTypes',
  anim: true,
- description: 'Sets the x coordinates of the arrow locations.'
+ description: 'Sets the x coordinates of the vector arrow locations.'
  },
  x0: scatterAttrs.x0,
  dx: scatterAttrs.dx,
  y: {
  valType: 'data_array',
  editType: 'calc+clearAxisTypes',
  anim: true,
- description: 'Sets the y coordinates of the arrow locations.'
+ description: 'Sets the y coordinates of the vector arrow locations.'
  },
  y0: scatterAttrs.y0,
  dy: scatterAttrs.dy,
  u: {
  valType: 'data_array',
  editType: 'calc',
  anim: true,
- description: 'Sets the x components of the arrow vectors.'
+ description: 'Sets the x components of the vector arrows.'
  },
  v: {
  valType: 'data_array',
  editType: 'calc',
  anim: true,
- description: 'Sets the y components of the arrow vectors.'
+ description: 'Sets the y components of the vector arrows.'
  },
-anglemode: {
+arrowref: {
  valType: 'enumerated',
  values: ['paper', 'data'],
- dflt: 'axis',
+ dflt: 'data',
  editType: 'calc',
  description: [
- 'Sets the mode used to determine the angle of the arrow vectors.',
+ 'Determines how the u/v vector components are interpreted.',
  'If *paper*, u/v are interpreted in pixel coordinates and the rendered vector angle',
- 'does not change regardless of the axes scales.',
+ 'does not change regardless of the axis scales.',
  'If *data*, u/v are interpreted in data coordinates and the rendered vector angle',
  'may change, e.g. if zooming in along a single axis'
  ].join(' ')
  },
-sizemode: {
+lengthmode: {
  valType: 'enumerated',
  values: ['scaled', 'raw'],
  editType: 'calc',
  dflt: 'scaled',
  description: [
- 'Determines whether arrows are drawn according to their raw lengths,',
- 'or scaled based on the maximum vector length and point density. Note: When `anglemode` is *data*',
- 'arrows are alwyas scaled and `sizemode` *raw* is ignored.',
+ 'Determines whether vector arrows are drawn according to their raw lengths,',
+ 'or scaled based on the maximum vector length and point density. Note: When `arrowref` is *paper*',
+ 'vectors are always scaled and `lengthmode` *raw* is ignored.'
  ].join(' ')
  },
-sizeref: {
+lengthfactor: {
  valType: 'number',
  min: 0,
  editType: 'calc',
  dflt: 1,
  description: [
- 'Adjusts the arrow size scaling. The arrow length is determined by the vector norm multiplied by `sizeref`,',
- 'optionally normalized when `sizemode` is *scaled* (`sizeref` is applied after scaling).'
+ 'Adjusts the drawn length of the vector arrows. The arrow length is determined by',
+ 'the values of u and v, then optionally rescaled when `lengthmode` is *scaled*,',
+ 'then multiplied by `lengthfactor`.',
  ].join(' ')
  },
  anchor: {
@@ -78,9 +79,9 @@ var attrs = {
  dflt: 'tail',
  editType: 'calc',
  description: [
- 'Sets the arrows\' anchor with respect to their (x,y) positions.',
+ 'Sets the vector arrows\' anchor with respect to their (x,y) positions.',
  'Use *tail* to place (x,y) at the base, *tip* to place (x,y) at the head,',
- 'or *center* to center the arrow on (x,y).'
+ 'or *center* to center the vector arrow on (x,y).'
  ].join(' ')
  },
  xhoverformat: axisHoverFormat('x'),
@@ -107,7 +108,7 @@ var attrs = {
  arrowsize: extendFlat({}, annotationAttrs.arrowsize, {
  editType: 'calc',
  description: [
- 'Sets the size of the arrow head relative to `marker.line.width`.',
+ 'Sets the size of the vector arrowhead relative to `marker.line.width`.',
  'A value of 1 (default) gives a head about 3x as wide as the line.'
  ].join(' ')
  }),
@@ -117,7 +118,7 @@ var attrs = {
  min: 0,
  dflt: 2,
  editType: 'style',
- description: 'Sets the width (in px) of the arrow lines.'
+ description: 'Sets the width (in px) of the vector arrow lines.'
  },
  dash: dash,
  editType: 'style'

src/traces/quiver/calc.js

@@ -7,10 +7,11 @@ var BADNUM = require('../../constants/numerical').BADNUM;
 var colorscaleCalc = require('../../components/colorscale/calc');
 var calcSelection = require('../scatter/calc_selection');
 
-/**
- * Main calculation function for quiver trace
- * Creates calcdata with arrow path data for each vector
- */
+// For scaled lengthmode: Constant to multiply by the computed distance between
+// neighboring points, such that the arrows are _just slightly shorter_ than
+// that distance
+const SHRINK_FACTOR = 0.97;
+
 module.exports = function calc(gd, trace) {
  // Map x/y through axes so category/date values become numeric calcdata
  const xa = trace._xA = Axes.getFromId(gd, trace.xaxis || 'x', 'x');
@@ -33,9 +34,7 @@ module.exports = function calc(gd, trace) {
  const uArr = trace.u || [];
  const vArr = trace.v || [];
 
- const anglemode = trace.anglemode;
- const sizemode = trace.sizemode;
- const anchor = trace.anchor;
+ const { anchor, lengthmode, arrowref } = trace;
  const isTip = anchor === 'tip';
  const isCenter = anchor === 'center';
 
@@ -54,7 +53,7 @@ module.exports = function calc(gd, trace) {
  var nValid = 0;
 
  // First pass: build calcdata, and keep track of the maximum and minimum vector norm in the trace,
- // to be used for sizemode 'scaled' (max norm only) and for magnitude-based colorscale range
+ // to be used for lengthmode 'scaled' (max norm only) and for magnitude-based colorscale range
  for(var i = 0; i < len; i++) {
  var cdi = cd[i] = { i: i };
  var xValid = isNumeric(xVals[i]);
@@ -109,37 +108,59 @@ module.exports = function calc(gd, trace) {
  // Store maxNorm for use by plot step
  trace._maxNorm = normMax;
 
- if (sizemode === 'scaled' || anglemode === 'paper') {
- // Ignore sizemode 'raw' if anglemode is set to 'paper': always scale
-
- // Compute point density of the entire trace: Area of bounding box
- // divided by number of points. This is used to scale arrows in
- // 'scaled' sizemode.
- // TODO: How to handle the case where there is just one point in a trace,
- // or all points have the same x or y value? This will give a boxArea of 0.
- // For now I'm going to just normalize to a vector of unit length (1) in that case,
- // but that's not a great solution
- const boxArea = (xMax - xMin) * (yMax - yMin);
- const pointDensity = boxArea / len;
- // Now, compute the scale factor for scaled size mode
- // The scale factor should be such that
- // _maxNorm * _scaleFactor = Math.sqrt(_pointDensity)
- // Therefore: _scaleFactor = Math.sqrt(_pointDensity) / _maxNorm
- if (pointDensity === 0) {
- trace._scaleFactor = 1 / trace._maxNorm
+ // Ignore lengthmode 'raw' if arrowref is set to 'paper': always scale
+ if (lengthmode === 'scaled' || arrowref === 'paper') {
+ /**
+ * Compute the maximum arrow length we should allow, using a heuristic
+ * to estimate the distance between neighboring points.
+ *
+ * Let:
+ * - D be the distance between neighboring points (the value we want to compute)
+ * - N be the number of points in the trace
+ * - dX be the x-width of the bounding box of all the points
+ * - dY be the y-width of the bounding box
+ *
+ * We want to satisfy this equation: D = sqrt((dX + D) * (dY + D) / N)
+ *
+ * This is basically the square root of the point density, with an additional
+ * adjustment to account for the points on the edges (we add D to each dimension
+ * of the bounding box). This equation gives us the _exact_ correct distance when
+ * the points are arranged in a perfect grid; otherwise, it's just an estimate.
+ *
+ * Solving for D gives us:
+ * D = (dX + dY + sqrt((dX - dY)^2 + 4N * dX * dY)) / (2 * (N - 1))
+ * which is the forumla we'll use below.
+ *
+ * Note: this formula was derived and documented by a human ;)
+ */
+
+ const dX = xMax - xMin;
+ const dY = yMax - yMin;
+ var pointDist;
+ if (dX === 0 && dY === 0) {
+ // If all points share the same x and y value, we can't estimate pointDist.
+ // Default to an arbitrary value of 1.
+ pointDist = 1;
  } else {
- trace._scaleFactor = Math.sqrt(pointDensity) / trace._maxNorm;
+ // Use the formula derived above
+ pointDist = (dX + dY + Math.sqrt((dX - dY) * (dX - dY) + 4 * nValid * dX * dY)) / (2 * (nValid - 1));
  }
- // Note: If anglemode === 'paper', this scale factor must be
+ pointDist *= SHRINK_FACTOR; // Adjust to slightly less than the computed distance
+
+ // Set the trace scale factor such that the longest vector will have
+ // a length equal to the computed pointDist
+ trace._scaleFactor = pointDist / trace._maxNorm;
+
+ // Note: If arrowref === 'paper', this scale factor must be
  // multiplied by Math.sqrt(xa._m * ya._m), but we can't do that quite yet
  // since the axis scales are not fully determined. Do it in plot step instead.
- } else { // sizemode === 'raw'
- // For raw sizemode, scale factor is always 1
+ } else {
+ // lengthmode === 'raw'
  trace._scaleFactor = 1;
  }
 
- // Multiply scale factor by sizeref
- trace._scaleFactor *= trace.sizeref;
+ // Multiply computed scale factor by lengthfactor attr
+ trace._scaleFactor *= trace.lengthfactor;
 
  // Now we need to compute the arrow geometry for axis autorange
  const xTipPositions = new Array(len);
@@ -148,7 +169,7 @@ module.exports = function calc(gd, trace) {
  const yTailPositions = new Array(len);
  var arrowLenX, arrowLenY;
  // Compute the x- and y-positions of the tip of each arrow,
- // assuming anglemode === 'data' (i.e. u/v are in data coordinates)
+ // assuming arrowref === 'data' (i.e. u/v are in data coordinates)
  for(var i = 0; i < len; i++) {
  var cdi = cd[i];
  arrowLenX = cdi._u * trace._scaleFactor;
@@ -171,14 +192,15 @@ module.exports = function calc(gd, trace) {
  }
  }
 
- if (anglemode === 'data') {
- // If anglemode is 'data', we can use the arrow tip positions directly to expand the axes ranges
+ if (arrowref === 'data') {
+ // If arrowref is 'data', we can use the arrow tip positions directly to expand the axes ranges
  trace._extremes[xa._id] = Axes.findExtremes(xa, xTipPositions.concat(xTailPositions), {padded: true});
  trace._extremes[ya._id] = Axes.findExtremes(ya, yTipPositions.concat(yTailPositions), {padded: true});
- } else { // anglemode === 'paper'
- // TODO: For now, just do the same thing as for anglemode === 'data', but this is not correct.
+ } else { // arrowref === 'paper'
+ // TODO: For now, just do the same thing as for arrowref === 'data', but this is not correct.
  // We actually need more sophisticated logic here, since this will give a bad result
  // if the data aspect ratio is very different from the plot aspect ratio.
+ // See https://github.com/plotly/plotly.js/issues/7979
  trace._extremes[xa._id] = Axes.findExtremes(xa, xTipPositions.concat(xTailPositions), {padded: true});
  trace._extremes[ya._id] = Axes.findExtremes(ya, yTipPositions.concat(yTailPositions), {padded: true});
  }

src/traces/quiver/defaults.js

@@ -30,11 +30,11 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
  for(var j = 0; j < len; j++) traceOut.v[j] = 0;
  }
 
- coerce('anglemode');
+ coerce('arrowref');
 
  // Sizing API inspired by cone, but not identical
- coerce('sizemode');
- coerce('sizeref');
+ coerce('lengthmode');
+ coerce('lengthfactor');
  coerce('anchor');
 
  // Arrow styling

src/traces/quiver/plot.js

@@ -102,14 +102,10 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
  lineSegments.exit().remove();
 
  // Use maxNorm precomputed in calc
- const maxNorm = trace._maxNorm || 0;
- const anglemode = trace.anglemode;
- const sizemode = trace.sizemode;
- const sizeref = trace.sizeref;
- const anchor = trace.anchor;
-
- // Adjust scale factor if anglemode is 'paper'
- const scaleFactor = (anglemode === 'paper') ? trace._scaleFactor * Math.sqrt(Math.abs(xa._m * ya._m)) : trace._scaleFactor;
+ const { anchor, maxNorm = 0, arrowref } = trace;
+
+ // Adjust scale factor if arrowref is 'paper'
+ const scaleFactor = (arrowref === 'paper') ? trace._scaleFactor * Math.sqrt(Math.abs(xa._m * ya._m)) : trace._scaleFactor;
  const markerArrowsize = trace.marker.arrowsize;
 
  // Update line segments
@@ -123,12 +119,12 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
  }
 
  // Compute pixel location of vector tip, *relative to* vector base (before scaling).
- // If anglemode is 'paper', then u/v are interpreted in pixel coordinates, so we can use them directly.
- // If anglemode is 'data', then u/v are interpreted in data coordinates, so we need to convert them to pixel coordinates.
+ // If arrowref is 'paper', then u/v are interpreted in pixel coordinates, so we can use them directly.
+ // If arrowref is 'data', then u/v are interpreted in data coordinates, so we need to convert them to pixel coordinates.
  // TODO: This probably doesn't work for log axes, but let's ignore log axes for now
  // since I'm not sure they make sense for quiver plots anyway
- const pu = ((anglemode === 'paper') ? cdi._u * Math.sign(xa._m) : d3.round(xa._m * cdi._u)) * scaleFactor;
- const pv = ((anglemode === 'paper') ? cdi._v * Math.sign(ya._m) : d3.round(ya._m * cdi._v)) * scaleFactor;
+ const pu = ((arrowref === 'paper') ? cdi._u * Math.sign(xa._m) : d3.round(xa._m * cdi._u)) * scaleFactor;
+ const pv = ((arrowref === 'paper') ? cdi._v * Math.sign(ya._m) : d3.round(ya._m * cdi._v)) * scaleFactor;
 
  // Compute arrow in data space
  // Check whether arrowsize was set explicitly in the input trace