Merge pull request #347 from plotly/fix-surface-intensity

Add `surfacecolor` functionality to surface traces

Author: etpinard

devtools/test_dashboard/test_gl3d.js

@@ -35,6 +35,7 @@ plots['marker-arrays'] = require('@mocks/gl3d_marker-arrays.json');
 plots['scatter3d-colorscale'] = require('@mocks/gl3d_scatter3d-colorscale.json');
 plots['autocolorscale'] = require('@mocks/gl3d_autocolorscale.json');
 plots['nan-holes'] = require('@mocks/gl3d_nan-holes.json');
-plots['tetrahedra'] = require('@mocks/gl3d_tet.json');
+plots['tet'] = require('@mocks/gl3d_tet.json');
+plots['surface_intensity'] = require('@mocks/gl3d_surface_intensity.json');
 
 plotButtons(plots, figDir);

package.json

@@ -64,7 +64,7 @@
     "gl-scatter3d": "^1.0.4",
     "gl-select-box": "^1.0.1",
     "gl-spikes2d": "^1.0.1",
-    "gl-surface3d": "^1.1.1",
+    "gl-surface3d": "^1.2.3",
     "mouse-change": "^1.1.1",
     "mouse-wheel": "^1.0.2",
     "ndarray": "^1.0.16",

src/traces/choropleth/calc.js

@@ -0,0 +1,17 @@
+/**
+* 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 colorscaleCalc = require('../../components/colorscale/calc');
+
+
+module.exports = function calc(gd, trace) {
+    colorscaleCalc(trace, trace.z, '', 'z');
+};

src/traces/choropleth/index.js

@@ -14,7 +14,7 @@ var Choropleth = {};
 Choropleth.attributes = require('./attributes');
 Choropleth.supplyDefaults = require('./defaults');
 Choropleth.colorbar = require('../heatmap/colorbar');
-Choropleth.calc = require('../surface/calc');
+Choropleth.calc = require('./calc');
 Choropleth.plot = require('./plot').plot;
 
 Choropleth.moduleType = 'trace';

src/traces/surface/attributes.js

@@ -95,9 +95,16 @@ module.exports = {
         valType: 'data_array',
         description: 'Sets the text elements associated with each z value.'
     },
-    zauto: colorscaleAttrs.zauto,
-    zmin: colorscaleAttrs.zmin,
-    zmax: colorscaleAttrs.zmax,
+    surfacecolor: {
+        valType: 'data_array',
+        description: [
+            'Sets the surface color values,',
+            'used for setting a color scale independent of `z`.'
+        ].join(' ')
+    },
+    cauto: colorscaleAttrs.zauto,
+    cmin: colorscaleAttrs.zmin,
+    cmax: colorscaleAttrs.zmax,
     colorscale: colorscaleAttrs.colorscale,
     autocolorscale: extendFlat({}, colorscaleAttrs.autocolorscale,
         {dflt: false}),
@@ -161,5 +168,17 @@ module.exports = {
 
     _nestedModules: {  // nested module coupling
         'colorbar': 'Colorbar'
+    },
+
+    _deprecated: {
+        zauto: extendFlat({}, colorscaleAttrs.zauto, {
+            description: 'Obsolete. Use `cauto` instead.'
+        }),
+        zmin: extendFlat({}, colorscaleAttrs.zmin, {
+            description: 'Obsolete. Use `cmin` instead.'
+        }),
+        zmax: extendFlat({}, colorscaleAttrs.zmax, {
+            description: 'Obsolete. Use `cmax` instead.'
+        })
     }
 };

src/traces/surface/calc.js

@@ -14,5 +14,9 @@ var colorscaleCalc = require('../../components/colorscale/calc');
 
 // Compute auto-z and autocolorscale if applicable
 module.exports = function calc(gd, trace) {
-    colorscaleCalc(trace, trace.z, '', 'z');
+    if(trace.surfacecolor) {
+        colorscaleCalc(trace, trace.surfacecolor, '', 'c');
+    } else {
+        colorscaleCalc(trace, trace.z, '', 'c');
+    }
 };

src/traces/surface/colorbar.js

@@ -0,0 +1,47 @@
+/**
+* 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 isNumeric = require('fast-isnumeric');
+
+var Lib = require('../../lib');
+var Plots = require('../../plots/plots');
+var getColorscale = require('../../components/colorscale/get_scale');
+var drawColorbar = require('../../components/colorbar/draw');
+
+
+module.exports = function colorbar(gd, cd) {
+    var trace = cd[0].trace,
+        cbId = 'cb' + trace.uid,
+        scl = getColorscale(trace.colorscale),
+        zmin = trace.cmin,
+        zmax = trace.cmax,
+        vals = trace.surfacecolor || trace.z;
+
+    if(!isNumeric(zmin)) zmin = Lib.aggNums(Math.min, null, vals);
+    if(!isNumeric(zmax)) zmax = Lib.aggNums(Math.max, null, vals);
+
+    gd._fullLayout._infolayer.selectAll('.' + cbId).remove();
+
+    if(!trace.showscale) {
+        Plots.autoMargin(gd, cbId);
+        return;
+    }
+
+    var cb = cd[0].t.cb = drawColorbar(gd, cbId);
+    cb.fillcolor(d3.scale.linear()
+            .domain(scl.map(function(v) { return zmin + v[0]*(zmax-zmin); }))
+            .range(scl.map(function(v) { return v[1]; })))
+        .filllevels({start: zmin, end: zmax, size: (zmax-zmin)/254})
+        .options(trace.colorbar)();
+
+    Lib.markTime('done colorbar');
+};

src/traces/surface/convert.js

@@ -20,7 +20,6 @@ var str2RgbaArray = require('../../lib/str2rgbarray');
 
 var MIN_RESOLUTION = 128;
 
-
 function SurfaceTrace(scene, surface, uid) {
     this.scene = scene;
     this.uid = uid;
@@ -136,7 +135,7 @@ function refine(coords) {
             Math.floor((coords[0].shape[1]) * scaleF+1)|0 ];
         var nsize = nshape[0] * nshape[1];
 
-        for(var i = 0; i < 3; ++i) {
+        for(var i = 0; i < coords.length; ++i) {
             var padImg = padField(coords[i]);
             var scaledImg = ndarray(new Float32Array(nsize), nshape);
             homography(scaledImg, padImg, [scaleF, 0, 0,
@@ -230,9 +229,6 @@ proto.update = function(data) {
         });
     }
 
-    //Refine if necessary
-    this.dataScale = refine(coords);
-
     var params = {
         colormap: colormap,
         levels: [[], [], []],
@@ -249,10 +245,33 @@ proto.update = function(data) {
         dynamicColor: [[1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1]],
         dynamicWidth: [1, 1, 1],
         dynamicTint: [1, 1, 1],
-        opacity: 1,
-        colorBounds: [data.zmin * scaleFactor[2], data.zmax * scaleFactor[2]]
+        opacity: 1
     };
 
+    params.intensityBounds = [data.cmin, data.cmax];
+
+    //Refine if necessary
+    if(data.surfacecolor) {
+        var intensity = ndarray(new Float32Array(xlen * ylen), [xlen, ylen]);
+
+        fill(intensity, function(row, col) {
+            return data.surfacecolor[col][row];
+        });
+
+        coords.push(intensity);
+    }
+    else {
+        // when 'z' is used as 'intensity',
+        // we must scale its value
+        params.intensityBounds[0] *= scaleFactor[2];
+        params.intensityBounds[1] *= scaleFactor[2];
+    }
+
+    this.dataScale = refine(coords);
+
+    if(data.surfacecolor) {
+        params.intensity = coords.pop();
+    }
 
     if('opacity' in data) {
         if(data.opacity < 1) {
@@ -300,6 +319,7 @@ proto.update = function(data) {
     }
 
     params.coords = coords;
+
     surface.update(params);
 
     surface.highlightEnable = highlightEnable;

src/traces/surface/defaults.js

@@ -58,6 +58,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('hidesurface');
     coerce('opacity');
 
+    var surfaceColor = coerce('surfacecolor');
+
     coerce('colorscale');
 
     var dims = ['x', 'y', 'z'];
@@ -85,7 +87,20 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         }
     }
 
+    // backward compatibility block
+    if(!surfaceColor) {
+        mapLegacy(traceIn, 'zmin', 'cmin');
+        mapLegacy(traceIn, 'zmax', 'cmax');
+        mapLegacy(traceIn, 'zauto', 'cauto');
+    }
+
     colorscaleDefaults(
-        traceIn, traceOut, layout, coerce, {prefix: '', cLetter: 'z'}
+        traceIn, traceOut, layout, coerce, {prefix: '', cLetter: 'c'}
     );
 };
+
+function mapLegacy(traceIn, oldAttr, newAttr) {
+    if(oldAttr in traceIn && !(newAttr in traceIn)) {
+        traceIn[newAttr] = traceIn[oldAttr];
+    }
+}

src/traces/surface/index.js

@@ -13,7 +13,7 @@ var Surface = {};
 
 Surface.attributes = require('./attributes');
 Surface.supplyDefaults = require('./defaults');
-Surface.colorbar = require('../heatmap/colorbar');
+Surface.colorbar = require('./colorbar');
 Surface.calc = require('./calc');
 Surface.plot = require('./convert');
 
@@ -30,7 +30,11 @@ Surface.meta = {
         'or {2D arrays} (e.g. to graph parametric surfaces).',
 
         'If not provided in `x` and `y`, the x and y coordinates are assumed',
-        'to be linear starting at 0 with a unit step.'
+        'to be linear starting at 0 with a unit step.',
+
+        'The color scale corresponds to the `z` values by default.',
+        'For custom color scales, use `surfacecolor` which should be a {2D array},',
+        'where its bounds can be controlled using `cmin` and `cmax`.'
     ].join(' ')
 };