Add zorder attribute to control stacking order of SVG traces drawn into cartesian subplots

draftlogs/6918_add.md

@@ -0,0 +1 @@
+- Add a new attribute `zindex` to SVG based Cartesian traces (not to WebGL traces). Traces with higher `zindex` values are drawn in front of traces with lower `zindex` values. This feature was anonymously sponsored: thank you to our sponsor!

src/plots/cartesian/index.js

@@ -130,21 +130,27 @@ exports.plot = function(gd, traces, transitionOpts, makeOnCompleteCallback) {
     var calcdata = gd.calcdata;
     var i;
 
+    // Traces is a list of trace indices to (re)plot. If it's not provided,
+    // then it's a complete replot so we create a new list and add all trace indices
+    // which are in calcdata.
+
     if(!Array.isArray(traces)) {
         // If traces is not provided, then it's a complete replot and missing
         // traces are removed
         traces = [];
         for(i = 0; i < calcdata.length; i++) traces.push(i);
     }
 
+    // For each subplot
     for(i = 0; i < subplots.length; i++) {
         var subplot = subplots[i];
         var subplotInfo = fullLayout._plots[subplot];
 
-        // Get all calcdata for this subplot:
+        // Get all calcdata (traces) for this subplot:
         var cdSubplot = [];
         var pcd;
 
+        // For each trace
         for(var j = 0; j < calcdata.length; j++) {
             var cd = calcdata[j];
             var trace = cd[0].trace;
@@ -178,7 +184,7 @@ exports.plot = function(gd, traces, transitionOpts, makeOnCompleteCallback) {
                 pcd = cd;
             }
         }
-
+        // Plot the traces for this subplot
         plotOne(gd, subplotInfo, cdSubplot, transitionOpts, makeOnCompleteCallback);
     }
 };
@@ -189,41 +195,60 @@ function plotOne(gd, plotinfo, cdSubplot, transitionOpts, makeOnCompleteCallback
     var modules = fullLayout._modules;
     var _module, cdModuleAndOthers, cdModule;
 
+    // Separate traces by zindex and plot each zindex group separately
+    // TODO: Performance
+    var traceZindexGroups = {};
+    for(var t = 0; t < cdSubplot.length; t++) {
+        var trace = cdSubplot[t][0].trace;
+        var zi = trace.zindex || 0;
+        if(!traceZindexGroups[zi]) traceZindexGroups[zi] = [];
+        traceZindexGroups[zi].push(cdSubplot[t]);
+    }
+
     var layerData = [];
     var zoomScaleQueryParts = [];
 
-    for(var i = 0; i < modules.length; i++) {
-        _module = modules[i];
-        var name = _module.name;
-        var categories = Registry.modules[name].categories;
-
-        if(categories.svg) {
-            var className = (_module.layerName || name + 'layer');
-            var plotMethod = _module.plot;
-
-            // plot all visible traces of this type on this subplot at once
-            cdModuleAndOthers = getModuleCalcData(cdSubplot, plotMethod);
-            cdModule = cdModuleAndOthers[0];
-            // don't need to search the found traces again - in fact we need to NOT
-            // so that if two modules share the same plotter we don't double-plot
-            cdSubplot = cdModuleAndOthers[1];
-
-            if(cdModule.length) {
-                layerData.push({
-                    i: traceLayerClasses.indexOf(className),
-                    className: className,
-                    plotMethod: plotMethod,
-                    cdModule: cdModule
-                });
-            }
+    // Plot each zindex group in ascending order
+    var zindices = Object.keys(traceZindexGroups)
+        .map(Number)
+        .sort(Lib.sorterAsc);
+    for(var z = 0; z < zindices.length; z++) {
+        var zindex = zindices[z];
+        // For each "module" (trace type)
+        for(var i = 0; i < modules.length; i++) {
+            _module = modules[i];
+            var name = _module.name;
+            var categories = Registry.modules[name].categories;
+
+            if(categories.svg) {
+                var className = (_module.layerName || name + 'layer') + (zindex ? '-' + z : '');
+                var plotMethod = _module.plot;
+
+                // plot all visible traces of this type on this subplot at once
+                cdModuleAndOthers = getModuleCalcData(cdSubplot, plotMethod, zindex);
+                cdModule = cdModuleAndOthers[0];
+                // don't need to search the found traces again - in fact we need to NOT
+                // so that if two modules share the same plotter we don't double-plot
+                cdSubplot = cdModuleAndOthers[1];
+
+                if(cdModule.length) {
+                    layerData.push({
+                        i: traceLayerClasses.indexOf(className),
+                        zindex: z,
+                        className: className,
+                        plotMethod: plotMethod,
+                        cdModule: cdModule
+                    });
+                }
 
-            if(categories.zoomScale) {
-                zoomScaleQueryParts.push('.' + className);
+                if(categories.zoomScale) {
+                    zoomScaleQueryParts.push('.' + className);
+                }
             }
         }
     }
-
-    layerData.sort(function(a, b) { return a.i - b.i; });
+    // Sort the layers primarily by z, then by i
+    layerData.sort(function(a, b) { return (a.zindex || 0) - (b.zindex || 0) || a.i - b.i; });
 
     var layers = plotinfo.plot.selectAll('g.mlayer')
         .data(layerData, function(d) { return d.className; });
@@ -434,7 +459,6 @@ function makeSubplotData(gd) {
         }
         subplotData[i] = d;
     }
-
     return subplotData;
 }
 

src/plots/get_data.js

@@ -39,10 +39,10 @@ exports.getSubplotCalcData = function(calcData, type, subplotId) {
  * @param {array} calcdata: as in gd.calcdata
  * @param {object|string|fn} arg1:
  *  the plotting module, or its name, or its plot method
- *
+ * @param {int} arg2: (optional) zindex to filter on
  * @return {array[array]} [foundCalcdata, remainingCalcdata]
  */
-exports.getModuleCalcData = function(calcdata, arg1) {
+exports.getModuleCalcData = function(calcdata, arg1, arg2) {
     var moduleCalcData = [];
     var remainingCalcData = [];
 
@@ -57,10 +57,12 @@ exports.getModuleCalcData = function(calcdata, arg1) {
     if(!plotMethod) {
         return [moduleCalcData, calcdata];
     }
+    var zindex = arg2;
 
     for(var i = 0; i < calcdata.length; i++) {
         var cd = calcdata[i];
         var trace = cd[0].trace;
+        var filterByZ = (trace.zindex !== undefined);
         // N.B.
         // - 'legendonly' traces do not make it past here
         // - skip over 'visible' traces that got trimmed completely during calc transforms
@@ -70,7 +72,7 @@ exports.getModuleCalcData = function(calcdata, arg1) {
         // would suggest), but by 'module plot method' so that if some traces
         // share the same module plot method (e.g. bar and histogram), we
         // only call it one!
-        if(trace._module && trace._module.plot === plotMethod) {
+        if(trace._module && trace._module.plot === plotMethod && (!filterByZ || trace.zindex === zindex)) {
             moduleCalcData.push(cd);
         } else {
             remainingCalcData.push(cd);

src/traces/bar/attributes.js

@@ -226,6 +226,7 @@ module.exports = {
         textfont: scatterAttrs.unselected.textfont,
         editType: 'style'
     },
+    zindex: scatterAttrs.zindex,
 
     _deprecated: {
         bardir: {

src/traces/bar/defaults.js

@@ -29,6 +29,8 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     coerce('xhoverformat');
     coerce('yhoverformat');
 
+    coerce('zindex');
+
     coerce('orientation', (traceOut.x && !traceOut.y) ? 'h' : 'v');
     coerce('base');
     coerce('offset');

src/traces/bar/style.js

@@ -14,7 +14,7 @@ var attributeOutsideTextFont = attributes.outsidetextfont;
 var helpers = require('./helpers');
 
 function style(gd) {
-    var s = d3.select(gd).selectAll('g.barlayer').selectAll('g.trace');
+    var s = d3.select(gd).selectAll('g[class^="barlayer"]').selectAll('g.trace');
     resizeText(gd, s, 'bar');
 
     var barcount = s.size();

src/traces/box/attributes.js

@@ -451,5 +451,6 @@ module.exports = {
             'Do the hover effects highlight individual boxes ',
             'or sample points or both?'
         ].join(' ')
-    }
+    },
+    zindex: scatterAttrs.zindex
 };

src/traces/box/defaults.js

@@ -67,6 +67,7 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     if(notched) coerce('notchwidth');
 
     handlePointsDefaults(traceIn, traceOut, coerce, {prefix: 'box'});
+    coerce('zindex');
 }
 
 function handleSampleDefaults(traceIn, traceOut, coerce, layout) {

src/traces/candlestick/attributes.js

@@ -4,6 +4,7 @@ var extendFlat = require('../../lib').extendFlat;
 var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var OHLCattrs = require('../ohlc/attributes');
 var boxAttrs = require('../box/attributes');
+var scatterAttrs = require('../scatter/attributes');
 
 function directionAttrs(lineColorDefault) {
     return {
@@ -53,4 +54,5 @@ module.exports = {
     whiskerwidth: extendFlat({}, boxAttrs.whiskerwidth, { dflt: 0 }),
 
     hoverlabel: OHLCattrs.hoverlabel,
+    zindex: scatterAttrs.zindex
 };

src/traces/candlestick/defaults.js

@@ -31,6 +31,7 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('whiskerwidth');
 
     layout._requestRangeslider[traceOut.xaxis] = true;
+    coerce('zindex');
 };
 
 function handleDirection(traceIn, traceOut, coerce, direction) {

src/traces/carpet/attributes.js

@@ -8,6 +8,9 @@ var carpetFont = fontAttrs({
     editType: 'calc',
     description: 'The default font used for axis & tick labels on this carpet'
 });
+
+var scatterAttrs = require('../scatter/attributes');
+
 // TODO: inherit from global font
 carpetFont.family.dflt = '"Open Sans", verdana, arial, sans-serif';
 carpetFont.size.dflt = 12;
@@ -112,5 +115,6 @@ module.exports = {
             'Individual pieces can override this.'
         ].join(' ')
     },
-    transforms: undefined
+    transforms: undefined,
+    zindex: scatterAttrs.zindex
 };

src/traces/carpet/defaults.js

@@ -45,4 +45,5 @@ module.exports = function supplyDefaults(traceIn, traceOut, dfltColor, fullLayou
     if(traceOut._cheater) {
         coerce('cheaterslope');
     }
+    coerce('zindex');
 };

src/traces/contour/attributes.js

@@ -265,7 +265,8 @@ module.exports = extendFlat({
             ].join(' ')
         }),
         editType: 'plot'
-    }
+    },
+    zindex: scatterAttrs.zindex
 },
     colorScaleAttrs('', {
         cLetter: 'z',

src/traces/contour/defaults.js

@@ -51,4 +51,5 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     ) {
         handleHeatmapLabelDefaults(coerce, layout);
     }
+    coerce('zindex');
 };

src/traces/contourcarpet/attributes.js

@@ -2,6 +2,7 @@
 
 var heatmapAttrs = require('../heatmap/attributes');
 var contourAttrs = require('../contour/attributes');
+var scatterAttrs = require('../scatter/attributes');
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 
 var extendFlat = require('../../lib/extend').extendFlat;
@@ -70,7 +71,8 @@ module.exports = extendFlat({
         editType: 'plot'
     },
 
-    transforms: undefined
+    transforms: undefined,
+    zindex: scatterAttrs.zindex
 },
 
     colorScaleAttrs('', {

src/traces/contourcarpet/defaults.js

@@ -55,4 +55,5 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         traceOut._defaultColor = defaultColor;
         traceOut._length = null;
     }
+    coerce('zindex');
 };

src/traces/funnel/attributes.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var barAttrs = require('../bar/attributes');
+var scatterAttrs = require('../scatter/attributes');
 var lineAttrs = require('../scatter/attributes').line;
 var baseAttrs = require('../../plots/attributes');
 var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
@@ -109,7 +110,8 @@ module.exports = {
     },
 
     offsetgroup: barAttrs.offsetgroup,
-    alignmentgroup: barAttrs.alignmentgroup
+    alignmentgroup: barAttrs.alignmentgroup,
+    zindex: scatterAttrs.zindex
 };
 
 function funnelMarker() {

src/traces/funnel/defaults.js

@@ -61,6 +61,7 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
             coerce('connector.line.dash');
         }
     }
+    coerce('zindex');
 }
 
 function defaultFillColor(markerColor) {

src/traces/funnel/style.js

@@ -10,7 +10,7 @@ var resizeText = require('../bar/uniform_text').resizeText;
 var styleTextPoints = barStyle.styleTextPoints;
 
 function style(gd, cd, sel) {
-    var s = sel ? sel : d3.select(gd).selectAll('g.funnellayer').selectAll('g.trace');
+    var s = sel ? sel : d3.select(gd).selectAll('g[class^="funnellayer"]').selectAll('g.trace');
     resizeText(gd, s, 'funnel');
 
     s.style('opacity', function(d) { return d[0].trace.opacity; });

src/traces/heatmap/attributes.js

@@ -132,7 +132,8 @@ module.exports = extendFlat({
         description: 'Sets the text font.'
     }),
 
-    showlegend: extendFlat({}, baseAttrs.showlegend, {dflt: false})
+    showlegend: extendFlat({}, baseAttrs.showlegend, {dflt: false}),
+    zindex: scatterAttrs.zindex
 }, {
     transforms: undefined
 },

src/traces/heatmap/defaults.js

@@ -36,4 +36,5 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('connectgaps', Lib.isArray1D(traceOut.z) && (traceOut.zsmooth !== false));
 
     colorscaleDefaults(traceIn, traceOut, layout, coerce, {prefix: '', cLetter: 'z'});
+    coerce('zindex');
 };

src/traces/image/attributes.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var baseAttrs = require('../../plots/attributes');
+var scatterAttrs = require('../scatter/attributes');
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
 var extendFlat = require('../../lib/extend').extendFlat;
 var colormodel = require('./constants').colormodel;
@@ -133,5 +134,6 @@ module.exports = extendFlat({
         keys: ['z', 'color', 'colormodel']
     }),
 
-    transforms: undefined
+    transforms: undefined,
+    zindex: scatterAttrs.zindex
 });

src/traces/image/defaults.js

@@ -45,4 +45,6 @@ module.exports = function supplyDefaults(traceIn, traceOut) {
     coerce('hovertemplate');
 
     traceOut._length = null;
+
+    coerce('zindex');
 };

src/traces/ohlc/attributes.js

@@ -133,4 +133,6 @@ module.exports = {
             ].join(' ')
         }
     }),
+
+    zindex: scatterAttrs.zindex
 };

src/traces/ohlc/defaults.js

@@ -31,6 +31,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('tickwidth');
 
     layout._requestRangeslider[traceOut.xaxis] = true;
+
+    coerce('zindex');
 };
 
 function handleDirection(traceIn, traceOut, coerce, direction) {