Merge pull request #6918 from plotly/trace-zindex

Add z-index stacking attribute to cartesian SVG traces

Author: archmoj

draftlogs/6918_add.md

@@ -0,0 +1 @@
+- Add a new attribute `zorder` to SVG based Cartesian traces (not to WebGL traces). Traces with higher `zorder` values are drawn in front of traces with lower `zorder` 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 zorder and plot each zorder group separately
+    // TODO: Performance
+    var traceZorderGroups = {};
+    for(var t = 0; t < cdSubplot.length; t++) {
+        var trace = cdSubplot[t][0].trace;
+        var zi = trace.zorder || 0;
+        if(!traceZorderGroups[zi]) traceZorderGroups[zi] = [];
+        traceZorderGroups[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 zorder group in ascending order
+    var zindices = Object.keys(traceZorderGroups)
+        .map(Number)
+        .sort(Lib.sorterAsc);
+    for(var z = 0; z < zindices.length; z++) {
+        var zorder = 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') + (z ? Number(z) + 1 : '');
+                var plotMethod = _module.plot;
+
+                // plot all visible traces of this type on this subplot at once
+                cdModuleAndOthers = getModuleCalcData(cdSubplot, plotMethod, zorder);
+                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),
+                        zorder: 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.zorder || 0) - (b.zorder || 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) zorder 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 zorder = arg2;
 
     for(var i = 0; i < calcdata.length; i++) {
         var cd = calcdata[i];
         var trace = cd[0].trace;
+        var filterByZ = (trace.zorder !== 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.zorder === zorder)) {
             moduleCalcData.push(cd);
         } else {
             remainingCalcData.push(cd);

src/traces/bar/attributes.js

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

src/traces/bar/defaults.js

@@ -29,6 +29,8 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     coerce('xhoverformat');
     coerce('yhoverformat');
 
+    coerce('zorder');
+
     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(' ')
-    }
+    },
+    zorder: scatterAttrs.zorder
 };

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('zorder');
 }
 
 function handleSampleDefaults(traceIn, traceOut, coerce, layout) {

src/traces/candlestick/attributes.js

@@ -53,4 +53,5 @@ module.exports = {
     whiskerwidth: extendFlat({}, boxAttrs.whiskerwidth, { dflt: 0 }),
 
     hoverlabel: OHLCattrs.hoverlabel,
+    zorder: boxAttrs.zorder
 };

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('zorder');
 };
 
 function handleDirection(traceIn, traceOut, coerce, direction) {