improve interplay between vector and cone position attributes

- x/y/z always refers vector positions (their length should match
  u/v/w)
- if nothing else provided, x/y/z correspond to the cone position also,
- to set cone position, use `cones.(x|y|z)` for now
- update attribute descriptions and trace meta info

src/traces/cone/attributes.js

@@ -22,29 +22,29 @@ var attrs = {
         role: 'info',
         editType: 'calc+clearAxisTypes',
         description: [
-            'Sets the x positions of the cones.',
-            'When `vx`, `vy`, `vz` are not set,',
-            ' these are also the x coordinates of the u/v/w vector field.'
+            'Sets the x coordinates of the vector field',
+            'If `cones` positions are not provided, this array',
+            'corresponds to the x coordinates of the cones displayed as well.'
         ].join(' ')
     },
     y: {
         valType: 'data_array',
         role: 'info',
         editType: 'calc+clearAxisTypes',
         description: [
-            'Sets the y positions of the cones.',
-            'When `vx`, `vy`, `vz` are not set,',
-            ' these are also the y coordinates of the u/v/w vector field.'
+            'Sets the y coordinates of the vector field',
+            'If `cones` positions are not provided, this array',
+            'corresponds to the y coordinates of the cones displayed as well.'
         ].join(' ')
     },
     z: {
         valType: 'data_array',
         role: 'info',
         editType: 'calc+clearAxisTypes',
         description: [
-            'Sets the z positions of the cones.',
-            'When `vx`, `vy`, `vz` are not set,',
-            ' these are also the z coordinates of the u/v/w vector field.'
+            'Sets the z coordinates of the vector field',
+            'If `cones` positions are not provided, this array',
+            'corresponds to the z coordinates of the cones displayed as well.'
         ].join(' ')
     },
 
@@ -64,20 +64,37 @@ var attrs = {
         description: 'Sets the z components of the vector field.'
     },
 
-    vx: {
-        valType: 'data_array',
-        editType: 'calc',
-        description: 'Sets the x coordinates of the vector field mesh.'
-    },
-    vy: {
-        valType: 'data_array',
-        editType: 'calc',
-        description: 'Sets the y coordinates of the vector field mesh.'
-    },
-    vz: {
-        valType: 'data_array',
+    cones: {
+        // potential attributes to add:
+        //
+        // - meshmode: 'cartesian-product', 'pts', 'grid'
+        //
+        // under `meshmode: 'grid'`
+        // - (x|y|z)grid.start
+        // - (x|y|z)grid.end
+        // - (x|y|z)grid.size
+
+        x: {
+            valType: 'data_array',
+            editType: 'calc',
+            description: 'Sets the x coordinates of the cones to be displayed.'
+        },
+        y: {
+            valType: 'data_array',
+            editType: 'calc',
+            description: 'Sets the y coordinates of the cones to be displayed.'
+        },
+        z: {
+            valType: 'data_array',
+            editType: 'calc',
+            description: 'Sets the z coordinates of the cones to be displayed.'
+        },
+
         editType: 'calc',
-        description: 'Sets the z coordinates of the vector field mesh.'
+        description: [
+            'By setting `cones.x`, `cones.y` and `cones.z` to 1D arrays,',
+            'plotly creates a mesh using the cartesian product of those 3 arrays.'
+        ].join(' ')
     },
 
     sizemode: {

src/traces/cone/convert.js

@@ -71,6 +71,7 @@ var anchor2coneOffset = {tip: 1, tail: 0, cm: 0.25, center: 0.5};
 function convert(scene, trace) {
     var sceneLayout = scene.fullSceneLayout;
     var dataScale = scene.dataScale;
+    var hasConesPos = trace.cones && trace.cones.x && trace.cones.y && trace.cones.z;
     var coneOpts = {};
 
     function toDataCoords(arr, axisName) {
@@ -91,11 +92,11 @@ function convert(scene, trace) {
         toDataCoords(trace.z, 'zaxis')
     );
 
-    if(trace.vx && trace.vy && trace.vz) {
+    if(hasConesPos) {
         coneOpts.meshgrid = [
-            toDataCoords(trace.vx, 'xaxis'),
-            toDataCoords(trace.vy, 'yaxis'),
-            toDataCoords(trace.vz, 'zaxis')
+            toDataCoords(trace.cones.x, 'xaxis'),
+            toDataCoords(trace.cones.y, 'yaxis'),
+            toDataCoords(trace.cones.z, 'zaxis')
         ];
     }
 

src/traces/cone/defaults.js

@@ -35,9 +35,9 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         return;
     }
 
-    coerce('vx');
-    coerce('vy');
-    coerce('vz');
+    coerce('cones.x');
+    coerce('cones.y');
+    coerce('cones.z');
 
     coerce('sizeref');
     coerce('sizemode');
@@ -56,14 +56,12 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('lightposition.y');
     coerce('lightposition.z');
 
-    // TODO should the default be viridis
-    // ... and should we restrict cmin,cmax > 0 ???
     colorscaleDefaults(traceIn, traceOut, layout, coerce, {prefix: '', cLetter: 'c'});
 
     coerce('text');
 
     // disable 1D transforms
-    // x/y/z should match lengths, u/v/w and vx/vy/vz  should match as well, but
+    // x/y/z and u/v/w should match lengths, cones.(x|y|z) should match as well, but
     // the two sets have different lengths so transforms wouldn't work.
     traceOut._length = null;
 };

src/traces/cone/index.js

@@ -22,7 +22,16 @@ module.exports = {
 
     meta: {
         description: [
-            '...'
+            'Use cone traces to visualize vector fields.',
+            '',
+            'Specify a vector field using 6 1D arrays,',
+            '3 position arrays `x`, `y` and `z`',
+            'and 3 vector component arrays `u`, `v`, `w`.',
+            '',
+            'If nothing else is provided, the cones are drawn exactly at the positions given',
+            'by `x`, `y` and `z`.',
+            'To specify the cone positions manually, use arrays attributes',
+            '`cones.x`, `cones.y` and `cones.z`.'
         ].join(' ')
     }
 };

test/image/mocks/gl3d_cone-sparse.json

@@ -5036,33 +5036,35 @@
         0.021351568113512426,
         0.611131516169977
       ],
-      "vx": [
-        0,
-        15,
-        30,
-        35,
-        40,
-        55,
-        70
-      ],
-      "vy": [
-        0,
-        15,
-        30,
-        35,
-        40,
-        45,
-        50
-      ],
-      "vz": [
-        0,
-        1,
-        2,
-        3,
-        30,
-        31,
-        50
-      ]
+      "cones": {
+        "x": [
+          0,
+          15,
+          30,
+          35,
+          40,
+          55,
+          70
+        ],
+        "y": [
+          0,
+          15,
+          30,
+          35,
+          40,
+          45,
+          50
+        ],
+        "z": [
+          0,
+          1,
+          2,
+          3,
+          30,
+          31,
+          50
+        ]
+      }
     }
   ],
   "layout": {