Adding the ability to specify the tail of an annotation arrow in absolute point in grid terms rather than relative pixel offset terms. This is useful for the specification of trendlines which will continue to show the correct trend when the chart is zoomed in or out.

Author: MFed

src/components/annotations/attributes.js

@@ -131,14 +131,31 @@ module.exports = {
         role: 'style',
         description: 'Sets the width (in px) of annotation arrow.'
     },
+    absoluteArrowTail: {
+        valType: 'boolean',
+        dflt: false,
+        role: 'style',
+        description: [
+            'Indicates if the tail of this arrow is a point in ',
+            'the coordinate system vs a relative offset in pixels.',
+            'This is useful for trendline annotations which should ',
+            'continue to indicate the correct trend when zoomed.',
+            'If *true*, `ax` is a value on the x axis and `ay` is ',
+            'a value on the y axis.',
+            'If *false*, `ax` and `ay` assume their normal offset ',
+            'roles.'
+        ].join(' ')
+    },
     ax: {
         valType: 'number',
         dflt: -10,
         role: 'info',
         description: [
             'Sets the x component of the arrow tail about the arrow head.',
-            'A positive (negative) component corresponds to an arrow pointing',
-            'from right to left (left to right)'
+            'If `absoluteArrowTail` is false, a positive (negative) ',
+            'component corresponds to an arrow pointing',
+            'from right to left (left to right).',
+            'If `absoluteArrowTail` is true, this is a value on the x axis.'
         ].join(' ')
     },
     ay: {
@@ -147,8 +164,10 @@ module.exports = {
         role: 'info',
         description: [
             'Sets the y component of the arrow tail about the arrow head.',
-            'A positive (negative) component corresponds to an arrow pointing',
-            'from bottom to top (top to bottom)'
+            'If `absoluteArrowTail` is false, a positive (negative) ',
+            'component corresponds to an arrow pointing',
+            'from bottom to top (top to bottom).',
+            'If `absoluteArrowTail` is true, this is a value on the y axis.'
         ].join(' ')
     },
     // positioning

src/components/annotations/index.js

@@ -59,6 +59,7 @@ function handleAnnotationDefaults(annIn, fullLayout) {
         coerce('arrowwidth', ((borderOpacity && borderWidth) || 1) * 2);
         coerce('ax');
         coerce('ay');
+        coerce('absoluteArrowTail');
 
         // if you have one part of arrow length you should have both
         Lib.noneOrAll(annIn, annOut, ['ax', 'ay']);
@@ -89,6 +90,11 @@ function handleAnnotationDefaults(annIn, fullLayout) {
                 if(ax.type === 'date') {
                     newval = Lib.dateTime2ms(annIn[axLetter]);
                     if(newval !== false) annIn[axLetter] = newval;
+
+                    if(annIn.absoluteArrowTail) {
+                        var newvalB = Lib.dateTime2ms(annIn['a' + axLetter]);
+                        if(newvalB !== false) annIn['a' + axLetter] = newvalB;
+                    }
                 }
                 else if((ax._categories || []).length) {
                     newval = ax._categories.indexOf(annIn[axLetter]);
@@ -450,13 +456,17 @@ annotations.draw = function(gd, index, opt, value) {
             }
 
             var alignShift = 0;
-            if(options.showarrow) {
-                alignShift = options['a' + axLetter];
-            }
-            else {
-                alignShift = annSize * shiftFraction(alignPosition, anchor);
+            if(options.absoluteArrowTail) {
+                annPosPx['aa' + axLetter] = ax._offset + ax.l2p(options['a' + axLetter]);
+            } else {
+                if(options.showarrow) {
+                    alignShift = options['a' + axLetter];
+                }
+                else {
+                    alignShift = annSize * shiftFraction(alignPosition, anchor);
+                }
+                annPosPx[axLetter] += alignShift;
             }
-            annPosPx[axLetter] += alignShift;
 
             // save the current axis type for later log/linear changes
             options['_' + axLetter + 'type'] = ax && ax.type;
@@ -473,11 +483,16 @@ annotations.draw = function(gd, index, opt, value) {
 
         var arrowX, arrowY;
 
-        // make sure the arrowhead (if there is one)
-        // and the annotation center are visible
-        if(options.showarrow) {
-            arrowX = Lib.constrain(annPosPx.x - options.ax, 1, fullLayout.width - 1);
-            arrowY = Lib.constrain(annPosPx.y - options.ay, 1, fullLayout.height - 1);
+        if(options.absoluteArrowTail) {
+            arrowX = Lib.constrain(annPosPx.x, 1, fullLayout.width - 1);
+            arrowY = Lib.constrain(annPosPx.y, 1, fullLayout.height - 1);
+        } else {
+            // make sure the arrowhead (if there is one)
+            // and the annotation center are visible
+            if(options.showarrow) {
+                arrowX = Lib.constrain(annPosPx.x - options.ax, 1, fullLayout.width - 1);
+                arrowY = Lib.constrain(annPosPx.y - options.ay, 1, fullLayout.height - 1);
+            }
         }
         annPosPx.x = Lib.constrain(annPosPx.x, 1, fullLayout.width - 1);
         annPosPx.y = Lib.constrain(annPosPx.y, 1, fullLayout.height - 1);
@@ -534,27 +549,32 @@ annotations.draw = function(gd, index, opt, value) {
                     [arrowX0 + xHalf, arrowY0 - yHalf, arrowX0 - xHalf, arrowY0 - yHalf]
                 ].map(applyTransform2);
 
-            // Remove the line if it ends inside the box.  Use ray
-            // casting for rotated boxes: see which edges intersect a
-            // line from the arrowhead to far away and reduce with xor
-            // to get the parity of the number of intersections.
-            if(edges.reduce(function(a, x) {
-                return a ^
-                    !!lineIntersect(arrowX, arrowY, arrowX + 1e6, arrowY + 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(arrowX0, arrowY0, arrowX, arrowY,
-                            x[0], x[1], x[2], x[3]);
-                if(p) {
-                    arrowX0 = p.x;
-                    arrowY0 = p.y;
+            if(options.absoluteArrowTail) {
+                arrowX0 = annPosPx.aax;
+                arrowY0 = annPosPx.aay;
+            } else {
+                // Remove the line if it ends inside the box.  Use ray
+                // casting for rotated boxes: see which edges intersect a
+                // line from the arrowhead to far away and reduce with xor
+                // to get the parity of the number of intersections.
+                if(edges.reduce(function(a, x) {
+                    return a ^
+                        !!lineIntersect(arrowX, arrowY, arrowX + 1e6, arrowY + 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(arrowX0, arrowY0, arrowX, arrowY,
+                      x[0], x[1], x[2], x[3]);
+                    if(p) {
+                        arrowX0 = p.x;
+                        arrowY0 = p.y;
+                    }
+                });
+            }
 
             var strokewidth = options.arrowwidth,
                 arrowColor = options.arrowcolor;
@@ -618,10 +638,19 @@ annotations.draw = function(gd, index, opt, value) {
                             (options.y + dy / ya._m) :
                             (1 - ((arrowY + dy - gs.t) / gs.h));
 
-                        anng.attr({
-                            transform: 'rotate(' + textangle + ',' +
-                                   xcenter + ',' + ycenter + ')'
-                        });
+                        if(options.absoluteArrowTail) {
+                            update[annbase + '.ax'] = xa ?
+                              (options.ax + dx / xa._m) :
+                              ((arrowX + dx - gs.l) / gs.w);
+                            update[annbase + '.ay'] = ya ?
+                              (options.ay + dy / ya._m) :
+                              (1 - ((arrowY + dy - gs.t) / gs.h));
+                        } else {
+                            anng.attr({
+                                transform: 'rotate(' + textangle + ',' +
+                                xcenter + ',' + ycenter + ')'
+                            });
+                        }
                     },
                     doneFn: function(dragged) {
                         if(dragged) {

test/image/baselines/annotations.png

@@ -41,7 +41,8 @@
                 "bordercolor":"rgb(255, 0, 0)","borderwidth":4,"bgcolor":"rgba(255,255,0,0.5)",
                 "font":{"color":"rgb(0, 0, 255)","size":20},
                 "arrowcolor":"rgb(166, 28, 0)","borderpad":3,"textangle":50,"x":5,"y":1
-            }
+            },
+            {"text":"","showarrow":true,"borderwidth":1.2,"arrowhead":2,"absoluteArrowTail":true,"x":5,"y":5,"ax":4,"ay":3}
         ]
     }
 }

test/image/mocks/annotations.json

@@ -0,0 +1,30 @@
+var Annotations = require('@src/components/annotations');
+var Plots = require('@src/plots/plots');
+
+describe('Test annotations', function() {
+    'use strict';
+
+    describe('supplyLayoutDefaults', function() {
+        it('should default to not use absolute arrow tail', function() {
+            var annotationDefaults = {};
+            annotationDefaults._has = Plots._hasPlotType.bind(annotationDefaults);
+
+            Annotations.supplyLayoutDefaults({ annotations: [{ showarrow: true, arrowhead: 2}] }, annotationDefaults);
+
+            expect(annotationDefaults.annotations[0].absoluteArrowTail).toBe(false);
+        });
+
+        it('should convert ax/ay date coordinates to milliseconds if absoluteArrowTail is true', function() {
+            var annotationOut = { xaxis: { type: 'date', range: ['2000-01-01', '2016-01-01'] }};
+            annotationOut._has = Plots._hasPlotType.bind(annotationOut);
+
+            var annotationIn = {
+                annotations: [{ showarrow: true, absoluteArrowTail: true, x: '2008-07-01', ax: '2004-07-01', y: 0, ay: 50}]
+            };
+
+            Annotations.supplyLayoutDefaults(annotationIn, annotationOut);
+
+            expect(annotationIn.annotations[0].ax).toEqual(1088654400000);
+        });
+    });
+});