Skip to content

Commit be7e1e2

Browse files
timhoffmtimhoffm
committed
Cleanup logic and documentation of tripcolor
This issues more and more precise warnings on usage errors but does not change behavior.
1 parent 39cfe2b commit be7e1e2

File tree

3 files changed

+162
-64
lines changed

3 files changed

+162
-64
lines changed

‎lib/matplotlib/tests/test_triangulation.py‎

Lines changed: 71 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,21 +41,42 @@ def test_extract_triangulation_params(args, kwargs, expected):
4141
assert kwargs_ == other_kwargs
4242

4343

44+
del x
45+
del y
46+
del triangles
47+
del mask
48+
49+
4450
def test_extract_triangulation_positional_mask():
45-
global x, y, triangles, mask
4651
# mask cannot be passed positionally
52+
mask = [True]
53+
args = [[0, 2, 1], [0, 0, 1], [[0, 1, 2]], mask]
4754
x_, y_, triangles_, mask_, args_, kwargs_ = \
48-
mtri.Triangulation._extract_triangulation_params(x, y, triangles, mask)
55+
mtri.Triangulation._extract_triangulation_params(args, {})
4956
assert mask_ is None
5057
assert args_ == [mask]
51-
# the positional mask has to be catched downstream because this must pass
58+
# the positional mask must be caught downstream because this must pass
5259
# unknown args through
5360

5461

55-
del x
56-
del y
57-
del triangles
58-
del mask
62+
def test_triangulation_init():
63+
x = [-1, 0, 1, 0]
64+
y = [0, -1, 0, 1]
65+
with pytest.raises(ValueError, match="x and y must be equal-length"):
66+
mtri.Triangulation(x, [1, 2])
67+
with pytest.raises(
68+
ValueError,
69+
match=r"triangles must be a \(N, 3\) int array, but found shape "
70+
r"\(3,\)"):
71+
mtri.Triangulation(x, y, [0, 1, 2])
72+
with pytest.raises(
73+
ValueError,
74+
match=r"triangles must be a \(N, 3\) int array, not 'other'"):
75+
mtri.Triangulation(x, y, 'other')
76+
with pytest.raises(ValueError, match="found value 99"):
77+
mtri.Triangulation(x, y, [[0, 1, 99]])
78+
with pytest.raises(ValueError, match="found value -1"):
79+
mtri.Triangulation(x, y, [[0, 1, -1]])
5980

6081

6182
def test_delaunay():
@@ -223,6 +244,49 @@ def test_tripcolor():
223244
plt.title('facecolors')
224245

225246

247+
def test_tripcolor_color():
248+
x = [-1, 0, 1, 0]
249+
y = [0, -1, 0, 1]
250+
fig, ax = plt.subplots()
251+
with pytest.raises(ValueError, match="Missing color parameter"):
252+
ax.tripcolor(x, y)
253+
with pytest.raises(ValueError, match="The length of C must match either"):
254+
ax.tripcolor(x, y, [1, 2, 3])
255+
with pytest.raises(ValueError,
256+
match="length of facecolors must match .* triangles"):
257+
ax.tripcolor(x, y, facecolors=[1, 2, 3, 4])
258+
with pytest.raises(ValueError,
259+
match="'gouraud' .* at the points.* not at the faces"):
260+
ax.tripcolor(x, y, facecolors=[1, 2], shading='gouraud')
261+
with pytest.raises(ValueError,
262+
match="'gouraud' .* at the points.* not at the faces"):
263+
ax.tripcolor(x, y, [1, 2], shading='gouraud') # faces
264+
with pytest.raises(ValueError,
265+
match=r"pass C positionally or facecolors via keyword"):
266+
ax.tripcolor(x, y, C=[1, 2, 3, 4])
267+
268+
# smoke test for valid color specifications (via C or facecolors)
269+
ax.tripcolor(x, y, [1, 2, 3, 4]) # edges
270+
ax.tripcolor(x, y, [1, 2, 3, 4], shading='gouraud') # edges
271+
ax.tripcolor(x, y, [1, 2]) # faces
272+
ax.tripcolor(x, y, facecolors=[1, 2]) # faces
273+
274+
275+
def test_tripcolor_warnings():
276+
x = [-1, 0, 1, 0]
277+
y = [0, -1, 0, 1]
278+
C = [0.4, 0.5]
279+
fig, ax = plt.subplots()
280+
# additional parameters
281+
with pytest.warns(UserWarning, match="Additional positional parameters"):
282+
ax.tripcolor(x, y, C, 'unused_positional')
283+
# facecolors takes precednced over C
284+
with pytest.warns(UserWarning, match="Positional parameter C .*no effect"):
285+
ax.tripcolor(x, y, C, facecolors=C)
286+
with pytest.warns(UserWarning, match="Positional parameter C .*no effect"):
287+
ax.tripcolor(x, y, 'interpreted as C', facecolors=C)
288+
289+
226290
def test_no_modify():
227291
# Test that Triangulation does not modify triangles array passed to it.
228292
triangles = np.array([[3, 2, 0], [3, 1, 0]], dtype=np.int32)

‎lib/matplotlib/tri/triangulation.py‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,9 @@ def __init__(self, x, y, triangles=None, mask=None):
4343
self.x = np.asarray(x, dtype=np.float64)
4444
self.y = np.asarray(y, dtype=np.float64)
4545
if self.x.shape != self.y.shape or self.x.ndim != 1:
46-
raise ValueError("x and y must be equal-length 1D arrays")
46+
raise ValueError("x and y must be equal-length 1D arrays, but "
47+
f"found shapes {self.x.shape!r} and "
48+
f"{self.y.shape!r}")
4749

4850
self.mask = None
4951
self._edges = None
@@ -58,13 +60,25 @@ def __init__(self, x, y, triangles=None, mask=None):
5860
else:
5961
# Triangulation specified. Copy, since we may correct triangle
6062
# orientation.
61-
self.triangles = np.array(triangles, dtype=np.int32, order='C')
63+
try:
64+
self.triangles = np.array(triangles, dtype=np.int32, order='C')
65+
except ValueError as e:
66+
raise ValueError('triangles must be a (N, 3) int array, not '
67+
f'{triangles!r}') from e
6268
if self.triangles.ndim != 2 or self.triangles.shape[1] != 3:
63-
raise ValueError('triangles must be a (?, 3) array')
69+
raise ValueError(
70+
'triangles must be a (N, 3) array, but found shape '
71+
f'{self.triangles.shape!r}')
6472
if self.triangles.max() >= len(self.x):
65-
raise ValueError('triangles max element is out of bounds')
73+
raise ValueError(
74+
'triangles are indices into the points and must be in the '
75+
f'range 0 <= i < {len(self.x)} but found value '
76+
f'{self.triangles.max()}')
6677
if self.triangles.min() < 0:
67-
raise ValueError('triangles min element is out of bounds')
78+
raise ValueError(
79+
'triangles are indices into the points and must be in the '
80+
f'range 0 <= i < {len(self.x)} but found value '
81+
f'{self.triangles.min()}')
6882

6983
if mask is not None:
7084
self.mask = np.asarray(mask, dtype=bool)

‎lib/matplotlib/tri/tripcolor.py‎

Lines changed: 72 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -21,62 +21,82 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
2121
optionally the *triangles* and a *mask*. See `.Triangulation` for an
2222
explanation of these parameters.
2323
24+
If neither of *triangulation* or *triangles* are given, the triangulation
25+
is calculated on the fly. In this case, it does not make sense to provide
26+
colors at the triangle faces via *C* or *facecolors* because there are
27+
multiple possible triangulations for a group of points and you don't know
28+
which triangles will be constructed.
29+
2430
Parameters
2531
----------
2632
triangulation : `.Triangulation`
2733
An already created triangular grid.
2834
x, y, triangles, mask
29-
Parameters specifying defining the triangular grid. See
30-
`.Triangulation`.
31-
32-
33-
The next argument must be *C*, the array of color values, either
34-
one per point in the triangulation if color values are defined at
35-
points, or one per triangle in the triangulation if color values
36-
are defined at triangles. If there are the same number of points
37-
and triangles in the triangulation it is assumed that color
38-
values are defined at points; to force the use of color values at
39-
triangles use the kwarg ``facecolors=C`` instead of just ``C``.
40-
41-
*shading* may be 'flat' (the default) or 'gouraud'. If *shading*
42-
is 'flat' and C values are defined at points, the color values
43-
used for each triangle are from the mean C of the triangle's
44-
three points. If *shading* is 'gouraud' then color values must be
45-
defined at points.
46-
47-
48-
49-
tripcolor(x, y, [triangles], C, [mask=mask], ...)
50-
51-
52-
The remaining kwargs are the same as for `~.Axes.pcolor`.
35+
Parameters defining the triangular grid. See `.Triangulation`.
36+
This is mutually exclusive with specifying *triangulation*.
37+
C : array-like
38+
The color values, either for the points or for the triangles. Which one
39+
is automatically inferred from the length of *C*, i.e. does it match
40+
the number of points or the number of triangles. If there are the same
41+
number of points and triangles in the triangulation it is assumed that
42+
color values are defined at points; to force the use of color values at
43+
triangles use the keyword argument ``facecolors=C`` instead of just
44+
``C``.
45+
This parameter is position-only.
46+
facecolors : array-like, optional
47+
Can be used alternatively to *C* to specify colors at the triangle
48+
faces. This parameter takes precedence over *C*.
49+
shading : {'flat', 'gouraud'}, default: 'flat'
50+
If 'flat' and the color values *C* are defined at points, the color
51+
values used for each triangle are from the mean C of the triangle's
52+
three points. If *shading* is 'gouraud' then color values must be
53+
defined at points.
54+
other_parameters
55+
All other parameters are the same as for `~.Axes.pcolor`.
56+
57+
Notes
58+
-----
59+
It is possible to pass the triangles positionally, i.e.
60+
``tripcolor(x, y, triangles, C, ...)``. However, this is discouraged.
61+
For more clarity, pass *triangles* via keyword argument.
5362
"""
5463
_api.check_in_list(['flat', 'gouraud'], shading=shading)
5564

5665
tri, args, kwargs = Triangulation.get_from_args_and_kwargs(*args, **kwargs)
5766

58-
# C is the colors array defined at either points or faces (i.e. triangles).
59-
# If facecolors is None, C are defined at points.
60-
# If facecolors is not None, C are defined at faces.
67+
# Parse the color to be in one of (the other variable will be None):
68+
# - facecolors: if specified at the triangle faces
69+
# - point_colors: if specified at the points
6170
if facecolors is not None:
62-
C = facecolors
71+
if args:
72+
_api.warn_external(
73+
"Positional parameter C has no effect when the keyword "
74+
"facecolors is given")
75+
point_colors = None
76+
if len(facecolors) != len(tri.triangles):
77+
raise ValueError("The length of facecolors must match the number "
78+
"of triangles")
6379
else:
80+
# Color from positional parameter C
81+
if not args:
82+
raise ValueError(
83+
"Missing color parameter. Please pass C positionally or "
84+
"facecolors via keyword")
85+
elif len(args) > 1:
86+
_api.warn_external(
87+
"Additional positional parameters {args[1:]!r} are ignored")
6488
C = np.asarray(args[0])
65-
66-
# If there are a different number of points and triangles in the
67-
# triangulation, can omit facecolors kwarg as it is obvious from
68-
# length of C whether it refers to points or faces.
69-
# Do not do this for gouraud shading.
70-
if (facecolors is None and len(C) == len(tri.triangles) and
71-
len(C) != len(tri.x) and shading != 'gouraud'):
72-
facecolors = C
73-
74-
# Check length of C is OK.
75-
if ((facecolors is None and len(C) != len(tri.x)) or
76-
(facecolors is not None and len(C) != len(tri.triangles))):
77-
raise ValueError('Length of color values array must be the same '
78-
'as either the number of triangulation points '
79-
'or triangles')
89+
if len(C) == len(tri.x):
90+
# having this before the len(tri.triangles) comparison gives
91+
# precedence to nodes if there are as many nodes as triangles
92+
point_colors = C
93+
facecolors = None
94+
elif len(C) == len(tri.triangles):
95+
point_colors = None
96+
facecolors = C
97+
else:
98+
raise ValueError('The length of C must match either the number '
99+
'of points or the number of triangles')
80100

81101
# Handling of linewidths, shading, edgecolors and antialiased as
82102
# in Axes.pcolor
@@ -97,13 +117,11 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
97117

98118
if shading == 'gouraud':
99119
if facecolors is not None:
100-
raise ValueError('Gouraud shading does not support the use '
101-
'of facecolors kwarg')
102-
if len(C) != len(tri.x):
103-
raise ValueError('For gouraud shading, the length of color '
104-
'values array must be the same as the '
105-
'number of triangulation points')
120+
raise ValueError(
121+
"shading='gouraud' can only be used when the colors "
122+
"are specified at the points, not at the faces.")
106123
collection = TriMesh(tri, **kwargs)
124+
colors = point_colors
107125
else:
108126
# Vertices of triangles.
109127
maskedTris = tri.get_masked_triangles()
@@ -112,15 +130,17 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
112130
# Color values.
113131
if facecolors is None:
114132
# One color per triangle, the mean of the 3 vertex color values.
115-
C = C[maskedTris].mean(axis=1)
133+
colors = point_colors[maskedTris].mean(axis=1)
116134
elif tri.mask is not None:
117135
# Remove color values of masked triangles.
118-
C = C[~tri.mask]
136+
colors = facecolors[~tri.mask]
137+
else:
138+
colors = facecolors
119139

120140
collection = PolyCollection(verts, **kwargs)
121141

122142
collection.set_alpha(alpha)
123-
collection.set_array(C)
143+
collection.set_array(colors)
124144
_api.check_isinstance((Normalize, None), norm=norm)
125145
collection.set_cmap(cmap)
126146
collection.set_norm(norm)

0 commit comments

Comments
 (0)