8000 Clarify quiver documentation · matplotlib/matplotlib@3762274 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3762274

Browse files
timhoffmtimhoffm
committed
Clarify quiver documentation
1 parent 4baf29d commit 3762274

File tree

1 file changed

+76
-64
lines changed

1 file changed

+76
-64
lines changed

‎lib/matplotlib/quiver.py

Lines changed: 76 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -38,29 +38,23 @@
3838
*X*, *Y* define the arrow locations, *U*, *V* define the arrow directions, and
3939
*C* optionally sets the color.
4040
41-
Each arrow is internally represented by a filled polygon with a default edge
42-
linewidth of 0. As a result, an arrow is rather a filled area, not a line with
43-
a head, and `.PolyCollection` properties like *linewidth*, *linestyle*,
44-
*facecolor*, etc. act accordingly.
45-
46-
**Arrow size**
41+
**Arrow length**
4742
4843
The default settings auto-scales the length of the arrows to a reasonable size.
4944
To change this behavior see the *scale* and *scale_units* parameters.
5045
5146
**Arrow shape**
5247
53-
The defaults give a slightly swept-back arrow; to make the head a
54-
triangle, make *headaxislength* the same as *headlength*. To make the
55-
arrow more pointed, reduce *headwidth* or increase *headlength* and
56-
*headaxislength*. To make the head smaller relative to the shaft,
57-
scale down all the head parameters. See also the notes section below.
58-
You will probably do best to leave *minshaft* alone.
48+
The arrow shape is determined by *width*, *headwidth*, *headlength* and
49+
*headaxislength*. See the notes below.
5950
60-
**Arrow outline**
51+
**Arrow styling**
52+
53+
Each arrow is internally represented by a filled polygon with a default edge
54+
linewidth of 0. As a result, an arrow is rather a filled area, not a line with
55+
a head, and `.PolyCollection` properties like *linewidth*, *edgecolor*,
56+
*facecolor*, etc. act accordingly.
6157
62-
*linewidths* and *edgecolors* can be used to customize the arrow
63-
outlines.
6458
6559
Parameters
6660
----------
@@ -75,11 +69,12 @@
7569
must match the column and row dimensions of *U* and *V*.
7670
7771
U, V : 1D or 2D array-like
78-
The x and y direction components of the arrow vectors.
72+
The x and y direction components of the arrow vectors. The interpretation
73+
of these components (in data or in screen space) depends on *angles*.
7974
80-
They must have the same number of elements, matching the number of arrow
81-
locations. *U* and *V* may be masked. Only locations unmasked in
82-
*U*, *V*, and *C* will be drawn.
75+
*U* and *V* must have the same number of elements, matching the number of
76+
arrow locations in *X*, *Y*. *U* and *V* may be masked. Locations masked
77+
in any of *U*, *V*, and *C* will not be drawn.
8378
8479
C : 1D or 2D array-like, optional
8580
Numeric data that defines the arrow colors by colormapping via *norm* and
@@ -89,46 +84,36 @@
8984
use *color* instead. The size of *C* must match the number of arrow
9085
locations.
9186
92-
units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'
93-
The arrow dimensions (except for *length*) are measured in multiples of
94-
this unit.
95-
96-
The following values are supported:
97-
98-
- 'width', 'height': The width or height of the axis.
99-
- 'dots', 'inches': Pixels or inches based on the figure dpi.
100-
- 'x', 'y', 'xy': *X*, *Y* or :math:`\\sqrt{X^2 + Y^2}` in data units.
101-
102-
The arrows scale differently depending on the units. For
103-
'x' or 'y', the arrows get larger as one zooms in; for other
104-
units, the arrow size is independent of the zoom state. For
105-
'width or 'height', the arrow size increases with the width and
106-
height of the axes, respectively, when the window is resized;
107-
for 'dots' or 'inches', resizing does not change the arrows.
108-
10987
angles : {'uv', 'xy'} or array-like, default: 'uv'
11088
Method for determining the angle of the arrows.
11189
112-
- 'uv': The arrow axis aspect ratio is 1 so that
113-
if *U* == *V* the orientation of the arrow on the plot is 45 degrees
114-
counter-clockwise from the horizontal axis (positive to the right).
90+
- 'uv': Arrow direction in screen coordinates. Use this if the arrows
91+
symbolize a quantity that is not based on *X*, *Y* data coordinates.
11592
116-
Use this if the arrows symbolize a quantity that is not based on
117-
*X*, *Y* data coordinates.
93+
If *U* == *V* the orientation of the arrow on the plot is 45 degrees
94+
counter-clockwise from the horizontal axis (positive to the right).
11895
119-
- 'xy': Arrows point from (x, y) to (x+u, y+v).
120-
Use this for plotting a gradient field, for example.
96+
- 'xy': Arrow direction in data coordinates, i.e. the arrows point from
97+
(x, y) to (x+u, y+v). Use this e.g. for plotting a gradient field.
12198
122-
- Alternatively, arbitrary angles may be specified explicitly as an array
123-
of values in degrees, counter-clockwise from the horizontal axis.
99+
- Arbitrary angles may be specified explicitly as an array of values
100+
in degrees, counter-clockwise from the horizontal axis.
124101
125102
In this case *U*, *V* is only used to determine the length of the
126103
arrows.
127104
128105
Note: inverting a data axis will correspondingly invert the
129106
arrows only with ``angles='xy'``.
130107
108+
pivot : {'tail', 'mid', 'middle', 'tip'}, default: 'tail'
109+
The part of the arrow that is anchored to the *X*, *Y* grid. The arrow
110+
rotates about this point.
111+
112+
'mid' is a synonym for 'middle'.
113+
131114
scale : float, optional
115+
Scales the length of the arrow inversely.
116+
132117
Number of data units per arrow length unit, e.g., m/s per plot width; a
133118
smaller scale parameter makes the arrow longer. Default is *None*.
134119
@@ -150,19 +135,42 @@
150135
the same units as x and y, use
151136
``angles='xy', scale_units='xy', scale=1``.
152137
138+
units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'
139+
Affects the arrow size (except for the length). In particular, the shaft
140+
*width* is measured in multiples of this unit.
141+
142+
Supported values are:
143+
144+
- 'width', 'height': The width or height of the Axes.
145+
- 'dots', 'inches': Pixels or inches based on the figure dpi.
146+
- 'x', 'y', 'xy': *X*, *Y* or :math:`\\sqrt{X^2 + Y^2}` in data units.
147+
148+
The following table summarizes how these values affect the visible arrow
149+
size under zooming and figure size changes:
150+
151+
================= ================= ==================
152+
units zoom figure size change
153+
================= ================= ==================
154+
'x', 'y', 'xy' arrow size scales -
155+
'width', 'height' - arrow size scales
156+
'dots', 'inches' - -
157+
================= ================= ==================
158+
153159
width : float, optional
154-
Shaft width in arrow units; default depends on choice of units,
155-
above, and number of vectors; a typical starting value is about
156-
0.005 times the width of the plot.
160+
Shaft width in arrow units. All head parameters are relative to *width*.
161+
162+
The default depends on choice of *units* above, and number of vectors;
163+
a typical starting value is about 0.005 times the width of the plot.
157164
158165
headwidth : float, default: 3
159-
Head width as multiple of shaft width. See the notes below.
166+
Head width as multiple of shaft *width*. See the notes below.
160167
161168
headlength : float, default: 5
162-
Head length as multiple of shaft width. See the notes below.
169+
Head length as multiple of shaft *width*. See the notes below.
163170
164171
headaxislength : float, default: 4.5
165-
Head length at shaft intersection. See the notes below.
172+
Head length at shaft intersection as multiple of shaft *width*.
173+
See the notes below.
166174
167175
minshaft : float, default: 1
168176
Length below which arrow scales, in units of head length. Do not
@@ -172,12 +180,6 @@
172180
Minimum length as a multiple of shaft width; if an arrow length
173181
is less than this, plot a dot (hexagon) of this diameter instead.
174182
175-
pivot : {'tail', 'mid', 'middle', 'tip'}, default: 'tail'
176-
The part of the arrow that is anchored to the *X*, *Y* grid. The arrow
177-
rotates about this point.
178-
179-
'mid' is a synonym for 'middle'.
180-
181183
color : color or color sequence, optional
182184
Explicit color(s) for the arrows. If *C* has been set, *color* has no
183185
effect.
@@ -204,18 +206,28 @@
204206
205207
Notes
206208
-----
209+
210+
**Arrow shape**
211+
207212
The arrow is drawn as a polygon using the nodes as shown below. The values
208-
*headwidth*, *headlength* and *headaxislength* are in units of width.
213+
*headwidth*, *headlength*, and *headaxislength* are in units of *width*.
209214
210215
.. image:: /_static/quiver_sizes.svg
211216
:width: 500px
212217
213-
To remove the head completely, set all *head* parameters to 0.
214-
215-
For *headlength* < *headaxislength* you will get a diamond-shaped head.
216-
For *headaxislength* < (*headlength* / *headwidth*), the "headaxis" nodes (i.e.
217-
the ones connecting the head with the shaft) will protrude out of the head
218-
so that the arrow head looks broken.
218+
The defaults give a slightly swept-back arrow. Here are some guidelines how to
219+
get other head shapes:
220+
221+
- To make the head a triangle, make *headaxislength* the same as *headlength*.
222+
- To make the arrow more pointed, reduce *headwidth* or increase *headlength*
223+
and *headaxislength*.
224+
- To make the head smaller relative to the shaft, scale down all the head
225+
parameters proportionally.
226+
- To remove the head completely, set all *head* parameters to 0.
227+
- To get a diamond-shaped head, make *headaxislength* larger than *headlength*.
228+
- Warning: For *headaxislength* < (*headlength* / *headwidth*), the "headaxis"
229+
nodes (i.e. the ones connecting the head with the shaft) will protrude out
230+
of the head in forward direction so that the arrow head looks broken.
219231
""" % _docstring.interpd.params
220232

221233
_docstring.interpd.update(quiver_doc=_quiver_doc)

0 commit comments

Comments
 (0)
0