diff --git a/doc/api/next_api_changes/deprecations/24985-OG.rst b/doc/api/next_api_changes/deprecations/24985-OG.rst new file mode 100644 index 000000000000..5662d5f3ef28 --- /dev/null +++ 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 index 14511f4a8c2d..63cfe9a1cf1e 100644 --- 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 index f9a48136285a..a1d541a477c6 100644 --- 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 index 3d75aabb65eb..d6d50fd953b9 100644 --- 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 index 646a19781e40..a1692ea15baf 100644 --- 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 index 2ff7d428291c..50634adc5b95 100644 --- 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