Feature: Plot layout images

src/components/images/attributes.js

@@ -0,0 +1,158 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+var cartesianConstants = require('../../plots/cartesian/constants');
+
+
+module.exports = {
+    _isLinkedToArray: true,
+
+    source: {
+        valType: 'string',
+        role: 'info',
+        description: [
+            'Specifies the URL of the image to be used.',
+            'The URL must be accessible from the domain where the',
+            'plot code is run, and can be either relative or absolute.'
+
+        ].join(' ')
+    },
+
+    layer: {
+        valType: 'enumerated',
+        values: ['below', 'above'],
+        dflt: 'above',
+        role: 'info',
+        description: [
+            'Specifies whether images are drawn below or above traces.',
+            'When `xref` and `yref` are both set to `paper`,',
+            'image is drawn below the entire plot area.'
+        ].join(' ')
+    },
+
+    width: {
+        valType: 'number',
+        role: 'info',
+        dflt: 0,
+        description: [
+            'Sets the image container width.',
+            'The image will be sized based on the `position` value.',
+            'When `xref` is set to `paper`, units are sized relative',
+            'to the plot width.'
+        ].join(' ')
+    },
+
+    height: {
+        valType: 'number',
+        role: 'info',
+        dflt: 0,
+        description: [
+            'Sets the image container height.',
+            'The image will be sized based on the `position` value.',
+            'When `yref` is set to `paper`, units are sized relative',
+            'to the plot height.'
+        ].join(' ')
+    },
+
+    sizing: {
+        valType: 'enumerated',
+        values: ['fill', 'contain', 'stretch'],
+        dflt: 'contain',
+        role: 'info',
+        description: [
+            'Specifies which dimension of the image to constrain.'
+        ].join(' ')
+    },
+
+    opacity: {
+        valType: 'number',
+        role: 'info',
+        min: 0,
+        max: 1,
+        dflt: 1,
+        description: 'Sets the opacity of the image.'
+    },
+
+    x: {
+        valType: 'number',
+        role: 'info',
+        dflt: 0,
+        description: [
+            'Sets the image\'s x position.',
+            'When `xref` is set to `paper`, units are sized relative',
+            'to the plot height.',
+            'See `xref` for more info'
+        ].join(' ')
+    },
+
+    y: {
+        valType: 'number',
+        role: 'info',
+        dflt: 0,
+        description: [
+            'Sets the image\'s y position.',
+            'When `yref` is set to `paper`, units are sized relative',
+            'to the plot height.',
+            'See `yref` for more info'
+        ].join(' ')
+    },
+
+    xanchor: {
+        valType: 'enumerated',
+        values: ['left', 'center', 'right'],
+        dflt: 'left',
+        role: 'info',
+        description: 'Sets the anchor for the x position'
+    },
+
+    yanchor: {
+        valType: 'enumerated',
+        values: ['top', 'middle', 'bottom'],
+        dflt: 'top',
+        role: 'info',
+        description: 'Sets the anchor for the y position.'
+    },
+
+    xref: {
+        valType: 'enumerated',
+        values: [
+            'paper',
+            cartesianConstants.idRegex.x.toString()
+        ],
+        dflt: 'paper',
+        role: 'info',
+        description: [
+            'Sets the images\'s x coordinate axis.',
+            'If set to a x axis id (e.g. *x* or *x2*), the `x` position',
+            'refers to an x data coordinate',
+            'If set to *paper*, the `x` position refers to the distance from',
+            'the left of plot in normalized coordinates',
+            'where *0* (*1*) corresponds to the left (right).'
+        ].join(' ')
+    },
+
+    yref: {
+        valType: 'enumerated',
+        values: [
+            'paper',
+            cartesianConstants.idRegex.y.toString()
+        ],
+        dflt: 'paper',
+        role: 'info',
+        description: [
+            'Sets the images\'s y coordinate axis.',
+            'If set to a y axis id (e.g. *y* or *y2*), the `y` position',
+            'refers to a y data coordinate.',
+            'If set to *paper*, the `y` position refers to the distance from',
+            'the bottom of the plot in normalized coordinates',
+            'where *0* (*1*) corresponds to the bottom (top).'
+        ].join(' ')
+    }
+};

src/components/images/defaults.js

@@ -0,0 +1,65 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+var Axes = require('../../plots/cartesian/axes');
+var Lib = require('../../lib');
+var attributes = require('./attributes');
+
+
+module.exports = function supplyLayoutDefaults(layoutIn, layoutOut) {
+
+    if(!layoutIn.images) return;
+
+
+    var containerIn = Array.isArray(layoutIn.images) ?
+            layoutIn.images : [layoutIn.images],
+        containerOut = layoutOut.images = [];
+
+
+    for(var i = 0; i < containerIn.length; i++) {
+        var image = containerIn[i];
+
+        if(!image.source) continue;
+
+        var defaulted = imageDefaults(containerIn[i] || {}, containerOut[i] || {}, layoutOut);
+        containerOut.push(defaulted);
+    }
+};
+
+
+function imageDefaults(imageIn, imageOut, fullLayout) {
+
+    imageOut = imageOut || {};
+
+    function coerce(attr, dflt) {
+        return Lib.coerce(imageIn, imageOut, attributes, attr, dflt);
+    }
+
+    coerce('source');
+    coerce('layer');
+    coerce('x');
+    coerce('y');
+    coerce('xanchor');
+    coerce('yanchor');
+    coerce('width');
+    coerce('height');
+    coerce('sizing');
+    coerce('opacity');
+
+    for(var i = 0; i < 2; i++) {
+        var tdMock = { _fullLayout: fullLayout },
+            axLetter = ['x', 'y'][i];
+
+        // 'paper' is the fallback axref
+        Axes.coerceRef(imageIn, imageOut, tdMock, axLetter, 'paper');
+    }
+
+    return imageOut;
+}

src/components/images/draw.js

@@ -0,0 +1,125 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+var d3 = require('d3');
+var Drawing = require('../drawing');
+var Axes = require('../../plots/cartesian/axes');
+
+module.exports = function draw(gd) {
+
+    var fullLayout = gd._fullLayout,
+        imageDataAbove = [],
+        imageDataSubplot = [],
+        imageDataBelow = [];
+
+    if(!fullLayout.images) return;
+
+
+    // Sort into top, subplot, and bottom layers
+    for(var i = 0; i < fullLayout.images.length; i++) {
+        var img = fullLayout.images[i];
+
+        if(img.layer === 'below' && img.xref !== 'paper' && img.yref !== 'paper') {
+            imageDataSubplot.push(img);
+        } else if(img.layer === 'above') {
+            imageDataAbove.push(img);
+        } else {
+            imageDataBelow.push(img);
+        }
+    }
+
+
+    var anchors = {
+        x: {
+            left: { sizing: 'xMin', offset: 0 },
+            center: { sizing: 'xMid', offset: -1 / 2 },
+            right: { sizing: 'xMax', offset: -1 }
+        },
+        y: {
+            top: { sizing: 'YMin', offset: 0 },
+            middle: { sizing: 'YMid', offset: -1 / 2 },
+            bottom: { sizing: 'YMax', offset: -1 }
+        }
+    };
+
+
+    function applyAttributes(d) {
+
+        var thisImage = d3.select(this);
+
+        // Axes if specified
+        var xref = Axes.getFromId(gd, d.xref),
+            yref = Axes.getFromId(gd, d.yref);
+
+        var size = fullLayout._size,
+            width = xref ? Math.abs(xref.l2p(d.width) - xref.l2p(0)) : d.width * size.w,
+            height = yref ? Math.abs(yref.l2p(d.height) - yref.l2p(0)) : d.width * size.h;
+
+        // Offsets for anchor positioning
+        var xOffset = width * anchors.x[d.xanchor].offset + size.l,
+            yOffset = height * anchors.y[d.yanchor].offset + size.t;
+
+        var sizing = anchors.x[d.xanchor].sizing + anchors.y[d.yanchor].sizing;
+
+        // Final positions
+        var xPos = (xref ? xref.l2p(d.x) : d.x * width) + xOffset,
+            yPos = (yref ? yref.l2p(d.y) : -d.y * width) + yOffset;
+
+
+        // Construct the proper aspectRatio attribute
+        switch(d.sizing) {
+            case 'fill':
+                sizing += ' slice';
+                break;
+
+            case 'stretch':
+                sizing = 'none';
+                break;
+        }
+
+        thisImage.attr({
+            href: d.source,
+            x: xPos,
+            y: yPos,
+            width: width,
+            height: height,
+            preserveAspectRatio: sizing,
+            opacity: d.opacity
+        });
+
+
+        // Set proper clipping on images
+        var xId = xref ? xref._id : '',
+            yId = yref ? yref._id : '',
+            clipAxes = xId + yId;
+
+        thisImage.call(Drawing.setClipUrl, 'clip' + fullLayout._uid + clipAxes);
+    }
+
+
+    var imagesBelow = fullLayout._imageLowerLayer.selectAll('image')
+            .data(imageDataBelow),
+        imagesSubplot = fullLayout._imageSubplotLayer.selectAll('image')
+            .data(imageDataSubplot),
+        imagesAbove = fullLayout._imageUpperLayer.selectAll('image')
+            .data(imageDataAbove);
+
+    imagesBelow.enter().append('image');
+    imagesSubplot.enter().append('image');
+    imagesAbove.enter().append('image');
+
+    imagesBelow.exit().remove();
+    imagesSubplot.exit().remove();
+    imagesAbove.exit().remove();
+
+    imagesBelow.each(applyAttributes);
+    imagesSubplot.each(applyAttributes);
+    imagesAbove.each(applyAttributes);
+};

src/components/images/index.js

@@ -0,0 +1,19 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+
+var draw = require('./draw');
+var supplyLayoutDefaults = require('./defaults');
+
+
+module.exports = {
+    draw: draw,
+    supplyLayoutDefaults: supplyLayoutDefaults
+};

src/components/rangeslider/defaults.js

@@ -21,8 +21,7 @@ module.exports = function supplyLayoutDefaults(layoutIn, layoutOut, axName, coun
         containerOut = layoutOut[axName].rangeslider = {};
 
     function coerce(attr, dflt) {
-        return Lib.coerce(containerIn, containerOut,
-            attributes, attr, dflt);
+        return Lib.coerce(containerIn, containerOut, attributes, attr, dflt);
     }
 
     coerce('bgcolor');

src/components/shapes/index.js

@@ -98,7 +98,7 @@ shapes.drawAll = function(gd) {
     // Remove previous shapes before drawing new in shapes in fullLayout.shapes
     fullLayout._shapeUpperLayer.selectAll('path').remove();
     fullLayout._shapeLowerLayer.selectAll('path').remove();
-    fullLayout._subplotShapeLayer.selectAll('path').remove();
+    fullLayout._shapeSubplotLayer.selectAll('path').remove();
 
     for(var i = 0; i < fullLayout.shapes.length; i++) {
         shapes.draw(gd, i);
@@ -356,7 +356,7 @@ function getShapeLayer(gd, index) {
     else if(shape.layer === 'below') {
         shapeLayer = (shape.xref === 'paper' && shape.yref === 'paper') ?
             gd._fullLayout._shapeLowerLayer :
-            gd._fullLayout._subplotShapeLayer;
+            gd._fullLayout._shapeSubplotLayer;
     }
 
     return shapeLayer;