zindex first pass. scatter and bar traces only

Author: emilykl

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(function(a, b) { return a - b; });
+    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),
+                        z: 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.z - b.z || 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,6 +57,8 @@ exports.getModuleCalcData = function(calcdata, arg1) {
     if(!plotMethod) {
         return [moduleCalcData, calcdata];
     }
+    var zindex = arg2;
+    var filterByZ = (zindex !== undefined);
 
     for(var i = 0; i < calcdata.length; i++) {
         var cd = calcdata[i];
@@ -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/scatter/attributes.js

@@ -686,4 +686,14 @@ module.exports = {
         arrayOk: true,
         description: 'Sets the text font.'
     }),
+    zindex: {
+        valType: 'integer',
+        dflt: 0,
+        editType: 'calc',
+        description: [
+            'Sets the layer on which this trace is displayed, relative to ',
+            'other traces on the same axes. Traces with higher `zindex` ',
+            'appear in front of those with lower `zindex`.'
+        ].join(' ')
+    }
 };

src/traces/scatter/defaults.js

@@ -30,6 +30,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('xhoverformat');
     coerce('yhoverformat');
 
+    coerce('zindex');
+
     var stackGroupOpts = handleStackDefaults(traceIn, traceOut, layout, coerce);
     if(
         layout.scattermode === 'group' &&

test/image/mocks/zindex_basic.json

@@ -0,0 +1,53 @@
+{
+    "data": [
+        {
+            "x": [2, 3, 4, 5],
+            "y": [4, 3, 9, 5],
+            "name": "blue",
+            "type": "scatter",
+            "marker": {"size": 20},
+            "line": {"width": 6},
+            "zindex": 5
+        },
+        {
+            "x": [2, 3, 4, 5, 6],
+            "y": [2, 5, 4, 6, 4],
+            "name": "orange",
+            "type": "scatter",
+            "marker": {"size": 20},
+            "line": {"width": 6},
+            "zindex": 4
+        },
+        {
+            "x": [3, 4, 5, 6, 7],
+            "y": [1, 8, 6, 8, 5],
+            "name": "green",
+            "type": "scatter",
+            "marker": {"size": 20},
+            "line": {"width": 6}
+        },
+        {
+            "x": [4, 5, 6, 7],
+            "y": [2, 8, 2, 7],
+            "name": "red",
+            "type": "scatter",
+            "marker": {"size": 20},
+            "line": {"width": 6},
+            "zindex": 300
+        },
+        {
+            "x": [2, 3, 4, 5, 6, 7],
+            "y": [4, 2, 6, 1, 6, 9],
+            "name": "purple",
+            "type": "bar",
+            "zindex": 6
+        }
+    ],
+    "layout": {
+        "xaxis": {
+            "title": {
+                "text": "zindex stacking"
+            }
+        }
+    }
+}