Model quiver api closer to 3d cone trace

Author: degzhaus

lib/quiver.js

@@ -1,5 +1,3 @@
 'use strict';
 
 module.exports = require('../src/traces/quiver');
-
-

src/traces/quiver/attributes.js

@@ -32,13 +32,38 @@ var attrs = {
         anim: true,
         description: 'Sets the y components of the arrow vectors.'
     },
-    scale: {
+    sizemode: {
+        valType: 'enumerated',
+        values: ['scaled', 'absolute', 'raw'],
+        editType: 'calc',
+        dflt: 'scaled',
+        description: [
+            'Determines whether `sizeref` is set as a *scaled* (unitless) scalar',
+            '(normalized by the max u/v norm in the vector field), as an *absolute*',
+            'value (in the same units as the vector field), or *raw* to use the',
+            'raw vector lengths.'
+        ].join(' ')
+    },
+    sizeref: {
         valType: 'number',
-        dflt: 0.1,
         min: 0,
-        max: 1,
         editType: 'calc',
-        description: 'Scales size of the arrows (ideally to avoid overlap). Default = 0.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*.'
+        ].join(' ')
+    },
+    anchor: {
+        valType: 'enumerated',
+        values: ['tip', 'tail', 'cm', 'center', 'middle'],
+        dflt: 'tail',
+        editType: 'calc',
+        description: [
+            'Sets the 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 *cm*/*center*/*middle* to center the arrow on (x,y).'
+        ].join(' ')
     },
     arrow_scale: {
         valType: 'number',

src/traces/quiver/defaults.js

@@ -36,8 +36,12 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     // Set basic properties
     traceOut.type = 'quiver';
 
+    // Sizing API similar to cone
+    var sizemode = coerce('sizemode');
+    coerce('sizeref', sizemode === 'raw' ? 1 : 0.5);
+    coerce('anchor');
+
     // Set default values using coerce
-    coerce('scale', 0.1);
     coerce('arrow_scale', 0.3);
     coerce('angle', Math.PI / 9);
     coerce('scaleratio');

src/traces/quiver/plot.js

@@ -81,6 +81,20 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
 
     lineSegments.exit().remove();
 
+    // Precompute norms for sizing
+    var uArr = trace.u || [];
+    var vArr = trace.v || [];
+    var maxNorm = 0;
+    for (var ni = 0; ni < trace._length; ni++) {
+        var uu = uArr[ni] || 0;
+        var vv = vArr[ni] || 0;
+        var nrm = Math.sqrt(uu * uu + vv * vv);
+        if (nrm > maxNorm) maxNorm = nrm;
+    }
+    var sizemode = trace.sizemode || 'scaled';
+    var sizeref = (trace.sizeref !== undefined) ? trace.sizeref : (sizemode === 'raw' ? 1 : 0.5);
+    var anchor = trace.anchor || 'tail';
+
     // Update line segments
     lineSegments.each(function(cdi) {
         var path = d3.select(this);
@@ -92,27 +106,52 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
         }
 
         // Compute arrow in data space
-        var scale = trace.scale || 1;
         var scaleRatio = trace.scaleratio || 1;
         var arrowScale = trace.arrow_scale || 0.2;
         var angle = trace.angle || Math.PI / 12; // small default
 
         var u = (trace.u && trace.u[cdi.i]) || 0;
         var v = (trace.v && trace.v[cdi.i]) || 0;
 
-        var dx = u * scale * scaleRatio;
-        var dy = v * scale;
+        var norm = Math.sqrt(u * u + v * v);
+        var unitx = norm ? (u / norm) : 0;
+        var unity = norm ? (v / norm) : 0;
+        var baseLen;
+        if (sizemode === 'scaled') {
+            var n = maxNorm ? (norm / maxNorm) : 0;
+            baseLen = n * sizeref;
+        } else {
+            baseLen = norm * sizeref;
+        }
+
+        var dxBase = unitx * baseLen;
+        var dyBase = unity * baseLen;
+        var dx = dxBase * scaleRatio;
+        var dy = dyBase;
         var barbLen = Math.sqrt((dx * dx) / scaleRatio + dy * dy);
         var arrowLen = barbLen * arrowScale;
         var barbAng = Math.atan2(dy, dx / scaleRatio);
 
         var ang1 = barbAng + angle;
         var ang2 = barbAng - angle;
 
-        var x0 = cdi.x;
-        var y0 = cdi.y;
-        var x1 = x0 + dx;
-        var y1 = y0 + dy;
+        var x0, y0, x1, y1;
+        if (anchor === 'tip') {
+            x1 = cdi.x;
+            y1 = cdi.y;
+            x0 = x1 - dx;
+            y0 = y1 - dy;
+        } else if (anchor === 'cm' || anchor === 'center' || anchor === 'middle') {
+            x0 = cdi.x - dx / 2;
+            y0 = cdi.y - dy / 2;
+            x1 = cdi.x + dx / 2;
+            y1 = cdi.y + dy / 2;
+        } else { // tail
+            x0 = cdi.x;
+            y0 = cdi.y;
+            x1 = x0 + dx;
+            y1 = y0 + dy;
+        }
 
         var xh1 = x1 - arrowLen * Math.cos(ang1) * scaleRatio;
         var yh1 = y1 - arrowLen * Math.sin(ang1);

test/plot-schema.json

@@ -79654,14 +79654,36 @@
      "min": 0,
      "valType": "number"
     },
-    "scale": {
-     "description": "Scales size of the arrows (ideally to avoid overlap). Default = 0.1",
-     "dflt": 0.1,
+    "sizemode": {
+     "description": "Determines whether `sizeref` is set as a *scaled* (unitless) scalar (normalized by the max u/v norm in the vector field), as an *absolute* value (in the same units as the vector field), or *raw* to use the raw vector lengths.",
+     "dflt": "scaled",
+     "editType": "calc",
+     "valType": "enumerated",
+     "values": [
+      "scaled",
+      "absolute",
+      "raw"
+     ]
+    },
+    "sizeref": {
+     "description": "Adjusts the arrow size scaling. The arrow length is determined by the vector norm multiplied by `sizeref`, optionally normalized when `sizemode` is *scaled*.",
      "editType": "calc",
-     "max": 1,
      "min": 0,
      "valType": "number"
     },
+    "anchor": {
+     "description": "Sets the 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 *cm*/*center*/*middle* to center the arrow on (x,y).",
+     "dflt": "tail",
+     "editType": "calc",
+     "valType": "enumerated",
+     "values": [
+      "tip",
+      "tail",
+      "cm",
+      "center",
+      "middle"
+     ]
+    },
     "scaleratio": {
      "description": "The ratio between the scale of the y-axis and the scale of the x-axis (scale_y / scale_x). Default = null, the scale ratio is not fixed.",
      "editType": "calc",