matplotlib.pyplot.quiver#

matplotlib.pyplot.quiver(*args,data=None,**kwargs)[source]#

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, andC optionally sets the color. The argumentsX,Y,U,V,C arepositional-only.

Arrow length

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

Arrow shape

The arrow shape is determined bywidth,headwidth,headlength andheadaxislength. See the notes below.

Arrow styling

Each arrow is internally represented by a filled polygon with a default edgelinewidth of 0. As a result, an arrow is rather a filled area, not a line witha head, andPolyCollection properties likelinewidth,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 basedon the dimensions ofU andV.

IfX andY are 1D butU,V are 2D,X,Y are expanded to 2DusingX,Y=np.meshgrid(X,Y). In this caselen(X) andlen(Y)must match the column and row dimensions ofU andV.

U, V1D or 2D array-like

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

U andV must have the same number of elements, matching the number ofarrow locations inX,Y.U andV may be masked. Locations maskedin any ofU,V, andC will not be drawn.

C1D or 2D array-like, optional

Numeric data that defines the arrow colors by colormapping vianorm andcmap.

This does not support explicit colors. If you want to set colors directly,usecolor instead. The size ofC must match the number of arrowlocations.

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

Method for determining the angle of the arrows.

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

  IfU ==V the orientation of the arrow on the plot is 45 degreescounter-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 plotswhere the arrows should directly represent movements or gradients in thex and y directions.

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

  In this caseU,V is only used to determine the length of thearrows.

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

Note: inverting a data axis will correspondingly invert thearrows only withangles='xy'.

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

The part of the arrow that is anchored to theX,Y grid. The arrowrotates 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), thescale parameter determines how many meters per second correspond to one unit ofarrow 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 areasonable size, which is based on the average vector length and the number ofvectors.

The arrow length unit is given by thescale_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 dataU,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) withscale=10,scale_unit="width" resultsin a horizontal arrow with a length of0.5 / 10 * "width", i.e. 0.05 times theAxes 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 lengthof 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) withscale_units='inches',scale=2 resultsin 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) withscale_units='x',scale=1 resultsin 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 havethe same units as x and y. To plot vectors in the x-y plane with u and v havingthe same units as x and y, useangles='xy',scale_units='xy',scale=1.

Note: Settingscale_units without setting scale does not have any effect becausethe scale units only differ by a constant factor and that is rescaled throughautoscaling.

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

Affects the arrow size (except for the length). In particular, the shaftwidth 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 arrowsize 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 towidth.

The default depends on choice ofunits 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 shaftwidth. See the notes below.

headlengthfloat, default: 5

Head length as multiple of shaftwidth. See the notes below.

headaxislengthfloat, default: 4.5

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

minshaftfloat, default: 1

Length below which arrow scales, in units of head length. Do notset 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 lengthis less than this, plot a dot (hexagon) of this diameter instead.

colorcolor or listcolor, optional

Explicit color(s) for the arrows. IfC has been set,color has noeffect.

This is a synonym for thePolyCollectionfacecolor parameter.

Returns:

Quiver

Other Parameters:

dataindexable object, optional

If given, all parameters also accept a strings, which isinterpreted asdata[s] ifs is a key indata.

**kwargsPolyCollection properties, optional

All other keyword arguments are passed on toPolyCollection:

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 float or None
animated	bool
antialiased oraa orantialiaseds	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 orec oredgecolors	color or list ofcolor or 'face'
facecolor orfacecolors orfc	color or list ofcolor
figure	Figure orSubFigure
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	unknown
hatchcolor	color or list ofcolor or 'edge'
in_layout	bool
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle ordashes orlinestyles orls	str or tuple or list thereof
linewidth orlinewidths orlw	float or list of floats
mouseover	bool
norm	Normalize or str or None
offset_transform ortransOffset	Transform
offsets	(N, 2) or (2,) array-like
path_effects	list ofAbstractPathEffect
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

Note

This is thepyplot wrapper foraxes.Axes.quiver.

Arrow shape

The arrow is drawn as a polygon using the nodes as shown below. The valuesheadwidth,headlength, andheadaxislength are in units ofwidth.

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

• To make the head a triangle, makeheadaxislength the same asheadlength.

• To make the arrow more pointed, reduceheadwidth or increaseheadlengthandheadaxislength.

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

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

• To get a diamond-shaped head, makeheadaxislength larger thanheadlength.

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

Examples usingmatplotlib.pyplot.quiver#

Advanced quiver and quiverkey functions

Advanced quiver and quiverkey functions

Quiver Simple Demo

Quiver Simple Demo

Trigradient Demo

Trigradient Demo