Merge pull request #2658 from plotly/streamtube-traces

3D streamtube traces

lib/index-gl3d.js

@@ -14,7 +14,8 @@ Plotly.register([
     require('./scatter3d'),
     require('./surface'),
     require('./mesh3d'),
-    require('./cone')
+    require('./cone'),
+    require('./streamtube')
 ]);
 
 module.exports = Plotly;

lib/index.js

@@ -27,6 +27,7 @@ Plotly.register([
     require('./surface'),
     require('./mesh3d'),
     require('./cone'),
+    require('./streamtube'),
 
     require('./scattergeo'),
     require('./choropleth'),

lib/streamtube.js

@@ -0,0 +1,11 @@
+/**
+* Copyright 2012-2018, 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';
+
+module.exports = require('../src/traces/streamtube');

package.json

@@ -83,6 +83,7 @@
     "gl-select-box": "^1.0.2",
     "gl-spikes2d": "^1.0.1",
     "gl-surface3d": "^1.3.5",
+    "gl-streamtube3d": "^1.0.0",
     "gl-text": "^1.1.5",
     "glslify": "^6.1.1",
     "has-hover": "^1.0.1",

src/components/colorscale/attributes.js

@@ -8,76 +8,216 @@
 
 'use strict';
 
-module.exports = {
-    zauto: {
+var palettes = require('./scales.js');
+var paletteStr = Object.keys(palettes);
+
+function code(s) {
+    return '`' + s + '`';
+}
+
+/**
+ * Make colorscale attribute declarations for
+ *
+ * - colorscale,
+ * - (c|z)auto, (c|z)min, (c|z)max,
+ * - autocolorscale, reversescale,
+ * - showscale (optionally)
+ * - color (optionally)
+ *
+ * @param {string} context (dflt: '', i.e. from trace root):
+ *     the container this is in ('', *marker*, *marker.line* etc)
+ *
+ * @param {object} opts:
+ *   - cLetter {string} (dflt: 'c'):
+ *     leading letter for 'min', 'max and 'auto' attribute (either 'z' or 'c')
+ *
+ *   - colorAttr {string} (dflt: 'z' if `cLetter: 'z'`, 'color' if `cLetter: 'c'`):
+ *     (for descriptions) sets the name of the color attribute that maps to the colorscale.
+ *
+ *     N.B. if `colorAttr: 'color'`, we include the `color` declaration here.
+ *
+ *   - onlyIfNumerical {string} (dflt: false' if `cLetter: 'z'`, true if `cLetter: 'c'`):
+ *     (for descriptions) set to true if colorscale attribute only
+ *
+ *   - colorscaleDflt {string}:
+ *     overrides the colorscale dflt
+ *
+ *   - autoColorDflt {boolean} (dflt true):
+ *     normally autocolorscale.dflt is `true`, but pass `false` to override
+ *
+ *   - noScale {boolean} (dflt: true if `context: 'marker.line'`, false otherwise):
+ *     set to `false` to not include showscale attribute (e.g. for 'marker.line')
+ *
+ *   - showScaleDflt {boolean} (dflt: true if `cLetter: 'z'`, false otherwise)
+ *
+ *   - editTypeOverride {boolean} (dflt: ''):
+ *     most of these attributes already require a recalc, but the ones that do not
+ *     have editType *style* or *plot* unless you override (presumably with *calc*)
+ *
+ * @return {object}
+ */
+module.exports = function colorScaleAttrs(context, opts) {
+    context = context || '';
+    opts = opts || {};
+
+    var cLetter = opts.cLetter || 'c';
+    var onlyIfNumerical = ('onlyIfNumerical' in opts) ? opts.onlyIfNumerical : Boolean(context);
+    var noScale = ('noScale' in opts) ? opts.noScale : context === 'marker.line';
+    var showScaleDflt = ('showScaleDflt' in opts) ? opts.showScaleDflt : cLetter === 'z';
+    var colorscaleDflt = typeof opts.colorscaleDflt === 'string' ? palettes[opts.colorscaleDflt] : null;
+    var editTypeOverride = opts.editTypeOverride || '';
+    var contextHead = context ? (context + '.') : '';
+
+    var colorAttr, colorAttrFull;
+
+    if('colorAttr' in opts) {
+        colorAttr = opts.colorAttr;
+        colorAttrFull = opts.colorAttr;
+    } else {
+        colorAttr = {z: 'z', c: 'color'}[cLetter];
+        colorAttrFull = 'in ' + code(contextHead + colorAttr);
+    }
+
+    var effectDesc = onlyIfNumerical ?
+        ' Has an effect only if ' + colorAttrFull + 'is set to a numerical array.' :
+        '';
+
+    var auto = cLetter + 'auto';
+    var min = cLetter + 'min';
+    var max = cLetter + 'max';
+    var minFull = code(contextHead + min);
+    var maxFull = code(contextHead + max);
+    var minmaxFull = minFull + ' and ' + maxFull;
+    var autoImpliedEdits = {};
+    autoImpliedEdits[min] = autoImpliedEdits[max] = undefined;
+    var minmaxImpliedEdits = {};
+    minmaxImpliedEdits[auto] = false;
+
+    var attrs = {};
+
+    if(colorAttr === 'color') {
+        attrs.color = {
+            valType: 'color',
+            arrayOk: true,
+            role: 'style',
+            editType: editTypeOverride || 'style',
+            description: [
+                'Sets the', context, 'color.',
+                ' It accepts either a specific color',
+                ' or an array of numbers that are mapped to the colorscale',
+                ' relative to the max and min values of the array or relative to',
+                ' ' + minmaxFull + ' if set.'
+            ].join('')
+        };
+    }
+
+    attrs[auto] = {
         valType: 'boolean',
         role: 'info',
         dflt: true,
         editType: 'calc',
-        impliedEdits: {zmin: undefined, zmax: undefined},
+        impliedEdits: autoImpliedEdits,
         description: [
-            'Determines the whether or not the color domain is computed',
-            'with respect to the input data.'
-        ].join(' ')
-    },
-    zmin: {
+            'Determines whether or not the color domain is computed',
+            ' with respect to the input data (here ' + colorAttrFull + ') or the bounds set in',
+            ' ', minmaxFull,
+            ' ', effectDesc,
+            ' Defaults to `false` when ', minmaxFull, ' are set by the user.'
+        ].join('')
+    };
+
+    attrs[min] = {
         valType: 'number',
         role: 'info',
         dflt: null,
-        editType: 'plot',
-        impliedEdits: {zauto: false},
-        description: 'Sets the lower bound of color domain.'
-    },
-    zmax: {
+        editType: editTypeOverride || 'plot',
+        impliedEdits: minmaxImpliedEdits,
+        description: [
+            'Sets the lower bound of the color domain.',
+            effectDesc,
+            ' Value should have the same units as ', colorAttrFull,
+            ' and if set, ', maxFull, ' must be set as well.'
+        ].join('')
+    };
+
+    attrs[max] = {
         valType: 'number',
         role: 'info',
         dflt: null,
-        editType: 'plot',
-        impliedEdits: {zauto: false},
-        description: 'Sets the upper bound of color domain.'
-    },
-    colorscale: {
+        editType: editTypeOverride || 'plot',
+        impliedEdits: minmaxImpliedEdits,
+        description: [
+            'Sets the upper bound of the color domain.',
+            effectDesc,
+            ' Value should have the same units as ', colorAttrFull,
+            ' and if set, ', minFull, ' must be set as well.'
+        ].join('')
+    };
+
+    attrs.colorscale = {
         valType: 'colorscale',
         role: 'style',
         editType: 'calc',
+        dflt: colorscaleDflt,
         impliedEdits: {autocolorscale: false},
         description: [
             'Sets the colorscale.',
-            'The colorscale must be an array containing',
-            'arrays mapping a normalized value to an',
-            'rgb, rgba, hex, hsl, hsv, or named color string.',
-            'At minimum, a mapping for the lowest (0) and highest (1)',
-            'values are required. For example,',
-            '`[[0, \'rgb(0,0,255)\', [1, \'rgb(255,0,0)\']]`.',
-            'To control the bounds of the colorscale in z space,',
-            'use zmin and zmax'
-        ].join(' ')
-    },
-    autocolorscale: {
+            effectDesc,
+            ' The colorscale must be an array containing',
+            ' arrays mapping a normalized value to an',
+            ' rgb, rgba, hex, hsl, hsv, or named color string.',
+            ' At minimum, a mapping for the lowest (0) and highest (1)',
+            ' values are required. For example,',
+            ' `[[0, \'rgb(0,0,255)\', [1, \'rgb(255,0,0)\']]`.',
+            ' To control the bounds of the colorscale in color space,',
+            ' use', minmaxFull, '.',
+            ' Alternatively, `colorscale` may be a palette name string',
+            ' of the following list: ' + paletteStr + '.'
+        ].join('')
+    };
+
+    attrs.autocolorscale = {
         valType: 'boolean',
         role: 'style',
-        dflt: true,  // gets overrode in 'heatmap' & 'surface' for backwards comp.
+        // gets overrode in 'heatmap' & 'surface' for backwards comp.
+        dflt: opts.autoColorDflt === false ? false : true,
         editType: 'calc',
         impliedEdits: {colorscale: undefined},
         description: [
-            'Determines whether or not the colorscale is picked using the sign of',
-            'the input z values.'
-        ].join(' ')
-    },
-    reversescale: {
+            'Determines whether the colorscale is a default palette (`autocolorscale: true`)',
+            ' or the palette determined by ', code(contextHead + 'colorscale'), '.',
+            effectDesc,
+            ' In case `colorscale` is unspecified or `autocolorscale` is true, the default ',
+            ' palette will be chosen according to whether numbers in the `color` array are',
+            ' all positive, all negative or mixed.'
+        ].join('')
+    };
+
+    attrs.reversescale = {
         valType: 'boolean',
         role: 'style',
         dflt: false,
         editType: 'calc',
-        description: 'Reverses the colorscale.'
-    },
-    showscale: {
-        valType: 'boolean',
-        role: 'info',
-        dflt: true,
-        editType: 'calc',
         description: [
-            'Determines whether or not a colorbar is displayed for this trace.'
-        ].join(' ')
+            'Reverses the color mapping if true.',
+            effectDesc,
+            ' If true, ', minFull, ' will correspond to the last color',
+            ' in the array and ', maxFull, ' will correspond to the first color.'
+        ].join('')
+    };
+
+    if(!noScale) {
+        attrs.showscale = {
+            valType: 'boolean',
+            role: 'info',
+            dflt: showScaleDflt,
+            editType: 'calc',
+            description: [
+                'Determines whether or not a colorbar is displayed for this trace.',
+                effectDesc
+            ].join('')
+        };
     }
+
+    return attrs;
 };