drawScene               package:misc3d               R Documentation

_R_e_n_d_e_r_i_n_g _o_f _T_r_i_a_n_g_u_l_a_r _M_e_s_h _S_u_r_f_a_c_e _D_a_t_a

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

     Draw scenes consisting of one or more surfaces described by
     triangular mesh data structures.

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

     drawScene(scene, light = c(0, 0, 1),
               screen = list(z = 40, x = -60), scale = TRUE, R.mat = diag(4),
               perspective = FALSE, distance = if (perspective) 0.2 else 0, 
               fill = TRUE, xlim = NULL, ylim = NULL, zlim = NULL,
               aspect = c(1, 1), col.mesh = if (fill) NA else "black",
               polynum = 100, lighting = phongLighting, add = FALSE,
               engine = "standard", col.bg = "transparent", depth = 0)
     drawScene.rgl(scene, add = FALSE, ...)

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

   scene: a triangle mesh object of class 'Triangles3D' or a list of
          such objects representing the scene to be rendered.

   light: numeric vector of length 3 or 4.  The first three elements
          represent the direction to the light in viewer coordinates;
          the viewer is at '(0, 0, 1 / distance)' looking down along
          the positive z-axis.  The fourth element, if present,
          represents light intensity; the default is 1.

  screen: as for 'panel.3dwire', a list giving sequence of rotations to
          be applied to the scene before being rendered. The initial
          position starts with the viewing point along the positive
          z-axis, and the x and y axes in the usual position. Each
          component of the list should be named one of "x", "y" or "z";
          repetitions are allowed.  The values values indicate the
          amount of rotation about that axis in degrees.

   scale: logical. Before viewing the x, y and z coordinates of the
          scene defining the surface are transformed to the interval
          [-0.5,0.5].  If 'scale' is true the x, y and z coordinates
          are transformed separately.  Otherwise, the coordinates are
          scaled so that aspect ratios are retained.

   R.mat: initial rotation matrix in homogeneous coordinates, to be
          applied to the data before 'screen' rotates the view further.

perspective: logical, whether to render a perspective view. Setting
          this to 'FALSE' is equivalent to setting 'distance' to 0

distance: numeric, between 0 and 1, controls amount of perspective. The
          distance of the viewing point from the origin (in the
          transformed coordinate system) is '1 / distance'. This is
          described in a little more detail in the documentation for
          'cloud'.

    fill: logical; if 'TRUE', drawing should use filled surfaces or
          wire frames as indicated by the object properties. Otherwise
          all objects in the scene should be rendered as wire frames.

xlim,ylim,zlim: x-, y-  and z-limits.  The scene is rendered so that
          the rectangular volume defined by these limits is visible.

  aspect: vector of length 2. Gives the relative aspects of the
          y-size/x-size and z-size/x-size of the enclosing cube.

col.mesh: color to use for the wire frame if 'frames' is true.

 polynum: integer.  Number of triangles to pass in batches to grid
          primitives for the "grid" engine.  The default should be
          adequate.

lighting: a lighting function.  Current options are 'phongLighting' and
          'perspLighting'.

     add: logical; if 'TRUE', add to current 'rgl' graph.

  engine: character; currently "standard" or "grid".

  col.bg: background dolor to use in color depth cuing.

   depth: numeric, between 0 and 1.  Controls the amount of color
          blending to 'col.bg' for objects farther from the viewer.
          'depth' equal to zero means no depth cuing.

     ...: rgl material and texture properties; see documentation for
          'rgl.material'

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

     'drawScene' renders a scene consisting of one or more triangle
     mesh objects using standard or grid graphics.  Object-specific
     rendering features such as smoothing and material are controlled
     by setting in the objects.  Arguments to 'drawScene' control
     global factors such as viewer and light position.

     'drawScene.rgl' renders the scene in an rgl window.

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

     'drawScene.rgl' returns 'NULL'. The return value of 'drawScene' is
     the viewing transformation as returned by 'persp'.

_N_o_t_e:

     The "rgl" engine now uses the standard rgl coordinates instead of
     negating 'y' and swapping 'y' and 'z'. If you need to reproduce
     the previous behavior you can use
     'options(old.misc3d.orientation=TRUE)'.

     Transparency only works properly in the "rgl" engine.  For
     standard or grid graphics on pdf or quartz devices using alpha
     levels less than 1 does work but the triangle borders show as a
     less transparent mesh.

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

     'rgl.material'

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

       vtri <- local({
           z <- 2 * volcano
           x <- 10 * (1:nrow(z))
           y <- 10 * (1:ncol(z))
           surfaceTriangles(x, y, z, color="green3")
       })
       drawScene(vtri, scale = FALSE)
       drawScene(vtri, screen=list(x=40, y=-40, z=-135), scale = FALSE)
       drawScene(vtri, screen=list(x=40, y=-40, z=-135), scale = FALSE,
                 perspective = TRUE)
       drawScene(vtri, screen=list(x=40, y=-40, z=-135), scale = FALSE,
                 perspective = TRUE, depth = 0.4)

