box aspect for axes

ImportanceOfBeingErnest · ImportanceOfBeingErnest · commit cdd284316291 · 2019-07-31T17:43:00.000+02:00
diff --git a/doc/users/next_whats_new/2019-07-31_axes-box-aspect.rst b/doc/users/next_whats_new/2019-07-31_axes-box-aspect.rst
@@ -0,0 +1,14 @@
+:orphan:
+
+Setting axes box aspect
+-----------------------
+
+It is now possible to set the aspect of an axes box directly via
+`~Axes.set_box_aspect`. The box aspect is the ratio between axes height
+and axes width in physical units, independent of the data limits.
+This is useful to e.g. produce a square plot, independent of the data it
+contains, or to have a usual plot with the same axes dimensions next to
+an image plot with fixed (data-)aspect.
+
+For use cases check out the :doc:`Axes box aspect
+</gallery/subplots_axes_and_figures/axes_box_aspect>` example.
diff --git a/examples/subplots_axes_and_figures/axes_box_aspect.py b/examples/subplots_axes_and_figures/axes_box_aspect.py
@@ -0,0 +1,29 @@
+"""
+===============
+Axes box aspect
+===============
+
+This demo shows how to set the aspect of an axes box directly via
+`~Axes.set_box_aspect`. The box aspect is the ratio between axes height
+and axes width in physical units, independent of the data limits.
+This is useful to e.g. produce a square plot, independent of the data it
+contains, or to have a usual plot with the same axes dimensions next to
+an image plot with fixed (data-)aspect.
+"""
+
+import matplotlib
+print("Placeholder, still to be filled")
+
+
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods and classes is shown
+# in this example:
+
+matplotlib.axes.Axes.set_box_aspect
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -426,6 +426,7 @@ def __init__(self, fig, rect,
         self.axes = self
         self._aspect = 'auto'
         self._adjustable = 'box'
+        self._box_aspect = None
         self._anchor = 'C'
         self._stale_viewlim_x = False
         self._stale_viewlim_y = False
@@ -1282,6 +1283,18 @@ def set_aspect(self, aspect, adjustable=None, anchor=None, share=False):
         self.stale = True
 
     def get_adjustable(self):
+        """
+        Returns the adjustable parameter, *{'box', 'datalim'}* that defines
+        which parameter the Axes will change to achieve a given aspect.
+
+        See Also
+        --------
+        matplotlib.axes.Axes.set_adjustable
+            defining the parameter to adjust in order to meet the required
+            aspect.
+        matplotlib.axes.Axes.set_aspect
+            for a description of aspect handling.
+        """
         return self._adjustable
 
     def set_adjustable(self, adjustable, share=False):
@@ -1333,6 +1346,54 @@ def set_adjustable(self, adjustable, share=False):
             ax._adjustable = adjustable
         self.stale = True
 
+    def get_box_aspect(self):
+        """
+        Get the axes box aspect.
+        Will be ``None`` if not explicitely specified.
+
+        See Also
+        --------
+        matplotlib.axes.Axes.set_box_aspect
+            for a description of box aspect.
+        matplotlib.axes.Axes.set_aspect
+            for a description of aspect handling.
+        """
+        return self._box_aspect
+
+    def set_box_aspect(self, aspect=None):
+        """
+        Set the axes box aspect. The box aspect is the ratio of the
+        axes height to the axes width in physical units. This is not to be
+        confused with the data aspect, set via `~Axes.set_aspect`.
+
+        Parameters
+        ----------
+        aspect : None, or a number
+            Changes the physical dimensions of the Axes, such that the ratio
+            of the axes height to the axes width in physical units is equal to
+            *aspect*. If *None*, the axes geometry will not be adjusted.
+        
+        Note that this changes the adjustable to *datalim*.
+
+        See Also
+        --------
+        matplotlib.axes.Axes.set_aspect
+            for a description of aspect handling.
+        """
+        axs = {*self._twinned_axes.get_siblings(self),
+               *self._twinned_axes.get_siblings(self)}
+
+        if aspect is not None:
+            aspect = float(aspect)
+            # when box_aspect is set to other than ´None`,
+            # adjustable must be "datalim"
+            for ax in axs:
+                ax.set_adjustable("datalim")
+
+        for ax in axs:
+            ax._box_aspect = aspect
+            ax.stale = True
+
     def get_anchor(self):
         """
         Get the anchor location.
@@ -1464,7 +1525,7 @@ def apply_aspect(self, position=None):
 
         aspect = self.get_aspect()
 
-        if aspect == 'auto':
+        if aspect == 'auto' and self._box_aspect is None:
             self._set_position(position, which='active')
             return
 
@@ -1484,11 +1545,20 @@ def apply_aspect(self, position=None):
             self._set_position(pb1.anchored(self.get_anchor(), pb), 'active')
             return
 
-        # self._adjustable == 'datalim'
+        # The following is only seen if self._adjustable == 'datalim'
+        if self._box_aspect is not None:
+            pb = position.frozen()
+            pb1 = pb.shrunk_to_aspect(self._box_aspect, pb, fig_aspect)
+            self._set_position(pb1.anchored(self.get_anchor(), pb), 'active')
+            if aspect == "auto":
+                return
 
         # reset active to original in case it had been changed by prior use
         # of 'box'
-        self._set_position(position, which='active')
+        if self._box_aspect is None:
+            self._set_position(position, which='active')
+        else:
+            position = pb1.anchored(self.get_anchor(), pb)
 
         x_trf = self.xaxis.get_transform()
         y_trf = self.yaxis.get_transform()
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -6560,3 +6560,52 @@ def test_aspect_nonlinear_adjustable_datalim():
     ax.margins(0)
     ax.apply_aspect()
     assert ax.get_xlim() == pytest.approx(np.array([1/10, 10]) * np.sqrt(10))
+
+
+def test_box_aspect():
+    # Test if axes with box_aspect=1 has same dimensions
+    # as axes with aspect equal and adjustable="box"
+
+    fig1, ax1 = plt.subplots()
+    axtwin = ax1.twinx()
+    axtwin.plot([12,344])
+
+    ax1.set_box_aspect(1)
+
+    fig2, ax2 = plt.subplots()
+    ax2.margins(0)
+    ax2.plot([0,2],[6,8])
+    ax2.set_aspect("equal", adjustable="box")
+
+    fig1.canvas.draw()
+    fig2.canvas.draw()
+
+    bb1 = ax1.get_position()
+    bbt = axtwin.get_position()
+    bb2 = ax2.get_position()
+
+    assert_array_equal(bb1.extents, bb2.extents)
+    assert_array_equal(bbt.extents, bb2.extents)
+
+
+def test_box_aspect_custom_position():
+    # Test if axes with custom position and box_aspect
+    # behaves the same independent of the order of setting those.
+
+    fig1, ax1 = plt.subplots()
+    ax1.set_position([0.1, 0.1, 0.9, 0.2])
+    fig1.canvas.draw()
+    ax1.set_box_aspect(1.)
+
+    fig2, ax2 = plt.subplots()
+    ax2.set_box_aspect(1.)
+    fig2.canvas.draw()
+    ax2.set_position([0.1, 0.1, 0.9, 0.2])
+
+    fig1.canvas.draw()
+    fig2.canvas.draw()
+
+    bb1 = ax1.get_position()
+    bb2 = ax2.get_position()
+
+    assert_array_equal(bb1.extents, bb2.extents)
