Merge pull request matplotlib#18647 from johan12345/master

Axes.axline: implement support transform argument (for points but not slope)

Author: QuLogic

doc/users/next_whats_new/axline_transform.rst

@@ -0,0 +1,6 @@
+axline supports *transform* parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`~.Axes.axline` now supports the *transform* parameter, which applies to
+the points *xy1*, *xy2*. The *slope* (if given) is always in data coordinates.
+This can be used e.g. with ``ax.transAxes`` for drawing grid lines with a fixed
+slope.

examples/pyplots/axline.py

@@ -27,6 +27,19 @@
 plt.legend(fontsize=14)
 plt.show()
 
+##############################################################################
+# `~.axes.Axes.axline` can also be used with a ``transform`` parameter, which
+# applies to the point, but not to the slope. This can be useful for drawing
+# diagonal grid lines with a fixed slope, which stay in place when the
+# plot limits are moved.
+
+for pos in np.linspace(-2, 1, 10):
+    plt.axline((pos, 0), slope=0.5, color='k', transform=plt.gca().transAxes)
+
+plt.ylim([0, 1])
+plt.xlim([0, 1])
+plt.show()
+
 #############################################################################
 #
 # ------------

lib/matplotlib/axes/_axes.py

@@ -814,6 +814,11 @@ def axline(self, xy1, xy2=None, *, slope=None, **kwargs):
         all other scales, and thus the behavior is undefined. Please specify
         the line using the points *xy1*, *xy2* for non-linear scales.
 
+        The *transform* keyword argument only applies to the points *xy1*,
+        *xy2*. The *slope* (if given) is always in data coordinates. This can
+        be used e.g. with ``ax.transAxes`` for drawing grid lines with a fixed
+        slope.
+
         Parameters
         ----------
         xy1, xy2 : (float, float)
@@ -829,8 +834,7 @@ def axline(self, xy1, xy2=None, *, slope=None, **kwargs):
         Other Parameters
         ----------------
         **kwargs
-            Valid kwargs are `.Line2D` properties, with the exception of
-            'transform':
+            Valid kwargs are `.Line2D` properties
 
             %(_Line2D_docstr)s
 
@@ -845,30 +849,17 @@ def axline(self, xy1, xy2=None, *, slope=None, **kwargs):
 
             >>> axline((0, 0), (1, 1), linewidth=4, color='r')
         """
-        def _to_points(xy1, xy2, slope):
-            """
-            Check for a valid combination of input parameters and convert
-            to two points, if necessary.
-            """
-            if (xy2 is None and slope is None or
-                    xy2 is not None and slope is not None):
-                raise TypeError(
-                    "Exactly one of 'xy2' and 'slope' must be given")
-            if xy2 is None:
-                x1, y1 = xy1
-                xy2 = (x1, y1 + 1) if np.isinf(slope) else (x1 + 1, y1 + slope)
-            return xy1, xy2
-
-        if "transform" in kwargs:
-            raise TypeError("'transform' is not allowed as a kwarg; "
-                            "axline generates its own transform")
         if slope is not None and (self.get_xscale() != 'linear' or
                                   self.get_yscale() != 'linear'):
             raise TypeError("'slope' cannot be used with non-linear scales")
 
         datalim = [xy1] if xy2 is None else [xy1, xy2]
-        (x1, y1), (x2, y2) = _to_points(xy1, xy2, slope)
-        line = mlines._AxLine([x1, x2], [y1, y2], **kwargs)
+        if "transform" in kwargs:
+            # if a transform is passed (i.e. line points not in data space),
+            # data limits should not be adjusted.
+            datalim = []
+
+        line = mlines._AxLine(xy1, xy2, slope, **kwargs)
         # Like add_line, but correctly handling data limits.
         self._set_artist_props(line)
         if line.get_clip_path() is None:

lib/matplotlib/lines.py

@@ -16,8 +16,7 @@
 from .colors import is_color_like, get_named_colors_mapping
 from .markers import MarkerStyle
 from .path import Path
-from .transforms import (
-    Affine2D, Bbox, BboxTransformFrom, BboxTransformTo, TransformedPath)
+from .transforms import Bbox, BboxTransformTo, TransformedPath
 
 # Imported here for backward compatibility, even though they don't
 # really belong.
@@ -1412,34 +1411,57 @@ class _AxLine(Line2D):
     transform at draw time.
     """
 
+    def __init__(self, xy1, xy2, slope, **kwargs):
+        super().__init__([0, 1], [0, 1], **kwargs)
+
+        if (xy2 is None and slope is None or
+                xy2 is not None and slope is not None):
+            raise TypeError(
+                "Exactly one of 'xy2' and 'slope' must be given")
+
+        self._slope = slope
+        self._xy1 = xy1
+        self._xy2 = xy2
+
     def get_transform(self):
         ax = self.axes
-        (x1, y1), (x2, y2) = ax.transScale.transform([*zip(*self.get_data())])
-        dx = x2 - x1
-        dy = y2 - y1
-        if np.allclose(x1, x2):
-            if np.allclose(y1, y2):
-                raise ValueError(
-                    f"Cannot draw a line through two identical points "
-                    f"(x={self.get_xdata()}, y={self.get_ydata()})")
-            # First send y1 to 0 and y2 to 1.
-            return (Affine2D.from_values(1, 0, 0, 1 / dy, 0, -y1 / dy)
-                    + ax.get_xaxis_transform(which="grid"))
-        if np.allclose(y1, y2):
-            # First send x1 to 0 and x2 to 1.
-            return (Affine2D.from_values(1 / dx, 0, 0, 1, -x1 / dx, 0)
-                    + ax.get_yaxis_transform(which="grid"))
+        points_transform = self._transform + ax.transData.inverted()
+
+        if self._xy2 is not None:
+            # two points were given
+            (x1, y1), (x2, y2) = \
+                points_transform.transform([self._xy1, self._xy2])
+            dx = x2 - x1
+            dy = y2 - y1
+            if np.allclose(x1, x2):
+                if np.allclose(y1, y2):
+                    raise ValueError(
+                        f"Cannot draw a line through two identical points "
+                        f"(x={(x1, x2)}, y={(y1, y2)})")
+                slope = np.inf
+            else:
+                slope = dy / dx
+        else:
+            # one point and a slope were given
+            x1, y1 = points_transform.transform(self._xy1)
+            slope = self._slope
         (vxlo, vylo), (vxhi, vyhi) = ax.transScale.transform(ax.viewLim)
         # General case: find intersections with view limits in either
         # direction, and draw between the middle two points.
-        _, start, stop, _ = sorted([
-            (vxlo, y1 + (vxlo - x1) * dy / dx),
-            (vxhi, y1 + (vxhi - x1) * dy / dx),
-            (x1 + (vylo - y1) * dx / dy, vylo),
-            (x1 + (vyhi - y1) * dx / dy, vyhi),
-        ])
-        return (BboxTransformFrom(Bbox([*zip(*self.get_data())]))
-                + BboxTransformTo(Bbox([start, stop]))
+        if np.isclose(slope, 0):
+            start = vxlo, y1
+            stop = vxhi, y1
+        elif np.isinf(slope):
+            start = x1, vylo
+            stop = x1, vyhi
+        else:
+            _, start, stop, _ = sorted([
+                (vxlo, y1 + (vxlo - x1) * slope),
+                (vxhi, y1 + (vxhi - x1) * slope),
+                (x1 + (vylo - y1) / slope, vylo),
+                (x1 + (vyhi - y1) / slope, vyhi),
+            ])
+        return (BboxTransformTo(Bbox([start, stop]))
                 + ax.transLimits + ax.transAxes)
 
     def draw(self, renderer):

lib/matplotlib/tests/test_axes.py

@@ -4089,6 +4089,43 @@ def test_axline(fig_test, fig_ref):
     ax.axvline(-0.5, color='C5')
 
 
+@check_figures_equal()
+def test_axline_transaxes(fig_test, fig_ref):
+    ax = fig_test.subplots()
+    ax.set(xlim=(-1, 1), ylim=(-1, 1))
+    ax.axline((0, 0), slope=1, transform=ax.transAxes)
+    ax.axline((1, 0.5), slope=1, color='C1', transform=ax.transAxes)
+    ax.axline((0.5, 0.5), slope=0, color='C2', transform=ax.transAxes)
+    ax.axline((0.5, 0), (0.5, 1), color='C3', transform=ax.transAxes)
+
+    ax = fig_ref.subplots()
+    ax.set(xlim=(-1, 1), ylim=(-1, 1))
+    ax.plot([-1, 1], [-1, 1])
+    ax.plot([0, 1], [-1, 0], color='C1')
+    ax.plot([-1, 1], [0, 0], color='C2')
+    ax.plot([0, 0], [-1, 1], color='C3')
+
+
+@check_figures_equal()
+def test_axline_transaxes_panzoom(fig_test, fig_ref):
+    # test that it is robust against pan/zoom and
+    # figure resize after plotting
+    ax = fig_test.subplots()
+    ax.set(xlim=(-1, 1), ylim=(-1, 1))
+    ax.axline((0, 0), slope=1, transform=ax.transAxes)
+    ax.axline((0.5, 0.5), slope=2, color='C1', transform=ax.transAxes)
+    ax.axline((0.5, 0.5), slope=0, color='C2', transform=ax.transAxes)
+    ax.set(xlim=(0, 5), ylim=(0, 10))
+    fig_test.set_size_inches(3, 3)
+
+    ax = fig_ref.subplots()
+    ax.set(xlim=(0, 5), ylim=(0, 10))
+    fig_ref.set_size_inches(3, 3)
+    ax.plot([0, 5], [0, 5])
+    ax.plot([0, 5], [0, 10], color='C1')
+    ax.plot([0, 5], [5, 5], color='C2')
+
+
 def test_axline_args():
     """Exactly one of *xy2* and *slope* must be specified."""
     fig, ax = plt.subplots()
@@ -4103,6 +4140,10 @@ def test_axline_args():
     ax.set_yscale('log')
     with pytest.raises(TypeError):
         ax.axline((0, 0), slope=1)
+    ax.set_yscale('linear')
+    with pytest.raises(ValueError):
+        ax.axline((0, 0), (0, 0))  # two identical points are not allowed
+        plt.draw()
 
 
 @image_comparison(['vlines_basic', 'vlines_with_nan', 'vlines_masked'],