Add options to display text over heatmaps & histogram2d

draftlogs/6028_add.md

@@ -0,0 +1,2 @@
+ - Add `texttemplate` and `textfont` to `heatmap` and `histogram2d` traces as well as
+   `histogram2dcontour` and `contour` traces when `coloring` is set "heatmap" [[#6028](https://github.com/plotly/plotly.js/pull/6028)]

src/traces/contour/attributes.js

@@ -42,6 +42,8 @@ module.exports = extendFlat({
     yhoverformat: axisHoverFormat('y'),
     zhoverformat: axisHoverFormat('z', 1),
     hovertemplate: heatmapAttrs.hovertemplate,
+    texttemplate: heatmapAttrs.texttemplate,
+    textfont: heatmapAttrs.textfont,
     hoverongaps: heatmapAttrs.hoverongaps,
     connectgaps: extendFlat({}, heatmapAttrs.connectgaps, {
         description: [

src/traces/contour/defaults.js

@@ -31,8 +31,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
 
     coerce('text');
     coerce('hovertext');
-    coerce('hovertemplate');
     coerce('hoverongaps');
+    coerce('hovertemplate');
 
     var isConstraint = (coerce('contours.type') === 'constraint');
     coerce('connectgaps', Lib.isArray1D(traceOut.z));
@@ -43,4 +43,15 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         handleContoursDefaults(traceIn, traceOut, coerce, coerce2);
         handleStyleDefaults(traceIn, traceOut, coerce, layout);
     }
+
+    if(
+        traceOut.contours &&
+        traceOut.contours.coloring === 'heatmap'
+    ) {
+        coerce('texttemplate');
+
+        var fontDflt = Lib.extendFlat({}, layout.font);
+        fontDflt.color = undefined; // color contrast by default
+        Lib.coerceFont(coerce, 'textfont', fontDflt);
+    }
 };

src/traces/heatmap/attributes.js

@@ -2,8 +2,10 @@
 
 var scatterAttrs = require('../scatter/attributes');
 var baseAttrs = require('../../plots/attributes');
+var fontAttrs = require('../../plots/font_attributes');
 var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
+var texttemplateAttrs = require('../../plots/template_attributes').texttemplateAttrs;
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 
 var extendFlat = require('../../lib/extend').extendFlat;
@@ -116,6 +118,15 @@ module.exports = extendFlat({
     zhoverformat: axisHoverFormat('z', 1),
 
     hovertemplate: hovertemplateAttrs(),
+    texttemplate: texttemplateAttrs({editType: 'plot'}, {
+        keys: ['x', 'y', 'z', 'text']
+    }),
+    textfont: fontAttrs({
+        editType: 'plot',
+        colorEditType: 'style',
+        description: 'Sets the text font.'
+    }),
+
     showlegend: extendFlat({}, baseAttrs.showlegend, {dflt: false})
 }, {
     transforms: undefined

src/traces/heatmap/defaults.js

@@ -27,6 +27,11 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     coerce('text');
     coerce('hovertext');
     coerce('hovertemplate');
+    coerce('texttemplate');
+
+    var fontDflt = Lib.extendFlat({}, layout.font);
+    fontDflt.color = undefined; // color contrast by default
+    Lib.coerceFont(coerce, 'textfont', fontDflt);
 
     handleStyleDefaults(traceIn, traceOut, coerce, layout);
 

src/traces/heatmap/plot.js

@@ -4,9 +4,27 @@ var d3 = require('@plotly/d3');
 var tinycolor = require('tinycolor2');
 
 var Registry = require('../../registry');
+var Drawing = require('../../components/drawing');
+var Axes = require('../../plots/cartesian/axes');
 var Lib = require('../../lib');
+var svgTextUtils = require('../../lib/svg_text_utils');
+var formatLabels = require('../scatter/format_labels');
+var Color = require('../../components/color');
+var extractOpts = require('../../components/colorscale').extractOpts;
 var makeColorScaleFuncFromTrace = require('../../components/colorscale').makeColorScaleFuncFromTrace;
 var xmlnsNamespaces = require('../../constants/xmlns_namespaces');
+var alignmentConstants = require('../../constants/alignment');
+var LINE_SPACING = alignmentConstants.LINE_SPACING;
+
+var labelClass = 'label';
+
+function selectLabels(plotGroup) {
+    return plotGroup.selectAll('g.' + labelClass);
+}
+
+function removeLabels(plotGroup) {
+    selectLabels(plotGroup).remove();
+}
 
 module.exports = function(gd, plotinfo, cdheatmaps, heatmapLayer) {
     var xa = plotinfo.xaxis;
@@ -31,7 +49,7 @@ module.exports = function(gd, plotinfo, cdheatmaps, heatmapLayer) {
         var xrev = false;
         var yrev = false;
 
-        var left, right, temp, top, bottom, i;
+        var left, right, temp, top, bottom, i, j;
 
         // TODO: if there are multiple overlapping categorical heatmaps,
         // or if we allow category sorting, then the categories may not be
@@ -112,6 +130,8 @@ module.exports = function(gd, plotinfo, cdheatmaps, heatmapLayer) {
         if(isOffScreen) {
             var noImage = plotGroup.selectAll('image').data([]);
             noImage.exit().remove();
+
+            removeLabels(plotGroup);
             return;
         }
 
@@ -167,7 +187,7 @@ module.exports = function(gd, plotinfo, cdheatmaps, heatmapLayer) {
         var gcount = 0;
         var bcount = 0;
 
-        var xb, j, xi, v, row, c;
+        var xb, xi, v, row, c;
 
         function setColor(v, pixsize) {
             if(v !== undefined) {
@@ -332,6 +352,130 @@ module.exports = function(gd, plotinfo, cdheatmaps, heatmapLayer) {
             y: top,
             'xlink:href': canvas.toDataURL('image/png')
         });
+
+        removeLabels(plotGroup);
+
+        var texttemplate = trace.texttemplate;
+        if(texttemplate) {
+            // dummy axis for formatting the z value
+            var cOpts = extractOpts(trace);
+            var dummyAx = {
+                type: 'linear',
+                range: [cOpts.min, cOpts.max],
+                _separators: xa._separators,
+                _numFormat: xa._numFormat
+            };
+
+            var aHistogram2dContour = trace.type === 'histogram2dcontour';
+            var aContour = trace.type === 'contour';
+            var iStart = aContour ? 1 : 0;
+            var iStop = aContour ? m - 1 : m;
+            var jStart = aContour ? 1 : 0;
+            var jStop = aContour ? n - 1 : n;
+
+            var textData = [];
+            for(i = iStart; i < iStop; i++) {
+                var yVal;
+                if(aContour) {
+                    yVal = cd0.y[i];
+                } else if(aHistogram2dContour) {
+                    if(i === 0 || i === m - 1) continue;
+                    yVal = cd0.y[i];
+                } else if(cd0.yCenter) {
+                    yVal = cd0.yCenter[i];
+                } else {
+                    if(i + 1 === m && cd0.y[i + 1] === undefined) continue;
+                    yVal = (cd0.y[i] + cd0.y[i + 1]) / 2;
+                }
+
+                var _y = Math.round(ya.c2p(yVal));
+                if(0 > _y || _y > ya._length) continue;
+
+                for(j = jStart; j < jStop; j++) {
+                    var xVal;
+                    if(aContour) {
+                        xVal = cd0.x[j];
+                    } else if(aHistogram2dContour) {
+                        if(j === 0 || j === n - 1) continue;
+                        xVal = cd0.x[j];
+                    } else if(cd0.xCenter) {
+                        xVal = cd0.xCenter[j];
+                    } else {
+                        if(j + 1 === n && cd0.x[j + 1] === undefined) continue;
+                        xVal = (cd0.x[j] + cd0.x[j + 1]) / 2;
+                    }
+
+                    var _x = Math.round(xa.c2p(xVal));
+                    if(0 > _x || _x > xa._length) continue;
+
+                    var obj = formatLabels({
+                        x: xVal,
+                        y: yVal
+                    }, trace, gd._fullLayout);
+
+                    obj.x = xVal;
+                    obj.y = yVal;
+
+                    var zVal = cd0.z[i][j];
+                    if(zVal === undefined) {
+                        obj.z = '';
+                        obj.zLabel = '';
+                    } else {
+                        obj.z = zVal;
+                        obj.zLabel = Axes.tickText(dummyAx, zVal, 'hover').text;
+                    }
+
+                    var theText = cd0.text && cd0.text[i] && cd0.text[i][j];
+                    if(theText === undefined || theText === false) theText = '';
+                    obj.text = theText;
+
+                    var _t = Lib.texttemplateString(texttemplate, obj, gd._fullLayout._d3locale, obj, trace._meta || {});
+                    if(!_t) continue;
+
+                    textData.push({
+                        t: _t,
+                        x: _x,
+                        y: _y,
+                        z: zVal
+                    });
+                }
+            }
+
+            var font = trace.textfont;
+            var xFn = function(d) { return d.x; };
+            var yFn = function(d) {
+                var nlines = d.t.split('<br>').length;
+                return d.y - font.size * ((nlines * LINE_SPACING) / 2 - 1);
+            };
+
+            var labels = selectLabels(plotGroup).data(textData);
+
+            labels
+                .enter()
+                .append('g')
+                .classed(labelClass, 1)
+                .append('text')
+                .attr('text-anchor', 'middle')
+                .each(function(d) {
+                    var thisLabel = d3.select(this);
+
+                    var fontColor = font.color;
+                    if(!fontColor) {
+                        fontColor = Color.contrast(
+                            'rgba(' +
+                                sclFunc(d.z).join() +
+                            ')'
+                        );
+                    }
+
+                    thisLabel
+                        .attr('data-notex', 1)
+                        .call(svgTextUtils.positionText, xFn(d), yFn(d))
+                        .call(Drawing.font, font.family, font.size, fontColor)
+                        .text(d.t)
+                        .call(svgTextUtils.convertToTspans, gd);
+                });
+        }
     });
 };
 

src/traces/histogram2d/attributes.js

@@ -6,6 +6,7 @@ var heatmapAttrs = require('../heatmap/attributes');
 var baseAttrs = require('../../plots/attributes');
 var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var hovertemplateAttrs = require('../../plots/template_attributes').hovertemplateAttrs;
+var texttemplateAttrs = require('../../plots/template_attributes').texttemplateAttrs;
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 
 var extendFlat = require('../../lib/extend').extendFlat;
@@ -69,6 +70,8 @@ module.exports = extendFlat(
         yhoverformat: axisHoverFormat('y'),
         zhoverformat: axisHoverFormat('z', 1),
         hovertemplate: hovertemplateAttrs({}, {keys: 'z'}),
+        texttemplate: texttemplateAttrs({editType: 'plot'}, {keys: 'z'}),
+        textfont: heatmapAttrs.textfont,
         showlegend: extendFlat({}, baseAttrs.showlegend, {dflt: false})
     },
     colorScaleAttrs('', {cLetter: 'z', autoColorDflt: false})

src/traces/histogram2d/defaults.js

@@ -19,6 +19,12 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     handleStyleDefaults(traceIn, traceOut, coerce, layout);
     colorscaleDefaults(traceIn, traceOut, layout, coerce, {prefix: '', cLetter: 'z'});
     coerce('hovertemplate');
+    coerce('texttemplate');
+
+    var fontDflt = Lib.extendFlat({}, layout.font);
+    fontDflt.color = undefined; // color contrast by default
+    Lib.coerceFont(coerce, 'textfont', fontDflt);
+
     coerce('xhoverformat');
     coerce('yhoverformat');
 };

src/traces/histogram2dcontour/attributes.js

@@ -42,7 +42,9 @@ module.exports = extendFlat({
     xhoverformat: axisHoverFormat('x'),
     yhoverformat: axisHoverFormat('y'),
     zhoverformat: axisHoverFormat('z', 1),
-    hovertemplate: histogram2dAttrs.hovertemplate
+    hovertemplate: histogram2dAttrs.hovertemplate,
+    texttemplate: histogram2dAttrs.texttemplate,
+    textfont: histogram2dAttrs.textfont
 },
     colorScaleAttrs('', {
         cLetter: 'z',

src/traces/histogram2dcontour/defaults.js

@@ -22,7 +22,17 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
 
     handleContoursDefaults(traceIn, traceOut, coerce, coerce2);
     handleStyleDefaults(traceIn, traceOut, coerce, layout);
-    coerce('hovertemplate');
     coerce('xhoverformat');
     coerce('yhoverformat');
+    coerce('hovertemplate');
+    if(
+        traceOut.contours &&
+        traceOut.contours.coloring === 'heatmap'
+    ) {
+        coerce('texttemplate');
+
+        var fontDflt = Lib.extendFlat({}, layout.font);
+        fontDflt.color = undefined; // color contrast by default
+        Lib.coerceFont(coerce, 'textfont', fontDflt);
+    }
 };

test/image/mocks/13.json

@@ -1,6 +1,8 @@
 {
     "data": [
         {
+            "texttemplate": "%{z:.1f}",
+            "textfont": {"size": 8},
             "z": [
                 [
                     1,

test/image/mocks/4.json

@@ -1,6 +1,7 @@
 {
     "data": [
         {
+            "texttemplate": "%{z}",
             "z": [
                 [
                     1,

test/image/mocks/contour_heatmap_coloring_reversescale.json

@@ -11,6 +11,7 @@
       "x": [ -9, -6, -5, -3, -1 ],
       "y": [ 0, 1, 4, 5, 7 ],
       "type": "contour",
+      "texttemplate": "%{z}",
       "contours": {
         "coloring": "heatmap"
       },
@@ -33,6 +34,7 @@
       "x": [ -9, -6, -5, -3, -1 ],
       "y": [ 0, 1, 4, 5, 7 ],
       "type": "contour",
+      "texttemplate": "%{z}",
       "contours": {
         "coloring": "heatmap"
       },

test/image/mocks/contour_legend-colorscale.json

@@ -58,6 +58,13 @@
         }
     ],
     "layout": {
+        "template": {
+            "data": {
+                "contour": [{
+                    "texttemplate": "%{z:.2s}"
+                }]
+            }
+        },
         "title": {"text": "<b>contour legends with heatmap coloring</b><br>red-blue should be equal to reversed blue-red.<br>i.e. display identical legends for identical graphs"},
         "margin": {
             "t": 125,

test/image/mocks/heatmap_categoryorder.json

@@ -13,6 +13,10 @@
   },
   "data": [{
     "type": "heatmap",
+    "texttemplate": "x: %{x}<br>y: %{y}<br>z: %{z}",
+    "textfont": {
+      "size": 14
+    },
 
     "x": ["z", "y", "x", "w"],
     "y": ["d", "c", "b", "a"],

test/image/mocks/heatmap_columnar.json

@@ -3,7 +3,13 @@
     "type": "heatmap",
     "x": ["a", "a", "a", "b", "b", "b", "c", "c", "c"],
     "y": ["A", "B", "C", "A", "B", "C", "A", "B", "C"],
-    "z": [0, 50, 100, 50, 0, 255, 100, 510, 1010]
+    "z": [0, 50, 100, 50, 0, 255, 100, 510, 1010],
+    "text": ["zero", "fifty", "one hundred", "fifty", "zero", "two hundred<br>and fifty-five", "one hundred", "five hundred<br>and ten", "one thousand ten"],
+    "texttemplate": "%{text}",
+    "textfont": {
+      "size": 20,
+      "color": "rgba(255,255,255,0.5)"
+    }
   }],
   "layout": {
       "xaxis": {