spacepy.plot.utils.add_arrows

spacepy.plot.utils.add_arrows(lines, n=3, size=12, style='->', dorestrict=False, positions=False)

Add directional arrows along a plotted line. Useful for plotting flow lines, magnetic field lines, or other directional traces.

lines can be either Line2D, a list or tuple of lines, or a LineCollection object.

For each line, arrows will be added using annotate(). Arrows will be spread evenly over the line using the number of points in the line as the metric for spacing. For example, if a line has 120 points and 3 arrows are requested, an arrow will be added at point number 30, 60, and 90. Arrow color and alpha is obtained from the parent line.

Parameters:

linesLine2D, a list/tuple, or LineCollection

A single line or group of lines on which to place the arrows. Arrows inherent color and transparency (alpha) from the line on which they are placed.

Returns:

None

Other Parameters:

ninteger

Number of arrows to add to each line; defaults to 3.

sizeinteger

The size of the arrows in points. Defaults to 12.

stylestring

Set the style of the arrow via ArrowStyle, e.g. ‘->’ (default)

dorestrictboolean

If True (default), only points along the line within the current limits of the axes will be considered when distributing arrows.

positionsNx2 array

N must be the number of lines provided via the argument lines. If provided, only one arrow will be placed per line. positions sets the explicit location of each arrow for each line as X-Y space in Axes coordinates.

Notes

The algorithm works by dividing the line in to n*+1 segments and placing an arrow between each segment, endpoints excluded. Arrows span the shortest distance possible, i.e., two adjacent points along a line. For lines that are long spatially but sparse in points, the arrows will have long tails that may extend beyond axes bounds. For explicit positions, the arrow is placed at the point on the curve closest to that position and the exact position is not always attainable. A maximum number of arrows equal to one-half of the number of points in a line per line will be created, so not all lines will receive *n arrows.

Examples

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> x = np.arange(1, 10, .01)
>>> y = np.sin(x)
>>> line = plt.plot(x,y)
>>> add_arrows(line, n=15, style='-|>')