matplotlib.axes.Axes.quiver#

Axes.quiver(*args, data=None, **kwargs)[源码]#

绘制 2D 箭头场。

调用签名

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

X, Y 定义箭头的起始位置，U, V 定义箭头的方向，C 可选地设置颜色。参数 X, Y, U, V, C 仅支持位置参数。

箭头长度

默认设置会自动将箭头的长度缩放到合理的大小。要更改此行为，请参阅 scale 和 scale_units 参数。

箭头形状

箭头的形状由 width, headwidth, headlength 和 headaxislength 决定。请参阅下面的注意事项。

箭头样式

每个箭头在内部表示为一个填充的多边形，默认边线宽度为 0。因此，箭头是一个填充区域，而不是带箭头的线条，并且 PolyCollection 的属性如 linewidth、edgecolor、facecolor 等也会相应地起作用。

参数:

X, Y一维或二维类数组，可选

箭头位置的 x 和 y 坐标。

如果未给出，将根据 U 和 V 的维度生成一个均匀的整数网格。

如果 X 和 Y 是一维的，但 U, V 是二维的，则使用 X, Y = np.meshgrid(X, Y) 将 X, Y 扩展为二维。在这种情况下，len(X) 和 len(Y) 必须与 U 和 V 的列和行维度匹配。

U, V一维或二维类数组

箭头矢量的 x 和 y 方向分量。这些分量（在数据坐标系中或屏幕坐标系中）的解释取决于 angles。

U 和 V 必须具有相同数量的元素，与 X, Y 中箭头位置的数量匹配。U 和 V 可以被掩码。在 U, V 和 C 中任何被掩码的位置都不会被绘制。

C一维或二维类数组，可选

通过 norm 和 cmap 进行颜色映射来定义箭头颜色的数值数据。

这不支持显式颜色。如果要直接设置颜色，请使用 color。C 的大小必须与箭头位置的数量匹配。

angles{'uv', 'xy'} 或类数组，默认值: 'uv'

确定箭头角度的方法。

'uv'：箭头方向基于显示坐标；即，45° 角将始终在屏幕上显示为对角线，无论图形或坐标轴的纵横比或数据范围如何。当箭头表示方向不与 x 和 y 数据坐标绑定的量时，这非常有用。

如果 U == V，则图上箭头的方向为从水平轴（向右为正）逆时针旋转 45 度。
'xy'：数据坐标系中的箭头方向，即箭头从 (x, y) 指向 (x+u, y+v)。这对于矢量场或梯度图是理想的选择，其中箭头应直接表示 x 和 y 方向的运动或梯度。
任意角度可以显式指定为度数值数组，从水平轴逆时针方向计算。

在这种情况下，U, V 仅用于确定箭头的长度。

例如，angles=[30, 60, 90] 将分别以 30、60 和 90 度角定向箭头，而无论 U 和 V 分量如何。

注意：反转数据轴只会在使用 angles='xy' 时相应地反转箭头。

pivot{'tail', 'mid', 'middle', 'tip'}，默认值: 'tail'

箭头的哪个部分锚定到 X, Y 网格。箭头围绕此点旋转。

'mid' 是 'middle' 的同义词。

scale浮点数，可选

反向缩放箭头长度。

图上一个箭头长度单位所代表的数据值数量。例如，如果数据表示速度（米/秒），则 scale 参数决定了每秒多少米对应于相对于绘图宽度的单个箭头长度单位。较小的 scale 参数会使箭头更长。

默认情况下，使用自动缩放算法将箭头长度缩放到合理的大小，该算法基于平均矢量长度和矢量数量。

箭头长度单位由 scale_units 参数给出。

scale_units{'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}，默认值: 'width'

物理图像单位，用于渲染缩放后的箭头数据 U, V。

渲染后的箭头长度由以下公式给出：

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

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

例如，(u, v) = (0.5, 0) 和 scale=10, scale_unit="width" 会生成一个水平箭头，其长度为 0.5 / 10 * "width"，即坐标轴宽度的 0.05 倍。

支持的值有：

'width' 或 'height'：箭头长度相对于坐标轴的宽度或高度进行缩放。
例如，scale_units='width', scale=1.0 将导致箭头长度等于坐标轴的宽度。
'dots'：箭头的长度以显示点（像素）为单位测量。
'inches'：箭头长度根据图形的 DPI（每英寸点数）进行缩放。
这确保了箭头在图中具有一致的物理尺寸（以英寸为单位），无论数据值或绘图缩放如何。例如，(u, v) = (1, 0) 和 scale_units='inches', scale=2 会生成一个 0.5 英寸长的箭头。
'x' 或 'y'：箭头长度相对于 x 或 y 轴单位进行缩放。
例如，(u, v) = (0, 1) 和 scale_units='x', scale=1 会生成一个垂直箭头，其长度为 1 个 x 轴单位。
'xy'：箭头长度将与 'x' 或 'y' 单位相同。
这对于在 x-y 平面中创建矢量非常有用，其中 u 和 v 与 x 和 y 具有相同的单位。要在 x-y 平面中绘制 u 和 v 与 x 和 y 具有相同单位的矢量，请使用 angles='xy', scale_units='xy', scale=1。

注意：在不设置 scale 的情况下设置 scale_units 没有效果，因为缩放单位仅相差一个常数因子，并且会通过自动缩放进行重新缩放。

units{'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}，默认值: 'width'

影响箭头大小（除了长度）。特别是，轴的 width 以该单位的倍数测量。

支持的值有：

'width'、'height'：坐标轴的宽度或高度。
'dots'、'inches'：基于图形 DPI 的像素或英寸。
'x'、'y'、'xy'：数据单位中的 X、Y 或 $\sqrt{X^2 + Y^2}$。

下表总结了这些值在缩放和图形大小更改时如何影响可见箭头的大小：

单位	缩放	图形大小变化
'x', 'y', 'xy'	箭头大小缩放	—
'width', 'height'	—	箭头大小缩放
'dots', 'inches'	—	—

width浮点数，可选

箭头轴的宽度，以箭头单位表示。所有箭头头部参数都相对于 width。

默认值取决于上面 units 的选择和矢量数量；一个典型的起始值大约是绘图宽度的 0.005 倍。

headwidth浮点数，默认值: 3

头部宽度是轴 width 的倍数。请参阅下面的注意事项。

headlength浮点数，默认值: 5

头部长度是轴 width 的倍数。请参阅下面的注意事项。

headaxislength浮点数，默认值: 4.5

轴交点处的头部长度是轴 width 的倍数。请参阅下面的注意事项。

minshaft浮点数，默认值: 1

箭头缩放的最小长度，以头部长度为单位。不要将其设置为小于 1，否则小箭头会看起来很糟糕！

minlength浮点数，默认值: 1

最小长度是轴宽度的倍数；如果箭头长度小于此值，则改为绘制一个直径为该值的点（六边形）。

color颜色或颜色列表，可选

箭头的显式颜色。如果 C 已设置，则 color 无效。

这是 PolyCollection 的 facecolor 参数的同义词。

返回:

箭场图

其他参数:

data可索引对象，可选

如果给定，所有参数也接受字符串 s，如果 s 是 data 中的键，则将其解释为 data[s]。

**kwargsPolyCollection 属性，可选

所有其他关键字参数都传递给 PolyCollection

属性	描述
`agg_filter`	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
`alpha`	类数组或浮点数或 None
`animated`	布尔值
`antialiased` 或 `aa` 或 `antialiaseds`	布尔值或布尔值列表
`array`	类数组或 None
`capstyle`	`CapStyle` 或 {'butt', 'projecting', 'round'}
`clim`	(vmin: 浮点数, vmax: 浮点数)
`clip_box`	`BboxBase` 或 None
`clip_on`	布尔值
`clip_path`	Patch 或 (Path, Transform) 或 None
`cmap`	`Colormap` 或字符串或 None
`color`	颜色或 RGBA 元组列表
`edgecolor` 或 `ec` 或 `edgecolors`	颜色或颜色列表或 'face'
`facecolor` 或 `facecolors` 或 `fc`	颜色或颜色列表
`figure`	`Figure` 或 `SubFigure`
`gid`	str
`hatch`	{'/', '\', '\|', '-', '+', 'x', 'o', 'O', '.', '*'}
`hatch_linewidth`	未知
`in_layout`	布尔值
`joinstyle`	`JoinStyle` 或 {'miter', 'round', 'bevel'}
`label`	对象
`linestyle` 或 `dashes` 或 `linestyles` 或 `ls`	字符串或元组或其列表
`linewidth` 或 `linewidths` 或 `lw`	浮点数或浮点数列表
`mouseover`	布尔值
`norm`	`Normalize` 或字符串或 None
`offset_transform` 或 `transOffset`	`变换`
`offsets`	(N, 2) 或 (2,) 类数组
`path_effects`	`AbstractPathEffect` 的列表
`paths`	类数组列表
`picker`	None 或布尔值或浮点数或可调用对象
`pickradius`	浮点数
`rasterized`	布尔值
`sizes`	`numpy.ndarray` 或 None
`sketch_params`	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
`snap`	布尔值或 None
`transform`	`变换`
`url`	str
`字符串列表或 None`	urls
`verts`	类数组列表
`verts_and_codes`	未知
`visible`	布尔值
`zorder`	浮点数

另请参阅

Axes.quiverkey: 为quiver图添加图例。

备注

箭头形状

箭头使用如下所示的节点绘制为多边形。headwidth、headlength 和 headaxislength 的值以 width 为单位。

默认值会生成一个稍微后掠的箭头。以下是一些获取其他头部形状的指导：

要将头部制成三角形，请将 headaxislength 设置为与 headlength 相同。
要使箭头更尖，请减小 headwidth 或增加 headlength 和 headaxislength。
要使头部相对于轴更小，请按比例缩小所有头部参数。
要完全移除头部，请将所有 head 参数设置为 0。
要获得菱形头部，请将 headaxislength 设置为大于 headlength。
警告：对于 headaxislength < (headlength / headwidth) 的情况，“headaxis”节点（即连接头部与轴的节点）将向前突出头部，从而使箭头头部看起来损坏。