matplotlib
diff --git a/‎doc/users/next_whats_new/2019-03-25-mplot3d-projection.rst
Lines changed: 14 additions & 2 deletions b/‎doc/users/next_whats_new/2019-03-25-mplot3d-projection.rst
Lines changed: 14 additions & 2 deletions
diff --git a/‎lib/mpl_toolkits/mplot3d/axes3d.py
Lines changed: 46 additions & 13 deletions b/‎lib/mpl_toolkits/mplot3d/axes3d.py
Lines changed: 46 additions & 13 deletions
diff --git a/‎lib/mpl_toolkits/tests/baseline_images/test_mplot3d/equal_box_aspect.png
54 KB b/‎lib/mpl_toolkits/tests/baseline_images/test_mplot3d/equal_box_aspect.png
54 KB
@@ -4,6 +4,18 @@
 Plots made with :class:`~mpl_toolkits.mplot3d.axes3d.Axes3D` were previously
 stretched to fit a square bounding box. As this stretching was done after
 the projection from 3D to 2D, it resulted in distorted images if non-square
-bounding boxes were used.
+bounding boxes were used.  As of this release, this no longer occurs by default.
 
-As of this release, this no longer occurs.
+We have extended the functionality of `.Axes3D.set_aspect` to accept
+the modes ``'auto_Pb'``, which uses a fixed ratios between the sizes,
+in display space, of the axis.  To control these ratios use the
+`.Axes3D.set_box_aspect` method which accepts the ratios at as a
+3-tuple of X:Y:Z.  The default aspect ratio is 4:4:3.
+
+Currently modes of setting the aspect, in data space, are not
+supported for Axes3D but maybe in the future.  If you want to simulate
+having equal aspect in data space, set the ratio of your data limits
+to match the value of `.Axes3D.get_box_aspect`.
+
+To restore the old behavior (which may result in distorted images) use
+``ax.set_aspect('auto')``.
@@ -53,6 +53,7 @@ class Axes3D(Axes):
     def __init__(
             self, fig, rect=None, *args,
             azim=-60, elev=30, sharez=None, proj_type='persp',
+            box_aspect=None, aspect='auto_pb',
             **kwargs):
         """
         Parameters
@@ -91,11 +92,7 @@ def __init__(
         self.zz_viewLim = Bbox.unit()
         self.xy_dataLim = Bbox.unit()
         self.zz_dataLim = Bbox.unit()
-        if 'pb_aspect' in kwargs:
-            self.pb_aspect = np.asarray(kwargs['pb_aspect'])
-        else:
-            # chosen for similarity with the previous initial view
-            self.pb_aspect = np.array([4, 4, 3]) / 3.5
+
         # inhibit autoscale_view until the axes are defined
         # they can't be defined until Axes.__init__ has been called
         self.view_init(self.initial_elev, self.initial_azim)
@@ -105,8 +102,9 @@ def __init__(
             self._shared_z_axes.join(self, sharez)
             self._adjustable = 'datalim'
 
-        kwargs.setdefault('aspect', 'auto_pb')
-        super().__init__(fig, rect, frameon=True, *args, **kwargs)
+        super().__init__(fig, rect, frameon=True,
+                         box_aspect=box_aspect, aspect=aspect,
+                         *args, **kwargs)
         # Disable drawing of axes by base class
         super().set_axis_off()
         # Enable drawing of axes by Axes3D class
@@ -353,8 +351,43 @@ def set_anchor(self, anchor, share=False):
             ax._anchor = anchor
             ax.stale = True
 
-    def set_pb_aspect(self, pb_aspect, zoom=1):
-        self.pb_aspect = pb_aspect * 1.8 * zoom / proj3d.mod(pb_aspect)
+    def set_box_aspect(self, aspect, zoom=1):
+        """
+        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 : 3-tuple of floats on None
+            Changes the physical dimensions of the Axes, such that the ratio
+            of the size of the axis in physical units is x:y:z
+
+            The input will be normalized to a unit vector.
+
+            If None, it is approximately ::
+
+                ax.set_box_aspect(aspect=(4, 4, 3), zoom=1)
+
+        zoom : float
+            Control the "zoom" of the
+
+        See Also
+        --------
+        matplotlib.axes.Axes3D.set_aspect
+            for a description of aspect handling.
+        """
+        if aspect is None:
+            aspect = zoom * np.asarray((4, 4, 3)) / 3.5
+        else:
+            aspect = np.asarray(aspect, dtype=float)
+            # default scale tuned to match the
+            aspect *= 1.829 * zoom / np.linalg.norm(aspect)
+
+        self._box_aspect = aspect
+        self.stale = True
 
     def apply_aspect(self, position=None):
         if position is None:
@@ -434,6 +467,7 @@ def get_axis_position(self):
         return xhigh, yhigh, zhigh
 
     def _on_units_changed(self, scalex=False, scaley=False, scalez=False):
+
         """
         Callback for processing changes to axis units.
 
@@ -981,8 +1015,6 @@ def set_proj_type(self, proj_type):
 
     def get_proj(self):
         """Create the projection matrix from the current viewing position."""
-        # chosen for similarity with the initial view before gh-8896
-
         # elev stores the elevation angle in the z plane
         # azim stores the azimuth angle in the x,y plane
         #
@@ -998,10 +1030,11 @@ def get_proj(self):
         # transform to uniform world coordinates 0-1, 0-1, 0-1
         worldM = proj3d.world_transformation(xmin, xmax,
                                              ymin, ymax,
-                                             zmin, zmax, pb_aspect=self.pb_aspect)
+                                             zmin, zmax,
+                                             pb_aspect=self._box_aspect)
 
         # look into the middle of the new coordinates
-        R = self.pb_aspect / 2
+        R = self._box_aspect / 2
 
         xp = R[0] + np.cos(razim) * np.cos(relev) * self.dist
         yp = R[1] + np.sin(razim) * np.cos(relev) * self.dist