Contour line labels

src/components/annotations/draw.js

@@ -487,15 +487,15 @@ function drawRaw(gd, options, index, subplotId, xa, ya) {
             // to get the parity of the number of intersections.
             if(edges.reduce(function(a, x) {
                 return a ^
-                    !!lineIntersect(headX, headY, headX + 1e6, headY + 1e6,
+                    !!Lib.segmentsIntersect(headX, headY, headX + 1e6, headY + 1e6,
                             x[0], x[1], x[2], x[3]);
             }, false)) {
                 // no line or arrow - so quit drawArrow now
                 return;
             }
 
             edges.forEach(function(x) {
-                var p = lineIntersect(tailX, tailY, headX, headY,
+                var p = Lib.segmentsIntersect(tailX, tailY, headX, headY,
                             x[0], x[1], x[2], x[3]);
                 if(p) {
                     tailX = p.x;
@@ -701,24 +701,3 @@ function drawRaw(gd, options, index, subplotId, xa, ya) {
     }
     else annText.call(textLayout);
 }
-
-// look for intersection of two line segments
-//   (1->2 and 3->4) - returns array [x,y] if they do, null if not
-function lineIntersect(x1, y1, x2, y2, x3, y3, x4, y4) {
-    var a = x2 - x1,
-        b = x3 - x1,
-        c = x4 - x3,
-        d = y2 - y1,
-        e = y3 - y1,
-        f = y4 - y3,
-        det = a * f - c * d;
-    // parallel lines? intersection is undefined
-    // ignore the case where they are colinear
-    if(det === 0) return null;
-    var t = (b * f - c * e) / det,
-        u = (b * d - a * e) / det;
-    // segments do not intersect?
-    if(u < 0 || u > 1 || t < 0 || t > 1) return null;
-
-    return {x: x1 + a * t, y: y1 + d * t};
-}

src/components/drawing/index.js

@@ -34,7 +34,7 @@ var drawing = module.exports = {};
 
 drawing.font = function(s, family, size, color) {
     // also allow the form font(s, {family, size, color})
-    if(family && family.family) {
+    if(Lib.isPlainObject(family)) {
         color = family.color;
         size = family.size;
         family = family.family;

src/lib/geometry2d.js

@@ -0,0 +1,176 @@
+/**
+* Copyright 2012-2017, 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 mod = require('./mod');
+
+/*
+ * look for intersection of two line segments
+ *   (1->2 and 3->4) - returns array [x,y] if they do, null if not
+ */
+exports.segmentsIntersect = segmentsIntersect;
+function segmentsIntersect(x1, y1, x2, y2, x3, y3, x4, y4) {
+    var a = x2 - x1,
+        b = x3 - x1,
+        c = x4 - x3,
+        d = y2 - y1,
+        e = y3 - y1,
+        f = y4 - y3,
+        det = a * f - c * d;
+    // parallel lines? intersection is undefined
+    // ignore the case where they are colinear
+    if(det === 0) return null;
+    var t = (b * f - c * e) / det,
+        u = (b * d - a * e) / det;
+    // segments do not intersect?
+    if(u < 0 || u > 1 || t < 0 || t > 1) return null;
+
+    return {x: x1 + a * t, y: y1 + d * t};
+}
+
+/*
+ * find the minimum distance between two line segments (1->2 and 3->4)
+ */
+exports.segmentDistance = function segmentDistance(x1, y1, x2, y2, x3, y3, x4, y4) {
+    if(segmentsIntersect(x1, y1, x2, y2, x3, y3, x4, y4)) return 0;
+
+    // the two segments and their lengths squared
+    var x12 = x2 - x1;
+    var y12 = y2 - y1;
+    var x34 = x4 - x3;
+    var y34 = y4 - y3;
+    var l2_12 = x12 * x12 + y12 * y12;
+    var l2_34 = x34 * x34 + y34 * y34;
+
+    // calculate distance squared, then take the sqrt at the very end
+    var dist2 = Math.min(
+        perpDistance2(x12, y12, l2_12, x3 - x1, y3 - y1),
+        perpDistance2(x12, y12, l2_12, x4 - x1, y4 - y1),
+        perpDistance2(x34, y34, l2_34, x1 - x3, y1 - y3),
+        perpDistance2(x34, y34, l2_34, x2 - x3, y2 - y3)
+    );
+
+    return Math.sqrt(dist2);
+};
+
+/*
+ * distance squared from segment ab to point c
+ * [xab, yab] is the vector b-a
+ * [xac, yac] is the vector c-a
+ * l2_ab is the length squared of (b-a), just to simplify calculation
+ */
+function perpDistance2(xab, yab, l2_ab, xac, yac) {
+    var fc_ab = (xac * xab + yac * yab);
+    if(fc_ab < 0) {
+        // point c is closer to point a
+        return xac * xac + yac * yac;
+    }
+    else if(fc_ab > l2_ab) {
+        // point c is closer to point b
+        var xbc = xac - xab;
+        var ybc = yac - yab;
+        return xbc * xbc + ybc * ybc;
+    }
+    else {
+        // perpendicular distance is the shortest
+        var crossProduct = xac * yab - yac * xab;
+        return crossProduct * crossProduct / l2_ab;
+    }
+}
+
+// a very short-term cache for getTextLocation, just because
+// we're often looping over the same locations multiple times
+// invalidated as soon as we look at a different path
+var locationCache, workingPath, workingTextWidth;
+
+// turn a path and position along it into x, y, and angle for the given text
+exports.getTextLocation = function getTextLocation(path, totalPathLen, positionOnPath, textWidth) {
+    if(path !== workingPath || textWidth !== workingTextWidth) {
+        locationCache = {};
+        workingPath = path;
+        workingTextWidth = textWidth;
+    }
+    if(locationCache[positionOnPath]) {
+        return locationCache[positionOnPath];
+    }
+
+    // for the angle, use points on the path separated by the text width
+    // even though due to curvature, the text will cover a bit more than that
+    var p0 = path.getPointAtLength(mod(positionOnPath - textWidth / 2, totalPathLen));
+    var p1 = path.getPointAtLength(mod(positionOnPath + textWidth / 2, totalPathLen));
+    // note: atan handles 1/0 nicely
+    var theta = Math.atan((p1.y - p0.y) / (p1.x - p0.x));
+    // center the text at 2/3 of the center position plus 1/3 the p0/p1 midpoint
+    // that's the average position of this segment, assuming it's roughly quadratic
+    var pCenter = path.getPointAtLength(mod(positionOnPath, totalPathLen));
+    var x = (pCenter.x * 4 + p0.x + p1.x) / 6;
+    var y = (pCenter.y * 4 + p0.y + p1.y) / 6;
+
+    var out = {x: x, y: y, theta: theta};
+    locationCache[positionOnPath] = out;
+    return out;
+};
+
+exports.clearLocationCache = function() {
+    workingPath = null;
+};
+
+/*
+ * Find the segment of `path` that's within the visible area
+ * given by `bounds` {left, right, top, bottom}, to within a
+ * precision of `buffer` px
+ *
+ * returns {
+ *   min: position where the path first enters bounds, or 0 if it
+ *        starts within bounds
+ *   max: position where the path last exits bounds, or the path length
+ *        if it finishes within bounds
+ *   total: the total path length - just included so the caller doesn't
+ *        need to call path.getTotalLength() again
+ * }
+ *
+ * Works by starting from either end and repeatedly finding the distance from
+ * that point to the plot area, and if it's outside the plot, moving along the
+ * path by that distance (because the plot must be at least that far away on
+ * the path). Note that if a path enters, exits, and re-enters the plot, we
+ * will not capture this behavior.
+ */
+exports.getVisibleSegment = function getVisibleSegment(path, bounds, buffer) {
+    var left = bounds.left;
+    var right = bounds.right;
+    var top = bounds.top;
+    var bottom = bounds.bottom;
+
+    function getDistToPlot(len) {
+        var pt = path.getPointAtLength(len);
+        var dx = (pt.x < left) ? left - pt.x : (pt.x > right ? pt.x - right : 0);
+        var dy = (pt.y < top) ? top - pt.y : (pt.y > bottom ? pt.y - bottom : 0);
+        return Math.sqrt(dx * dx + dy * dy);
+    }
+
+    var pMin = 0;
+    var pTotal = path.getTotalLength();
+    var pMax = pTotal;
+
+    var distToPlot = getDistToPlot(pMin);
+    while(distToPlot) {
+        pMin += distToPlot + buffer;
+        if(pMin > pMax) return;
+        distToPlot = getDistToPlot(pMin);
+    }
+
+    distToPlot = getDistToPlot(pMax);
+    while(distToPlot) {
+        pMax -= distToPlot + buffer;
+        if(pMin > pMax) return;
+        distToPlot = getDistToPlot(pMax);
+    }
+
+    return {min: pMin, max: pMax, total: pTotal};
+};

src/lib/index.js

@@ -74,6 +74,13 @@ lib.rotationXYMatrix = matrixModule.rotationXYMatrix;
 lib.apply2DTransform = matrixModule.apply2DTransform;
 lib.apply2DTransform2 = matrixModule.apply2DTransform2;
 
+var geom2dModule = require('./geometry2d');
+lib.segmentsIntersect = geom2dModule.segmentsIntersect;
+lib.segmentDistance = geom2dModule.segmentDistance;
+lib.getTextLocation = geom2dModule.getTextLocation;
+lib.clearLocationCache = geom2dModule.clearLocationCache;
+lib.getVisibleSegment = geom2dModule.getVisibleSegment;
+
 var extendModule = require('./extend');
 lib.extendFlat = extendModule.extendFlat;
 lib.extendDeep = extendModule.extendDeep;

src/plot_api/plot_api.js

@@ -1374,7 +1374,8 @@ function _restyle(gd, aobj, _traces) {
         'line.cmin', 'line.cmax',
         'marker.line.cmin', 'marker.line.cmax',
         'contours.start', 'contours.end', 'contours.size',
-        'contours.showlines',
+        'contours.showlines', 'contours.showlabels', 'contours.labelformat',
+        'contours.font', 'contours.font.family', 'contours.font.size',
         'line', 'line.smoothing', 'line.shape',
         'error_y.width', 'error_x.width', 'error_x.copy_ystyle',
         'marker.maxdisplayed'

src/traces/contour/attributes.js

@@ -13,6 +13,7 @@ var scatterAttrs = require('../scatter/attributes');
 var colorscaleAttrs = require('../../components/colorscale/attributes');
 var colorbarAttrs = require('../../components/colorbar/attributes');
 var dash = require('../../components/drawing/attributes').dash;
+var fontAttrs = require('../../plots/font_attributes');
 var extendFlat = require('../../lib/extend').extendFlat;
 
 var scatterLineAttrs = scatterAttrs.line;
@@ -106,7 +107,33 @@ module.exports = extendFlat({}, {
             role: 'style',
             description: [
                 'Determines whether or not the contour lines are drawn.',
-                'Has only an effect if `contours.coloring` is set to *fill*.'
+                'Has an effect only if `contours.coloring` is set to *fill*.'
+            ].join(' ')
+        },
+        showlabels: {
+            valType: 'boolean',
+            dflt: false,
+            role: 'style',
+            description: [
+                'Determines whether to label the contour lines with their values.'
+            ].join(' ')
+        },
+        font: extendFlat({}, fontAttrs, {
+            description: [
+                'Sets the font used for labeling the contour levels.',
+                'The default color comes from the lines, if shown.',
+                // TODO: same size as layout.font, or smaller? 80%?
+                'The default family and size come from `layout.font`.'
+            ].join(' ')
+        }),
+        labelformat: {
+            valType: 'string',
+            dflt: '',
+            role: 'style',
+            description: [
+                'Sets the contour label formatting rule using d3 formatting',
+                'mini-language which is very similar to Python, see:',
+                'https://github.com/d3/d3-format/blob/master/README.md#locale_format.'
             ].join(' ')
         }
     },

src/traces/contour/constants.js

@@ -7,32 +7,70 @@
 */
 
 'use strict';
+module.exports = {
+    // some constants to help with marching squares algorithm
+    // where does the path start for each index?
+    BOTTOMSTART: [1, 9, 13, 104, 713],
+    TOPSTART: [4, 6, 7, 104, 713],
+    LEFTSTART: [8, 12, 14, 208, 1114],
+    RIGHTSTART: [2, 3, 11, 208, 1114],
 
-// some constants to help with marching squares algorithm
-// where does the path start for each index?
-module.exports.BOTTOMSTART = [1, 9, 13, 104, 713];
-module.exports.TOPSTART = [4, 6, 7, 104, 713];
-module.exports.LEFTSTART = [8, 12, 14, 208, 1114];
-module.exports.RIGHTSTART = [2, 3, 11, 208, 1114];
-
-// which way [dx,dy] do we leave a given index?
-// saddles are already disambiguated
-module.exports.NEWDELTA = [
-    null, [-1, 0], [0, -1], [-1, 0],
-    [1, 0], null, [0, -1], [-1, 0],
-    [0, 1], [0, 1], null, [0, 1],
-    [1, 0], [1, 0], [0, -1]
-];
-
-// for each saddle, the first index here is used
-// for dx||dy<0, the second for dx||dy>0
-module.exports.CHOOSESADDLE = {
-    104: [4, 1],
-    208: [2, 8],
-    713: [7, 13],
-    1114: [11, 14]
-};
+    // which way [dx,dy] do we leave a given index?
+    // saddles are already disambiguated
+    NEWDELTA: [
+        null, [-1, 0], [0, -1], [-1, 0],
+        [1, 0], null, [0, -1], [-1, 0],
+        [0, 1], [0, 1], null, [0, 1],
+        [1, 0], [1, 0], [0, -1]
+    ],
+
+    // for each saddle, the first index here is used
+    // for dx||dy<0, the second for dx||dy>0
+    CHOOSESADDLE: {
+        104: [4, 1],
+        208: [2, 8],
+        713: [7, 13],
+        1114: [11, 14]
+    },
+
+    // after one index has been used for a saddle, which do we
+    // substitute to be used up later?
+    SADDLEREMAINDER: {1: 4, 2: 8, 4: 1, 7: 13, 8: 2, 11: 14, 13: 7, 14: 11},
+
+    // length of a contour, as a multiple of the plot area diagonal, per label
+    LABELDISTANCE: 2,
 
-// after one index has been used for a saddle, which do we
-// substitute to be used up later?
-module.exports.SADDLEREMAINDER = {1: 4, 2: 8, 4: 1, 7: 13, 8: 2, 11: 14, 13: 7, 14: 11};
+    // number of contour levels after which we start increasing the number of
+    // labels we draw. Many contours means they will generally be close
+    // together, so it will be harder to follow a long way to find a label
+    LABELINCREASE: 10,
+
+    // minimum length of a contour line, as a multiple of the label length,
+    // at which we draw *any* labels
+    LABELMIN: 3,
+
+    // max number of labels to draw on a single contour path, no matter how long
+    LABELMAX: 10,
+
+    // constants for the label position cost function
+    LABELOPTIMIZER: {
+        // weight given to edge proximity
+        EDGECOST: 1,
+        // weight given to the angle off horizontal
+        ANGLECOST: 1,
+        // weight given to distance from already-placed labels
+        NEIGHBORCOST: 5,
+        // cost multiplier for labels on the same level
+        SAMELEVELFACTOR: 10,
+        // minimum distance (as a multiple of the label length)
+        // for labels on the same level
+        SAMELEVELDISTANCE: 5,
+        // maximum cost before we won't even place the label
+        MAXCOST: 100,
+        // number of evenly spaced points to look at in the first
+        // iteration of the search
+        INITIALSEARCHPOINTS: 10,
+        // number of binary search iterations after the initial wide search
+        ITERATIONS: 5
+    }
+};