plot3D (version 1.0-1)

Composite plots: Handling and plotting plotting lists.

Description

S3 method plot.plist and function plotdev plot the plotting list to the current device. Changes can be made to the perspective view, to the lighting and shading, or to make colors transparent. getplist and setplist retrieve and store information in the plotting list. selectplist selects parts from the plotting list, based on a user-defined function.

Usage

getplist()
setplist(plist)
plotdev(...)
## S3 method for class 'plist':
plot(x, ...) 
selectplist(plist, SS)

Arguments

x, plist

The plotting list as generated (invisibly) by any of the 3D plotting functions.

SS

Function which tests points for inclusion in the plotting list. It should take as argument three vectors (x, y, z) and return a vector of equal length that is either TRUE or FALSE, denoting whether the point shoul

...

Additional arguments to change the view or coloration. Supported arguments to change the view are : theta, phi, xlim, ylim, zlim, d, r, scale, expand. See perspbox,

Value

• Returns the updated plotting list.

Details

All 3-D functions from package plot3D produce or update a plotting list that is local to the package. One can access this plotting list via getplist and setplist. The list is used to plot when, in a 3-D function, the argument plot is TRUE or via function plotdev. The plotting list can contain the following items:

• mat, the viewing transformation matrix, a 4 x 4 matrix suitable for projecting 3D coordinates (x, y, z) into the 2D plane using homogeneous 4D coordinates (x,y,z,v). It can be used to superimpose additional graphical elements on the 3D plot, by any function that is defined onpersp. It can also be used to addlines,arrowsorpoints, using the functiontrans3D.
• plt, with originalpltparameters and thepltparameters used for the main frame.
• persp, with settings for the perspective box.
• xlim, ylim, zlim, with ranges.
• scalefac, the scaling factors in x, y and z direction, used e.g. for shading.
• dotother plotting parameters passed topersp.
• colkey,numkey, with settings for the color key(s).
• poly, segm, pt, CIpt, labels, arrthe information for drawing polygons, segments, points, points with confidence intervals, labels and arrows, that are part of the plot.

For the item poly the elements are:

• x, y, z: A matrix with typically 4 or 5 rows, the first rows defining the x-, y- or z- values of each polygon, the last row containsNA(and which therefore terminates a polygon).
• col: a vector with the colors for the facets of each polygon.
• lwd, lty, border: a vector with the line widths, line type and colors for the border of each polygon. (note in R-functionpolygon, passing a vector of line widths is not implemented; therefore, only the first value oflwdwill be used for all polygons). Whenplot.plistis called, the projection depth is calculated and used to sort the facets and functionpolygonused to draw them.

Examples

# save plotting parameters                            
 pm   <- par("mfrow")
 pmar <- par("mar")

## ========================================================================
## The volcano
## ========================================================================

 par(mfrow = c(2, 2), mar = c(2, 2, 2, 2))

# The volcano at lower resolution
 x <- seq(1, nrow(volcano), by = 2)
 y <- seq(1, ncol(volcano), by = 2)
 V <- volcano[x,y]

 persp3D(z = V)

# rotate
 plotdev(theta = 0)

# light and transparence
 plotdev(lighting  = TRUE, lphi = 90, alpha = 0.6)  

# zoom
 plotdev(xlim = c(0.2, 0.6), ylim = c(0.2, 0.6), phi = 60) 
 
## ========================================================================
## Two spheres 
## ========================================================================

 par(mfrow = c(1, 1), mar = c(0, 0, 0, 0))

# create a sphere
 M  <- mesh(seq(0, 2*pi, length.out = 30),
            seq(0,   pi, length.out = 30))
 u  <- M$x ; v  <- M$y

 x <- cos(u)*sin(v)
 y <- sin(u)*sin(v)
 z <- cos(v)

 surf3D(x = 2*x, y = 2*y, z = 2*z, 
        colvar = NULL, lighting = TRUE, #plot = FALSE,
        facets = NA, col = "blue", lwd = 5)
 
 surf3D(x, y, z, colvar = NULL, lighting = TRUE, 
        col = "red", add = TRUE)

 names(getplist())

# plot with different view:
 plotdev(phi = 0)  
# will plot same 3-D graph to pdf
 pdf(file = "save.pdf")
 plotdev()
 dev.off()
             
## ========================================================================
## Two spheres and two planes 
## ========================================================================

 par(mar = c(2, 2, 2, 2))

# equation of a sphere
 M  <- mesh(seq(0, 2*pi, length.out = 100),                                     -
            seq(0,   pi, length.out = 100))
 u  <- M$x ; v  <- M$y

 x <- cos(u)*sin(v)
 y <- sin(u)*sin(v)
 z <- cos(v)

 surf3D(x, y, z, colvar = z, 
        theta = 45, phi = 20, bty = "b",
        xlim = c(-1.5, 1.5), ylim = c(-1, 2), 
        zlim = c(-1.5, 1.5), plot = FALSE)

# add a second sphere, shifted 1 unit to the right on y-axis; 
# no facets drawn for this sphere 
 surf3D (x, y+1, z, colvar = z, add = TRUE, 
         facets = FALSE, plot = FALSE)

# define a plane at z = 0
 Nx <- 100
 Ny <- 100
  
 x <- seq(-1.5, 1.5, length.out = Nx)
 y <- seq(-1, 2, length.out = Ny)

 image3D (x = x, y = y, z = 0, add = TRUE, colvar = NULL, 
          col = "blue", facets = TRUE, plot = FALSE)

# another, small plane at y = 0 - here x and y have to be matrices!
 x <- seq(-1., 1., length.out = 50)
 z <- seq(-1., 1., length.out = 50)
 
 image3D (x = x, y = 0, z = z, colvar = NULL, 
         add = TRUE, col = NA, border = "blue", 
         facets = TRUE, plot = TRUE)       

# rotate 
 for (angle in seq(0, 360, by = 10)) 
   plotdev(theta = angle)

## ========================================================================
## Zooming, rescaling, lighting,...
## ========================================================================

 par(mfrow = c(2, 2)) 

# The volcano
 x <- seq(1, nrow(volcano), by = 2)
 y <- seq(1, ncol(volcano), by = 2)
 V <- volcano[x,y]
# plot the volcano
 persp3D (x, y, z = V, colvar = V, theta = 10, phi = 20, 
          box = FALSE, scale = FALSE, expand = 0.3, 
          clim = range(V), plot = FALSE)

# add a plane (image) at z = 170; jetcolored, transparant: only border
 image3D(x, y, z = 170, add = TRUE, clim = range(V), 
         colvar = V, facets = NA, plot = FALSE, colkey = FALSE)

# add a contour (image) at z = 170; jetcolored, 
 contour3D(x, y, z = 170, add = TRUE, clim = range(V),
           colvar = V, plot = FALSE, colkey = FALSE)

# plot it  - 
 plot(getplist())   #  same as plotdev()

# plot but with different expansion
 plotdev(expand = 1)

# other perspective, and shading
 plotdev(d = 2, r = 10, shade = 0.3)
    
# zoom and rotate
 plotdev(xlim = c(10, 30), ylim = c(20, 30), phi = 50)

## ========================================================================
## Using setplist
## ========================================================================

 polygon3D(runif(3), runif(3), runif(3))
# retrieve plotting list
 plist <- getplist()
 names(plist)
 plist$poly
# change copy of plotting list
 plist$poly$col <- "red"
# update internal plotting list
 setplist(plist)
# plot updated list
 plotdev()
 

## ========================================================================
## Using selectplist
## ========================================================================

 polygon3D(runif(10), runif(10), runif(10), col = "red", 
   alpha = 0.2, plot = FALSE, ticktype = "detailed", 
   xlim = c(0,1), ylim = c(0, 1), zlim = c(0, 1))
 polygon3D(runif(10)*0.5, runif(10), runif(10), col = "yellow", 
   alpha = 0.2, plot = FALSE, add = TRUE)
 polygon3D(runif(10)*0.5+0.5, runif(10), runif(10), col = "green", 
   alpha = 0.2, plot = FALSE, add = TRUE)
 points3D(runif(10), runif(10), runif(10), col = "blue", 
   add = TRUE, plot = FALSE)
 segments3D(x0 = runif(10), y0 = runif(10), z0 = runif(10), 
   x1 = runif(10), y1 = runif(10), z1 = runif(10), 
   colvar = 1:10, add = TRUE, lwd = 3)

# retrieve plotting list
 plist <- getplist()

# selection function 
 SS <- function (x, y, z)  {
   sel <- rep(TRUE, length.out = length(x))
   sel[x < 0.5] <- FALSE
   return(sel)
 } 
# The whole polygon will be removed or kept.  
 plot(x = selectplist(plist, SS), 
   xlim = c(0, 1), ylim = c(0, 1), zlim = c(0, 1))

# restore plotting parameters
 par(mfrow = pm)
 par(mar = pmar)