rgl (version 0.97.0)

persp3d.function: Plot a function of two variables

Description

Plot a function z(x, y) or a parametric function (x(s, t), y(s, t), z(s, t)).

Usage

"persp3d"(x,  xlim = c(0, 1), ylim = c(0, 1),  slim = NULL, tlim = NULL,  n = 101,  xvals = seq.int(min(xlim), max(xlim), length.out = n[1]),  yvals = seq.int(min(ylim), max(ylim), length.out = n[2]),  svals = seq.int(min(slim), max(slim), length.out = n[1]),  tvals = seq.int(min(tlim), max(tlim), length.out = n[2]),  xlab, ylab, zlab,  col = "gray", otherargs = list(),  normal = NULL, texture = NULL, ...)
"plot3d"(x, ...)

Arguments

x

A function of two arguments. See the details below.

xlim, ylim

By default, the range of x and y values. For a parametric surface, if these are not missing, they are used as limits on the displayed x and y values.

slim, tlim

If not NULL, these give the range of s and t in the parametric specification of the surface. If only one is given, the other defaults to c(0, 1).

n

A one or two element vector giving the number of steps in the x and y (or s and t) grid.

xvals, yvals

The values at which to evaluate x and y. Ignored for a parametric surface. If used, xlim and/or ylim are ignored.

svals, tvals

The values at which to evaluate s and t for a parametric surface. Only used if slim or tlim is not NULL. As with xvals and yvals, these override the corresponding slim or tlim specification.

xlab, ylab, zlab

The axis labels. See the details below for the defaults.

col

The color to use for the plot. See the details below.

otherargs

Additional arguments to pass to the function.

normal, texture

Functions to set surface normals or texture coordinates. See the details below.

...

Additional arguments to pass to persp3d.

Value

This function constructs a call to persp3d and returns the value from that function.

Details

The "function" method for plot3d simply passes all arguments to persp3d. Thus this description applies to both.

The first argument x is required to be a function. It is named x only because of the requirements of the S3 system; in the remainder of this help page, we will assume that the assignment f <- x has been made, and will refer to the function f().

persp3d.function evaluates f() on a two-dimensional grid of values, and displays the resulting surface. The values on the grid will be passed in as vectors in the first two arguments to the function, so f() needs to be vectorized. Other optional arguments to f() can be specified in the otherargs list.

In the default form where slim and tlim are both NULL, it is assumed that f(x, y) returns heights, which will be plotted in the z coordinate. The default axis labels will be taken from the argument names to f() and the expression passed as argument x to this function.

If slim or tlim is specified, a parametric surface is plotted. The function f(s, t) must return a 3-column matrix, giving x, y and z coordinates of points on the surface. The default axis labels will be the column names if those are present. In this case xlim, ylim and zlim are used to define a clipping region only if specified; the defaults are ignored.

The color of the surface may be specified as the name of a color, or a vector or matrix of color names. In this case the colors will be recycled across the points on the grid of values.

Alternatively, a function may be given: it should be a function like rainbow that takes an integer argument and returns a vector of colors. In this case the colors are mapped to z values.

The normal argument allows specification of a function to compute normal vectors to the surface. This function is passed the same arguments as f() (incuding otherargs if present), and should produce a 3-column matrix containing the x, y and z coordinates of the normals.

The texture argument is a function similar to normal, but it produces a 2-column matrix containing texture coordinates.

Both normal and texture may also contain matrices, with 3 and 2 columns respectively, and rows corresponding to the points that were passed to f().

See Also

The curve function in base graphics does something similar for functions of one variable. See the example below for space curves.

Examples

# (1) The Obligatory Mathematical surface.
#     Rotated sinc function, with colors

f <- function(x, y) { 
  r <- sqrt(x^2 + y^2)
  ifelse(r == 0, 10, 10 * sin(r)/r)
}
open3d()
plot3d(f, col = colorRampPalette(c("blue", "white", "red")), 
       xlab = "X", ylab = "Y", zlab = "Sinc( r )", 
       xlim = c(-10, 10), ylim = c(-10, 10),
       aspect = c(1, 1, 0.5))
       
# (2) A cylindrical plot

f <- function(s, t) {
  r <- 1 + exp( -pmin( (s - t)^2, 
                       (s - t - 1)^2, 
                       (s - t + 1)^2 )/0.01 )
  cbind(r*cos(t*2*pi), r*sin(t*2*pi), s)
}

open3d()
plot3d(f, slim = c(0, 1), tlim = c(0, 1), col = "red", alpha = 0.8)

# Add a curve to the plot, fixing s at 0.5.

plot3d(f(0.5, seq.int(0, 1, length.out = 100)), type = "l", add = TRUE, 
       lwd = 3, depth_test = "lequal")