rgl Overview

About this document

This document was written in R Markdown, using the knitr package for production. It corresponds to rgl version 0.100.54.

Most of the highlighted function names are HTML links. The internal links should work in any browser; the links to help topics should work if you view the vignette from within the R help system.

The document includes WebGL figures. To view these, you must have Javascript and WebGL enabled in your browser. Some older browsers may not support this – see http://get.webgl.org for tests and links to a discussion.

Primitive shapes

Just as we have points and lines in classic graphics, there are a number of low level functions in rgl to add graphical elements to the currently active plot. The “primitive” shapes are those that are native to OpenGL:

Each of the above functions takes arguments x, y and z, again using xyz.coords for flexibility. They group successive entries as necessary. For example, the triangles3d function takes each successive triple of points as the vertices of a triangle.

You can use these functions to annotate the current graph, or to construct a figure from scratch.

Constructed shapes

rgl also has a number of objects which it constructs from the primitives.

Axes and other “decorations”

The following low-level functions control the look of the graph:

For example, to plot three random triangles, one could use

triangles3d(cbind(x=rnorm(9), y=rnorm(9), z=rnorm(9)), col = "green")
decorate3d()
bg3d("lightgray")
aspect3d(1,1,1)

You must enable Javascript to view this page properly.

Besides the *3d functions mentioned above, there are even lower-level functions rgl.primitive, rgl.points, rgl.linestrips, rgl.lines, rgl.triangles, rgl.quads, rgl.texts, rgl.abclines, rgl.planes, rgl.bg, rgl.clipplanes, rgl.bbox, rgl.spheres, rgl.sprites, rgl.surface.
You should avoid using these functions, which do not work well with the higher level *3d functions. See the ?r3d help topic for details.

Lighting

In most scenes, objects are “lit”, meaning that their appearance depends on their position and orientation relative to lights in the scene. The lights themselves don’t normally show up, but their effect on the objects does.

Use the light3d function to specify the position and characteristics of a light. Lights may be infinitely distant, or may be embedded within the scene. Their characteristics include ambient, diffuse, and specular components, all defaulting to white. The ambient component appears the same from any direction. The diffuse component depends on the angle between the surface and the light, while the specular component also takes the viewer’s position into account.

The rgl.light function is a lower-level function with different defaults; users should normally use light3d.

Materials

The mental model used in rgl is that the objects being shown in scenes are physical objects in space, with material properties that affect how light reflects from them (or is emitted by them). These are mainly controlled by the material3d function, or by arguments to other functions that are passed to it.

The material properties that can be set by calls to material3d are described in detail in the ?material3d help page. Here we give an overview.

Other properties include “texmipmap”, “texmagfilter”, “texminfilter”, “texenvmap”, “fog”, “point_antialias”, “line_antialias”, “depth_mask”, “depth_test” and “polygon_offset”; see the help page for details.

There is also an rgl.material function that works at a lower level; users should normally avoid it.

Textures

As described in the previous section, one of the material properties is texture, the name of a bitmap file (in .png format) containing an image to be displayed on the surface. This section gives more details about textures.

In OpenGL, each vertex in a polygon may be associated with a particular location in the bitmap. The interior of the polygon interpolates within the bitmap. There are two conventions in rgl functions for specifying these coordinates.

Functions which specify primitives (triangles3d, etc.) accept an optional matrix argument texcoords which gives s (horizontal) and t (vertical) locations within the bitmap in columns with one row per vertex. The coordinates are (0,0) for the lower left, and (1,1) for the upper right. If values outside this range are given, the image repeats, i.e. (1.1, 1.1) would specify the same point in the image as (0.1, 0.1).

Other functions such as surface3d that take matrices for each vertex coordinate accept texture coordinates as matrices as well, in arguments texture_s and texture_t.

For example, the following code displays four copies of a 2D plot on a quad, because the texture coordinates run from 0 to 2 in both s and t:

filename <- tempfile(fileext = ".png")
png(filename = filename)
plot(rnorm(1000), rnorm(1000))
dev.off()

## quartz_off_screen 
##                 2

open3d()

## null 
##   40

xyz <- cbind(c(0,1,1,0), 0, c(0,0,1,1))
quads3d(xyz, texture = filename, texcoords = xyz[,c(1, 3)]*2, col = "white", specular = "black")
rglwidget()

Some other notes:

• The color in the figure above was specified to be white. By default, the colors in the bitmap will modify the colour of the quad. If col is black (a common default), you won’t see anything.
• On the other hand, you usually don’t want specular reflections (which show up as glare). Setting specular to black prevents those.
• How the bitmap is handled is controlled by the material property "textype". The default is "rgb", which takes the red-green-blue colours from the bitmap and uses them to modify the corresponding colours in the polygon. Other possibilities for "textype" are described in the material3d help page.
• The other "tex*" material properties control how the interpolation within the image is done.
• Modern OpenGL supports 1- and 3-dimensional textures; these are not supported in rgl.

par3d: Miscellaneous graphical parameters

The par3d function, modelled after the classic graphics par function, sets or reads a variety of different rgl internal parameters. Some parameters are completely read-only; others are fixed at the time the window is opened, and others may be changed at any time.

Default settings

The r3dDefaults list and the getr3dDefaults function control defaults in new windows opened by open3d.
The function looks for the variable in the user’s global environment, and if not found there, finds the one in the rgl namespace. This allows the user to override the default settings for new windows.

Once found, the r3dDefaults list provides initial values for par3d parameters, as well as defaults for material3d and bg3d in components "material" and "bg" respectively.

Specific solids

These functions generate specific shapes. Optional arguments allow attributes such as colour or transformations to be specified.

open3d()
cols <- rainbow(7)
layout3d(matrix(1:16, 4,4), heights=c(1,3,1,3))
text3d(0,0,0,"tetrahedron3d"); next3d()
shade3d(tetrahedron3d(col=cols[1])); next3d()
text3d(0,0,0,"cube3d"); next3d()
shade3d(cube3d(col=cols[2])); next3d()
text3d(0,0,0,"octahedron3d"); next3d()
shade3d(octahedron3d(col=cols[3])); next3d()
text3d(0,0,0,"dodecahedron3d"); next3d()
shade3d(dodecahedron3d(col=cols[4])); next3d()
text3d(0,0,0,"icosahedron3d"); next3d()
shade3d(icosahedron3d(col=cols[5])); next3d()
text3d(0,0,0,"cuboctahedron3d"); next3d()
shade3d(cuboctahedron3d(col=cols[6])); next3d()
text3d(0,0,0,"oh3d"); next3d()
shade3d(oh3d(col=cols[7]))

You must enable Javascript to view this page properly.

A very large collection of polyhedra is contained in the Rpolyhedra package.

Generating new shapes

These functions generate new shapes:

A related function is triangulate, which takes a two dimensional polygon and divides it up into triangles using the “ear-clipping” algorithm.

The generic function as.mesh3d is provided to allow data structures produced by other code to be converted to mesh structures. Currently the following classes are supported:

The default as.mesh3d.default method is a simple way to construct a mesh from a matrix of vertices; it can use mergeVertices (which can also be used on its own) to merge repeated vertices within the matrix, allowing addNormals to be used to give a smooth appearance.

The underlying class structure for shapes

"shape3d" is the basic abstract type. Objects of this class can be displayed by shade3d (which shades faces), wire3d (which draws edges), or dot3d (which draws points at each vertex.)

"mesh3d" is a descendant type. Objects of this type contain the following fields:

Manipulating shapes

The final set of functions manipulate and modify mesh objects:

The individual steps in subdivision3d are also available: deform.mesh3d, divide.mesh3d, normalize.mesh3d. These are mainly intended for internal use.

User interaction

By default, rgl detects and handles mouse clicks within your scene, and uses these to control its appearance. You can find out the current handlers using the following code:

par3d("mouseMode")

##        left       right      middle       wheel 
## "trackball"      "zoom"       "fov"      "pull"

The labels c("left", "right", "middle") refer to the buttons on a three button mouse, or simulations of them on other mice. "wheel" refers to the mouse wheel.

The button actions generally correspond to click and drag operations. Possible values for “mouseMode” for buttons or the wheel are as follows:

The following functions make use of the mouse for selection within a scene.

The rgl.select3d function is an obsolete version of select3d, and rgl.select is a low-level support function.

Animations

rgl has several functions that can be used to construct animations. These are based on functions that update the scene according to the current real-world time, and repeated calls to those. The functions are:

See the movie3d function for a way to output an animation to a file on disk.
Animations are not currently supported in the HTML written by rglwidget, though the playwidget function provides equivalent functionality.

Integration with TCL/TK

There are three functions in rgl that support control of an rgl scene using the TCL/TK framework.

These functions were formerly contained (without the tk prefixes on their names) in the tkrgl package. That package is now deprecated.

Exporting and importing scenes

rgl contains several functions to write scenes to disk for use by other software, or to read them in.

In order from highest fidelity to lowest, the functions are:

There are also functions to save snapshots or other recordings of a scene, without any 3D information being saved:

The rgl.snapshot function is identical to snapshot3d. The functions rgl.Sweave.off, Sweave.snapshot are involved in Sweave processing and not normally called by users.

Default display

There are two ways in which rgl scenes are normally displayed within R. The older one is in a dedicated window. In Unix-alikes this is an X11 window; it is a native window in Microsoft Windows. On MacOS, the XQuartz system (see http://xquartz.org) needs to be installed to support this.

To suppress this display, set options(rgl.useNULL = TRUE) before opening a new rgl window. See the help page for the rgl.useNULL function for how to set this before starting R.

The newer way to display a scene is by using WebGL in a browser window or in the Viewer pane in RStudio. To select this, set options(rgl.printRglwidget = TRUE). Each operation that would change the scene will return a value which triggers a new WebGL display when printed.

Working with WebGL scenes

There are currently two schemes for exporting a scene to a web page.

The recommended approach works with the htmlwidgets framework (see http://www.htmlwidgets.org/). In an R Markdown document in knitr, use the rglwidget function. (You can also use chunk option webgl=TRUE; we recommend the explicit use of rglwidget.) This approach also allows display of rgl scenes in RStudio. Besides rgl scenes, various controls for them can be displayed, and there are a few utility functions that can be useful:

Some functions are mainly for internal use: elementId2Prefix, playwidgetOutput, renderPlaywidget, rglwidgetOutput, renderRglwidget, registerSceneChange. More details are given in the vignette User Interaction in WebGL. The functions lowlevel, highlevel, rglId are also for internal use, marking function results for automatic printing. Finally, the experimental function setUserShaders allows you to use hand-written shaders in WebGL.

The older approach uses the writeWebGL function to export a scene to HTML and Javascript code.
The functions below write HTML and Javascript for working with the exported scene.

Working with the scene

rgl maintains internal structures for all the scenes it displays. The following functions allow users to find information about them and manipulate them.

The as.triangles3d generic function is intended to extract coordinates in a form suitable for passing to triangles3d. Currently a method is provided for rglId objects.

In addition to these, there are some other related functions which should rarely be called by users: rgl.init, rgl.open, rgl.quit.

Working with 3-D vectors

Most rgl functions work internally with “homogeneous” coordinates. In this system, 3-D points are represented with 4 coordinates, generally called (x, y, z, w). The corresponding Euclidean point is (x/w, y/w, z/w), if w is nonzero; zero values of w correspond to “points at infinity”. The advantage of this system is that affine transformations including translations and perspective shifts become linear transformations, with multiplication by a 4 by 4 matrix.

rgl has the following functions to work with homogeneous coordinates:

There is also a function GramSchmidt, mainly for internal use: it does a Gram-Schmidt orthogonalization of a 3x3 matrix, with some specializations for its use in cylinder3d.

Working with other packages

Sometimes it may be convenient to interactively rotate a scene to a particular view, then display it in lattice or base graphics. The rglToLattice and rglToBase functions support this.

For example, we first display the volcano data in rgl:

persp3d(volcano, col = "green")
rglwidget()

lattice::wireframe(volcano, col = "green", 
           screen = rglToLattice())

angles <- rglToBase()
persp(volcano, col = "green", shade = TRUE,
      theta = angles$theta, phi = angles$phi)

Note that the orientlib package must be available for these functions to work.