Draw an arrow — arrow3d • rgl

Draws various types of arrows in a scene.

arrow3d(p0 = c(1, 1, 1), p1 = c(0, 0, 0), 
        barblen, s = 1/3, theta = pi/12, 
        type = c("extrusion", "lines", "flat", "rotation"), 
        n = 3, width = 1/3, thickness = 0.618 * width, 
        spriteOrigin = NULL, 
        plot = TRUE, ...)

Arguments

p0: The base of the arrow.
p1: The head of the arrow.
barblen: The length of the barbs (in display coordinates). Default given by s.
s: The length of the barbs as a fraction of line length. Ignored if barblen is present.
theta: Opening angle of barbs
type: Type of arrow to draw. Choose one from the list of defaults. Can be abbreviated. See below.
n: Number of barbs.
width: Width of shaft as fraction of barb width.
thickness: Thickness of shaft as fraction of barb width.
spriteOrigin: If arrow is to be replicated as sprites, the origins relative to which the sprites are drawn.
plot: If TRUE (the default), plot the object; otherwise return the computed data that would be used to plot it.
...: Material properties passed to polygon3d, shade3d or segments3d.

Details

Four types of arrows can be drawn. The shapes of all of them are affected by p0, p1, barblen, s, theta, material properties in ..., and spriteOrigin. Other parameters only affect some of the types, as shown.

"extrusion": (default) A 3-dimensional flat arrow, drawn with shade3d. Affected by width, thickness and smooth.
"lines": Drawn with lines, similar to arrows, drawn with segments3d. Affected by n.
"flat": A flat arrow, drawn with polygon3d. Affected by width and smooth.
"rotation": A solid of rotation, drawn with shade3d. Affected by n and width.

Normally this function draws just one arrow from p0 to p1, but if spriteOrigin is given (in any form that xyz.coords(spriteOrigin) can handle), arrows will be drawn for each point specified, with p0 and p1 interpreted relative to those origins. The arrows will be drawn as 3D sprites which will maintain their orientation as the scene is rotated, so this is a good way to indicate particular locations of interest in the scene.

Value

If plot = TRUE (the default), this is called mainly for the side effect of drawing the arrow; invisibly returns the id(s) of the objects drawn.

If plot = FALSE, the data that would be used in the plot (not including material properties) is returned.

Author

Design based on heplots::arrow3d, which contains modifications by Michael Friendly to a function posted by Barry Rowlingson to R-help on 1/10/2010. Additions by Duncan Murdoch.

Examples

xyz <- matrix(rnorm(300), ncol = 3)
plot3d(xyz)
arrow3d(xyz[1,], xyz[2,], type = "extrusion", col = "red")
arrow3d(xyz[3,], xyz[4,], type = "flat",      col = "blue")
arrow3d(xyz[5,], xyz[6,], type = "rotation",  col = "green")
arrow3d(xyz[7,], xyz[8,], type = "lines",     col = "black")
arrow3d(spriteOrigin = xyz[9:12,],            col = "purple")
3D plot