matplotlib · anntzer · Feb 12, 2019 · Aug 18, 2018 · Dec 20, 2018 · Dec 20, 2018
diff --git a/doc/api/api_changes/2018-12-20-AL-deprecations.rst b/doc/api/api_changes/2018-12-20-AL-deprecations.rst
@@ -0,0 +1,5 @@
+Deprecations
+````````````
+
+Multiple internal functions that were exposed as part of the public API
+of ``mpl_toolkits.mplot3d`` are deprecated.
diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py
@@ -20,22 +20,34 @@
 from . import proj3d
 
 
-def norm_angle(a):
+def _norm_angle(a):
     """Return the given angle normalized to -180 < *a* <= 180 degrees."""
     a = (a + 360) % 360
     if a > 180:
         a = a - 360
     return a
 
 
-def norm_text_angle(a):
+@cbook.deprecated("3.1")
+def norm_angle(a):
+    """Return the given angle normalized to -180 < *a* <= 180 degrees."""
+    return _norm_angle(a)
+
+
+def _norm_text_angle(a):
     """Return the given angle normalized to -90 < *a* <= 90 degrees."""
     a = (a + 180) % 180
     if a > 90:
         a = a - 180
     return a
 
 
+@cbook.deprecated("3.1")
+def norm_text_angle(a):
+    """Return the given angle normalized to -90 < *a* <= 90 degrees."""
+    return _norm_text_angle(a)
+
+
 def get_dir_vector(zdir):
     """
     Return a direction vector.
@@ -109,7 +121,7 @@ def draw(self, renderer):
         dy = proj[1][1] - proj[1][0]
         angle = math.degrees(math.atan2(dy, dx))
         self.set_position((proj[0][0], proj[1][0]))
-        self.set_rotation(norm_text_angle(angle))
+        self.set_rotation(_norm_text_angle(angle))
         mtext.Text.draw(self, renderer)
         self.stale = False
 
@@ -166,7 +178,7 @@ def line_2d_to_3d(line, zs=0, zdir='z'):
     line.set_3d_properties(zs, zdir)
 
 
-def path_to_3d_segment(path, zs=0, zdir='z'):
+def _path_to_3d_segment(path, zs=0, zdir='z'):
     """Convert a path to a 3D segment."""
 
     zs = np.broadcast_to(zs, len(path))
@@ -176,16 +188,28 @@ def path_to_3d_segment(path, zs=0, zdir='z'):
     return seg3d
 
 
-def paths_to_3d_segments(paths, zs=0, zdir='z'):
+@cbook.deprecated("3.1")
+def path_to_3d_segment(path, zs=0, zdir='z'):
+    """Convert a path to a 3D segment."""
+    return _path_to_3d_segment(path, zs=zs, zdir=zdir)
+
+
+def _paths_to_3d_segments(paths, zs=0, zdir='z'):
     """Convert paths from a collection object to 3D segments."""
 
     zs = np.broadcast_to(zs, len(paths))
-    segs = [path_to_3d_segment(path, pathz, zdir)
+    segs = [_path_to_3d_segment(path, pathz, zdir)
             for path, pathz in zip(paths, zs)]
     return segs
 
 
-def path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
+@cbook.deprecated("3.1")
+def paths_to_3d_segments(paths, zs=0, zdir='z'):
+    """Convert paths from a collection object to 3D segments."""
+    return _paths_to_3d_segments(paths, zs=zs, zdir=zdir)
+
+
+def _path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
     """Convert a path to a 3D segment with path codes."""
 
     zs = np.broadcast_to(zs, len(path))
@@ -200,13 +224,19 @@ def path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
     return seg3d, list(codes)
 
 
-def paths_to_3d_segments_with_codes(paths, zs=0, zdir='
10000
z'):
+@cbook.deprecated("3.1")
+def path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
+    """Convert a path to a 3D segment with path codes."""
+    return _path_to_3d_segment_with_codes(path, zs=zs, zdir=zdir)
+
+
+def _paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):
     """
     Convert paths from a collection object to 3D segments with path codes.
     """
 
     zs = np.broadcast_to(zs, len(paths))
-    segments_codes = [path_to_3d_segment_with_codes(path, pathz, zdir)
+    segments_codes = [_path_to_3d_segment_with_codes(path, pathz, zdir)
                       for path, pathz in zip(paths, zs)]
     if segments_codes:
         segments, codes = zip(*segments_codes)
@@ -215,6 +245,14 @@ def paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):
     return list(segments), list(codes)
 
 
+@cbook.deprecated("3.1")
+def paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):
+    """
+    Convert paths from a collection object to 3D segments with path codes.
+    """
+    return _paths_to_3d_segments_with_codes(paths, zs=zs, zdir=zdir)
+
+
 class Line3DCollection(LineCollection):
     """
     A collection of 3D lines.
@@ -257,7 +295,7 @@ def draw(self, renderer, project=False):
 
 def line_collection_2d_to_3d(col, zs=0, zdir='z'):
     """Convert a LineCollection to a Line3DCollection object."""
-    segments3d = paths_to_3d_segments(col.get_paths(), zs, zdir)
+    segments3d = _paths_to_3d_segments(col.get_paths(), zs, zdir)
     col.__class__ = Line3DCollection
     col.set_segments(segments3d)
 
@@ -316,7 +354,7 @@ def do_3d_projection(self, renderer):
         return min(vzs)
 
 
-def get_patch_verts(patch):
+def _get_patch_verts(patch):
     """Return a list of vertices for the path of a patch."""
     trans = patch.get_patch_transform()
     path = patch.get_path()
@@ -327,9 +365,15 @@ def get_patch_verts(patch):
         return []
 
 
+@cbook.deprecated("3.1")
+def get_patch_verts(patch):
+    """Return a list of vertices for the path of a patch."""
+    return _get_patch_verts(patch)
+
+
 def patch_2d_to_3d(patch, z=0, zdir='z'):
     """Convert a Patch to a Patch3D object."""
-    verts = get_patch_verts(patch)
+    verts = _get_patch_verts(patch)
     patch.__class__ = Patch3D
     patch.set_3d_properties(verts, z, zdir)
 
@@ -393,12 +437,12 @@ def do_3d_projection(self, renderer):
         xs, ys, zs = self._offsets3d
         vxs, vys, vzs, vis = proj3d.proj_transform_clip(xs, ys, zs, renderer.M)
 
-        fcs = (zalpha(self._facecolor3d, vzs) if self._depthshade else
+        fcs = (_zalpha(self._facecolor3d, vzs) if self._depthshade else
                self._facecolor3d)
         fcs = mcolors.to_rgba_array(fcs, self._alpha)
         self.set_facecolors(fcs)
 
-        ecs = (zalpha(self._edgecolor3d, vzs) if self._depthshade else
+        ecs = (_zalpha(self._edgecolor3d, vzs) if self._depthshade else
                self._edgecolor3d)
         ecs = mcolors.to_rgba_array(ecs, self._alpha)
         self.set_edgecolors(ecs)
@@ -459,12 +503,12 @@ def do_3d_projection(self, renderer):
         xs, ys, zs = self._offsets3d
         vxs, vys, vzs, vis = proj3d.proj_transform_clip(xs, ys, zs, renderer.M)
 
-        fcs = (zalpha(self._facecolor3d, vzs) if self._depthshade else
+        fcs = (_zalpha(self._facecolor3d, vzs) if self._depthshade else
                self._facecolor3d)
         fcs = mcolors.to_rgba_array(fcs, self._alpha)
         self.set_facecolors(fcs)
 
-        ecs = (zalpha(self._edgecolor3d, vzs) if self._depthshade else
+        ecs = (_zalpha(self._edgecolor3d, vzs) if self._depthshade else
                self._edgecolor3d)
         ecs = mcolors.to_rgba_array(ecs, self._alpha)
         self.set_edgecolors(ecs)
@@ -609,7 +653,7 @@ def do_3d_projection(self, renderer):
             self.update_scalarmappable()
             self._facecolors3d = self._facecolors
 
-        txs, tys, tzs = proj3d.proj_transform_vec(self._vec, renderer.M)
+        txs, tys, tzs = proj3d._proj_transform_vec(self._vec, renderer.M)
         xyzlist = [(txs[si:ei], tys[si:ei], tzs[si:ei])
                    for si, ei in self._segis]
 
@@ -647,7 +691,7 @@ def do_3d_projection(self, renderer):
         # Return zorder value
         if self._sort_zpos is not None:
             zvec = np.array([[0], [0], [self._sort_zpos], [1]])
-            ztrans = proj3d.proj_transform_vec(zvec, renderer.M)
+            ztrans = proj3d._proj_transform_vec(zvec, renderer.M)
             return ztrans[2][0]
         elif tzs.size > 0:
             # FIXME: Some results still don't look quite right.
@@ -700,8 +744,8 @@ def get_edgecolor(self):
 
 def poly_collection_2d_to_3d(col, zs=0, zdir='z'):
     """Convert a PolyCollection to a Poly3DCollection object."""
-    segments_3d, codes = paths_to_3d_segments_with_codes(col.get_paths(),
-                                                         zs, zdir)
+    segments_3d, codes = _paths_to_3d_segments_with_codes(
+            col.get_paths(), zs, zdir)
     col.__class__ = Poly3DCollection
     col.set_verts_and_codes(segments_3d, codes)
     col.set_3d_properties()
@@ -743,22 +787,34 @@ def rotate_axes(xs, ys, zs, zdir):
         return xs, ys, zs
 
 
-def get_colors(c, num):
+def _get_colors(c, num):
     """Stretch the color argument to provide the required number *num*."""
     return np.broadcast_to(
         mcolors.to_rgba_array(c) if len(c) else [0, 0, 0, 0],
         (num, 4))
 
 
-def zalpha(colors, zs):
+@cbook.deprecated("3.1")
+def get_colors(c, num):
+    """Stretch the color argument to provide the required number *num*."""
+    return _get_colors(c, num)
+
+
+def _zalpha(colors, zs):
     """Modify the alphas of the color list according to depth."""
     # FIXME: This only works well if the points for *zs* are well-spaced
     #        in all three dimensions. Otherwise, at certain orientations,
     #        the min and max zs are very close together.
     #        Should really normalize against the viewing depth.
-    colors = get_colors(colors, len(zs))
+    colors = _get_colors(colors, len(zs))
     if len(zs):
         norm = Normalize(min(zs), max(zs))
         sats = 1 - norm(zs) * 0.7
         colors = [(c[0], c[1], c[2], c[3] * s) for c, s in zip(colors, sats)]
     return colors
+
+
+@cbook.deprecated("3.1")
+def zalpha(colors, zs):
+    """Modify the alphas of the color list according to depth."""
+    return _zalpha(colors, zs)
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1030,7 +1030,7 @@ def get_proj(self):
 
         self.eye = E
         self.vvec = R - E
-        self.vvec = self.vvec / proj3d.mod(self.vvec)
+        self.vvec = self.vvec / proj3d._mod(self.vvec)
 
         if abs(relev) > np.pi/2:
             # upside down
@@ -1216,8 +1216,8 @@ def _on_move(self, event):
             # get the x and y pixel coords
             if dx == 0 and dy == 0:
                 return
-            self.elev = art3d.norm_angle(self.elev - (dy/h)*180)
-            self.azim = art3d.norm_angle(self.azim - (dx/w)*180)
+            self.elev = art3d._norm_angle(self.elev - (dy/h)*180)
+            self.azim = art3d._norm_angle(self.azim - (dx/w)*180)
             self.get_proj()
             self.stale = True
             self.figure.canvas.draw_idle()
@@ -1768,8 +1768,8 @@ def _shade_colors(self, color, normals, lightsource=None):
             # chosen for backwards-compatibility
             lightsource = LightSource(azdeg=225, altdeg=19.4712)
 
-        shade = np.array([np.dot(n / proj3d.mod(n), lightsource.direction)
-                          if proj3d.mod(n) else np.nan
+        shade = np.array([np.dot(n / proj3d._mod(n), lightsource.direction)
+                          if proj3d._mod(n) else np.nan
                           for n in normals])
         mask = ~np.isnan(shade)
 
@@ -2376,7 +2376,7 @@ def bar(self, left, height, zs=0, zdir='z', *args, **kwargs):
         verts = []
         verts_zs = []
         for p, z in zip(patches, zs):
-            vs = art3d.get_patch_verts(p)
+            vs = art3d._get_patch_verts(p)
             verts += vs.tolist()
             verts_zs += [z] * len(vs)
             art3d.patch_2d_to_3d(p, z, zdir)

diff --git a/lib/mpl_toolkits/mplot3d/axis3d.py b/lib/mpl_toolkits/mplot3d/axis3d.py
@@ -296,7 +296,7 @@ def draw(self, renderer):
                                               renderer.M)
         self.label.set_position((tlx, tly))
         if self.get_rotate_label(self.label.get_text()):
-            angle = art3d.norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
+            angle = art3d._norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
             self.label.set_rotation(angle)
         self.label.set_va(info['label']['va'])
         self.label.set_ha(info['label']['ha'])
@@ -319,7 +319,7 @@ def draw(self, renderer):
             pos[0], pos[1], pos[2], renderer.M)
         self.offsetText.set_text(self.major.formatter.get_offset())
         self.offsetText.set_position((olx, oly))
-        angle = art3d.norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
+        angle = art3d._norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
         self.offsetText.set_rotation(angle)
         # Must set rotation mode to "anchor" so that
         # the alignment point is used as the "fulcrum" for rotation.