image2Drgl: 2-D image, contour, scatterplots, segments and arrows in rgl.

Description

image2Drgl plots an image in rgl.

contour2Drgl creates a contourplot in rgl.

scatter2Drgl creates a scatterplot (lineplot, points, ...) in rgl.

points2Drgl is shorthand for scatter2Drgl(..., type = "p")

lines2Drgl is shorthand for scatter2Drgl(..., type = "l")

arrows2Drgl and segments3D plot arrows and segments in rgl.

text2Drgl plots labels in rgl.

These functions were implemented for their side effect that rgl plots can be zoomed, translocated, rectangular selections taken.

Usage

image2Drgl (z, x = seq(0, 1, length.out = nrow(z)), 
          y = seq(0, 1, length.out = ncol(z)), ...,
          col = NULL, NAcol = "white", breaks = NULL, border = NA,
          facets = TRUE, colkey = NULL, contour = FALSE,
          smooth = FALSE, clim = NULL, clab = NULL, shade = NA,
          inttype = 1, dz = 0, add = FALSE)
contour2Drgl (z, x = seq(0, 1, length.out = nrow(z)),
            y = seq(0, 1, length.out = ncol(z)), ...,
            col = NULL, colkey = NULL, clim = NULL, clab = NULL, dz = 0.1,
            add = FALSE)
scatter2Drgl (x, y, colvar = NULL, ...,
          col = NULL, NAcol = "white", breaks = NULL, colkey = NULL,
          clim = NULL, clab = NULL, CI = NULL, dz = 0.1, add = FALSE)
text2Drgl (x, y, labels, colvar = NULL, ...,
          col = NULL, NAcol = "white", breaks = NULL, colkey = NULL,
          clim = NULL, clab = NULL, dz = 0.1, add = FALSE)
arrows2Drgl (x0, y0, x1, y1, colvar = NULL, ...,
           col = NULL, NAcol = "white", breaks = NULL, colkey = NULL,
           clim = NULL, clab = NULL, type = "simple", dz = 0.1, add = FALSE)
segments2Drgl (x0, y0, x1, y1, colvar = NULL, ...,
           col = NULL, NAcol = "white", breaks = NULL, colkey = NULL,
           clim = NULL, clab = NULL, dz = 0.1, add = FALSE)
rect2Drgl (x0, y0, x1, y1, colvar = NULL, ...,
           col = NULL, NAcol = "white", breaks = NULL, colkey = NULL,
           clim = NULL, clab = NULL, dz = 0.1, add = FALSE)
lines2Drgl(x, y, ...)
points2Drgl(x, y, ...)

Arguments

x, y

Vectors with the x- and y- values.

z

The variable used for coloring the image plot, or containing the values to be plotted for the contour plot.

x0, y0

coordinates of points from which to draw the arrows.

x1, y1

coordinates of points to which to draw the arrows. At least one must be supplied.

colvar

The variable used for coloring the scatter plot or the arrows. If NULL, then col will be used as such.

labels

The text to be written. A vector of length equal to length of x, y.

col

Color palette to be used for the z or colvar variable. If colvar is NULL, then the colors are used as such.

NAcol

Color to be used for NA values; default is ``white''.

breaks

a set of finite numeric breakpoints for the colors; must have one more breakpoint than color and be in increasing order. Unsorted vectors will be sorted, with a warning.

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 will be colored as specified by col. If NA then the facets will be transparent.

shade

the degree of shading of the surface facets. Values of shade close to one yield shading similar to a point light source model and values close to zero produce no shading. Creates the illusion of perspective. See persp.

contour

If TRUE, then a contour plot will be added to the image plot. Also allowed is to pass a list with arguments for the contour2D function.

smooth

Logical, specifying whether Gouraud shading (smooth) or flat shading should be used. (if TRUE then function cutrgl will not work).

colkey

A logical, NULL (default), or a list with parameters for the color key (legend). Not all arguments from the original colkey function from plot3D are supported. For instance, color keys will always be put on the 4th margin.

clim

Only if colvar is specified, the range of the color variable used. Values of colvar that extend the range will be put to NA.

clab

Only if colkey = TRUE, 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 vector, with the first values empty strings.

inttype

The interpolation type to create the polygons, either interpolating the z (inttype = 1 or the x, y values (inttype = 2) - see persp3D.

CI

A list with parameters and values for the confidence intervals or NULL. If a list it should contain at least the item x or y. Other parameters should be one of (with defaults): alen = 0.01, lty = par("lty"), lwd = par("lwd"), col = NULL, to set the length of the arrow head, the line type and width, and the color. If col is NULL, then the colors of the scatter points are used.

type

The type of the arrow head, one of "simple" (the default, which uses R-function arrows) or "triangle".

dz

The 'layer depth', The z-position is defined as 1 + dz.

add

Logical. If TRUE, then the image, contour or points will be added to the current plot. If FALSE a new plot is started.

...

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, ticktype, shade, ltheta, lphi. In addition, the perspbox arguments col.axis, col.panel, lwd.panel, col.grid, lwd.grid can also be given a value.

Also the arguments lty, lwd can be specified.

The arguments after ... must be matched exactly.

Author

Karline Soetaert <karline.soetaert@nioz.nl>

Details

The first step in 2D rgl plotting consists in calling a 3-D function from package plot3D with argument plot set to FALSE.

image2Drgl and contour2Drgl call the image3D and contour3D functions of R-package plot3D, with colvar equal to z. Functions scatter2Drgl and arrows2Drgl call scatter3D and arrows3D.

The z value argument to the 3-D functions is set equal to 1 + dz; For contour3D, scatter3D and arrows3D, it is by default equal to 1.1, while for image3D it is 1. This way, contours, points, segments and arrows will be drawn on top of the image.

The next step is to create a 3-D rgl plot, by calling plotrgl. After that, the viewing arguments are set equal to view3d(phi = 0, fov = 0), i.e. the plot is viewed at from the top.

The actions of the mouse on the plots is to zoom (left, middle), and to move it (right key).

Examples

Run this code


## =======================================================================
## image and points
## =======================================================================
 image2Drgl(z = volcano, contour = TRUE, main = "volcano")
 scatter2Drgl(x = seq(0, 1, by = 0.2), y = seq(0, 1, by = 0.2), 
   cex = 3, add = TRUE)

if (FALSE) {
  cutrgl()    # select a rectangle
  uncutrgl()
}

## =======================================================================
## scatter points, and lines
## =======================================================================

 scatter2Drgl(cars[,1], cars[,2], xlab = "speed", ylab = "dist")
if (FALSE) {
  cutrgl()
}
 lc <- lowess(cars)
 scatter2Drgl(lc$x, lc$y, type = "l", add = TRUE, lwd = 4)
if (FALSE) {
  cutrgl()
  uncutrgl()
}

## =======================================================================
## confidence intervals
## =======================================================================
 x  <- sort(rnorm(10)) 
 y  <- runif(10)
 cv <- sqrt(x^2 + y^2)

 CI <- list(lwd = 2)
 CI$x <- matrix (nrow = length(x), ncol = 2, data = rep(0.125, 2*length(x)))
 scatter2D(x, y, colvar = cv, pch = 16, cex = 2, CI = CI)

 scatter2Drgl(x, y, colvar = cv, cex = 2, CI = CI)
 
## =======================================================================
## arrows
## =======================================================================

 arrows2Drgl(x0 = 100*runif(30), y0 = runif(30), x1 = 100*runif(30), 
    y1 = runif(30), length = 0.1*runif(30), col = 1:30, angle = 15:45, 
    type = c("simple", "triangle"), lwd = 2)

 x0 <- 1:30
 x1 <- 2:31
 arrows2Drgl(x0 = x0, y0 = sin(x0), x1 = x1, y1 = sin(x1), 
   colvar = x1, lwd = 2)