rgl.surface               package:rgl               R Documentation

_a_d_d _h_e_i_g_h_t-_f_i_e_l_d _s_u_r_f_a_c_e _s_h_a_p_e

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

      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

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     The object ID of the displayed surface is returned invisibly.

_S_e_e _A_l_s_o:

     'rgl.material', 'surface3d', 'terrain3d'

_E_x_a_m_p_l_e_s:

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

