drawScene: Rendering of Triangular Mesh Surface Data

Description

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

Usage

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,
          newpage = TRUE)
drawScene.rgl(scene, add = FALSE, ...)

Arguments

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 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. Ignored if draw = TRUE

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

newpage

logical; if TRUE, and add is true, then the "grid" engine will call "grid.newpage"; otherwise the current page is used.

...

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

Value

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

Details

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.

If add=TRUE in standard or grid graphics then coordinates are not further scaled after the transformations implied by R.mat, and distance are applied. For the grid engine drawing occurs in the current viewport.

Examples

Run this code

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