points3d                 package:rgl                 R Documentation

_a_d_d _p_r_i_m_i_t_i_v_e _s_e_t _s_h_a_p_e

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

     Adds a shape node to the current scene

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

     points3d(x, y = NULL, z = NULL,  ...)
     lines3d(x, y = NULL, z = NULL,  ...)
     segments3d(x, y = NULL, z = NULL, ...)
     triangles3d(x, y = NULL, z = NULL, ...)
     quads3d(x, y = NULL, z = NULL, ...)

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

 x, y, z: coordinates. Any reasonable way of defining the coordinates
          is acceptable.  See the function 'xyz.coords' for details.

    ... : Material properties. See 'rgl.material' for details.

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

     The functions 'points3d', 'lines3d', 'segments3d', 'triangles3d'
     and 'quads3d' add points, joined lines, line segments, filled
     triangles or quadrilaterals to the plots.  They correspond to the
     OpenGL types 'GL_POINTS, GL_LINE_STRIP, GL_LINES, GL_TRIANGLES'
     and 'GL_QUADS' respectively.  

     Points are taken in pairs by 'segments3d', triplets as the
     vertices of the triangles, and quadruplets for the quadrilaterals.
      Colours are applied vertex by vertex;  if different at each end
     of a line segment, or each vertex of a polygon, the colours are
     blended over the extent of the object.  Quadrilaterals must be
     entirely  in one plane and convex, or the results are undefined.

     These functions call the lower level functions 'rgl.points',
     'rgl.linestrips', and so on, and are provided for convenience.

     The appearance of the new objects are defined by the material
     properties. See 'rgl.material' for details.

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

     Each function returns the integer object ID of the shape that was
     added to the scene.  These can be passed to 'rgl.pop' to remove
     the object from the scene.

_A_u_t_h_o_r(_s):

     Ming Chen and Duncan Murdoch

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

     # Show 12 random vertices in various ways. 

     M <- matrix(rnorm(36), 3, 12, dimnames=list(c('x','y','z'), 
                                            rep(LETTERS[1:4], 3)))

     # Force 4-tuples to be convex in planes so that quads3d works.

     for (i in c(1,5,9)) {
         quad <- as.data.frame(M[,i+0:3])
         coeffs <- runif(2,0,3)
         if (mean(coeffs) < 1) coeffs <- coeffs + 1 - mean(coeffs)
         quad$C <- with(quad, coeffs[1]*(B-A) + coeffs[2]*(D-A) + A)
         M[,i+0:3] <- as.matrix(quad)
     }

     open3d()

     # Rows of M are x, y, z coords; transpose to plot

     M <- t(M)
     shift <- matrix(c(-3,3,0), 12, 3, byrow=TRUE)

     points3d(M, size=2)
     lines3d(M + shift)
     segments3d(M + 2*shift)
     triangles3d(M + 3*shift, col='red')
     quads3d(M + 4*shift, col='green')  
     text3d(M + 5*shift, texts=1:12)

     # Add labels

     shift <- outer(0:5, shift[1,])
     shift[,1] <- shift[,1] + 3
     text3d(shift, 
            texts = c('points3d','lines3d','segments3d',
              'triangles3d', 'quads3d','text3d'),
            adj = 0)
      rgl.bringtotop()

