Merge pull request #11780 from ImportanceOfBeingErnest/connectorpatch-coordinates

jklymak · web-flow · commit 2bb68f63afef · 2019-01-04T09:17:32.000-08:00
ENH: Allow arbitrary coordinates for ConnectionPatch
diff --git a/doc/users/next_whats_new/ConnectionPatch_accepts_arbitrary_transforms.rst b/doc/users/next_whats_new/ConnectionPatch_accepts_arbitrary_transforms.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+`ConnectionPatch` accepts arbitrary transforms
+----------------------------------------------
+
+Alternatively to strings like ``"data"`` or ``"axes fraction"``
+`ConnectionPatch` now accepts any `~matplotlib.transforms.Transform`
+as input for the ``coordsA`` and ``coordsB`` argument. This allows to
+draw lines between points defined in different user defined coordinate
+systems. Also see the :doc:`Connect Simple01 example
+</gallery/userdemo/connect_simple01>`.
diff --git a/examples/userdemo/connect_simple01.py b/examples/userdemo/connect_simple01.py
@@ -3,12 +3,16 @@
 Connect Simple01
 ================
 
+A `ConnectionPatch` can be used to draw a line (possibly with arrow head)
+between points defined in different coordinate systems and/or axes.
 """
 from matplotlib.patches import ConnectionPatch
 import matplotlib.pyplot as plt
 
 fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6, 3))
 
+# Draw a simple arrow between two points in axes coordinates
+# within a single axes.
 xyA = (0.2, 0.2)
 xyB = (0.8, 0.8)
 coordsA = "data"
@@ -19,6 +23,8 @@
 ax1.plot([xyA[0], xyB[0]], [xyA[1], xyB[1]], "o")
 ax1.add_artist(con)
 
+# Draw an arrow between the same point in data coordinates,
+# but in different axes.
 xy = (0.3, 0.2)
 coordsA = "data"
 coordsB = "data"
@@ -27,6 +33,16 @@
                       arrowstyle="->", shrinkB=5)
 ax2.add_artist(con)
 
+# Draw a line between the different points, defined in differnt coordinate
+# systems.
+xyA = (0.6, 1.0)  # in axes coordinates
+xyB = (0.0, 0.2)  # x in axes coordinates, y in data coordinates
+coordsA = "axes fraction"
+coordsB = ax2.get_yaxis_transform()
+con = ConnectionPatch(xyA=xyA, xyB=xyB, coordsA=coordsA, coordsB=coordsB,
+                      arrowstyle="-")
+ax2.add_artist(con)
+
 ax1.set_xlim(0, 1)
 ax1.set_ylim(0, 1)
 ax2.set_xlim(0, .5)
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -4386,6 +4386,8 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None,
                             system.
         =================   ===================================================
 
+        Alternatively they can be set to any valid
+        `~matplotlib.transforms.Transform`.
         """
         if coordsB is None:
             coordsB = coordsA
@@ -4518,6 +4520,11 @@ def _get_xy(self, x, y, s, axes=None):
             #(0,0) is lower left, (1,1) is upper right of axes
             trans = axes.transAxes
             return trans.transform_point((x, y))
+        elif isinstance(s, transforms.Transform):
+            return s.transform_point((x, y))
+        else:
+            raise ValueError("{} is not a valid coordinate "
+                             "transformation.".format(s))
 
     def set_annotation_clip(self, b):
         """
diff --git a/lib/matplotlib/tests/baseline_images/test_patches/connection_patch.png b/lib/matplotlib/tests/baseline_images/test_patches/connection_patch.png
diff --git a/lib/matplotlib/tests/test_patches.py b/lib/matplotlib/tests/test_patches.py
@@ -394,6 +394,14 @@ def test_connection_patch():
                                    arrowstyle="->")
     ax2.add_artist(con)
 
+    xyA = (0.6, 1.0)  # in axes coordinates
+    xyB = (0.0, 0.2)  # x in axes coordinates, y in data coordinates
+    coordsA = "axes fraction"
+    coordsB = ax2.get_yaxis_transform()
+    con = mpatches.ConnectionPatch(xyA=xyA, xyB=xyB, coordsA=coordsA,
+                                    coordsB=coordsB, arrowstyle="-")
+    ax2.add_artist(con)
+
 
 def test_datetime_rectangle():
     # Check that creating a rectangle with timedeltas doesn't fail
