image trace type

lib/image.js

@@ -0,0 +1,11 @@
+/**
+* Copyright 2012-2019, 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';
+
+module.exports = require('../src/traces/image');

lib/index-cartesian.js

@@ -17,6 +17,7 @@ Plotly.register([
     require('./histogram'),
     require('./histogram2d'),
     require('./histogram2dcontour'),
+    require('./image'),
     require('./pie'),
     require('./contour'),
     require('./scatterternary'),

lib/index.js

@@ -56,6 +56,7 @@ Plotly.register([
 
     require('./sankey'),
     require('./indicator'),
+    require('./image'),
 
     require('./table'),
 

src/plots/cartesian/layout_defaults.js

@@ -87,6 +87,11 @@ module.exports = function supplyLayoutDefaults(layoutIn, layoutOut, fullData) {
             if(!traceIs(trace, 'carpet') || (trace.type === 'carpet' && !trace._cheater)) {
                 if(xaName) xaMustDisplay[xaName] = true;
             }
+
+            if(trace.type === 'image') {
+                if(yaName) yaMustForward[yaName] = false;
+                if(yaName) yaMayBackward[yaName] = true;
+            }
         }
 
         // Two things trigger axis visibility:

src/traces/image/attributes.js

@@ -0,0 +1,84 @@
+/**
+* Copyright 2012-2019, 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 plotAttrs = require('../../plots/attributes');
+var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
+var extendFlat = require('../../lib/extend').extendFlat;
+
+module.exports = extendFlat({
+    z: {
+        valType: 'data_array',
+        role: 'info',
+        editType: 'calc',
+        description: [
+            'A 2-dimensional array in which each element is an array of 3 or 4 numbers representing a color.',
+        ].join(' ')
+    },
+    colormodel: {
+        valType: 'enumerated',
+        values: ['rgb', 'rgba', 'hsl', 'hsla'],
+        dflt: 'rgb',
+        role: 'info',
+        editType: 'plot',
+        description: 'Color model used to map the numerical color components described in `z` into colors.'
+    },
+    zmin: {
+        valType: 'data_array',
+        role: 'info',
+        editType: 'plot',
+        description: [
+            'Array defining the lower bound for each color component.',
+            'For example, for the `rgba` colormodel, the default value is [0, 0, 0, 0].'
+        ].join(' ')
+    },
+    zmax: {
+        valType: 'data_array',
+        role: 'info',
+        editType: 'plot',
+        description: [
+            'Array defining the higher bound for each color component.',
+            'For example, for the `rgba` colormodel, the default value is [255, 255, 255, 1].'
+        ].join(' ')
+    },
+    x0: {
+        valType: 'number',
+        dflt: 0,
+        role: 'info',
+        editType: 'calc',
+        description: 'Set the image\'s x position.'
+    },
+    y0: {
+        valType: 'number',
+        dflt: 0,
+        role: 'info',
+        editType: 'calc',
+        description: 'Set the image\'s y position.'
+    },
+    dx: {
+        valType: 'number',
+        dflt: 1,
+        role: 'info',
+        editType: 'calc',
+        description: 'Set the pixel\'s horizontal size.'
+    },
+    dy: {
+        valType: 'number',
+        dflt: 1,
+        role: 'info',
+        editType: 'calc',
+        description: 'Set the pixel\'s vertical size'
+    },
+    hoverinfo: extendFlat({}, plotAttrs.hoverinfo, {
+        flags: ['x', 'y', 'z', 'color', 'name']
+    }),
+    hovertemplate: hovertemplateAttrs({}, {
+        keys: ['z', 'c', 'colormodel']
+    })
+});

src/traces/image/calc.js

@@ -0,0 +1,35 @@
+/**
+* Copyright 2012-2019, 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 Registry = require('../../registry');
+// var Lib = require('../../lib');
+var Axes = require('../../plots/cartesian/axes');
+
+module.exports = function calc(gd, trace) {
+    var xa = Axes.getFromId(gd, trace.xaxis || 'x');
+    var ya = Axes.getFromId(gd, trace.yaxis || 'y');
+
+    var x0 = trace.x0 - trace.dx / 2;
+    var y0 = trace.y0 - trace.dy / 2;
+    var h = trace.z.length;
+    var w = trace.z[0].length;
+
+    trace._extremes[xa._id] = Axes.findExtremes(xa, [x0, x0 + w * trace.dx]);
+    trace._extremes[ya._id] = Axes.findExtremes(ya, [y0, y0 + h * trace.dy]);
+
+    var cd0 = {
+        x0: x0,
+        y0: y0,
+        z: trace.z,
+        w: w,
+        h: h
+    };
+    return [cd0];
+};

src/traces/image/constants.js

@@ -0,0 +1,49 @@
+/**
+* Copyright 2012-2019, 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';
+
+module.exports = {
+    colormodel: {
+        rgb: {
+            min: [0, 0, 0],
+            max: [255, 255, 255],
+            fmt: function(c) {return c.slice(0, 3);},
+            suffix: ['', '', '']
+        },
+        rgba: {
+            min: [0, 0, 0, 0],
+            max: [255, 255, 255, 1],
+            fmt: function(c) {return c.slice(0, 4);},
+            suffix: ['', '', '', '']
+        },
+        hsl: {
+            min: [0, 0, 0],
+            max: [360, 100, 100],
+            fmt: function(c) {
+                var p = c.slice(0, 3);
+                p[1] = p[1] + '%';
+                p[2] = p[2] + '%';
+                return p;
+            },
+            suffix: ['°', '%', '%']
+        },
+        hsla: {
+            min: [0, 0, 0, 0],
+            max: [360, 100, 100, 1],
+            fmt: function(c) {
+                var p = c.slice(0, 4);
+                p[1] = p[1] + '%';
+                p[2] = p[2] + '%';
+                return p;
+            },
+            suffix: ['°', '%', '%', '']
+        }
+    }
+};

src/traces/image/defaults.js

@@ -0,0 +1,36 @@
+/**
+* Copyright 2012-2019, 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 Lib = require('../../lib');
+var attributes = require('./attributes');
+var constants = require('./constants');
+
+module.exports = function supplyDefaults(traceIn, traceOut) {
+    function coerce(attr, dflt) {
+        return Lib.coerce(traceIn, traceOut, attributes, attr, dflt);
+    }
+    var z = coerce('z');
+    if(z === undefined || !z.length) {
+        traceOut.visible = false;
+        return;
+    }
+
+    coerce('x0');
+    coerce('y0');
+    coerce('dx');
+    coerce('dy');
+    var colormodel = coerce('colormodel');
+
+    coerce('zmin', constants.colormodel[colormodel].min);
+    coerce('zmax', constants.colormodel[colormodel].max);
+
+    coerce('hovertemplate');
+};

src/traces/image/event_data.js

@@ -0,0 +1,19 @@
+/**
+* Copyright 2012-2019, 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';
+
+module.exports = function eventData(out, pt) {
+    out.colormodel = pt.trace.colormodel;
+    if('xVal' in pt) out.x = pt.xVal;
+    if('yVal' in pt) out.y = pt.yVal;
+    if(pt.xa) out.xaxis = pt.xa;
+    if(pt.ya) out.yaxis = pt.ya;
+    out.c = pt.c;
+    return out;
+};

src/traces/image/hover.js

@@ -0,0 +1,79 @@
+/**
+* Copyright 2012-2019, 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 Fx = require('../../components/fx');
+var Lib = require('../../lib');
+var constants = require('./constants');
+
+// var Axes = require('../../plots/cartesian/axes');
+
+module.exports = function hoverPoints(pointData, xval, yval) {
+    var cd0 = pointData.cd[0];
+    var trace = cd0.trace;
+    var xa = pointData.xa;
+    var ya = pointData.ya;
+
+    // Return early if not on image
+    if(Fx.inbox(xval - cd0.x0, xval - (cd0.x0 + cd0.w * trace.dx), 0) > 0 ||
+            Fx.inbox(yval - cd0.y0, yval - (cd0.y0 + cd0.h * trace.dy), 0) > 0) {
+        return;
+    }
+
+    // Find nearest pixel's index and pixel center
+    var nx = Math.floor((xval - cd0.x0) / trace.dx);
+    var ny = Math.floor(Math.abs(yval - cd0.y0) / trace.dy);
+
+    var hoverinfo = cd0.hi || trace.hoverinfo;
+    var fmtColor;
+    if(hoverinfo) {
+        var parts = hoverinfo.split('+');
+        if(parts.indexOf('all') !== -1) parts = ['color'];
+        if(parts.indexOf('color') !== -1) fmtColor = true;
+    }
+
+    var colormodel = trace.colormodel;
+    var dims = colormodel.length;
+    var c = trace._scaler(cd0.z[ny][nx]);
+    var s = constants.colormodel[colormodel].suffix;
+
+    var colorstring = [];
+    if(trace.hovertemplate || fmtColor) {
+        colorstring.push('[' + [c[0] + s[0], c[1] + s[1], c[2] + s[2]].join(', '));
+        if(dims === 4) colorstring.push(', ' + c[3] + s[3]);
+        colorstring.push(']');
+        colorstring = colorstring.join('');
+        pointData.extraText = '<span style="text-transform:uppercase">' + colormodel + '</span>: ' + colorstring;
+    }
+
+    var py = ya.c2p(cd0.y0 + (ny + 0.5) * trace.dy);
+    var xVal = cd0.x0 + (nx + 0.5) * trace.dx;
+    var yVal = cd0.y0 + (ny + 0.5) * trace.dy;
+    var zLabel = '[' + cd0.z[ny][nx].slice(0, trace.colormodel.length).join(', ') + ']';
+    return [Lib.extendFlat(pointData, {
+        index: [ny, nx],
+        x0: xa.c2p(cd0.x0 + nx * trace.dx),
+        x1: xa.c2p(cd0.x0 + (nx + 1) * trace.dx),
+        y0: py,
+        y1: py,
+        c: c,
+        xVal: xVal,
+        xLabelVal: xVal,
+        yVal: yVal,
+        yLabelVal: yVal,
+        zLabelVal: zLabel,
+        hovertemplateLabels: {
+            'zLabel': zLabel,
+            'cLabel': colorstring,
+            'c[0]Label': c[0] + s[0],
+            'c[1]Label': c[1] + s[1],
+            'c[2]Label': c[2] + s[2]
+        }
+    })];
+};

src/traces/image/index.js

@@ -0,0 +1,30 @@
+/**
+* Copyright 2012-2019, 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';
+
+module.exports = {
+    attributes: require('./attributes'),
+    supplyDefaults: require('./defaults'),
+    calc: require('./calc'),
+    plot: require('./plot').plot,
+    style: require('./style'),
+    hoverPoints: require('./hover'),
+    eventData: require('./event_data'),
+
+    moduleType: 'trace',
+    name: 'image',
+    basePlotModule: require('../../plots/cartesian'),
+    categories: ['cartesian', 'svg', '2dMap'],
+    animatable: false,
+    meta: {
+        description: [
+            'Display an image, i.e. data on a 2D regular raster.'
+        ].join(' ')
+    }
+};