Merge pull request #617 from monfera/581-scatter3d-line-color

Color gradient for `scatter3d` snail trail lines [WIP]

Author: etpinard

src/components/colorscale/color_attributes.js

@@ -10,6 +10,7 @@
 
 var colorScaleAttributes = require('./attributes');
 var extendDeep = require('../../lib/extend').extendDeep;
+var palettes = require('./scales.js');
 
 module.exports = function makeColorScaleAttributes(context) {
     return {
@@ -19,7 +20,7 @@ module.exports = function makeColorScaleAttributes(context) {
             role: 'style',
             description: [
                 'Sets the ', context, ' color. It accepts either a specific color',
-                ' or an array of values that are mapped to the colorscale',
+                ' or an array of numbers that are mapped to the colorscale',
                 ' relative to the max and min values of the array or relative to',
                 ' `cmin` and `cmax` if set.'
             ].join('')
@@ -35,14 +36,19 @@ module.exports = function makeColorScaleAttributes(context) {
                 ' 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 `', context, '.cmin` and `', context, '.cmax`.'
-            ].join('')
+                ' use `', context, '.cmin` and `', context, '.cmax`.',
+                ' Alternatively, `colorscale` may be a palette name string',
+                ' of the following list: '
+            ].join('').concat(Object.keys(palettes).join(', '))
         }),
         cauto: extendDeep({}, colorScaleAttributes.zauto, {
             description: [
-                'Has an effect only if `', context, '.color` is set to a numerical array.',
-                ' Determines the whether or not the color domain is computed',
-                ' automatically.'
+                'Has an effect only if `', context, '.color` is set to a numerical array',
+                ' and `cmin`, `cmax` are set by the user. In this case,',
+                ' it controls whether the range of colors in `colorscale` is mapped to',
+                ' the range of values in the `color` array (`cauto: true`), or the `cmin`/`cmax`',
+                ' values (`cauto: false`).',
+                ' Defaults to `false` when `cmin`, `cmax` are set by the user.'
             ].join('')
         }),
         cmax: extendDeep({}, colorScaleAttributes.zmax, {
@@ -64,14 +70,18 @@ module.exports = function makeColorScaleAttributes(context) {
         autocolorscale: extendDeep({}, colorScaleAttributes.autocolorscale, {
             description: [
                 'Has an effect only if `', context, '.color` is set to a numerical array.',
-                ' Determines whether or not the colorscale is picked using',
-                ' values inside `', context, '.color`.'
+                ' Determines whether the colorscale is a default palette (`autocolorscale: true`)',
+                ' or the palette determined by `', context, '.colorscale`.',
+                ' 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('')
         }),
         reversescale: extendDeep({}, colorScaleAttributes.reversescale, {
             description: [
                 'Has an effect only if `', context, '.color` is set to a numerical array.',
-                ' Reverses the colorscale.'
+                ' Reverses the color mapping if true (`cmin` will correspond to the last color',
+                ' in the array and `cmax` will correspond to the first color).'
             ].join('')
         })
     };

src/plot_api/plot_api.js

@@ -1590,7 +1590,9 @@ Plotly.restyle = function restyle(gd, astr, val, traces) {
         'outsidetextfont.size', 'outsidetextfont.family', 'outsidetextfont.color',
         'hole', 'scalegroup', 'domain', 'domain.x', 'domain.y',
         'domain.x[0]', 'domain.x[1]', 'domain.y[0]', 'domain.y[1]',
-        'tilt', 'tiltaxis', 'depth', 'direction', 'rotation', 'pull'
+        'tilt', 'tiltaxis', 'depth', 'direction', 'rotation', 'pull',
+        'line.showscale', 'line.cauto', 'line.autocolorscale', 'line.reversescale',
+        'marker.line.showscale', 'marker.line.cauto', 'marker.line.autocolorscale', 'marker.line.reversescale'
     ];
     for(i = 0; i < traces.length; i++) {
         if(Plots.traceIs(gd._fullData[traces[i]], 'box')) {
@@ -1612,6 +1614,8 @@ Plotly.restyle = function restyle(gd, astr, val, traces) {
     var replotAttrs = [
         'zmin', 'zmax', 'zauto',
         'marker.cmin', 'marker.cmax', 'marker.cauto',
+        'line.cmin', 'line.cmax',
+        'marker.line.cmin', 'marker.line.cmax',
         'contours.start', 'contours.end', 'contours.size',
         'contours.showlines',
         'line', 'line.smoothing', 'line.shape',

src/traces/scatter/calc.js

@@ -15,7 +15,7 @@ var Axes = require('../../plots/cartesian/axes');
 var Lib = require('../../lib');
 
 var subTypes = require('./subtypes');
-var calcMarkerColorscale = require('./marker_colorscale_calc');
+var calcColorscale = require('./colorscale_calc');
 
 
 module.exports = function calc(gd, trace) {
@@ -73,7 +73,7 @@ module.exports = function calc(gd, trace) {
             s.map(markerTrans) : markerTrans(s);
     }
 
-    calcMarkerColorscale(trace);
+    calcColorscale(trace);
 
     // TODO: text size
 

src/traces/scatter/marker_colorscale_calc.js renamed to src/traces/scatter/colorscale_calc.js

@@ -17,16 +17,21 @@ var subTypes = require('./subtypes');
 
 // common to 'scatter', 'scatter3d' and 'scattergeo'
 module.exports = function calcMarkerColorscale(trace) {
-    if(!subTypes.hasMarkers(trace)) return;
-
-    var marker = trace.marker;
 
     // auto-z and autocolorscale if applicable
-    if(hasColorscale(trace, 'marker')) {
-        calcColorscale(trace, marker.color, 'marker', 'c');
+
+    if(subTypes.hasLines(trace) && hasColorscale(trace, 'line')) {
+        calcColorscale(trace, trace.line.color, 'line', 'c');
     }
 
-    if(hasColorscale(trace, 'marker.line')) {
-        calcColorscale(trace, marker.line.color, 'marker.line', 'c');
+    if(subTypes.hasMarkers(trace)) {
+
+        if(hasColorscale(trace, 'marker')) {
+            calcColorscale(trace, trace.marker.color, 'marker', 'c');
+        }
+
+        if(hasColorscale(trace, 'marker.line')) {
+            calcColorscale(trace, trace.marker.line.color, 'marker.line', 'c');
+        }
     }
 };

src/traces/scatter/defaults.js

@@ -40,7 +40,7 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('mode', defaultMode);
 
     if(subTypes.hasLines(traceOut)) {
-        handleLineDefaults(traceIn, traceOut, defaultColor, coerce);
+        handleLineDefaults(traceIn, traceOut, defaultColor, layout, coerce);
         handleLineShapeDefaults(traceIn, traceOut, coerce);
         coerce('connectgaps');
     }

src/traces/scatter/line_defaults.js

@@ -9,14 +9,26 @@
 
 'use strict';
 
+var hasColorscale = require('../../components/colorscale/has_colorscale');
+var colorscaleDefaults = require('../../components/colorscale/defaults');
+
 
 // common to 'scatter', 'scatter3d', 'scattergeo' and 'scattergl'
-module.exports = function lineDefaults(traceIn, traceOut, defaultColor, coerce) {
+module.exports = function lineDefaults(traceIn, traceOut, defaultColor, layout, coerce) {
+
     var markerColor = (traceIn.marker || {}).color;
 
-    // don't try to inherit a color array
-    coerce('line.color', (Array.isArray(markerColor) ? false : markerColor) ||
-                         defaultColor);
+    coerce('line.color', defaultColor);
+    if(hasColorscale(traceIn, 'line')) {
+        colorscaleDefaults(
+            traceIn, traceOut, layout, coerce, {prefix: 'line.', cLetter: 'c'}
+        );
+    } else {
+        coerce('line.color', (Array.isArray(markerColor) ? false : markerColor) ||
+            defaultColor);
+    }
+
+
     coerce('line.width');
     coerce('line.dash');
 };

src/traces/scatter/marker_defaults.js

@@ -19,7 +19,7 @@ var subTypes = require('./subtypes');
 // common to 'scatter', 'scatter3d', 'scattergeo' and 'scattergl'
 module.exports = function markerDefaults(traceIn, traceOut, defaultColor, layout, coerce) {
     var isBubble = subTypes.isBubble(traceIn),
-        lineColor = (traceIn.line || {}).color,
+        lineColor = !Array.isArray(traceIn.line) ? (traceIn.line || {}).color : undefined,
         defaultMLC;
 
     if(lineColor) defaultColor = lineColor;

src/traces/scatter3d/attributes.js

@@ -97,11 +97,21 @@ module.exports = {
         z: makeProjectionAttr('z')
     },
     connectgaps: scatterAttrs.connectgaps,
-    line: {
-        color: scatterLineAttrs.color,
+    line: extendFlat({}, {
         width: scatterLineAttrs.width,
-        dash: scatterLineAttrs.dash
+        dash: scatterLineAttrs.dash,
+        showscale: {
+            valType: 'boolean',
+            role: 'info',
+            dflt: false,
+            description: [
+                'Has an effect only if `line.color` is set to a numerical array.',
+                'Determines whether or not a colorbar is displayed.'
+            ].join(' ')
+        }
     },
+        colorAttributes('line')
+    ),
     marker: extendFlat({}, {  // Parity with scatter.js?
         symbol: {
             valType: 'enumerated',

src/traces/scatter3d/calc.js

@@ -9,7 +9,7 @@
 'use strict';
 
 var arraysToCalcdata = require('../scatter/arrays_to_calcdata');
-var calcMarkerColorscale = require('../scatter/marker_colorscale_calc');
+var calcColorscales = require('../scatter/colorscale_calc');
 
 
 /**
@@ -21,7 +21,7 @@ module.exports = function calc(gd, trace) {
     var cd = [{x: false, y: false, trace: trace, t: {}}];
 
     arraysToCalcdata(cd);
-    calcMarkerColorscale(trace);
+    calcColorscales(trace);
 
     return cd;
 };

src/traces/scatter3d/convert.js

@@ -204,7 +204,7 @@ function convertPlotlyOptions(scene, data) {
     };
 
     if('line' in data) {
-        params.lineColor = str2RgbaArray(line.color);
+        params.lineColor = formatColor(line, 1, len);
         params.lineWidth = line.width;
         params.lineDashes = line.dash;
     }