Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Deprecate internal functions exposed in the public API of mplot3d #13030

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Feb 12, 2019
Merged

Deprecate internal functions exposed in the public API of mplot3d #13030

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ae83f2c
Deprecate functions in art3d.py
rth Aug 18, 2018
8147734
More deprecations in proj3d
rth Dec 20, 2018
e4a983f
Add API change entry
rth Dec 20, 2018
4bc0e4a
List all deprecated fuctions
rth Jan 22, 2019
a55a4ea
Fix missing uses of deprecated functions
rth Jan 22, 2019
661deec
Suggest vendoring in the deprecation notice
rth Jan 22, 2019
9f11f64
Merge branch 'master' into private-funcs-mplot3d
rth Feb 12, 2019
f406cc1
Lint
rth Feb 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions doc/api/api_changes/2018-12-20-AL-deprecations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
Deprecations
````````````

Multiple internal functions that were exposed as part of the public API
of ``mpl_toolkits.mplot3d`` are deprecated,

**mpl_toolkits.mplot3d.art3d**

- :func:`mpl_toolkits.mplot3d.art3d.norm_angle`
- :func:`mpl_toolkits.mplot3d.art3d.norm_text_angle`
- :func:`mpl_toolkits.mplot3d.art3d.path_to_3d_segment`
- :func:`mpl_toolkits.mplot3d.art3d.paths_to_3d_segments`
- :func:`mpl_toolkits.mplot3d.art3d.path_to_3d_segment_with_codes`
- :func:`mpl_toolkits.mplot3d.art3d.paths_to_3d_segments_with_codes`
- :func:`mpl_toolkits.mplot3d.art3d.get_patch_verts`
- :func:`mpl_toolkits.mplot3d.art3d.get_colors`
- :func:`mpl_toolkits.mplot3d.art3d.zalpha`

**mpl_toolkits.mplot3d.proj3d**

- :func:`mpl_toolkits.mplot3d.proj3d.line2d`
- :func:`mpl_toolkits.mplot3d.proj3d.line2d_dist`
- :func:`mpl_toolkits.mplot3d.proj3d.line2d_seg_dist`
- :func:`mpl_toolkits.mplot3d.proj3d.mod`
- :func:`mpl_toolkits.mplot3d.proj3d.proj_transform_vec`
- :func:`mpl_toolkits.mplot3d.proj3d.proj_transform_vec_clip`
- :func:`mpl_toolkits.mplot3d.proj3d.vec_pad_ones`
- :func:`mpl_toolkits.mplot3d.proj3d.proj_trans_clip_points`

If your project relies on these functions, consider vendoring them.
100 changes: 78 additions & 22 deletions lib/mpl_toolkits/mplot3d/art3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -200,7 +212,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))
Expand All @@ -210,16 +222,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))
Expand All @@ -234,13 +258,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='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)
Expand All @@ -249,6 +279,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.
Expand Down Expand Up @@ -291,7 +329,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)

Expand Down Expand Up @@ -350,7 +388,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()
Expand All @@ -361,9 +399,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)

Expand Down Expand Up @@ -427,12 +471,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)
Expand Down Expand Up @@ -493,12 +537,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)
Expand Down Expand Up @@ -643,7 +687,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]

Expand Down Expand Up @@ -681,7 +725,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.
Expand Down Expand Up @@ -734,8 +778,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()
Expand Down Expand Up @@ -777,14 +821,20 @@ 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,
Expand All @@ -796,3 +846,9 @@ def zalpha(colors, zs):
sats = 1 - norm(zs) * 0.7
rgba = np.broadcast_to(mcolors.to_rgba_array(colors), (len(zs), 4))
return np.column_stack([rgba[:, :3], rgba[:, 3] * sats])


@cbook.deprecated("3.1")
def zalpha(colors, zs):
"""Modify the alphas of the color list according to depth."""
return _zalpha(colors, zs)
18 changes: 9 additions & 9 deletions lib/mpl_toolkits/mplot3d/axes3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1027,7 +1027,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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is going to conflict with #13020.

Copy link
Contributor

@anntzer anntzer Feb 6, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll rebase #13020 on top of this after this is merged.


if abs(relev) > np.pi/2:
# upside down
Expand Down Expand Up @@ -1162,7 +1162,7 @@ def format_coord(self, xd, yd):

# nearest edge
p0, p1 = min(self.tunit_edges(),
key=lambda edge: proj3d.line2d_seg_dist(
key=lambda edge: proj3d._line2d_seg_dist(
edge[0], edge[1], (xd, yd)))

# scale the z value to match
Expand Down Expand Up @@ -1209,8 +1209,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()
Expand Down Expand Up @@ -1762,8 +1762,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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Going to conflict with #13020

for n in normals])
mask = ~np.isnan(shade)

Expand Down Expand Up @@ -2029,8 +2029,8 @@ def _3d_extend_contour(self, cset, stride=5):
paths = linec.get_paths()
if not paths:
continue
topverts = art3d.paths_to_3d_segments(paths, z - dz)
botverts = art3d.paths_to_3d_segments(paths, z + dz)
topverts = art3d._paths_to_3d_segments(paths, z - dz)
botverts = art3d._paths_to_3d_segments(paths, z + dz)

color = linec.get_color()[0]

Expand Down Expand Up @@ -2394,7 +2394,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)
Expand Down
4 changes: 2 additions & 2 deletions lib/mpl_toolkits/mplot3d/axis3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -298,7 +298,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'])
Expand All @@ -321,7 +321,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.
Expand Down
Loading