Add Axes method for drawing infinite lines.

QuLogic · dstansby · commit 737ee9fee01a · 2019-01-20T22:00:14.000Z
Clean up axline

Add axline image test

Fix test image

Add what's new

Add note about log axes

Error if trying to draw line on non-linear axes

Fix scale checking

Fix docstring interpolation

Chnage to using xy1, xy2
diff --git a/doc/users/next_whats_new/2017-12-08-axline.rst b/doc/users/next_whats_new/2017-12-08-axline.rst
@@ -0,0 +1,5 @@
+New `axline` method
+-------------------
+
+A new `axline` method has been added to draw infinitely long lines that pass
+through two points.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -834,6 +834,75 @@ def axvline(self, x=0, ymin=0, ymax=1, **kwargs):
         self.autoscale_view(scalex=scalex, scaley=False)
         return l
 
+    @docstring.dedent_interpd
+    def axline(self, xy1, xy2, **kwargs):
+        """
+        Add an infinitely long straight line that passes through two points.
+
+        Parameters
+        ----------
+        xy1, xy2 : length 2 iterables
+            Points for the line to pass through.
+
+        Returns
+        -------
+        :class:`~matplotlib.lines.Line2D`
+
+        Other Parameters
+        ----------------
+        Valid kwargs are :class:`~matplotlib.lines.Line2D` properties,
+        with the exception of 'transform':
+
+        %(_Line2D_docstr)s
+
+        Examples
+        --------
+        * Draw a thick red line passing through (0, 0) with a gradient of 1::
+
+            >>> axline((0, 0), (1, 1), linewidth=4, color='r')
+
+
+        See Also
+        --------
+        axhline : for horizontal lines
+        axvline : for vertical lines
+
+        Notes
+        -----
+        Currently this method does not work properly with non-linear axes.
+        """
+        if not self.get_xscale() == self.get_yscale() == 'linear':
+            raise NotImplementedError('axline() is only supported on '
+                                      'linearly scaled axes')
+
+        if "transform" in kwargs:
+            raise TypeError("'transform' is not allowed as a kwarg; "
+                            "axline generates its own transform.")
+
+        x1, y1 = xy1
+        x2, y2 = xy2
+        # If x values the same, we have a vertical line
+        if x1 == x2:
+            line = self.axvline(x1, **kwargs)
+            return line
+
+        slope = (y2 - y1) / (x2 - x1)
+        intercept = y1 - (slope * x1)
+
+        xtrans = mtransforms.BboxTransformTo(self.viewLim)
+        viewLimT = mtransforms.TransformedBbox(
+            self.viewLim,
+            mtransforms.Affine2D().rotate_deg(90).scale(-1, 1))
+        ytrans = (mtransforms.BboxTransformTo(viewLimT) +
+                  mtransforms.Affine2D().scale(slope).translate(0, intercept))
+        trans = mtransforms.blended_transform_factory(xtrans, ytrans)
+
+        line = mlines.Line2D([0, 1], [0, 1],
+                             transform=trans + self.transData,
+                             **kwargs)
+        self.add_line(line)
+        return line
+
     @docstring.dedent_interpd
     def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs):
         """
diff --git a/lib/matplotlib/tests/baseline_images/test_axes/axline.png b/lib/matplotlib/tests/baseline_images/test_axes/axline.png
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -3539,6 +3539,18 @@ def test_eb_line_zorder():
     ax.set_title("errorbar zorder test")
 
 
+@image_comparison(baseline_images=['axline'], extensions=['png'],
+                  style='mpl20')
+def test_axline():
+    fig, ax = plt.subplots()
+    ax.set_xlim(-1, 1)
+    ax.set_ylim(-1, 1)
+    ax.axline((0, 0), (1, 1))
+    ax.axline((0, 0), (1, 0), color='C1')
+    ax.axline((0, 0.5), (1, 0.5), color='C2')
+    ax.axline((0.5, 0), (0.5, 1), color='C3')
+
+
 @image_comparison(
     baseline_images=['vlines_basic', 'vlines_with_nan', 'vlines_masked'],
     extensions=['png']
