perspbox: Creates an empty perspective box, ready for adding objects

In plot3D: Plotting Multi-Dimensional Data

Description

perspbox draws a box and labels, and makes space for a colorkey (if any).

Usage

perspbox (x = seq(0, 1, length.out = nrow(z)), 
          y = seq(0, 1, length.out = ncol(z)), z, 
          bty = c("b", "b2", "f", "g", "bl", "bl2", "u", "n"),  ..., 
          col.axis = "black", col.panel = NULL, lwd.panel = 1,                     
          col.grid = NULL, lwd.grid = 1, 
          phi = 40, theta = 40, col = NULL,
          colkey = NULL, plot = TRUE)

Arguments

x, y	Vectors with x and y values. It is sufficient to pass the ranges of the x- and y-values, as they will not be drawn. If z is a matrix, it is required that length(x) = nrow(z) and length(y) = ncol(z).
z	Matrix or vector with z-values. If z is a matrix, it is sufficient to pass a diagonal matrix with the range of the z-values, as they will not be drawn.
bty	The type of the box; only effective if the persp argument box equals TRUE (the default). Unless bty is equal to "u" then the arguments col.axis, col.panel, lwd.panel, col.grid, lwd.grid will be ignored. "f" is the full box, the default as from persp, "b" has only the back panels visible, when "b2" has back panels and grid lines, "g" has grey background with white gridlines, "bl" has a black background, "bl2" has a black background with grey lines. "u" means that the user will specify the arguments col.axis, col.panel, lwd.panel, col.grid, lwd.grid manually. "n" means that no box will be drawn. This is the same as setting box = FALSE.
col.axis, col.panel, col.grid	The color of the axis line, of the axis panel or of the grid lines. Only used if bty = "u".
lwd.panel, lwd.grid	The width of the panel border or of the grid lines. Only used if bty = "u".
theta, phi	The angles defining the viewing direction. theta gives the azimuthal direction and phi the colatitude. see persp.
col	Colors to be used for coloring the colvar variable. Here only used for assessing if a color key should be drawn.
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, adj.clab, font.clab and the axis parameters at, labels, tick, line, pos, outer, font, lty, lwd, lwd.ticks, col.box, col.axis, col.ticks, hadj, padj, cex.axis, mgp, tck, tcl, las. The defaults for the parameters are side = 4, plot = TRUE, length = 1, width = 1, dist = 0, shift = 0, addlines = FALSE, col.clab = NULL, cex.clab = par("cex.lab"), side.clab = NULL, line.clab = NULL, adj.clab = NULL, font.clab = NULL) See colkey. The default is to draw the color key on side = 4, i.e. in the right margin. If colkey = NULL then a color key will be added only if col is a vector. Setting colkey = list(plot = FALSE) will create room for the color key without drawing it. if colkey = FALSE, no color key legend will be added.
plot	Logical. If TRUE (default), a plot is created, otherwise the viewing transformation matrix is returned (as invisible).
...	additional arguments passed to persp. The following persp arguments can be specified: xlim, ylim, zlim, xlab, ylab, zlab, main, sub, r, d, scale, expand, box, axes, nticks, ticktype. Arguments scale and expand affect the size of the axes. The arguments after ... must be matched exactly.

Details

The arguments xlim, ylim, zlim only affect the axes. All objects will be plotted, including those that fall out of these ranges. To select objects only within the axis limits, use plotdev.

The predefined box types bty are defined as follows:

“f”: all panels are shown and transparent, also the persp default.

“b”: only backward panels shown.

“b2”: as “b” with col.grid = "grey".

“g”: only backward panels shown; col.panel = grey(0.95), col.axis = "grey", lwd.grid = 2 and col.grid = "white".

“bl”: only backward panels shown; col.panel = "black", col.axis = "grey", lwd.grid = 2 and col.grid = "white".

“n”: no box is drawn.

Value

Function perspbox returns the viewing transformation matrix. See trans3D.

Author(s)

Karline Soetaert <[e-mail]>

See Also

persp3D, scatter2D, surf3D for examples where box types different than the default are used.

Hypsometry for an example where colored axis-panels are added to a figure started with perspbox.

Examples

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

## ========================================================================
## The 4 predefined box types
## ========================================================================

 par(mfrow = c(2, 2), mar = c(1, 1, 1, 1))
 
# box type with only backward panels
 perspbox(z = volcano, bty = "b", ticktype = "detailed", d = 2, 
          main  = "bty = 'b'")
# box as in 'persp'
 perspbox(z = volcano, bty = "f", ticktype = "detailed", 
          d = 2, main  = "bty = 'f'")

# back panels with gridlines, detailed axes
 perspbox(z = volcano, bty = "b2", ticktype = "detailed", 
          d = 2, main  = "bty = 'b2'")

# ggplot-type, simple axes 
 perspbox(z = volcano, bty = "g", 
          d = 2, main  = "bty = 'g'")

## ========================================================================
## A user-defined box
## ========================================================================

 par(mfrow = c(1, 1))

 perspbox(z = diag(2), bty = "u", ticktype = "detailed", 
          col.panel = "gold", col.axis = "white",  
          scale = FALSE, expand = 0.4, 
          col.grid = "grey", main = "user-defined")

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

Example output

plot3D documentation built on May 19, 2021, 3 p.m.