8000 Merge pull request #13030 from rth/private-funcs-mplot3d · matplotlib/matplotlib@b6e8c19 · GitHub
[go: up one dir, main page]
Skip to content

Commit b6e8c19

Browse files
anntzeranntzer
authored
Merge pull request #13030 from rth/private-funcs-mplot3d
Deprecate internal functions exposed in the public API of mplot3d
2 parents ef48cef + f406cc1 commit b6e8c19

File tree

6 files changed

+229
-47
lines changed

6 files changed

+229
-47
lines changed

‎doc/api/api_changes/2018-12-20-AL-deprecations.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Deprecations
2+
````````````
3+
4+
Multiple internal functions that were exposed as part of the public API
5+
of ``mpl_toolkits.mplot3d`` are deprecated,
6+
7+
**mpl_toolkits.mplot3d.art3d**
8+
9+
- :func:`mpl_toolkits.mplot3d.art3d.norm_angle`
10+
- :func:`mpl_toolkits.mplot3d.art3d.norm_text_angle`
11+
- :func:`mpl_toolkits.mplot3d.art3d.path_to_3d_segment`
12+
- :func:`mpl_toolkits.mplot3d.art3d.paths_to_3d_segments`
13+
- :func:`mpl_toolkits.mplot3d.art3d.path_to_3d_segment_with_codes`
14+
- :func:`mpl_toolkits.mplot3d.art3d.paths_to_3d_segments_with_codes`
15+
- :func:`mpl_toolkits.mplot3d.art3d.get_patch_verts`
16+
- :func:`mpl_toolkits.mplot3d.art3d.get_colors`
17+
- :func:`mpl_toolkits.mplot3d.art3d.zalpha`
18+
19+
**mpl_toolkits.mplot3d.proj3d**
20+
21+
- :func:`mpl_toolkits.mplot3d.proj3d.line2d`
22+
- :func:`mpl_toolkits.mplot3d.proj3d.line2d_dist`
23+
- :func:`mpl_toolkits.mplot3d.proj3d.line2d_seg_dist`
24+
- :func:`mpl_toolkits.mplot3d.proj3d.mod`
25+
- :func:`mpl_toolkits.mplot3d.proj3d.proj_transform_vec`
26+
- :func:`mpl_toolkits.mplot3d.proj3d.proj_transform_vec_clip`
27+
- :func:`mpl_toolkits.mplot3d.proj3d.vec_pad_ones`
28+
- :func:`mpl_toolkits.mplot3d.proj3d.proj_trans_clip_points`
29+
30+
If your project relies on these functions, consider vendoring them.

‎lib/mpl_toolkits/mplot3d/art3d.py

Lines changed: 78 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -20,22 +20,34 @@
2020
from . import proj3d
2121

2222

23-
def norm_angle(a):
23+
def _norm_angle(a):
2424
"""Return the given angle normalized to -180 < *a* <= 180 degrees."""
2525
a = (a + 360) % 360
2626
if a > 180:
2727
a = a - 360
2828
return a
2929

3030

31-
def norm_text_angle(a):
31+
@cbook.deprecated("3.1")
32+
def norm_angle(a):
33+
"""Return the given angle normalized to -180 < *a* <= 180 degrees."""
34+
return _norm_angle(a)
35+
36+
37+
def _norm_text_angle(a):
3238
"""Return the given angle normalized to -90 < *a* <= 90 degrees."""
3339
a = (a + 180) % 180
3440
if a > 90:
3541
a = a - 180
3642
return a
3743

3844

45+
@cbook.deprecated("3.1")
46+
def norm_text_angle(a):
47+
"""Return the given angle normalized to -90 < *a* <= 90 degrees."""
48+
return _norm_text_angle(a)
49+
50+
3951
def get_dir_vector(zdir):
4052
"""
4153
Return a direction vector.
@@ -109,7 +121,7 @@ def draw(self, renderer):
109121
dy = proj[1][1] - proj[1][0]
110122
angle = math.degrees(math.atan2(dy, dx))
111123
self.set_position((proj[0][0], proj[1][0]))
112-
self.set_rotation(norm_text_angle(angle))
124+
self.set_rotation(_norm_text_angle(angle))
113125
mtext.Text.draw(self, renderer)
114126
self.stale = False
115127

@@ -200,7 +212,7 @@ def line_2d_to_3d(line, zs=0, zdir='z'):
200212
line.set_3d_properties(zs, zdir)
201213

202214

203-
def path_to_3d_segment(path, zs=0, zdir='z'):
215+
def _path_to_3d_segment(path, zs=0, zdir='z'):
204216
"""Convert a path to a 3D segment."""
205217

206218
zs = np.broadcast_to(zs, len(path))
@@ -210,16 +222,28 @@ def path_to_3d_segment(path, zs=0, zdir='z'):
210222
return seg3d
211223

212224

213-
def paths_to_3d_segments(paths, zs=0, zdir='z'):
225+
@cbook.deprecated("3.1")
226+
def path_to_3d_segment(path, zs=0, zdir='z'):
227+
"""Convert a path to a 3D segment."""
228+
return _path_to_3d_segment(path, zs=zs, zdir=zdir)
229+
230+
231+
def _paths_to_3d_segments(paths, zs=0, zdir='z'):
214232
"""Convert paths from a collection object to 3D segments."""
215233

216234
zs = np.broadcast_to(zs, len(paths))
217-
segs = [path_to_3d_segment(path, pathz, zdir)
235+
segs = [_path_to_3d_segment(path, pathz, zdir)
218236
for path, pathz in zip(paths, zs)]
219237
return segs
220238

221239

222-
def path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
240+
@cbook.deprecated("3.1")
241+
def paths_to_3d_segments(paths, zs=0, zdir='z'):
242+
"""Convert paths from a collection object to 3D segments."""
243+
return _paths_to_3d_segments(paths, zs=zs, zdir=zdir)
244+
245+
246+
def _path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
223247
"""Convert a path to a 3D segment with path codes."""
224248

225249
zs = np.broadcast_to(zs, len(path))
@@ -234,13 +258,19 @@ def path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
234258
return seg3d, list(codes)
235259

236260

237-
def paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):
261+
@cbook.deprecated("3.1")
262+
def path_to_3d_segment_with_codes(path, zs=0, zdir='z'):
263+
"""Convert a path to a 3D segment with path codes."""
264+
return _path_to_3d_segment_with_codes(path, zs=zs, zdir=zdir)
265+
266+
267+
def _paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):
238268
"""
239269
Convert paths from a collection object to 3D segments with path codes.
240270
"""
241271

242272
zs = np.broadcast_to(zs, len(paths))
243-
segments_codes = [path_to_3d_segment_with_codes(path, pathz, zdir)
273+
segments_codes = [_path_to_3d_segment_with_codes(path, pathz, zdir)
244274
for path, pathz in zip(paths, zs)]
245275
if segments_codes:
246276
segments, codes = zip(*segments_codes)
@@ -249,6 +279,14 @@ def paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):
249279
return list(segments), list(codes)
250280

251281

282+
@cbook.deprecated("3.1")
283+
def paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'):
284+
"""
285+
Convert paths from a collection object to 3D segments with path codes.
286+
"""
287+
return _paths_to_3d_segments_with_codes(paths, zs=zs, zdir=zdir)
288+
289+
252290
class Line3DCollection(LineCollection):
253291
"""
254292
A collection of 3D lines.
@@ -291,7 +329,7 @@ def draw(self, renderer, project=False):
291329

292330
def line_collection_2d_to_3d(col, zs=0, zdir='z'):
293331
"""Convert a LineCollection to a Line3DCollection object."""
294-
segments3d = paths_to_3d_segments(col.get_paths(), zs, zdir)
332+
segments3d = _paths_to_3d_segments(col.get_paths(), zs, zdir)
295333
col.__class__ = Line3DCollection
296334
col.set_segments(segments3d)
297335

@@ -350,7 +388,7 @@ def do_3d_projection(self, renderer):
350388
return min(vzs)
351389

352390

353-
def get_patch_verts(patch):
391+
def _get_patch_verts(patch):
354392
"""Return a list of vertices for the path of a patch."""
355393
trans = patch.get_patch_transform()
356394
path = patch.get_path()
@@ -361,9 +399,15 @@ def get_patch_verts(patch):
361399
return []
362400

363401

402+
@cbook.deprecated("3.1")
403+
def get_patch_verts(patch):
404+
"""Return a list of vertices for the path of a patch."""
405+
return _get_patch_verts(patch)
406+
407+
364408
def patch_2d_to_3d(patch, z=0, zdir='z'):
365409
"""Convert a Patch to a Patch3D object."""
366-
verts = get_patch_verts(patch)
410+
verts = _get_patch_verts(patch)
367411
patch.__class__ = Patch3D
368412
patch.set_3d_properties(verts, z, zdir)
369413

@@ -427,12 +471,12 @@ def do_3d_projection(self, renderer):
427471
xs, ys, zs = self._offsets3d
428472
vxs, vys, vzs, vis = proj3d.proj_transform_clip(xs, ys, zs, renderer.M)
429473

430-
fcs = (zalpha(self._facecolor3d, vzs) if self._depthshade else
474+
fcs = (_zalpha(self._facecolor3d, vzs) if self._depthshade else
431475
self._facecolor3d)
432476
fcs = mcolors.to_rgba_array(fcs, self._alpha)
433477
self.set_facecolors(fcs)
434478

435-
ecs = (zalpha(self._edgecolor3d, vzs) if self._depthshade else
479+
ecs = (_zalpha(self._edgecolor3d, vzs) if self._depthshade else
436480
self._edgecolor3d)
437481
ecs = mcolors.to_rgba_array(ecs, self._alpha)
438482
self.set_edgecolors(ecs)
@@ -493,12 +537,12 @@ def do_3d_projection(self, renderer):
493537
xs, ys, zs = self._offsets3d
494538
vxs, vys, vzs, vis = proj3d.proj_transform_clip(xs, ys, zs, renderer.M)
495539

496-
fcs = (zalpha(self._facecolor3d, vzs) if self._depthshade else
540+
fcs = (_zalpha(self._facecolor3d, vzs) if self._depthshade else
497541
self._facecolor3d)
498542
fcs = mcolors.to_rgba_array(fcs, self._alpha)
499543
self.set_facecolors(fcs)
500544

501-
ecs = (zalpha(self._edgecolor3d, vzs) if self._depthshade else
545+
ecs = (_zalpha(self._edgecolor3d, vzs) if self._depthshade else
502546
self._edgecolor3d)
503547
ecs = mcolors.to_rgba_array(ecs, self._alpha)
504548
self.set_edgecolors(ecs)
@@ -643,7 +687,7 @@ def do_3d_projection(self, renderer):
643687
self.update_scalarmappable()
644688
self._facecolors3d = self._facecolors
645689

646-
txs, tys, tzs = proj3d.proj_transform_vec(self._vec, renderer.M)
690+
txs, tys, tzs = proj3d._proj_transform_vec(self._vec, renderer.M)
647691
xyzlist = [(txs[si:ei], tys[si:ei], tzs[si:ei])
648692
for si, ei in self._segis]
649693

@@ -681,7 +725,7 @@ def do_3d_projection(self, renderer):
681725
# Return zorder value
682726
if self._sort_zpos is not None:
683727
zvec = np.array([[0], [0], [self._sort_zpos], [1]])
684-
ztrans = proj3d.proj_transform_vec(zvec, renderer.M)
728+
ztrans = proj3d._proj_transform_vec(zvec, renderer.M)
685729
return ztrans[2][0]
686730
elif tzs.size > 0:
687731
# FIXME: Some results still don't look quite right.
@@ -734,8 +778,8 @@ def get_edgecolor(self):
734778

735779
def poly_collection_2d_to_3d(col, zs=0, zdir='z'):
736780
"""Convert a PolyCollection to a Poly3DCollection object."""
737-
segments_3d, codes = paths_to_3d_segments_with_codes(col.get_paths(),
738-
zs, zdir)
781+
segments_3d, codes = _paths_to_3d_segments_with_codes(
782+
col.get_paths(), zs, zdir)
739783
col.__class__ = Poly3DCollection
740784
col.set_verts_and_codes(segments_3d, codes)
741785
col.set_3d_properties()
@@ -777,14 +821,20 @@ def rotate_axes(xs, ys, zs, zdir):
777821
return xs, ys, zs
778822

779823

780-
def get_colors(c, num):
824+
def _get_colors(c, num):
781825
"""Stretch the color argument to provide the required number *num*."""
782826
return np.broadcast_to(
783827
mcolors.to_rgba_array(c) if len(c) else [0, 0, 0, 0],
784828
(num, 4))
785829

786830

787-
def zalpha(colors, zs):
831+
@cbook.deprecated("3.1")
832+
def get_colors(c, num):
833+
"""Stretch the color argument to provide the required number *num*."""
834+
return _get_colors(c, num)
835+
836+
837+
def _zalpha(colors, zs):
788838
"""Modify the alphas of the color list according to depth."""
789839
# FIXME: This only works well if the points for *zs* are well-spaced
790840
# in all three dimensions. Otherwise, at certain orientations,
@@ -796,3 +846,9 @@ def zalpha(colors, zs):
796846
sats = 1 - norm(zs) * 0.7
797847
rgba = np.broadcast_to(mcolors.to_rgba_array(colors), (len(zs), 4))
798848
return np.column_stack([rgba[:, :3], rgba[:, 3] * sats])
849+
850+
851+
@cbook.deprecated("3.1")
852+
def zalpha(colors, zs):
853+
"""Modify the alphas of the color list according to depth."""
854+
return _zalpha(colors, zs)

‎lib/mpl_toolkits/mplot3d/axes3d.py

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1027,7 +1027,7 @@ def get_proj(self):
10271027

10281028
self.eye = E
10291029
self.vvec = R - E
1030-
self.vvec = self.vvec / proj3d.mod(self.vvec)
1030+
self.vvec = self.vvec / proj3d._mod(self.vvec)
10311031

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

11631163
# nearest edge
11641164
p0, p1 = min(self.tunit_edges(),
1165-
key=lambda edge: proj3d.line2d_seg_dist(
1165+
key=lambda edge: proj3d._line2d_seg_dist(
11661166
edge[0], edge[1], (xd, yd)))
11671167

11681168
# scale the z value to match
@@ -1209,8 +1209,8 @@ def _on_move(self, event):
12091209
# get the x and y pixel coords
12101210
if dx == 0 and dy == 0:
12111211
return
1212-
self.elev = art3d.norm_angle(self.elev - (dy/h)*180)
1213-
self.azim = art3d.norm_angle(self.azim - (dx/w)*180)
1212+
self.elev = art3d._norm_angle(self.elev - (dy/h)*180)
1213+
self.azim = art3d._norm_angle(self.azim - (dx/w)*180)
12141214
self.get_proj()
12151215
self.stale = True
12161216
self.figure.canvas.draw_idle()
@@ -1762,8 +1762,8 @@ def _shade_colors(self, color, normals, lightsource=None):
17621762
# chosen for backwards-compatibility
17631763
lightsource = LightSource(azdeg=225, altdeg=19.4712)
17641764

1765-
shade = np.array([np.dot(n / proj3d.mod(n), lightsource.direction)
1766-
if proj3d.mod(n) else np.nan
1765+
shade = np.array([np.dot(n / proj3d._mod(n), lightsource.direction)
1766+
if proj3d._mod(n) else np.nan
17671767
for n in normals])
17681768
mask = ~np.isnan(shade)
17691769

@@ -2029,8 +2029,8 @@ def _3d_extend_contour(self, cset, stride=5):
20292029
paths = linec.get_paths()
20302030
if not paths:
20312031
continue
2032-
topverts = art3d.paths_to_3d_segments(paths, z - dz)
2033-
botverts = art3d.paths_to_3d_segments(paths, z + dz)
2032+
topverts = art3d._paths_to_3d_segments(paths, z - dz)
2033+
botverts = art3d._paths_to_3d_segments(paths, z + dz)
20342034

20352035
color = linec.get_color()[0]
20362036

@@ -2394,7 +2394,7 @@ def bar(self, left, height, zs=0, zdir='z', *args, **kwargs):
23942394
verts = []
23952395
verts_zs = []
23962396
for p, z in zip(patches, zs):
2397-
vs = art3d.get_patch_verts(p)
2397+
vs = art3d._get_patch_verts(p)
23982398
verts += vs.tolist()
23992399
verts_zs += [z] * len(vs)
24002400
art3d.patch_2d_to_3d(p, z, zdir)

‎lib/mpl_toolkits/mplot3d/axis3d.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -298,7 +298,7 @@ def draw(self, renderer):
298298
renderer.M)
299299
self.label.set_position((tlx, tly))
300300
if self.get_rotate_label(self.label.get_text()):
301-
angle = art3d.norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
301+
angle = art3d._norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
302302
self.label.set_rotation(angle)
303303
self.label.set_va(info['label']['va'])
304304
self.label.set_ha(info['label']['ha'])
@@ -321,7 +321,7 @@ def draw(self, renderer):
321321
pos[0], pos[1], pos[2], renderer.M)
322322
self.offsetText.set_text(self.major.formatter.get_offset())
323323
self.offsetText.set_position((olx, oly))
324-
angle = art3d.norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
324+
angle = art3d._norm_text_angle(np.rad2deg(np.arctan2(dy, dx)))
325325
self.offsetText.set_rotation(angle)
326326
# Must set rotation mode to "anchor" so that
327327
# the alignment point is used as the "fulcrum" for rotation.

0 commit comments

Comments
 (0)
0