R: add height-field surface shape

rgl.surface {rgl} | R Documentation

## add height-field surface shape

### Description

Adds a surface to the current scene. The surface is defined by a matrix defining the height of each grid point and two vectors defining the grid.

### Usage

    rgl.surface(x, z, y, coords = 1:3, ...,
                normal_x = NULL, normal_y = NULL, normal_z = NULL,
                texture_s = NULL, texture_t = NULL)

### Arguments

`x` | values corresponding to rows of `y`, or matrix of x coordinates
`y` | matrix of height values
`z` | values corresponding to columns of `y`, or matrix of z coordinates
`coords` | See details
`...` | Material and texture properties. See `rgl.material` for details.
`normal_x, normal_y, normal_z` | matrices of the same dimension as `y` giving the coordinates of normals at each grid point
`texture_s, texture_t` | matrices of the same dimension as `z` giving the coordinates within the current texture of each grid point

### Details

Adds a surface mesh to the current scene. The surface is defined by the matrix of height values in `y`, with rows corresponding to the values in `x` and columns corresponding to the values in `z`.

The `coords` parameter can be used to change the geometric interpretation of `x`, `y`, and `z`. The first entry of `coords` indicates which coordinate (`1 = X`, `2 = Y`, `3 = Z`) corresponds to the `x` parameter. Similarly the second entry corresponds to the `y` parameter, and the third entry to the `z` parameter. In this way surfaces may be defined over any coordinate plane.

If the normals are not supplied, they will be calculated automatically based on neighbouring points.

Texture coordinates run from 0 to 1 over each dimension of the texture bitmap. If texture coordinates are not supplied, they will be calculated to render the texture exactly once over the grid. Values greater than 1 can be used to repeat the texture over the surface.

`rgl.surface` always draws the surface with the ‘front’ upwards (i.e. towards higher `y` values). This can be used to render the top and bottom differently; see `rgl.material` and the example below.

If the `x` or `z` argument is a matrix, then it must be of the same dimension as `y`, and the values in the matrix will be used for the corresponding coordinates. This is used to plot shapes such as cylinders where y is not a function of x and z.

`NA` values in the height matrix are not drawn.

### Value

The object ID of the displayed surface is returned invisibly.

### See Also

`rgl.material`, `surface3d`, `terrain3d`. See `persp3d` for a higher level interface.

### Examples

    #
    # volcano example taken from "persp"
    #

    data(volcano)

    y <- 2 * volcano        # Exaggerate the relief

    x <- 10 * (1:nrow(y))   # 10 meter spacing (S to N)
    z <- 10 * (1:ncol(y))   # 10 meter spacing (E to W)

    ylim <- range(y)
    ylen <- ylim[2] - ylim[1] + 1

    colorlut <- terrain.colors(ylen) # height color lookup table

    col <- colorlut[ y - ylim[1] + 1 ] # assign colors to heights for each point

    rgl.open()
    rgl.surface(x, z, y, color = col, back = "lines")

[Package rgl version 0.99.9 Index]