implement cliponaxis

- keep track of which subplots have 1 or more `cliponaxis: false` traces
  + if so, don't clip the subplot layer
  + instead, clip all trace module layers except for 'scatterlayer'
  + when `cliponaxis: false`, clip all lines and errorbar groups
- use ax.isWithinRange and Drawing.hideOutsideRangePoint to
  hide markers and text node that are out of range.

Author: etpinard

src/components/drawing/index.js

@@ -93,6 +93,13 @@ drawing.translatePoints = function(s, xa, ya) {
     });
 };
 
+drawing.hideOutsideRangePoint = function(d, sel, xa, ya) {
+    sel.attr(
+        'visibility',
+        xa.isPtWithinRange(d) && ya.isPtWithinRange(d) ? null : 'hidden'
+    );
+};
+
 drawing.getPx = function(s, styleAttr) {
     // helper to pull out a px value from a style that may contain px units
     // s is a d3 selection (will pull from the first one)

src/components/errorbars/plot.js

@@ -12,13 +12,14 @@
 var d3 = require('d3');
 var isNumeric = require('fast-isnumeric');
 
+var Drawing = require('../drawing');
 var subTypes = require('../../traces/scatter/subtypes');
 
 module.exports = function plot(traces, plotinfo, transitionOpts) {
     var isNew;
 
-    var xa = plotinfo.xaxis,
-        ya = plotinfo.yaxis;
+    var xa = plotinfo.xaxis;
+    var ya = plotinfo.yaxis;
 
     var hasAnimation = transitionOpts && transitionOpts.duration > 0;
 
@@ -60,6 +61,11 @@ module.exports = function plot(traces, plotinfo, transitionOpts) {
                 .style('opacity', 1);
         }
 
+        errorbars.call(
+            Drawing.setClipUrl,
+            plotinfo._hasClipOnAxisFalse ? plotinfo.clipId : null
+        );
+
         errorbars.each(function(d) {
             var errorbar = d3.select(this);
             var coords = errorCoords(d, xa, ya);

src/plot_api/subroutines.js

@@ -20,6 +20,7 @@ var Drawing = require('../components/drawing');
 var Titles = require('../components/titles');
 var ModeBar = require('../components/modebar');
 var initInteractions = require('../plots/cartesian/graph_interact');
+var cartesianConstants = require('../plots/cartesian/constants');
 
 exports.layoutStyles = function(gd) {
     return Lib.syncOrAsync([Plots.doAutoMargin, exports.lsInner], gd);
@@ -164,9 +165,27 @@ exports.lsInner = function(gd) {
                 'height': ya._length
             });
 
-
         plotinfo.plot.call(Drawing.setTranslate, xa._offset, ya._offset);
-        plotinfo.plot.call(Drawing.setClipUrl, plotinfo.clipId);
+
+        var plotClipId;
+        var layerClipId;
+
+        if(plotinfo._hasClipOnAxisFalse) {
+            plotClipId = null;
+            layerClipId = plotinfo.clipId;
+        } else {
+            plotClipId = plotinfo.clipId;
+            layerClipId = null;
+        }
+
+        plotinfo.plot.call(Drawing.setClipUrl, plotClipId);
+
+        for(i = 0; i < cartesianConstants.layers.length; i++) {
+            var layer = cartesianConstants.layers[i];
+            if(layer !== 'scatterlayer') {
+                plotinfo.plot.selectAll('g.' + layer).call(Drawing.setClipUrl, layerClipId);
+            }
+        }
 
         var xlw = Drawing.crispRound(gd, xa.linewidth, 1),
             ylw = Drawing.crispRound(gd, ya.linewidth, 1),

src/plots/cartesian/constants.js

@@ -49,5 +49,21 @@ module.exports = {
 
     // last resort axis ranges for x and y axes if we have no data
     DFLTRANGEX: [-1, 6],
-    DFLTRANGEY: [-1, 4]
+    DFLTRANGEY: [-1, 4],
+
+    // Layers to keep plot types in the right order.
+    // from back to front:
+    // 1. heatmaps, 2D histos and contour maps
+    // 2. bars / 1D histos
+    // 3. errorbars for bars and scatter
+    // 4. scatter
+    // 5. box plots
+    layers: [
+        'imagelayer',
+        'maplayer',
+        'barlayer',
+        'carpetlayer',
+        'boxlayer',
+        'scatterlayer'
+    ]
 };

src/plots/cartesian/index.js

@@ -294,24 +294,8 @@ function makeSubplotData(gd) {
 }
 
 function makeSubplotLayer(plotinfo) {
-    var plotgroup = plotinfo.plotgroup,
-        id = plotinfo.id;
-
-    // Layers to keep plot types in the right order.
-    // from back to front:
-    // 1. heatmaps, 2D histos and contour maps
-    // 2. bars / 1D histos
-    // 3. errorbars for bars and scatter
-    // 4. scatter
-    // 5. box plots
-    function joinPlotLayers(parent) {
-        joinLayer(parent, 'g', 'imagelayer');
-        joinLayer(parent, 'g', 'maplayer');
-        joinLayer(parent, 'g', 'barlayer');
-        joinLayer(parent, 'g', 'carpetlayer');
-        joinLayer(parent, 'g', 'boxlayer');
-        joinLayer(parent, 'g', 'scatterlayer');
-    }
+    var plotgroup = plotinfo.plotgroup;
+    var id = plotinfo.id;
 
     if(!plotinfo.mainplot) {
         var backLayer = joinLayer(plotgroup, 'g', 'layer-subplot');
@@ -354,7 +338,10 @@ function makeSubplotLayer(plotinfo) {
     }
 
     // common attributes for all subplots, overlays or not
-    plotinfo.plot.call(joinPlotLayers);
+
+    for(var i = 0; i < constants.layers.length; i++) {
+        joinLayer(plotinfo.plot, 'g', constants.layers[i]);
+    }
 
     plotinfo.xlines
         .style('fill', 'none')

src/plots/cartesian/set_convert.js

@@ -58,6 +58,8 @@ function fromLog(v) {
 module.exports = function setConvert(ax, fullLayout) {
     fullLayout = fullLayout || {};
 
+    var axLetter = (ax._id || 'x').charAt(0);
+
     // clipMult: how many axis lengths past the edge do we render?
     // for panning, 1-2 would suffice, but for zooming more is nice.
     // also, clipping can affect the direction of lines off the edge...
@@ -277,7 +279,6 @@ module.exports = function setConvert(ax, fullLayout) {
     ax.cleanRange = function(rangeAttr) {
         if(!rangeAttr) rangeAttr = 'range';
         var range = Lib.nestedProperty(ax, rangeAttr).get(),
-            axLetter = (ax._id || 'x').charAt(0),
             i, dflt;
 
         if(ax.type === 'date') dflt = Lib.dfltRange(ax.calendar);
@@ -341,8 +342,7 @@ module.exports = function setConvert(ax, fullLayout) {
 
     // set scaling to pixels
     ax.setScale = function(usePrivateRange) {
-        var gs = fullLayout._size,
-            axLetter = ax._id.charAt(0);
+        var gs = fullLayout._size;
 
         // TODO cleaner way to handle this case
         if(!ax._categories) ax._categories = [];
@@ -435,6 +435,18 @@ module.exports = function setConvert(ax, fullLayout) {
         );
     };
 
+    if(axLetter === 'x') {
+        ax.isPtWithinRange = function(d) {
+            var x = d.x;
+            return x >= ax.range[0] && x <= ax.range[1];
+        };
+    } else {
+        ax.isPtWithinRange = function(d) {
+            var y = d.y;
+            return y >= ax.range[0] && y <= ax.range[1];
+        };
+    }
+
     // for autoranging: arrays of objects:
     //      {val: axis value, pad: pixel padding}
     // on the low and high sides

src/plots/plots.js

@@ -656,6 +656,25 @@ plots.linkSubplots = function(newFullData, newFullLayout, oldFullData, oldFullLa
 
         plotinfo.xaxis = Plotly.Axes.getFromId(mockGd, id, 'x');
         plotinfo.yaxis = Plotly.Axes.getFromId(mockGd, id, 'y');
+
+        // By default, we clip at the subplot level,
+        // but if one trace on a given subplot has *cliponaxis* set to false,
+        // we need to clip at the trace module layer level;
+        // find this out here, once of for all.
+        plotinfo._hasClipOnAxisFalse = false;
+
+        for(var j = 0; j < newFullData.length; j++) {
+            var trace = newFullData[j];
+
+            if(
+                trace.xaxis === plotinfo.xaxis._id &&
+                trace.yaxis === plotinfo.yaxis._id &&
+                trace.cliponaxis === false
+            ) {
+                plotinfo._hasClipOnAxisFalse = true;
+                break;
+            }
+        }
     }
 };
 

src/traces/scatter/attributes.js

@@ -168,6 +168,7 @@ module.exports = {
             ].join(' ')
         }
     },
+
     connectgaps: {
         valType: 'boolean',
         dflt: false,
@@ -178,6 +179,17 @@ module.exports = {
             'in the provided data arrays are connected.'
         ].join(' ')
     },
+    cliponaxis: {
+        valType: 'boolean',
+        dflt: true,
+        role: 'info',
+        editType: 'doplot',
+        description: [
+            'Determines whether or not markers and text nodes',
+            'are clipped about the subplot axes.'
+        ].join(' ')
+    },
+
     fill: {
         valType: 'enumerated',
         values: ['none', 'tozeroy', 'tozerox', 'tonexty', 'tonextx', 'toself', 'tonext'],

src/traces/scatter/defaults.js

@@ -75,4 +75,6 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
 
     errorBarsSupplyDefaults(traceIn, traceOut, defaultColor, {axis: 'y'});
     errorBarsSupplyDefaults(traceIn, traceOut, defaultColor, {axis: 'x', inherit: 'y'});
+
+    coerce('cliponaxis');
 };

src/traces/scatter/plot.js

@@ -46,7 +46,7 @@ module.exports = function plot(gd, plotinfo, cdscatter, transitionOpts, makeOnCo
     // the z-order of fill layers is correct.
     linkTraces(gd, plotinfo, cdscatter);
 
-    createFills(gd, scatterlayer);
+    createFills(gd, scatterlayer, plotinfo);
 
     // Sort the traces, once created, so that the ordering is preserved even when traces
     // are shown and hidden. This is needed since we're not just wiping everything out
@@ -100,7 +100,7 @@ module.exports = function plot(gd, plotinfo, cdscatter, transitionOpts, makeOnCo
     scatterlayer.selectAll('path:not([d])').remove();
 };
 
-function createFills(gd, scatterlayer) {
+function createFills(gd, scatterlayer, plotinfo) {
     var trace;
 
     scatterlayer.selectAll('g.trace').each(function(d) {
@@ -138,6 +138,10 @@ function createFills(gd, scatterlayer) {
             tr.selectAll('.js-fill.js-tozero').remove();
             trace._ownFill = null;
         }
+
+        if(plotinfo._hasClipOnAxisFalse) {
+            tr.selectAll('.js-fill').call(Drawing.setClipUrl, plotinfo.clipId);
+        }
     });
 }
 
@@ -324,6 +328,10 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
         .call(Drawing.lineGroupStyle)
         .each(makeUpdate(true));
 
+    if(plotinfo._hasClipOnAxisFalse) {
+        Drawing.setClipUrl(lineJoin, plotinfo.clipId);
+    }
+
     if(segments.length) {
         if(ownFillEl3) {
             if(pt0 && pt1) {
@@ -400,7 +408,8 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
         var trace = d[0].trace,
             s = d3.select(this),
             showMarkers = subTypes.hasMarkers(trace),
-            showText = subTypes.hasText(trace);
+            showText = subTypes.hasText(trace),
+            hasClipOnAxisFalse = trace.cliponaxis === false;
 
         var keyFunc = getKeyFunc(trace),
             markerFilter = hideFilter,
@@ -426,7 +435,7 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
         if(hasTransition) {
             enter
                 .call(Drawing.pointStyle, trace, gd)
-                .call(Drawing.translatePoints, xa, ya, trace)
+                .call(Drawing.translatePoints, xa, ya)
                 .style('opacity', 0)
                 .transition()
                 .style('opacity', 1);
@@ -445,6 +454,10 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
             if(hasNode) {
                 Drawing.singlePointStyle(d, sel, trace, markerScale, lineScale, gd);
 
+                if(hasClipOnAxisFalse) {
+                    Drawing.hideOutsideRangePoint(d, sel, xa, ya);
+                }
+
                 if(trace.customdata) {
                     el.classed('plotly-customdata', d.data !== null && d.data !== undefined);
                 }
@@ -475,7 +488,14 @@ function plotOne(gd, idx, plotinfo, cdscatter, cdscatterAll, element, transition
             var g = d3.select(this);
             var sel = transition(g.select('text'));
             hasNode = Drawing.translatePoint(d, sel, xa, ya);
-            if(!hasNode) g.remove();
+
+            if(hasNode) {
+                if(hasClipOnAxisFalse) {
+                    Drawing.hideOutsideRangePoint(d, g, xa, ya);
+                }
+            } else {
+                g.remove();
+            }
         });
 
         join.selectAll('text')