Code review updates

scottshambaugh · scottshambaugh · commit 978889b674ca · 2023-04-29T13:52:37.000-06:00
diff --git a/doc/users/next_whats_new/3d_axis_limits.rst b/doc/users/next_whats_new/3d_axis_limits.rst
@@ -0,0 +1,17 @@
+Setting 3D axis limits now set the limits exactly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously, setting the limits of a 3D axis would always add a small margin to
+the limits. Limits are now set exactly by default. The newly introduced rcparam
+``axes3d.automargin`` can be used to revert to the old behavior.
+
+.. plot::
+    :include-source: true
+    :alt: Example of the new behavior of 3D axis limits, and how setting the rcparam reverts to the old behavior.
+
+    import matplotlib.pyplot as plt
+    fig, axs = plt.subplots(1, 2, subplot_kw={'projection': '3d'})
+    plt.rcParams['axes3d.automargin'] = False  # default in 3.8.0
+    axs[0].set(xlim=(0, 1), ylim=(0, 1), zlim=(0, 1), title='New Behavior')
+    plt.rcParams['axes3d.automargin'] = True
+    axs[1].set(xlim=(0, 1), ylim=(0, 1), zlim=(0, 1), title='Old Behavior')
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -829,14 +829,13 @@ def _get_autoscale_on(self):
     def _set_autoscale_on(self, b):
         """
         Set whether this Axis is autoscaled when drawing or by
-        `.Axes.autoscale_view`. If b is None, then the value is not changed.
+        `.Axes.autoscale_view`.
 
         Parameters
         ----------
         b : bool
         """
-        if b is not None:
-            self._autoscale_on = b
+        self._autoscale_on = b
 
     def get_children(self):
         return [self.label, self.offsetText,
@@ -1220,7 +1219,8 @@ def _set_lim(self, v0, v1, *, emit=True, auto):
         # Mark viewlims as no longer stale without triggering an autoscale.
         for ax in self._get_shared_axes():
             ax._stale_viewlims[name] = False
-        self._set_autoscale_on(auto)
+        if auto is not None:
+            self._set_autoscale_on(bool(auto))
 
         if emit:
             self.axes.callbacks.process(f"{name}lim_changed", self.axes)
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -2077,7 +2077,8 @@ def _raw_ticks(self, vmin, vmax):
 
         raw_step = ((_vmax - _vmin) / nbins)
         if hasattr(self.axis, "axes") and self.axis.axes.name == '3d':
-            raw_step = raw_step * 23/24  # needed to match mpl3.7 appearance
+            # scale factor of 0.9583333333333333 = 23/24 to match mpl3.7
+            raw_step = raw_step * 0.9583333333333333
         large_steps = steps >= raw_step
         if mpl.rcParams['axes.autolimit_mode'] == 'round_numbers':
             # Classic round_numbers mode may require a larger step.
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -129,7 +129,9 @@ def __init__(
 
         self.xy_viewLim = Bbox.unit()
         self.zz_viewLim = Bbox.unit()
-        xymargin = 0.05 * 10/11  # match mpl3.7 appearance
+
+        # default xymargin of 0.05 * 10/11 is to match mpl3.7 appearance
+        xymargin = 0.045454545454545454
         self.xy_dataLim = Bbox([[xymargin, xymargin],
                                 [1 - xymargin, 1 - xymargin]])
         # z-limits are encoded in the x-component of the Bbox, y is un-used
@@ -159,7 +161,8 @@ def __init__(
         self.set_axis_on()
         self.M = None
 
-        self._view_margin = 1/48  # default value to match mpl3.7
+        # default _view_margin is 1/48 to match mpl37
+        self._view_margin = 0.020833333333333332
         self.autoscale_view()
 
         # func used to format z -- fall back on major formatters
@@ -410,8 +413,9 @@ def set_box_aspect(self, aspect, *, zoom=1):
         else:
             aspect = np.asarray(aspect, dtype=float)
             _api.check_shape((3,), aspect=aspect)
-        # default scale tuned to match the mpl3.2 appearance.
-        aspect *= 1.8294640721620434 * 25/24 * zoom / np.linalg.norm(aspect)
+        # default scale tuned to match the mpl3.2 appearance
+        # 1.9056917418354617 = 1.8294640721620434 * 25/24
+        aspect *= 1.9056917418354617 * zoom / np.linalg.norm(aspect)
 
         self._box_aspect = aspect
         self.stale = True
@@ -581,17 +585,17 @@ def autoscale(self, enable=True, axis='both', tight=None):
             scalez = True
         else:
             if axis in ['x', 'both']:
-                self.set_autoscalex_on(enable)
+                self.set_autoscalex_on(bool(enable))
                 scalex = self.get_autoscalex_on()
             else:
                 scalex = False
             if axis in ['y', 'both']:
-                self.set_autoscaley_on(enable)
+                self.set_autoscaley_on(bool(enable))
                 scaley = self.get_autoscaley_on()
             else:
                 scaley = False
             if axis in ['z', 'both']:
-                self.set_autoscalez_on(enable)
+                self.set_autoscalez_on(bool(enable))
                 scalez = self.get_autoscalez_on()
             else:
                 scalez = False
@@ -700,20 +704,61 @@ def _set_bound3d(self, get_bound, set_lim, axis_inverted,
                 auto=None, view_margin=view_margin)
 
     def set_xbound(self, lower=None, upper=None, view_margin=None):
-        # docstring inherited
+        """
+        Set the lower and upper numerical bounds of the x-axis.
+
+        This method will honor axis inversion regardless of parameter order.
+        It will not change the autoscaling setting (`.get_autoscalex_on()`).
+
+        Parameters
+        ----------
+        lower, upper : float or None
+            The lower and upper bounds. If *None*, the respective axis bound
+            is not modified.
+        view_margin : float or None
+            The margin to apply to the bounds. If *None*, the margin is handled
+            by `set_xlim`.
+
+        See Also
+        --------
+        get_xbound
+        get_xlim, set_xlim
+        invert_xaxis, xaxis_inverted
+        """
         self._set_bound3d(self.get_xbound, self.set_xlim, self.xaxis_inverted,
                           lower, upper, view_margin)
 
     def set_ybound(self, lower=None, upper=None, view_margin=None):
-        # docstring inherited
+        """
+        Set the lower and upper numerical bounds of the y-axis.
+
+        This method will honor axis inversion regardless of parameter order.
+        It will not change the autoscaling setting (`.get_autoscaley_on()`).
+
+        Parameters
+        ----------
+        lower, upper : float or None
+            The lower and upper bounds. If *None*, the respective axis bound
+            is not modified.
+        view_margin : float or None
+            The margin to apply to the bounds. If *None*, the margin is handled
+            by `set_ylim`.
+
+        See Also
+        --------
+        get_ybound
+        get_ylim, set_ylim
+        invert_yaxis, yaxis_inverted
+        """
         self._set_bound3d(self.get_ybound, self.set_ylim, self.yaxis_inverted,
                           lower, upper, view_margin)
 
     def set_zbound(self, lower=None, upper=None, view_margin=None):
         """
         Set the lower and upper numerical bounds of the z-axis.
+
         This method will honor axis inversion regardless of parameter order.
-        It will not change the autoscaling setting (`.get_autoscaley_on()`).
+        It will not change the autoscaling setting (`.get_autoscalez_on()`).
 
         Parameters
         ----------
@@ -722,7 +767,7 @@ def set_zbound(self, lower=None, upper=None, view_margin=None):
             is not modified.
         view_margin : float or None
             The margin to apply to the bounds. If *None*, the margin is handled
-            by set_zlim.
+            by `set_zlim`.
 
         See Also
         --------
@@ -737,6 +782,7 @@ def _set_lim3d(self, axis, lower=None, upper=None, *, emit=True,
                    auto=False, view_margin=None, axmin=None, axmax=None):
         """
         Set 3D axis limits.
+
         See `.Axes.set_ylim` for full documentation
         """
         if upper is None:
@@ -770,6 +816,7 @@ def set_xlim(self, left=None, right=None, *, emit=True, auto=False,
                  view_margin=None, xmin=None, xmax=None):
         """
         Set 3D x limits.
+
         See `~.Axes.set_xlim` for full documentation
         """
         return self._set_lim3d(self.xaxis, left, right, emit=emit, auto=auto,
@@ -779,6 +826,7 @@ def set_ylim(self, bottom=None, top=None, *, emit=True, auto=False,
                  view_margin=None, ymin=None, ymax=None):
         """
         Set 3D y limits.
+
         See `~.Axes.set_ylim` for full documentation
         """
         return self._set_lim3d(self.yaxis, bottom, top, emit=emit, auto=auto,
@@ -788,6 +836,7 @@ def set_zlim(self, bottom=None, top=None, *, emit=True, auto=False,
                  view_margin=None, zmin=None, zmax=None):
         """
         Set 3D z limits.
+
         See `~.Axes.set_ylim` for full documentation
         """
         return self._set_lim3d(self.zaxis, bottom, top, emit=emit, auto=auto,
@@ -1080,12 +1129,15 @@ def clear(self):
         else:
             self._zmargin = 0.
 
-        xymargin = 0.05 * 10/11  # match mpl3.7 appearance
+        # default xymargin of 0.05 * 10/11 is to match mpl3.7 appearance
+        xymargin = 0.045454545454545454
         self.xy_dataLim = Bbox([[xymargin, xymargin],
                                 [1 - xymargin, 1 - xymargin]])
         # z-limits are encoded in the x-component of the Bbox, y is un-used
         self.zz_dataLim = Bbox.unit()
-        self._view_margin = 1/48  # default value to match mpl3.7
+
+        # default _view_margin is 1/48 to match mpl37
+        self._view_margin = 0.020833333333333333
         self.autoscale_view()
 
         self.grid(mpl.rcParams['axes3d.grid'])
@@ -2988,7 +3040,7 @@ def errorbar(self, x, y, z, zerr=None, yerr=None, xerr=None, fmt='',
             lower limits. In that case a caret symbol is used to indicate
             this. *lims*-arguments may be scalars, or array-likes of the same
             length as the errors. To use limits with inverted axes,
-            `~.Axes.set_xlim`, `~.Axes.set_ylim`, or `~.Axes.set_ylim` must be
+            `~.Axes.set_xlim`, `~.Axes.set_ylim`, or `~.Axes.set_zlim` must be
             called before `errorbar`. Note the tricky parameter names: setting
             e.g. *ylolims* to True means that the y-value is a *lower* limit of
             the True value, so, only an *upward*-pointing arrow will be drawn!
diff --git a/lib/mpl_toolkits/mplot3d/axis3d.py b/lib/mpl_toolkits/mplot3d/axis3d.py
@@ -325,7 +325,8 @@ def draw(self, renderer):
 
         mins, maxs, tc, highs = self._get_coord_info()
         centers = 0.5 * (maxs + mins)
-        deltas = (maxs - mins) * 1/12 * 23/24  # keep mpl3.7 appearance
+        # scale factor of 0.0798611111111111 = 1/12 * 23/24
+        deltas = (maxs - mins) * 0.0798611111111111  # keep mpl3.7 appearance
 
         minmax = np.where(highs, maxs, mins)
         maxmin = np.where(~highs, maxs, mins)
