# rgl.surface

##### add height-field surface shape

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.

- Keywords
- dynamic

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

```
# NOT RUN {
#
# 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")
# }
```

*Documentation reproduced from package rgl, version 0.100.50, License: GPL*