shade3d {rgl}

Draw 3D mesh objects

Description

Draws 3D mesh objects in full, or just the edges, or just the vertices.

Usage

  dot3d(x, ...)   # draw dots at the vertices of an object
  ## S3 method for class 'mesh3d'
dot3d(x, ...,
                         front = "points", back = "points")
  wire3d(x, ...)  # draw a wireframe object
  ## S3 method for class 'mesh3d'
wire3d(x, ...,
                          front = "lines", back = "lines")
  shade3d(x, ...) # draw a shaded object
  ## S3 method for class 'mesh3d'
shade3d(x, override = TRUE, 
                           meshColor = c("vertices", "edges", "faces", "legacy"), 
                           texcoords = NULL, ...,
                           front = "filled", back = "filled")

Arguments

x

a mesh3d object.

...

additional rendering parameters, or for dots3d and wire3d, parameters to pass to shade3d

override

should the parameters specified here override those stored in the object?

meshColor

how should colours be interpreted? See details below

texcoords

texture coordinates at each vertex.

front, back

Material properties for rendering.

Details

The meshColor argument controls how material colours and textures are interpreted. This parameter was added in rgl version 0.100.1 (0.100.27 for dot3d). Possible values are:

"vertices"

Colours and texture coordinates are applied by vertex, in the order they appear in the x$vb matrix.

"edges"

Colours are applied to each edge: first to the segments in the x$is matrix, then the 3 edges of each triangle in the x$it matrix, then the 4 edges of each quad in the x$ib matrix. This mode is only supported if both front and back materials are "lines", and the mesh contains no points.

"faces"

Colours are applied to each object in the mesh: first to the points, then the segments, triangles and finally quads. The entire whole face (or point or segment) receives one colour from the specified colours.

"legacy"

Colours and textures are applied in the same way as in rgl versions earlier than 0.100.1.

Unique partial matches of these values will be recognized.

If colours are specified but meshColor is not and options(rgl.meshColorWarning = TRUE), a warning will be given that their interpretation may have changed. In versions 0.100.1 to 0.100.26 of rgl, the default was to give the warning; now the default is for no warning.

Note that since version 0.102.10, meshColor = "edges" is only allowed when drawing lines (the wire3d default), and it may draw edges more than once. In general, if any rendering draws twice at the same location, which copy is visible depends on the order of drawing and the material3d("depth_test") setting.

Whether points, lines or solid faces are drawn is determined in 3 steps:

1. If arguments "front" or "back" are specified in the call, those are used.

2. If one or both of those arguments are not specified, but the material properties are present in the object, those are used.

3. If values are not specified in either of those places, shade3d draws filled surfaces, wire3d draws lines, and dot3d draws points.

Note: For some versions of rgl up to version 0.107.15, rule 2 above was not respected.

Value

dot3d, wire3d, and shade3d are called for their side effect of drawing an object into the scene; they return an object ID (or vector of IDs) invisibly.

See primitives for a discussion of texture coordinates.

See Also

mesh3d, par3d, shapelist3d for multiple shapes

Examples

  # generate a quad mesh object

  vertices <- c( 
     -1.0, -1.0, 0,
      1.0, -1.0, 0,
      1.0,  1.0, 0,
     -1.0,  1.0, 0
  )
  indices <- c( 1, 2, 3, 4 )
  
  open3d()  
  wire3d( mesh3d(vertices = vertices, quads = indices) )
  
  # render 4 meshes vertically in the current view

  open3d()  
  bg3d("gray")
  l0 <- oh3d(tran = par3d("userMatrix"), color = "green" )
  shade3d( translate3d( l0, -6, 0, 0 ))
  l1 <- subdivision3d( l0 )
  shade3d( translate3d( l1 , -2, 0, 0 ), color = "red", override = FALSE )
  l2 <- subdivision3d( l1 )
  shade3d( translate3d( l2 , 2, 0, 0 ), color = "red", override = TRUE )
  l3 <- subdivision3d( l2 )
  shade3d( translate3d( l3 , 6, 0, 0 ), color = "red" )
  
  # render all of the Platonic solids
  open3d()
  shade3d( translate3d( tetrahedron3d(col = "red"), 0, 0, 0) )
  shade3d( translate3d( cube3d(col = "green"), 3, 0, 0) )
  shade3d( translate3d( octahedron3d(col = "blue"), 6, 0, 0) )
  shade3d( translate3d( dodecahedron3d(col = "cyan"), 9, 0, 0) )
  shade3d( translate3d( icosahedron3d(col = "magenta"), 12, 0, 0) )