matplotlib.quiver.Quiver

class matplotlib.quiver.Quiver(ax, *args, scale=None, headwidth=3, headlength=5, headaxislength=4.5, minshaft=1, minlength=1, units='width', scale_units=None, angles='uv', width=None, color='k', pivot='tail', **kwargs)

Bases: PolyCollection

Specialized PolyCollection for arrows.

The only API method is set_UVC(), which can be used to change the size, orientation, and color of the arrows; their locations are fixed when the class is instantiated. Possibly this method will be useful in animations.

Much of the work in this class is done in the draw() method so that as much information as possible is available about the plot. In subsequent draw() calls, recalculation is limited to things that might have changed, so there should be no performance penalty from putting the calculations in the draw() method.

The constructor takes one required argument, an Axes instance, followed by the args and kwargs described by the following pyplot interface documentation:

Plot a 2D field of arrows.

Call signature:

quiver([X, Y], U, V, [C], /, **kwargs)

X, Y define the arrow locations, U, V define the arrow directions, and C optionally sets the color. The arguments X, Y, U, V, C are positional-only.

Arrow length

The default settings auto-scales the length of the arrows to a reasonable size. To change this behavior see the scale and scale_units parameters.

Arrow shape

The arrow shape is determined by width, headwidth, headlength and headaxislength. See the notes below.

Arrow styling

Each arrow is internally represented by a filled polygon with a default edge linewidth of 0. As a result, an arrow is rather a filled area, not a line with a head, and PolyCollection properties like linewidth, edgecolor, facecolor, etc. act accordingly.

Parameters:

X, Y1D or 2D array-like, optional

The x and y coordinates of the arrow locations.

If not given, they will be generated as a uniform integer meshgrid based on the dimensions of U and V.

If X and Y are 1D but U, V are 2D, X, Y are expanded to 2D using X, Y = np.meshgrid(X, Y). In this case len(X) and len(Y) must match the column and row dimensions of U and V.

U, V1D or 2D array-like

The x and y direction components of the arrow vectors. The interpretation of these components (in data or in screen space) depends on angles.

U and V must have the same number of elements, matching the number of arrow locations in X, Y. U and V may be masked. Locations masked in any of U, V, and C will not be drawn.

C1D or 2D array-like, optional

Numeric data that defines the arrow colors by colormapping via norm and cmap.

This does not support explicit colors. If you want to set colors directly, use color instead. The size of C must match the number of arrow locations.

angles{'uv', 'xy'} or array-like, default: 'uv'

Method for determining the angle of the arrows.

• 'uv': Arrow directions are based on display coordinates; i.e. a 45° angle will always show up as diagonal on the screen, irrespective of figure or Axes aspect ratio or Axes data ranges. This is useful when the arrows represent a quantity whose direction is not tied to the x and y data coordinates.

  If U == V the orientation of the arrow on the plot is 45 degrees counter-clockwise from the horizontal axis (positive to the right).

• 'xy': Arrow direction in data coordinates, i.e. the arrows point from (x, y) to (x+u, y+v). This is ideal for vector fields or gradient plots where the arrows should directly represent movements or gradients in the x and y directions.

• Arbitrary angles may be specified explicitly as an array of values in degrees, counter-clockwise from the horizontal axis.

  In this case U, V is only used to determine the length of the arrows.

  For example, angles=[30, 60, 90] will orient the arrows at 30, 60, and 90 degrees respectively, regardless of the U and V components.

Note: inverting a data axis will correspondingly invert the arrows only with angles='xy'.

pivot{'tail', 'mid', 'middle', 'tip'}, default: 'tail'

The part of the arrow that is anchored to the X, Y grid. The arrow rotates about this point.

'mid' is a synonym for 'middle'.

scalefloat, optional

Scales the length of the arrow inversely.

Number of data values represented by one unit of arrow length on the plot. For example, if the data represents velocity in meters per second (m/s), the scale parameter determines how many meters per second correspond to one unit of arrow length relative to the width of the plot. Smaller scale parameter makes the arrow longer.

By default, an autoscaling algorithm is used to scale the arrow length to a reasonable size, which is based on the average vector length and the number of vectors.

The arrow length unit is given by the scale_units parameter.

scale_units{'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'

The physical image unit, which is used for rendering the scaled arrow data U, V.

The rendered arrow length is given by

length in x direction = $frac{u}{mathrm{scale}} mathrm{scale_unit}$

length in y direction = $frac{v}{mathrm{scale}} mathrm{scale_unit}$

For example, (u, v) = (0.5, 0) with scale=10, scale_unit="width" results in a horizontal arrow with a length of 0.5 / 10 * "width", i.e. 0.05 times the Axes width.

Supported values are:

• 'width' or 'height': The arrow length is scaled relative to the width or height

  of the Axes. For example, scale_units='width', scale=1.0, will result in an arrow length of width of the Axes.

• 'dots': The arrow length of the arrows is in measured in display dots (pixels).

• 'inches': Arrow lengths are scaled based on the DPI (dots per inch) of the figure.

  This ensures that the arrows have a consistent physical size on the figure, in inches, regardless of data values or plot scaling. For example, (u, v) = (1, 0) with scale_units='inches', scale=2 results in a 0.5 inch-long arrow.

• 'x' or 'y': The arrow length is scaled relative to the x or y axis units.

  For example, (u, v) = (0, 1) with scale_units='x', scale=1 results in a vertical arrow with the length of 1 x-axis unit.

• 'xy': Arrow length will be same as 'x' or 'y' units.

  This is useful for creating vectors in the x-y plane where u and v have the same units as x and y. To plot vectors in the x-y plane with u and v having the same units as x and y, use angles='xy', scale_units='xy', scale=1.

Note: Setting scale_units without setting scale does not have any effect because the scale units only differ by a constant factor and that is rescaled through autoscaling.

units{'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'

Affects the arrow size (except for the length). In particular, the shaft width is measured in multiples of this unit.

Supported values are:

• 'width', 'height': The width or height of the Axes.

• 'dots', 'inches': Pixels or inches based on the figure dpi.

• 'x', 'y', 'xy': X, Y or \(\sqrt{X^2 + Y^2}\) in data units.

The following table summarizes how these values affect the visible arrow size under zooming and figure size changes:

units	zoom	figure size change
'x', 'y', 'xy'	arrow size scales	—
'width', 'height'	—	arrow size scales
'dots', 'inches'	—	—

widthfloat, optional

Shaft width in arrow units. All head parameters are relative to width.

The default depends on choice of units above, and number of vectors; a typical starting value is about 0.005 times the width of the plot.

headwidthfloat, default: 3

Head width as multiple of shaft width. See the notes below.

headlengthfloat, default: 5

Head length as multiple of shaft width. See the notes below.

headaxislengthfloat, default: 4.5

Head length at shaft intersection as multiple of shaft width. See the notes below.

minshaftfloat, default: 1

Length below which arrow scales, in units of head length. Do not set this to less than 1, or small arrows will look terrible!

minlengthfloat, default: 1

Minimum length as a multiple of shaft width; if an arrow length is less than this, plot a dot (hexagon) of this diameter instead.

colorcolor or list color, optional

Explicit color(s) for the arrows. If C has been set, color has no effect.

This is a synonym for the PolyCollection facecolor parameter.

Returns:

Quiver

Other Parameters:

dataindexable object, optional

DATA_PARAMETER_PLACEHOLDER

**kwargsPolyCollection properties, optional

All other keyword arguments are passed on to PolyCollection:

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	array-like or scalar or None
animated	bool
antialiased or aa or antialiaseds	bool or list of bools
array	array-like or None
capstyle	CapStyle or {'butt', 'projecting', 'round'}
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	Colormap or str or None
color	color or list of RGBA tuples
edgecolor or ec or edgecolors	color or list of color or 'face'
facecolor or facecolors or fc	color or list of color
figure	Figure or SubFigure
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	unknown
in_layout	bool
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle or dashes or linestyles or ls	str or tuple or list thereof
linewidth or linewidths or lw	float or list of floats
mouseover	bool
norm	Normalize or str or None
offset_transform or transOffset	Transform
offsets	(N, 2) or (2,) array-like
path_effects	list of AbstractPathEffect
paths	list of array-like
picker	None or bool or float or callable
pickradius	float
rasterized	bool
sizes	numpy.ndarray or None
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
urls	list of str or None
verts	list of array-like
verts_and_codes	unknown
visible	bool
zorder	float

See also

Axes.quiverkey

Add a key to a quiver plot.

Notes

Arrow shape

The arrow is drawn as a polygon using the nodes as shown below. The values headwidth, headlength, and headaxislength are in units of width.

The defaults give a slightly swept-back arrow. Here are some guidelines how to get other head shapes:

• To make the head a triangle, make headaxislength the same as headlength.

• To make the arrow more pointed, reduce headwidth or increase headlength and headaxislength.

• To make the head smaller relative to the shaft, scale down all the head parameters proportionally.

• To remove the head completely, set all head parameters to 0.

• To get a diamond-shaped head, make headaxislength larger than headlength.

• Warning: For headaxislength < (headlength / headwidth), the "headaxis" nodes (i.e. the ones connecting the head with the shaft) will protrude out of the head in forward direction so that the arrow head looks broken.

draw(renderer)

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:

rendererRendererBase subclass.

Notes

This method is overridden in the Artist subclasses.

get_datalim(transData)

set(*, UVC=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, array=<UNSET>, capstyle=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, gid=<UNSET>, hatch=<UNSET>, hatch_linewidth=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, norm=<UNSET>, offset_transform=<UNSET>, offsets=<UNSET>, path_effects=<UNSET>, paths=<UNSET>, picker=<UNSET>, pickradius=<UNSET>, rasterized=<UNSET>, sizes=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, urls=<UNSET>, verts=<UNSET>, verts_and_codes=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Property	Description
UVC	unknown
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	array-like or scalar or None
animated	bool
antialiased or aa or antialiaseds	bool or list of bools
array	array-like or None
capstyle	CapStyle or {'butt', 'projecting', 'round'}
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	Colormap or str or None
color	color or list of RGBA tuples
edgecolor or ec or edgecolors	color or list of color or 'face'
facecolor or facecolors or fc	color or list of color
figure	Figure or SubFigure
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	unknown
in_layout	bool
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle or dashes or linestyles or ls	str or tuple or list thereof
linewidth or linewidths or lw	float or list of floats
mouseover	bool
norm	Normalize or str or None
offset_transform or transOffset	Transform
offsets	(N, 2) or (2,) array-like
path_effects	list of AbstractPathEffect
paths	list of array-like
picker	None or bool or float or callable
pickradius	float
rasterized	bool
sizes	numpy.ndarray or None
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
urls	list of str or None
verts	list of array-like
verts_and_codes	unknown
visible	bool
zorder	float

set_UVC(U, V, C=None)

Examples using matplotlib.quiver.Quiver

Advanced quiver and quiverkey functions

Advanced quiver and quiverkey functions

Quiver Simple Demo

Quiver Simple Demo