persp3d.function {rgl} | R Documentation

## 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

    ## S3 method for class 'function'
    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, texcoords = NULL, ...)
    ## S3 method for class 'function'
    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, texcoords` | Functions to set surface normals or texture coordinates. See the details below.
`...` | Additional arguments to pass to `persp3d`.

### 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 `texcoords` argument is a function similar to `normal`, but it produces a 2-column matrix containing texture coordinates.

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

### Value

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

### Author(s)

Duncan Murdoch

### 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")

[Package rgl version 0.100.19 Index]