Learn R Programming

plot3D (version 1.0-1)

3-D arrows, segments, polygons, boxes, rectangles: Plots arrows, segments, points, lines, polygons, rectangles and boxes in a 3D perspective plot or in 2D.

Description

Functions arrows3D and segments3D draw arrows and line segments between pairs of points. Functions box3D and border3D draw boxes between pairs of points. polygon3D draws polygons; rect3D draws rectangles. The 2D functions arrows2D, segments2D, rect2D and polygon2D are included for their side effect of having a color key.

Usage

arrows3D (x0, y0, z0, x1 = x0, y1 = y0, z1 = z0, ...,  
         colvar = NULL, phi = 40, theta = 40,
         col = NULL, NAcol = "white", 
         colkey = NULL, panel.first = NULL,
         clim = NULL, clab = NULL, bty = "b", type = "triangle", 
         add = FALSE, plot = TRUE)

segments3D (x0, y0, z0, x1 = x0, y1 = y0, z1 = z0, ..., 
         colvar = NULL, phi = 40, theta = 40,
         col = NULL, NAcol = "white", 
         colkey = NULL, panel.first = NULL,
         clim = NULL, clab = NULL, bty = "b", 
         add = FALSE, plot = TRUE)

box3D (x0, y0, z0, x1, y1, z1, ..., 
         colvar = NULL, phi = 40, theta = 40,
         col = NULL, NAcol = "white", border = NA, facets = TRUE,
         colkey = NULL, panel.first = NULL,
         clim = NULL, clab = NULL, bty = "b", 
         add = FALSE, plot = TRUE)

border3D(x0, y0, z0, x1, y1, z1, ..., 
         colvar = NULL, phi = 40, theta = 40,
         col = NULL, NAcol = "white", 
         colkey = NULL, panel.first = NULL,
         clim = NULL, clab = NULL, bty = "b", 
         add = FALSE, plot = TRUE)  

rect3D (x0, y0, z0, x1 = NULL, y1 = NULL, z1 = NULL, ..., 
         colvar = NULL, phi = 40, theta = 40,
         col = NULL, NAcol = "white", border = NA, facets = TRUE,
         colkey = NULL, panel.first = NULL,
         clim = NULL, clab = NULL, bty = "b", 
         add = FALSE, plot = TRUE)

polygon3D (x, y, z, ..., 
         colvar = NULL, phi = 40, theta = 40,
         col = NULL, NAcol = "white", border = NA, facets = TRUE,
         colkey = NULL, panel.first = NULL,
         clim = NULL, clab = NULL, bty = "b", 
         add = FALSE, plot = TRUE)  
         
arrows2D (x0, y0, x1 = x0, y1 = y0, ..., colvar = NULL,
         col = NULL, NAcol = "white",
         colkey = NULL, clim = NULL, clab = NULL, 
         type = "triangle", add = FALSE, plot = TRUE)  

segments2D (x0, y0, x1 = x0, y1 = y0, ..., colvar = NULL,
         col = NULL, NAcol = "white",
         colkey = NULL, clim = NULL, clab = NULL, 
         add = FALSE, plot = TRUE) 

rect2D (x0, y0, x1 = x0, y1 = y0, ..., colvar = NULL,
         col = NULL, NAcol = "white",
         colkey = NULL, clim = NULL, clab = NULL, 
         add = FALSE, plot = TRUE) 
         
polygon2D (x, y, ..., colvar = NULL, 
         col = NULL, NAcol = "white", 
         border = NA, facets = TRUE,
         colkey = NULL, clim = NULL, clab = NULL, 
         add = FALSE, plot = TRUE)

Arguments

x0, y0, z0
coordinates of points from which to draw.
x1, y1, z1
coordinates of points to which to draw. For arrows3D and segments3D, at least one must be supplied. For rect3D exactly one must be NULL.
x, y, z
coordinates of the vertices of the polygon. The polygon will be closed by joining the last point to the first point. The coordinates can contain missing values (NA). These NA values break the polygon into severa
colvar
The variable used for coloring. It need not be present, but if specified, it should be a vector of dimension equal to the coordinates or to the number of polygons. Values of NULL, NA, or FALSE
theta, phi
the angles defining the viewing direction. theta gives the azimuthal direction and phi the colatitude. See persp.
col
Color palette to be used for coloring the arrows or segments as specified by the colvar variable. If col is NULL and colvar is specified, then a red-yellow-blue colorscheme (
NAcol
Colors to be used for colvar values that are NA.
colkey
A logical, NULL (default), or a list with parameters for the color key (legend). List parameters should be one of side, plot, length, width, dist, shift, addlines, col.clab, cex.clab, side.clab, line.clab
border
The color of the lines drawn around the surface facets. The default, NA, will disable the drawing of borders.
facets
If TRUE, then col denotes the color of the surface facets. If FALSE, then the surface facets are colored ``white'' and the border (if NA) will be colored as specified by co
panel.first
A function to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful e.g. for drawing background grids or scatterplot smooths. The function should have as argument the transformat
clab
Only if colkey is not NULL or FALSE, the label to be written on top of the color key. The label will be written at the same level as the main title. To lower it, clab can be made a vecto
clim
Only if colvar is specified, the range of the color variable, used for the color key. Values of colvar that extend the range will be put to NA.
bty
The type of the perspective box, the default draws only the back panels. Only effective if the persp argument (box) equals TRUE (this is the default). See
type
The type of the arrow head, one of "simple" (which uses R-function arrows), "curved" or "triangle" and "cone". The latter two are the same in plot3D
add
Logical. If TRUE, then the arrows, segments, ... will be added to the current plot. If FALSE a new plot is started.
plot
Logical. If TRUE (default), a plot is created, otherwise the viewing transformation matrix is returned (as invisible).
...
additional arguments passed to the plotting methods. The following persp arguments can be specified: xlim, ylim, zlim, xlab, ylab, zlab, main, sub, r, d, scale, expand, box, axes, nticks, ticktyp

Value

  • Returns the viewing transformation matrix. See trans3D.

See Also

arrows for the 2-D arrows function on which arrows3D is based. segments for the 2-D arrows function on which segments3D is based.

Examples

Run this code
# save plotting parameters
  pm <- par("mfrow")

## ========================================================================
## arrows, points, segments, box
## ========================================================================

# Create a grid of x, y, and z values
 xx <- yy <- seq(-0.8, 0.8, by = 0.2)
 zz <- seq(-0.8, 0.8, by = 0.8)

 M <- mesh(xx, yy, zz)
 x0 <- M$x; y0 <- M$y; z0 <- M$z
 x1 <- x0 + 0.1

 Col <- c("red", "blue", "green") 
 arrows3D(x0, y0, z0, x1 = x1, colvar = z0, lwd = 2, 
          d = 2, clab = "z-value", col = Col, length = 0.1,
          xlim = c(-0.8, 0.8), ylim = c(-0.8, 0.8),
          main = "arrows3D, points3D, segments3D, border3D")

# add starting point of arrows
 points3D(x0, y0, z0, add = TRUE, colvar = z0, 
           colkey = FALSE, pch = ".", cex = 3, col = Col)

# use segments to add section
 x0 <- c(-0.8, 0.8,  0.8, -0.8)
 x1 <- c( 0.8, 0.8, -0.8, -0.8)
         
 y0 <- c(-0.8, -0.8, 0.8, -0.8)
 y1 <- c(-0.8,  0.8, 0.8, 0.8)

 z0 <- c(0., 0., 0., 0.)
 segments3D(x0, y0, z0, x1, y1, z1 = z0,
     add = TRUE, col = "black", lwd = 2)

# add a box 
 border3D(-0.8, -0.8, -0.8, 0.8, 0.8, 0.8,
       col = "orange", add = TRUE, lwd = 3)

## ========================================================================
## boxes, cubes
## ========================================================================

# borders are boxes without facets  
 border3D(x0 = seq(-0.8, -0.1, by = 0.1), 
       y0 = seq(-0.8, -0.1, by = 0.1),
       z0 = seq(-0.8, -0.1, by = 0.1),
       x1 = seq(0.8, 0.1, by = -0.1),
       y1 = seq(0.8, 0.1, by = -0.1),
       z1 = seq(0.8, 0.1, by = -0.1),
       col = gg.col(8), lty = 2, 
       lwd = c(1, 4), phi = 20, main = "border3D")

 box3D(x0 = -0.8, y0 = -0.8, z0 = -0.8, 
       x1 = 0.8, y1 = 0.8, z1 = 0.8, 
       border = "black", lwd = 2, 
       col = gg.col(1, alpha = 0.8), 
       main = "box3D")

 box3D(x0 = seq(-0.8, -0.1, by = 0.1), 
       y0 = seq(-0.8, -0.1, by = 0.1),
       z0 = seq(-0.8, -0.1, by = 0.1),
       x1 = seq(0.8, 0.1, by = -0.1),
       y1 = seq(0.8, 0.1, by = -0.1),
       z1 = seq(0.8, 0.1, by = -0.1),
       col = rainbow(n = 8, alpha = 0.1), 
       border = "black", lwd = 2, phi = 20)

# here the perspective does not always work 
# use alpha.col to set the transparency of a vector of colors
 box3D(x0 = runif(3), y0 = runif(3), z0 = runif(3),
       x1 = runif(3), y1 = runif(3), z1 = runif(3),
       col = c("red", "lightblue", "orange"), alpha = 0.5,
       border = "black", lwd = 2)

## ========================================================================
## rectangles
## ========================================================================
# at constant 'z'
 rect3D(x0 = seq(-0.8, -0.1, by = 0.1), 
        y0 = seq(-0.8, -0.1, by = 0.1),
        z0 = seq(-0.8, -0.1, by = 0.1),
        x1 = seq(0.8, 0.1, by = -0.1),
        y1 = seq(0.8, 0.1, by = -0.1),
        col = gg.col(8), border = "black",
        bty = "g", lwd = 2, phi = 20, main = "rect3D")

# constant y and with transparent facets
 rect3D(x0 = 0, y0 = 0, z0 = 0, x1 = 1, z1 = 5,
        ylim = c(0, 1), facets = NA, border = "red",
        bty = "g", lwd = 2, phi = 20)

# add rect at constant z, with colored facet
 rect3D(x0 = 0, y0 = 0, z0 = 0, x1 = 1, y1 = 1,
        border = "red", add = TRUE)

## ========================================================================
## arrows added to a persp plot 
## ========================================================================

 x <- y <- seq(-10, 10, length = 30)
 z <- outer(x, y, FUN = function(x,y) x^2 + y^2)

 persp3D(x, y, z, theta = 30, phi = 30, 
         col = "lightblue", ltheta = 120, shade = 0.75, 
         ticktype = "detailed", xlab = "X", 
         ylab = "Y", zlab = "x^2+y^2" )  

# Points where to put the arrows
 x <- y <- seq(-10, 10, len = 6)
 X0 <- outer(x, y, FUN = function (x,y) x)
 Y0 <- outer(x, y, FUN = function (x,y) y)
 Z0 <- outer(x, y, FUN = function (x,y) x^2 + y^2)

 X1 <- X0 + 1
 Y1 <- Y0 + 1
 Z1 <- Z0 + 10

 arrows3D(X0, Y0, Z0, X1, Y1, Z1, lwd = 2, 
         add = TRUE, type = "curved", col = "red")

 segments3D(X0, Y0, Z0, X0, Y0, rep(0, length(X0)), lwd = 2, 
         add = TRUE, col = "green")

## ========================================================================
## polygon3D 
## ========================================================================

 x <- runif(10)
 y <- runif(10)
 z <- runif(10)
 
 polygon3D(x, y, z)

# several polygons, separated by NAs
 x <- runif(39) 
 y <- runif(39)
 z <- runif(39)
 ii <- seq(4, 36, by  = 4)
 x[ii] <- y[ii] <- z[ii] <- NA 

# transparent colors (alpha)
 polygon3D(x, y, z, border = "black", lwd = 3,
   col = gg.col(length(ii) + 1, alpha = 0.8), 
   main = "polygon3D")

## ========================================================================
## 2D examples, with color key
## ========================================================================

arrows2D(x0 = runif(10), y0 = runif(10), 
         x1 = runif(10), y1 = runif(10), colvar = 1:10, 
         code = 3, main = "arrows2D, segments2D")

segments2D(x0 = runif(10), y0 = runif(10), 
         x1 = runif(10), y1 = runif(10), colvar = 1:10, 
         lwd = 2, add = TRUE, colkey = FALSE) 

# transparency
rect2D(x0 = runif(10), y0 = runif(10), 
       x1 = runif(10), y1 = runif(10), colvar = 1:10, 
       alpha = 0.4, lwd = 2, main = "rect2D") 

## ========================================================================
## polygon2D 
## ========================================================================

 x <- runif(10)
 y <- runif(10)
 
 polygon2D(x, y)    # same as polygon

# several polygons, separated by NAs
 x <- runif(59) 
 y <- runif(59)

 ii <- seq(5, 55, by  = 5)
 x[ii] <- y[ii] <- NA 

# transparent colors (alpha)
 polygon2D(x, y, border = "black", lwd = 3,
   colvar = 1:(length(ii) + 1), 
   col = gg.col(), alpha = 0.2, 
   main = "polygon2D")

# restore plotting parameters
 par(mfrow = pm)

Run the code above in your browser using DataLab