Squashed commit of the following:

idahj · idahj · commit 4ba7f548a246 · 2018-05-01T10:34:58.000+02:00
commit a05a486 Merge: 6ec4f8f e751286 Author: Ida Hjorth <idahjorth@gmail.com> Date: Sun Apr 29 19:07:32 2018 +0200 Merge pull request matplotlib#3 from magnunor/idahj_anchored_directionarrows Idahj anchored directionarrows commit e751286 Merge: 3ba79fb 6ec4f8f Author: Magnus Nord <magnunor@gmail.com> Date: Sun Apr 29 09:00:34 2018 +0200 Merge branch 'NEW_AnchoredDirectionArrows' of github.com:idahj/matplotlib into idahj_anchored_directionarrows commit 6ec4f8f Author: Ida <idahjorth@gmail.com> Date: Fri Aug 25 13:14:26 2017 +0100 AnchoredDirectionArrows: Docstring, what's new commit 19f4a38 Author: Ida <idahjorth@gmail.com> Date: Thu Aug 24 14:27:23 2017 +0100 AnchoredDirectionArrows: Demo docstring commit d024684 Author: Ida <idahjorth@gmail.com> Date: Thu Aug 24 14:09:52 2017 +0100 AnchoredDirectionArrows: Fix error commit 27b6bc5 Author: Ida <idahjorth@gmail.com> Date: Thu Aug 24 13:58:58 2017 +0100 AnchoredDirectionArrows: make variable not private commit c0762d2 Author: Ida <idahjorth@gmail.com> Date: Thu Aug 24 13:02:38 2017 +0100 AnchoredDirectionArrows: Add docstring in demo commit 88d04d0 Author: Ida <idahjorth@gmail.com> Date: Wed Aug 23 14:19:06 2017 +0100 AnchoredDirectionArrows: docstring, what's new commit efcca59 Author: Magnus Nord <Magnus.Nord@glasgow.ac.uk> Date: Wed Aug 23 13:31:32 2017 +0100 AnchoredDirectionArrows: add test which uses many of the arguments commit e200c44 Author: Magnus Nord <Magnus.Nord@glasgow.ac.uk> Date: Wed Aug 23 12:06:05 2017 +0100 AnchoredDirectionArrows: minor docstring changes commit b6b0ea2 Author: Ida <idahjorth@gmail.com> Date: Tue Aug 22 13:28:56 2017 +0100 AnchoredDirectionArrows: PEP8 commit 5fde65a Author: Ida <idahjorth@gmail.com> Date: Tue Aug 22 13:23:25 2017 +0100 AnchoredDirectionArrows: Add demo commit 23f7d5b Author: Ida <idahjorth@gmail.com> Date: Tue Aug 22 11:16:41 2017 +0100 AnchoredDirectionArrows: Add working unit test commit 459ae07 Author: Ida <idahjorth@gmail.com> Date: Tue Aug 22 10:37:44 2017 +0100 AnchoredDirectionArrow: first attempt unit test Currently not working commit f4ec0e2 Author: Ida <idahjorth@gmail.com> Date: Wed Aug 16 19:31:05 2017 +0100 Cleanup, bug fix, begin merge overlapping arrows commit 75e52b0 Author: Magnus Nord <magnunor@gmail.com> Date: Mon Aug 14 23:05:30 2017 +0100 AnchoredDirectionArrows: PEP8 fixes, and improve docstring commit 4fff775 Author: Ida <idahjorth@gmail.com> Date: Mon Aug 14 22:04:22 2017 +0100 Add AnchoredDirectionArrows class in axes_grid1
diff --git a/doc/users/next_whats_new/anchored_direction_arrows.rst b/doc/users/next_whats_new/anchored_direction_arrows.rst
@@ -0,0 +1,15 @@
+Add ``AnchoredDirectionArrows`` feature to mpl_toolkits
+--------------------------------------------------------
+
+A new mpl_toolkits class
+:class:`~mpl_toolkits.axes_grid1.anchored_artists.AnchoredDirectionArrows`
+draws a pair of orthogonal arrows to inidcate directions on a 2D plot. A
+minimal working example takes in the transformation object for the coordinate
+system (typically ax.transAxes), and arrow labels. There are several optional
+parameters that can be used to alter layout. For example, the arrow pairs can
+be rotated and the color can be changed. By default the labels and arrows have
+the same color, but the class may also pass arguments for costumizing arrow
+and text layout, these are passed to :class:`matplotlib.text.TextPath` and
+`matplotlib.patches.FancyArrowPatch`. Location, length and width for both
+arrow tail and head can be adjusted, the the direction arrows and labels can
+have a frame. Padding and separation parameters can be adjusted.
diff --git a/examples/axes_grid1/demo_anchored_direction_arrows.py b/examples/axes_grid1/demo_anchored_direction_arrows.py
@@ -0,0 +1,78 @@
+"""
+=============================
+Demo Anchored Direction Arrow
+=============================
+
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+from mpl_toolkits.axes_grid1.anchored_artists import AnchoredDirectionArrows
+import matplotlib.font_manager as fm
+
+fig, ax = plt.subplots()
+ax.imshow(np.random.random((10, 10)))
+
+# Simple example
+simple_arrow = AnchoredDirectionArrows(ax.transAxes, 'X', 'Y')
+ax.add_artist(simple_arrow)
+
+# High contrast arrow
+high_contrast_part_1 = AnchoredDirectionArrows(
+                            ax.transAxes,
+                            '111', r'11$\overline{2}$',
+                            loc=1,
+                            arrow_props={'ec': 'w', 'fc': 'none', 'alpha': 1,
+                                         'lw': 2}
+                            )
+ax.add_artist(high_contrast_part_1)
+
+high_contrast_part_2 = AnchoredDirectionArrows(
+                            ax.transAxes,
+                            '111', r'11$\overline{2}$',
+                            loc=1,
+                            arrow_props={'ec': 'none', 'fc': 'k'},
+                            text_props={'ec': 'w', 'fc': 'k', 'lw': 0.4}
+                            )
+ax.add_artist(high_contrast_part_2)
+
+# Rotated arrow
+fontprops = fm.FontProperties(family='serif')
+
+roatated_arrow = AnchoredDirectionArrows(
+                    ax.transAxes,
+                    '30', '120',
+                    loc='center',
+                    color='w',
+                    angle=30,
+                    fontproperties=fontprops
+                    )
+ax.add_artist(roatated_arrow)
+
+# Altering arrow directions
+a1 = AnchoredDirectionArrows(
+        ax.transAxes, 'A', 'B', loc='lower center',
+        length=-0.15,
+        sep_x=0.03, sep_y=0.03,
+        color='r'
+    )
+ax.add_artist(a1)
+
+a2 = AnchoredDirectionArrows(
+        ax.transAxes, 'A', ' B', loc='lower left',
+        aspect_ratio=-1,
+        sep_x=0.01, sep_y=-0.02,
+        color='orange'
+        )
+ax.add_artist(a2)
+
+
+a3 = AnchoredDirectionArrows(
+        ax.transAxes, ' A', 'B', loc='lower right',
+        length=-0.15,
+        aspect_ratio=-1,
+        sep_y=-0.1, sep_x=0.04,
+        color='cyan'
+        )
+ax.add_artist(a3)
+
+plt.show()
diff --git a/lib/mpl_toolkits/axes_grid1/anchored_artists.py b/lib/mpl_toolkits/axes_grid1/anchored_artists.py
@@ -1,13 +1,14 @@
 import six
 
-from matplotlib import docstring
+from matplotlib import docstring, transforms
 from matplotlib.offsetbox import (AnchoredOffsetbox, AuxTransformBox,
                                   DrawingArea, TextArea, VPacker)
-from matplotlib.patches import Rectangle, Ellipse
-
+from matplotlib.patches import (Rectangle, Ellipse, ArrowStyle,
+                                FancyArrowPatch, PathPatch)
+from matplotlib.text import TextPath
 
 __all__ = ['AnchoredDrawingArea', 'AnchoredAuxTransformBox',
-           'AnchoredEllipse', 'AnchoredSizeBar']
+           'AnchoredEllipse', 'AnchoredSizeBar', 'AnchoredDirectionArrows']
 
 
 class AnchoredDrawingArea(AnchoredOffsetbox):
@@ -372,3 +373,222 @@ def __init__(self, transform, size, label, loc,
                                    child=self._box,
                                    prop=fontproperties,
                                    frameon=frameon, **kwargs)
+
+
+class AnchoredDirectionArrows(AnchoredOffsetbox):
+    @docstring.dedent
+    def __init__(self, transform, label_x, label_y, length=0.15,
+                 fontsize=0.08, loc=2, angle=0, aspect_ratio=1, pad=0.4,
+                 borderpad=0.4, frameon=False, color='w', alpha=1,
+                 sep_x=0.01, sep_y=0, fontproperties=None, back_length=0.15,
+                 head_width=10, head_length=15, tail_width=2,
+                 text_props=None, arrow_props=None,
+                 **kwargs):
+        """
+        Draw two perpendicular arrows to indicate directions.
+
+        Parameters
+        ----------
+        transform : `matplotlib.transforms.Transform`
+            The transformation object for the coordinate system in use, i.e.,
+            :attr:`matplotlib.axes.Axes.transAxes`.
+
+        label_x, label_y : string
+            Label text for the x and y arrows
+
+        length : int or float, optional
+            Length of the arrow, given in coordinates of
+            *transform*.
+            Defaults to 0.15.
+
+        fontsize : int, optional
+            Size of label strings, given in coordinates of *transform*.
+            Defaults to 0.08.
+
+        loc : int, optional
+            Location of the direction arrows. Valid location codes are::
+
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4,
+                'right'        : 5,
+                'center left'  : 6,
+                'center right' : 7,
+                'lower center' : 8,
+                'upper center' : 9,
+                'center'       : 10
+
+            Defaults to 2.
+
+        angle : int or float, optional
+            The angle of the arrows in degrees.
+            Defaults to 0.
+
+        aspect_ratio : int or float, optional
+            The ratio of the length of arrow_x and arrow_y.
+            Negative numbers can be used to change the direction.
+            Defaults to 1.
+
+        pad : int or float, optional
+            Padding around the labels and arrows, in fraction of the font
+            size. Defaults to 0.4.
+
+        borderpad : int or float, optional
+            Border padding, in fraction of the font size.
+            Defaults to 0.4.
+
+        frameon : bool, optional
+            If True, draw a box around the arrows and labels.
+            Defaults to False.
+
+        color : str, optional
+            Color for the arrows and labels.
+            Defaults to white.
+
+        alpha : int or float, optional
+            Alpha values of the arrows and labels
+            Defaults to 1.
+
+        sep_x, sep_y : int or float, optional
+            Separation between the arrows and labels in coordinates of
+            *transform*. Defaults to 0.01 and 0.
+
+        fontproperties : `matplotlib.font_manager.FontProperties`, optional
+            Font properties for the label text.
+
+        back_length : float, optional
+            Fraction of the arrow behind the arrow crossing.
+            Defaults to 0.15.
+
+        head_width : int or float, optional
+            Width of arrow head, sent to ArrowStyle.
+            Defaults to 10.
+
+        head_length : int or float, optional
+            Length of arrow head, sent to ArrowStyle.
+            Defaults to 15.
+
+        tail_width : int or float, optional
+            Width of arrow tail, sent to ArrowStyle.
+            Defaults to 2.
+
+        text_props, arrow_props : dict
+            Properties of the text and arrows, passed to
+            :class:`matplotlib.text.TextPath` and
+            `matplotlib.patches.FancyArrowPatch`
+
+        **kwargs :
+            Keyworded arguments to pass to
+            :class:`matplotlib.offsetbox.AnchoredOffsetbox`.
+
+        Attributes
+        ----------
+        arrow_x, arrow_y : `matplotlib.patches.FancyArrowPatch`
+            Arrow x and y
+
+        text_path_x, text_path_y : `matplotlib.text.TextPath`
+            Path for arrow labels
+
+        p_x, p_y : `matplotlib.patches.PathPatch`
+            Patch for arrow labels
+
+        box : `matplotlib.offsetbox.AuxTransformBox`
+            Container for the arrows and labels.
+
+        Notes
+        -----
+        If *prop* is passed as a keyword argument, but *fontproperties* is
+        not, then *prop* is be assumed to be the intended *fontproperties*.
+        Using both *prop* and *fontproperties* is not supported.
+
+        Examples
+        --------
+        >>> import matplotlib.pyplot as plt
+        >>> import numpy as np
+        >>> from mpl_toolkits.axes_grid1.anchored_artists import \
+        ...     AnchoredDirectionArrows
+        >>> fig, ax = plt.subplots()
+        >>> ax.imshow(np.random.random((10,10)))
+        >>> arrows = AnchoredDirectionArrows(ax.transAxes, '111', '110')
+        >>> ax.add_artist(arrows)
+        >>> fig.show()
+
+        Using several of the optional parameters, creating downward pointing
+        arrow and high contrast text labels.
+
+        >>> import matplotlib.font_manager as fm
+        >>> fontprops = fm.FontProperties(family='monospace')
+        >>> arrows = AnchoredDirectionArrows(ax.transAxes, 'East', 'South',
+        ... loc='lower left', color='k', aspect_ratio=-1, sep_x=0.02,
+        ... sep_y=-0.01, text_props={'ec':'w', 'fc':'k'},
+        ... fontproperties=fontprops)
+        """
+        if arrow_props is None:
+            arrow_props = {}
+
+        if text_props is None:
+            text_props = {}
+
+        arrowstyle = ArrowStyle("Simple",
+                                head_width=head_width,
+                                head_length=head_length,
+                                tail_width=tail_width)
+
+        if fontproperties is None and 'prop' in kwargs:
+            fontproperties = kwargs.pop('prop')
+
+        if 'color' not in arrow_props:
+            arrow_props['color'] = color
+
+        if 'alpha' not in arrow_props:
+            arrow_props['alpha'] = alpha
+
+        if 'color' not in text_props:
+            text_props['color'] = color
+
+        if 'alpha' not in text_props:
+            text_props['alpha'] = alpha
+
+        t_start = transform
+        t_end = t_start + transforms.Affine2D().rotate_deg(angle)
+
+        self.box = AuxTransformBox(t_end)
+
+        length_x = length
+        length_y = length*aspect_ratio
+
+        self.arrow_x = FancyArrowPatch(
+                (0, back_length*length_y),
+                (length_x, back_length*length_y),
+                arrowstyle=arrowstyle,
+                shrinkA=0.0,
+                shrinkB=0.0,
+                **arrow_props)
+
+        self.arrow_y = FancyArrowPatch(
+                (back_length*length_x, 0),
+                (back_length*length_x, length_y),
+                arrowstyle=arrowstyle,
+                shrinkA=0.0,
+                shrinkB=0.0,
+                **arrow_props)
+
+        self.box.add_artist(self.arrow_x)
+        self.box.add_artist(self.arrow_y)
+
+        text_path_x = TextPath((
+            length_x+sep_x, back_length*length_y+sep_y), label_x,
+            size=fontsize, prop=fontproperties)
+        self.p_x = PathPatch(text_path_x, transform=t_start, **text_props)
+        self.box.add_artist(self.p_x)
+
+        text_path_y = TextPath((
+            length_x*back_length+sep_x, length_y*(1-back_length)+sep_y),
+            label_y, size=fontsize, prop=fontproperties)
+        self.p_y = PathPatch(text_path_y, **text_props)
+        self.box.add_artist(self.p_y)
+
+        AnchoredOffsetbox.__init__(self, loc, pad=pad, borderpad=borderpad,
+                                   child=self.box,
+                                   frameon=frameon, **kwargs)
diff --git a/lib/mpl_toolkits/tests/baseline_images/test_axes_grid1/anchored_direction_arrows.png b/lib/mpl_toolkits/tests/baseline_images/test_axes_grid1/anchored_direction_arrows.png
diff --git a/lib/mpl_toolkits/tests/baseline_images/test_axes_grid1/anchored_direction_arrows_many_args.png b/lib/mpl_toolkits/tests/baseline_images/test_axes_grid1/anchored_direction_arrows_many_args.png
diff --git a/lib/mpl_toolkits/tests/test_axes_grid1.py b/lib/mpl_toolkits/tests/test_axes_grid1.py
@@ -13,7 +13,9 @@
     inset_axes,
     BboxConnectorPatch
 )
-from mpl_toolkits.axes_grid1.anchored_artists import AnchoredSizeBar
+from mpl_toolkits.axes_grid1.anchored_artists import (
+    AnchoredSizeBar,
+    AnchoredDirectionArrows)
 
 from matplotlib.colors import LogNorm
 from matplotlib.transforms import Bbox, TransformedBbox, \
@@ -322,3 +324,27 @@ def test_zooming_with_inverted_axes():
     ax.axis([3, 1, 3, 1])
     inset_ax = zoomed_inset_axes(ax, zoom=2.5, loc=4)
     inset_ax.axis([1.4, 1.1, 1.4, 1.1])
+
+
+@image_comparison(baseline_images=['anchored_direction_arrows'],
+                  extensions=['png'])
+def test_anchored_direction_arrows():
+    fig, ax = plt.subplots()
+    ax.imshow(np.zeros((10, 10)))
+
+    simple_arrow = AnchoredDirectionArrows(ax.transAxes, 'X', 'Y')
+    ax.add_artist(simple_arrow)
+
+
+@image_comparison(baseline_images=['anchored_direction_arrows_many_args'],
+                  extensions=['png'])
+def test_anchored_direction_arrows_many_args():
+    fig, ax = plt.subplots()
+    ax.imshow(np.ones((10, 10)))
+
+    direction_arrows = AnchoredDirectionArrows(
+            ax.transAxes, 'A', 'B', loc='upper right', color='red',
+            aspect_ratio=-0.5, pad=0.6, borderpad=2, frameon=True, alpha=0.7,
+            sep_x=-0.06, sep_y=-0.08, back_length=0.1, head_width=9,
+            head_length=10, tail_width=5)
+    ax.add_artist(direction_arrows)
