Added static gradient fills for scatter traces.

lumip · lumip · commit 63eb009e6605 · 2024-02-24T20:21:55.000+02:00
Adds a new attribute `fillgradient` to `scatter` traces
which allows the user to specify a gradient as a colorscale
and an orientation in which it will be applied. `fillgradient`
also has optional start and stop attributes which can be
used to define absolute start and stop points in plot coordiantes.
This allows to equip different traces with exactly matching fill gradients.
Omitting start and stop will apply the gradient between the extrema
of the fill polygon (along the fill direction).

When a legend is displayed, multiple passes are made through the
`Drawing.setFillStyle` function, for the legend previews and the
actual plot, during which the axes are re-scaled.
This leads to errors with gradients not computing start and stop
coordinates correctly. To work around this, `setFillStyle` was
modified to allow distinguishing between legend and plot passes.
diff --git a/src/components/color/index.js b/src/components/color/index.js
@@ -53,6 +53,25 @@ color.combine = function(front, back) {
     return tinycolor(fcflat).toRgbString();
 };
 
+/*
+ * Linearly interpolate between two colors at a normalized interpolation position (0 to 1).
+ *
+ * Ignores alpha channel values.
+ * The resulting color is computed as: factor * first + (1 - factor) * second.
+ */
+color.interpolate = function(first, second, factor) {
+    var fc = tinycolor(first).toRgb();
+    var sc = tinycolor(second).toRgb();
+
+    var ic = {
+        r: factor * fc.r + (1 - factor) * sc.r,
+        g: factor * fc.g + (1 - factor) * sc.g,
+        b: factor * fc.b + (1 - factor) * sc.b,
+    };
+
+    return tinycolor(ic).toRgbString();
+};
+
 /*
  * Create a color that contrasts with cstr.
  *
diff --git a/src/components/drawing/index.js b/src/components/drawing/index.js
@@ -177,7 +177,7 @@ drawing.dashStyle = function(dash, lineWidth) {
     return dash;
 };
 
-function setFillStyle(sel, trace, gd) {
+function setFillStyle(sel, trace, gd, forLegend) {
     var markerPattern = trace.fillpattern;
     var patternShape = markerPattern && drawing.getPatternAttr(markerPattern.shape, 0, '');
     if(patternShape) {
@@ -192,6 +192,55 @@ function setFillStyle(sel, trace, gd) {
             undefined, markerPattern.fillmode,
             patternBGColor, patternFGColor, patternFGOpacity
         );
+    } else if(trace.fillgradient && trace.fillgradient.orientation !== 'none') {
+        var direction = trace.fillgradient.orientation;
+        var gradientID = 'scatterfill-' + trace.uid;
+        if(forLegend) {
+            gradientID = 'legendfill-' + trace.uid;
+        }
+
+        if(!forLegend && (trace.fillgradient.start !== undefined || trace.fillgradient.stop !== undefined)) {
+            var start, stop;
+            if(direction === 'horizontal') {
+                start = {
+                    x: trace.fillgradient.start,
+                    y: 0,
+                };
+                stop = {
+                    x: trace.fillgradient.stop,
+                    y: 0,
+                };
+            } else if(direction === 'vertical') {
+                start = {
+                    x: 0,
+                    y: trace.fillgradient.start,
+                };
+                stop = {
+                    x: 0,
+                    y: trace.fillgradient.stop,
+                };
+            }
+
+            start.x = trace._xA.c2p(
+                (start.x === undefined) ? trace._extremes.x.min[0].val : start.x, true
+            );
+            start.y = trace._yA.c2p(
+                (start.y === undefined) ? trace._extremes.y.min[0].val : start.y, true
+            );
+
+            stop.x = trace._xA.c2p(
+                (stop.x === undefined) ? trace._extremes.x.max[0].val : stop.x, true
+            );
+            stop.y = trace._yA.c2p(
+                (stop.y === undefined) ? trace._extremes.y.max[0].val : stop.y, true
+            );
+            sel.call(gradientWithBounds, gd, gradientID, 'linear', trace.fillgradient.colorscale, 'fill', start, stop, true, false);
+        } else {
+            if(direction === 'horizontal') {
+                direction = direction + 'reversed';
+            }
+            sel.call(drawing.gradient, gd, gradientID, direction, trace.fillgradient.colorscale, 'fill');
+        }
     } else if(trace.fillcolor) {
         sel.call(Color.fill, trace.fillcolor);
     }
@@ -202,17 +251,17 @@ drawing.singleFillStyle = function(sel, gd) {
     var node = d3.select(sel.node());
     var data = node.data();
     var trace = ((data[0] || [])[0] || {}).trace || {};
-    setFillStyle(sel, trace, gd);
+    setFillStyle(sel, trace, gd, false);
 };
 
-drawing.fillGroupStyle = function(s, gd) {
+drawing.fillGroupStyle = function(s, gd, forLegend) {
     s.style('stroke-width', 0)
     .each(function(d) {
         var shape = d3.select(this);
         // N.B. 'd' won't be a calcdata item when
         // fill !== 'none' on a segment-less and marker-less trace
         if(d[0].trace) {
-            setFillStyle(shape, d[0].trace, gd);
+            setFillStyle(shape, d[0].trace, gd, forLegend);
         }
     });
 };
@@ -294,16 +343,14 @@ function makePointPath(symbolNumber, r, t, s) {
     return drawing.symbolFuncs[base](r, t, s) + (symbolNumber >= 200 ? DOTPATH : '');
 }
 
-var HORZGRADIENT = {x1: 1, x2: 0, y1: 0, y2: 0};
-var VERTGRADIENT = {x1: 0, x2: 0, y1: 1, y2: 0};
 var stopFormatter = numberFormat('~f');
 var gradientInfo = {
-    radial: {node: 'radialGradient'},
-    radialreversed: {node: 'radialGradient', reversed: true},
-    horizontal: {node: 'linearGradient', attrs: HORZGRADIENT},
-    horizontalreversed: {node: 'linearGradient', attrs: HORZGRADIENT, reversed: true},
-    vertical: {node: 'linearGradient', attrs: VERTGRADIENT},
-    verticalreversed: {node: 'linearGradient', attrs: VERTGRADIENT, reversed: true}
+    radial: {type: 'radial'},
+    radialreversed: {type: 'radial', reversed: true},
+    horizontal: {type: 'linear', start: {x: 1, y: 0}, stop: {x: 0, y: 0}},
+    horizontalreversed: {type: 'linear', start: {x: 1, y: 0}, stop: {x: 0, y: 0}, reversed: true},
+    vertical: {type: 'linear', start: {x: 0, y: 1}, stop: {x: 0, y: 0}},
+    verticalreversed: {type: 'linear', start: {x: 0, y: 1}, stop: {x: 0, y: 0}, reversed: true}
 };
 
 /**
@@ -321,8 +368,57 @@ var gradientInfo = {
  * @param {string} prop: the property to apply to, 'fill' or 'stroke'
  */
 drawing.gradient = function(sel, gd, gradientID, type, colorscale, prop) {
-    var len = colorscale.length;
     var info = gradientInfo[type];
+    return gradientWithBounds(
+        sel, gd, gradientID, info.type, colorscale, prop, info.start, info.stop, false, info.reversed
+    );
+};
+
+/**
+ * gradient_with_bounds: create and apply a gradient fill for defined start and stop positions
+ *
+ * @param {object} sel: d3 selection to apply this gradient to
+ *     You can use `selection.call(Drawing.gradient, ...)`
+ * @param {DOM element} gd: the graph div `sel` is part of
+ * @param {string} gradientID: a unique (within this plot) identifier
+ *     for this gradient, so that we don't create unnecessary definitions
+ * @param {string} type: 'radial' or 'linear'. Radial goes center to edge,
+ *     horizontal goes as defined by start and stop
+ * @param {array} colorscale: as in attribute values, [[fraction, color], ...]
+ * @param {string} prop: the property to apply to, 'fill' or 'stroke'
+ * @param {object} start: start point for linear gradients, { x: number, y: number }.
+ *     Ignored if type is 'radial'.
+ * @param {object} stop: stop point for linear gradients, { x: number, y: number }.
+ *     Ignored if type is 'radial'.
+ * @param {boolean} inUserSpace: If true, start and stop give absolute values in the plot.
+ *     If false, start and stop are fractions of the traces extent along each axis.
+ * @param {boolean} reversed: If true, the gradient is reversed between normal start and stop,
+ *     i.e., the colorscale is applied in order from stop to start for linear, from edge
+ *     to center for radial gradients.
+ */
+function gradientWithBounds(sel, gd, gradientID, type, colorscale, prop, start, stop, inUserSpace, reversed) {
+    var len = colorscale.length;
+
+    var info;
+    if(type === 'linear') {
+        info = {
+            node: 'linearGradient',
+            attrs: {
+                x1: start.x,
+                y1: start.y,
+                x2: stop.x,
+                y2: stop.y,
+                gradientUnits: inUserSpace ? 'userSpaceOnUse' : 'objectBoundingBox',
+            },
+            reversed: reversed,
+        };
+    } else if(type === 'radial') {
+        info = {
+            node: 'radialGradient',
+            reversed: reversed,
+        };
+    }
+
     var colorStops = new Array(len);
     for(var i = 0; i < len; i++) {
         if(info.reversed) {
@@ -368,7 +464,7 @@ drawing.gradient = function(sel, gd, gradientID, type, colorscale, prop) {
         .style(prop + '-opacity', null);
 
     sel.classed('gradient_filled', true);
-};
+}
 
 /**
  * pattern: create and apply a pattern fill
diff --git a/src/components/legend/style.js b/src/components/legend/style.js
@@ -114,7 +114,7 @@ module.exports = function style(s, gd, legend) {
         var fillStyle = function(s) {
             if(s.size()) {
                 if(showFill) {
-                    Drawing.fillGroupStyle(s, gd);
+                    Drawing.fillGroupStyle(s, gd, true);
                 } else {
                     var gradientID = 'legendfill-' + trace.uid;
                     Drawing.gradient(s, gd, gradientID,
@@ -673,7 +673,6 @@ function getStyleGuide(d) {
             showGradientFill = true;
         }
     }
-
     return {
         showMarker: showMarker,
         showLine: showLine,
diff --git a/src/traces/scatter/attributes.js b/src/traces/scatter/attributes.js
@@ -398,9 +398,67 @@ module.exports = {
         description: [
             'Sets the fill color.',
             'Defaults to a half-transparent variant of the line color,',
-            'marker color, or marker line color, whichever is available.'
+            'marker color, or marker line color, whichever is available.',
+            'If fillgradient is specified, fillcolor is ignored except for',
+            'setting the background color of the hover label, if any.'
         ].join(' ')
     },
+    fillgradient: extendFlat({
+        orientation: {
+            valType: 'enumerated',
+            values: ['radial', 'horizontal', 'vertical', 'none'],
+            dflt: 'none',
+            editType: 'style',
+            description: [
+                'Sets the orientation of the color gradient.',
+                'Defaults to *none*.'
+            ].join(' ')
+        },
+        start: {
+            valType: 'number',
+            editType: 'calc',
+            description: [
+                'Sets the gradient start value.',
+                'It is given as the absolute position on the axis determined by',
+                'the orientiation. E.g., if orientation is *horizontal*, the',
+                'gradient will be horizontal and start from the x-position',
+                'given by start. If omitted, the gradient starts at the lowest',
+                'value of the trace along the respective axis.',
+                'Ignored if orientation is *radial*.'
+            ].join(' ')
+        },
+        stop: {
+            valType: 'number',
+            editType: 'calc',
+            description: [
+                'Sets the gradient end value.',
+                'It is given as the absolute position on the axis determined by',
+                'the orientiation. E.g., if orientation is *horizontal*, the',
+                'gradient will be horizontal and end at the x-position',
+                'given by end. If omitted, the gradient ends at the highest',
+                'value of the trace along the respective axis.',
+                'Ignored if orientation is *radial*.'
+            ].join(' ')
+        },
+        colorscale: {
+            valType: 'colorscale',
+            editType: 'style',
+            anim: true,
+            description: [
+                'Sets the fill gradient colors as a color scale.',
+                'The color scale is interpreted as a gradient',
+                'applied in the direction specified by *orientation*,',
+                'from the lowest to the highest value of the scatter',
+                'plot along that axis, or from the center to the most',
+                'distant point from it, if orientation is *radial*.'
+            ].join(' ')
+        },
+        editType: 'style',
+        description: [
+            'Sets a fill gradient.',
+            'If not specified, the fillcolor is used instead.'
+        ].join(' ')
+    }),
     fillpattern: pattern,
     marker: extendFlat({
         symbol: {
diff --git a/src/traces/scatter/fillcolor_defaults.js b/src/traces/scatter/fillcolor_defaults.js
@@ -2,6 +2,17 @@
 
 var Color = require('../../components/color');
 var isArrayOrTypedArray = require('../../lib').isArrayOrTypedArray;
+var assert = require('assert');
+
+function averageColors(colorscale) {
+    assert(colorscale.length >= 2);
+    var color = Color.interpolate(colorscale[0][1], colorscale[1][1], 0.5);
+    for(var i = 2; i < colorscale.length; i++) {
+        var averageColorI = Color.interpolate(colorscale[i - 1][1], colorscale[i][1], 0.5);
+        color = Color.interpolate(color, averageColorI, colorscale[i - 1][0] / colorscale[i][0]);
+    }
+    return color;
+}
 
 module.exports = function fillColorDefaults(traceIn, traceOut, defaultColor, coerce) {
     var inheritColorFromMarker = false;
@@ -18,9 +29,25 @@ module.exports = function fillColorDefaults(traceIn, traceOut, defaultColor, coe
         }
     }
 
+    var averageGradientColor;
+    if(traceIn.fillgradient) {
+        // if a fillgradient is specified, we use the average gradient color
+        // to specifiy fillcolor after all other more specific candidates
+        // are considered, but before the global default color.
+        // fillcolor affects the background color of the hoverlabel in this case.
+        var gradientOrientation = coerce('fillgradient.orientation');
+        if(gradientOrientation !== 'none') {
+            coerce('fillgradient.start');
+            coerce('fillgradient.stop');
+            coerce('fillgradient.colorscale');
+            averageGradientColor = averageColors(traceOut.fillgradient.colorscale);
+        }
+    }
+
     coerce('fillcolor', Color.addOpacity(
         (traceOut.line || {}).color ||
         inheritColorFromMarker ||
+        averageGradientColor ||
         defaultColor, 0.5
     ));
 };
diff --git a/src/traces/scatter/style.js b/src/traces/scatter/style.js
@@ -27,7 +27,7 @@ function style(gd) {
         .call(Drawing.lineGroupStyle);
 
     s.selectAll('g.trace path.js-fill')
-        .call(Drawing.fillGroupStyle, gd);
+        .call(Drawing.fillGroupStyle, gd, false);
 
     Registry.getComponentMethod('errorbars', 'style')(s);
 }
diff --git a/test/image/baselines/scatter_fill_gradient_tonext.png b/test/image/baselines/scatter_fill_gradient_tonext.png
diff --git a/test/image/baselines/scatter_fill_gradient_tonexty_toself.png b/test/image/baselines/scatter_fill_gradient_tonexty_toself.png
diff --git a/test/image/mocks/scatter_fill_gradient_tonext.json b/test/image/mocks/scatter_fill_gradient_tonext.json
@@ -0,0 +1,42 @@
+{
+    "data": [
+        {
+            "x": [1, 1, 2, 2],
+            "y": [1, 2, 2, 1],
+            "type": "scatter",
+            "mode": "none",
+            "fill": "tonext",
+            "hoveron": "points+fills",
+            "fillgradient": {
+                "orientation": "horizontal",
+                "colorscale": [
+                    [0.0, "rgba(0, 255, 0, 1)"],
+                    [0.5, "rgba(0, 255, 0, 0)"],
+                    [1.0, "rgba(0, 255, 0, 1)"]
+                ]
+            }
+        },
+        {
+            "x": [0, 0, 3, 3],
+            "y": [0, 4, 4, 1],
+            "type": "scatter",
+            "mode": "none",
+            "fill": "tonext",
+            "hoveron": "fills+points",
+                "fillgradient": {
+                "orientation": "radial",
+                "colorscale": [
+                    [0.0, "rgba(255, 255, 0, 0.0)"],
+                    [0.8, "rgba(255, 0, 0, 0.3)"],
+                    [1.0, "rgba(255, 255, 0, 1.0)"]
+                ]
+            }
+        }
+    ],
+
+    "layout": {
+        "autosize": true,
+        "title": { "text": "Scatter traces with radial color gradient fills" },
+        "showlegend": true
+    }
+}
diff --git a/test/image/mocks/scatter_fill_gradient_tonexty_toself.json b/test/image/mocks/scatter_fill_gradient_tonexty_toself.json

Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@ function style(gd) {`
`27`	`27`	`.call(Drawing.lineGroupStyle);`
`28`	`28`
`29`	`29`	`s.selectAll('g.trace path.js-fill')`
`30`		`- .call(Drawing.fillGroupStyle, gd);`
	`30`	`+ .call(Drawing.fillGroupStyle, gd, false);`
`31`	`31`
`32`	`32`	`Registry.getComponentMethod('errorbars', 'style')(s);`
`33`	`33`	`}`