Deprecate unused/undocumented functions

oscargus · oscargus · commit dc4eb4335545 · 2023-01-14T20:37:01.000+01:00
diff --git a/doc/api/next_api_changes/deprecations/24985-OG.rst b/doc/api/next_api_changes/deprecations/24985-OG.rst
@@ -0,0 +1,17 @@
+Functions in ``mpl_toolkits.mplot3d.proj3d``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The function ``transform`` is just an alias for ``proj_transform``,
+use the latter instead.
+
+The following functions are either unused (so no longer required in Matplotlib)
+or considered private. If you rely on them, please make a copy of the code,
+including all functions that starts with a ``_`` (considered private).
+
+* ``ortho_transformation``
+* ``persp_transformation``
+* ``proj_points``
+* ``proj_trans_points``
+* ``rot_x``
+* ``rotation_about_vector``
+* ``view_transformation``
diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py
@@ -148,7 +148,7 @@ def set_3d_properties(self, z=0, zdir='z'):
     @artist.allow_rasterization
     def draw(self, renderer):
         position3d = np.array((self._x, self._y, self._z))
-        proj = proj3d.proj_trans_points(
+        proj = proj3d._proj_trans_points(
             [position3d, position3d + self._dir_vec], self.axes.M)
         dx = proj[0][1] - proj[0][0]
         dy = proj[1][1] - proj[1][0]
@@ -359,7 +359,7 @@ def do_3d_projection(self):
         """
         Project the points according to renderer matrix.
         """
-        xyslist = [proj3d.proj_trans_points(points, self.axes.M)
+        xyslist = [proj3d._proj_trans_points(points, self.axes.M)
                    for points in self._segments3d]
         segments_2d = [np.column_stack([xs, ys]) for xs, ys, zs in xyslist]
         LineCollection.set_segments(self, segments_2d)
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -249,7 +249,7 @@ def _tunit_cube(self, vals=None, M=None):
         if M is None:
             M = self.M
         xyzs = self._unit_cube(vals)
-        tcube = proj3d.proj_points(xyzs, M)
+        tcube = proj3d._proj_points(xyzs, M)
         return tcube
 
     @_api.deprecated("3.7")
@@ -918,15 +918,15 @@ def get_proj(self):
         if self._focal_length == np.inf:
             # Orthographic projection
             viewM = proj3d._view_transformation_uvw(u, v, w, eye)
-            projM = proj3d.ortho_transformation(-self._dist, self._dist)
+            projM = proj3d._ortho_transformation(-self._dist, self._dist)
         else:
             # Perspective projection
             # Scale the eye dist to compensate for the focal length zoom effect
             eye_focal = R + self._dist * ps * self._focal_length
             viewM = proj3d._view_transformation_uvw(u, v, w, eye_focal)
-            projM = proj3d.persp_transformation(-self._dist,
-                                                self._dist,
-                                                self._focal_length)
+            projM = proj3d._persp_transformation(-self._dist,
+                                                 self._dist,
+                                                 self._focal_length)
 
         # Combine all the transformation matrices to get the final projection
         M0 = np.dot(viewM, worldM)
diff --git a/lib/mpl_toolkits/mplot3d/axis3d.py b/lib/mpl_toolkits/mplot3d/axis3d.py
@@ -367,7 +367,7 @@ def draw(self, renderer):
 
         # Project the edge points along the current position and
         # create the line:
-        pep = proj3d.proj_trans_points([edgep1, edgep2], self.axes.M)
+        pep = proj3d._proj_trans_points([edgep1, edgep2], self.axes.M)
         pep = np.asarray(pep)
         self.line.set_data(pep[0], pep[1])
         self.line.draw(renderer)
diff --git a/lib/mpl_toolkits/mplot3d/proj3d.py b/lib/mpl_toolkits/mplot3d/proj3d.py
@@ -5,6 +5,8 @@
 import numpy as np
 import numpy.linalg as linalg
 
+from matplotlib import _api
+
 
 def _line2d_seg_dist(p, s0, s1):
     """
@@ -51,7 +53,15 @@ def world_transformation(xmin, xmax,
                      [0,    0,    0,    1]])
 
 
+@_api.deprecated("3.8")
 def rotation_about_vector(v, angle):
+    """
+    Produce a rotation matrix for an angle in radians about a vector.
+    """
+    return _rotation_about_vector(v, angle)
+
+
+def _rotation_about_vector(v, angle):
     """
     Produce a rotation matrix for an angle in radians about a vector.
     """
@@ -101,7 +111,7 @@ def _view_axes(E, R, V, roll):
     # Save some computation for the default roll=0
     if roll != 0:
         # A positive rotation of the camera is a negative rotation of the world
-        Rroll = rotation_about_vector(w, -roll)
+        Rroll = _rotation_about_vector(w, -roll)
         u = np.dot(Rroll, u)
         v = np.dot(Rroll, v)
     return u, v, w
@@ -130,6 +140,7 @@ def _view_transformation_uvw(u, v, w, E):
     return M
 
 
+@_api.deprecated("3.8")
 def view_transformation(E, R, V, roll):
     """
     Return the view transformation matrix.
@@ -150,7 +161,12 @@ def view_transformation(E, R, V, roll):
     return M
 
 
+@_api.deprecated("3.8")
 def persp_transformation(zfront, zback, focal_length):
+    return _persp_transformation(zfront, zback, focal_length)
+
+
+def _persp_transformation(zfront, zback, focal_length):
     e = focal_length
     a = 1  # aspect ratio
     b = (zfront+zback)/(zfront-zback)
@@ -162,7 +178,12 @@ def persp_transformation(zfront, zback, focal_length):
     return proj_matrix
 
 
+@_api.deprecated("3.8")
 def ortho_transformation(zfront, zback):
+    return _ortho_transformation(zfront, zback)
+
+
+def _ortho_transformation(zfront, zback):
     # note: w component in the resulting vector will be (zback-zfront), not 1
     a = -(zfront + zback)
     b = -(zfront - zback)
@@ -218,7 +239,9 @@ def proj_transform(xs, ys, zs, M):
     return _proj_transform_vec(vec, M)
 
 
-transform = proj_transform
+transform = _api.deprecated(
+    "3.8", obj_type="function", name="transform",
+    alternative="proj_transform")(proj_transform)
 
 
 def proj_transform_clip(xs, ys, zs, M):
@@ -231,15 +254,26 @@ def proj_transform_clip(xs, ys, zs, M):
     return _proj_transform_vec_clip(vec, M)
 
 
+@_api.deprecated("3.8")
 def proj_points(points, M):
-    return np.column_stack(proj_trans_points(points, M))
+    return _proj_points(points, M)
+
 
+def _proj_points(points, M):
+    return np.column_stack(_proj_trans_points(points, M))
 
+
+@_api.deprecated("3.8")
 def proj_trans_points(points, M):
+    return _proj_trans_points(points, M)
+
+
+def _proj_trans_points(points, M):
     xs, ys, zs = zip(*points)
     return proj_transform(xs, ys, zs, M)
 
 
+@_api.deprecated("3.8")
 def rot_x(V, alpha):
     cosa, sina = np.cos(alpha), np.sin(alpha)
     M1 = np.array([[1, 0, 0, 0],
diff --git a/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py b/lib/mpl_toolkits/mplot3d/tests/test_axes3d.py
@@ -1007,7 +1007,7 @@ def _test_proj_make_M():
     roll = 0
     u, v, w = proj3d._view_axes(E, R, V, roll)
     viewM = proj3d._view_transformation_uvw(u, v, w, E)
-    perspM = proj3d.persp_transformation(100, -100, 1)
+    perspM = proj3d._persp_transformation(100, -100, 1)
     M = np.dot(perspM, viewM)
     return M
 
@@ -1074,7 +1074,7 @@ def test_proj_axes_cube_ortho():
     roll = 0
     u, v, w = proj3d._view_axes(E, R, V, roll)
     viewM = proj3d._view_transformation_uvw(u, v, w, E)
-    orthoM = proj3d.ortho_transformation(-1, 1)
+    orthoM = proj3d._ortho_transformation(-1, 1)
     M = np.dot(orthoM, viewM)
 
     ts = '0 1 2 3 0 4 5 6 7 4'.split()
@@ -1095,16 +1095,6 @@ def test_proj_axes_cube_ortho():
     ax.set_ylim(-200, 200)
 
 
-def test_rot():
-    V = [1, 0, 0, 1]
-    rotated_V = proj3d.rot_x(V, np.pi / 6)
-    np.testing.assert_allclose(rotated_V, [1, 0, 0, 1])
-
-    V = [0, 1, 0, 1]
-    rotated_V = proj3d.rot_x(V, np.pi / 6)
-    np.testing.assert_allclose(rotated_V, [0, np.sqrt(3) / 2, 0.5, 1])
-
-
 def test_world():
     xmin, xmax = 100, 120
     ymin, ymax = -100, 100
