rgl package is used to produce interactive 3-D plots. It contains high-level graphics commands modelled loosely after classic R graphics, but working in three dimensions. It also contains low level structure inspired by (but incompatible with) the
This document gives an overview. See the help pages for details.
For installation instructions, see the
README file in the top level directory of the source tarball rgl_0.104.16.tar.gz (or a later version).
This document was written in R Markdown, using the
knitr package for production. It corresponds to rgl version 0.104.16.
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.
can be used to plot three columns of the
iris data. Allowed plot types include
"p", "l", "h", "s", meaning points, lines, segments from z=0, and spheres. There’s a lot of flexibility in specifying the coordinates; the
xyz.coords function from the
grDevices package is used for this.
You can use your mouse to manipulate the plot. The default is that if you click and hold with the left mouse button, you can rotate the plot by dragging it. The right mouse button is used to resize it, and the middle button changes the perspective in the point of view.
The other high level function is
persp3d to draw surfaces. It is similar to the classic
persp function, but with greater flexibility. First, any of
z can be specified using matrices, not just
z. This allows parametric surfaces to be plotted. An even simpler specification is possible:
x may be a function, in which case
persp3d will work out the grid itself. See ?persp3d.function for details. For example, the
MASS package estimates Gamma parameters using maximum likelihood in a ?MASS::fitdistr example. Here we show the log likelihood surface.
library(MASS) # from the fitdistr example set.seed(123) x <- rgamma(100, shape = 5, rate = 0.1) fit <- fitdistr(x, dgamma, list(shape = 1, rate = 0.1), lower = 0.001) loglik <- function(shape, rate) sum(dgamma(x, shape=shape, rate=rate, log=TRUE)) loglik <- Vectorize(loglik) xlim <- fit$estimate+4*fit$sd*c(-1,1) ylim <- fit$estimate+4*fit$sd*c(-1,1) mfrow3d(1, 2, sharedMouse = TRUE) persp3d(loglik, xlim = xlim, ylim = ylim, n = 30) zlim <- fit$loglik + c(-qchisq(0.99, 2)/2, 0) next3d() persp3d(loglik, xlim = xlim, ylim = ylim, zlim = zlim, n = 30)
Note: this example used the
knitr hook functions (see
setupKnitr) to insert the scene into this vignette; the previous example used the
rglwidget function. We generally recommend the newer
Note that both
persp3d are generic functions, with the following methods defined:
##  plot3d.ashape3d* plot3d.default* plot3d.deldir* ##  plot3d.formula* plot3d.function* plot3d.lm* ##  plot3d.mesh3d* plot3d.rglWebGL* plot3d.rglbackground* ##  plot3d.rglbboxdeco* plot3d.rglobject* plot3d.rglscene* ##  plot3d.rglsubscene* plot3d.tri* plot3d.triSht* ## see '?methods' for accessing help and source code
##  persp3d.ashape3d* persp3d.default* persp3d.deldir* persp3d.formula* ##  persp3d.function* persp3d.tri* persp3d.triSht* ## see '?methods' for accessing help and source code
Just as we have
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:
||adds line segments|
Each of the above functions takes arguments
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.
rgl also has a number of objects which it constructs from the primitives.
||adds straight lines to plot (like
||adds spherical arcs or spirals to plot|
||adds planes to plot|
||add clipping planes to plot|
||add sprites (fixed shapes or images) to plot|
||a surface (as used in
||add an arrow to a scene|
||draw base-style plotting symbols|
The following low-level functions control the look of the graph:
||add axes to plot|
||add box around plot|
||add title to plot|
||add marginal text to plot|
||add multiple “decorations” (scales, etc.) to plot|
||set the aspect ratios for the plot|
||set the background of the scene|
||show a 2D plot or image in a 3D scene|
||set a legend for the scene|
||add a reference grid to a graph|
||choose label positions to avoid overlap|
For example, to plot three random triangles, one could use
*3d functions mentioned above, there are even lower-level functions
You should avoid using these functions, which do not work well with the higher level
*3d functions. See the ?r3d help topic for details.
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.
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
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 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.
|color||white||vector of surface colors to apply to successive vertices for diffuse light|
|alpha||1||transparency: 0 is invisible, 1 is opaque|
|lit||TRUE||whether lighting calculations should be done|
|ambient||black||color in ambient light|
|specular||white||color in specular light|
|emission||black||color emitted by the surface|
|shininess||50||controls the specular lighting: high values look shiny|
|smooth||TRUE||whether shading should be interpolated between vertices|
|texture||NULL||optional path to a “texture” bitmap to be displayed on the surface|
|front, back||fill||should polygons be filled, or outlined?|
|size||3||size of points in pixels|
|lwd||1||width of lines in pixels|
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.
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.
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
Other functions such as
surface3d that take matrices for each vertex coordinate accept texture coordinates as matrices as well, in arguments
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
## quartz_off_screen ## 2
## null ## 35
Some other notes:
colis black (a common default), you won’t see anything.
specularto black prevents those.
"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.
"tex*"material properties control how the interpolation within the image is done.
OpenGLsupports 1- and 3-dimensional textures; these are not supported in
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.
|antialias||fixed||Amount of hardware antialiasing|
|cex||Default size for text|
|family||Device-independent font family name; see ?text3d|
|font||Integer font number|
|useFreeType||Should FreeType fonts be used if available?|
|fontname||read-only||System-dependent font name set by
|FOV||Field of view, in degrees. Zero means isometric perspective|
|maxClipPlanes||read-only||How many clip planes can be defined?|
|modelMatrix||read-only||The OpenGL ModelView matrix; partly set by
|projMatrix||read-only||The OpenGL Projection matrix|
|bbox||read-only||Current bounding-box of the scene|
|viewport||Dimensions in pixels of the scene within the window|
|windowRect||Dimensions in pixels of the window on the whole screen|
|listeners||Which subscenes respond to mouse actions in the current one|
|mouseMode||What the mouse buttons do. See
|observer||read-only||The position of the observer; set by
|scale||Rescaling for each coordinate; see
|zoom||Magnification of the scene|
r3dDefaults list and the
getr3dDefaults function control defaults in new windows opened by
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.
rgl includes a number of functions to construct and display various solid shapes. These generate objects of class
"shapelist3d". The details of the classes are described below. We start with functions to generate them.
These functions generate specific shapes. Optional arguments allow attributes such as colour or transformations to be specified.
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)); next3d() text3d(0,0,0,"cube3d"); next3d() shade3d(cube3d(col=cols)); next3d() text3d(0,0,0,"octahedron3d"); next3d() shade3d(octahedron3d(col=cols)); next3d() text3d(0,0,0,"dodecahedron3d"); next3d() shade3d(dodecahedron3d(col=cols)); next3d() text3d(0,0,0,"icosahedron3d"); next3d() shade3d(icosahedron3d(col=cols)); next3d() text3d(0,0,0,"cuboctahedron3d"); next3d() shade3d(cuboctahedron3d(col=cols)); next3d() text3d(0,0,0,"oh3d"); next3d() shade3d(oh3d(col=cols))
A very large collection of polyhedra is contained in the Rpolyhedra package.
These functions generate new shapes:
||generate a tube or cylinder|
||generate a flat polygon by triangulation|
||generate an “extrusion” of a polygon|
||generate a solid of rotation|
||generate an ellipsoid in various ways|
||generate a shape from vertices and faces|
||generate a shape by combining other shapes|
||a generic function; see below|
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:
||Delaunay triangulations of irregular point clouds|
||Also Delaunay triangulations|
||Generalized Delaunay triangulations|
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.
"mesh3d" is a descendant type. Objects of this type contain the following fields:
|vb||A 4 by n matrix of vertices in homogeneous coordinates. Each column is a point.|
|it||(optional) A 3 by t matrix of vertex indices. Each column is a triangle.|
|ib||(optional) A 4 by q matrix of vertex indices. Each column is a quadrilateral.|
|material||(optional) A list of material properties.|
|normals||(optional) A matrix of the same shape as vb, containing normal vectors at each vertex.|
|texcoords||(optional) A 2 by n matrix of texture coordinates corresponding to each vertex.|
|values||(optional) A vector of length n holding values at each vertex|
These functions compute and plot contours of functions on surfaces, or clip objects along a contour of a function.
||draw contour lines on surface|
||fill between contours on surface|
||clip mesh object using curved boundary|
||clip general object using curved boundary|
These functions manipulate and modify mesh objects:
||add normal vectors to make a shape look smooth|
||add extra vertices to make it look even smoother|
||merge mesh objects|
rgl has several functions to support displaying multiple different “subscenes” in the same window. The high level functions are
||Multiple figures (like par(“mfrow”)|
||Multiple figures (like
||Move to the next figure (like
||List all the subscenes in the current layout|
||Clear the current list and revert to the previous one|
There are also lower level functions.
||Create a new subscene, with fine control over what is inherited from the parent|
||Report on the active subscene|
||Get information on current subscene|
||Make a different subscene active|
||Add objects to a subscene, or delete them|
||Do “garbage collection”: delete objects that are not displayed in any subscene|
rgl package can produce output that can be embedded in other documents. The recommended way to do this has changed several times over the years. We will start with the current recommendation, then list older methods.
Currently the best way to embed an
rgl scene in a document is to produce the document in HTML using R Markdown. Early in the document, you should have code like this in one of the setup code chunks:
The call to
setupKnitr() will install a number of hooks and set options in
knitr so that
rgl code is handled properly. The
autoprint = TRUE argument makes
rgl act in the document almost the same way it would act in the console, or the way base graphics are handled by
knitr: If you print the value of high level
rgl functions, a plot will be inserted into the output, but maybe only after low level modifications to it are complete. For example, this code block prints both triangles and spheres in a single plot at the end:
There are a few differences if you have a complicated situation:
rglfunction calls being automatically printed. If the calls are in a loop or other code block where automatic printing doesn’t happen, you’ll need some trickery to get things to print. For example, this will print three plots:
rglfunctions return results using
highlevel()to mark which kind of plot they are. If you are using a function from another package to produce the plot, you may need to insert an explicit call to one of those to get it to print. Use
lowlevel()if the function just modifies an existing plot,
highlevel()if it starts a new one. For example,
This should display the output at the end of the code chunk, when modifications are assumed complete.
While some PDF previewers support interactive 3D graphics, most don’t. To produce a screenshot of an
rgl scene in an R Markdown document with PDF output, simply follow the directions given above. The auto-printing will detect PDF output and use
rgl.snapshot to produce a PNG file to insert. (See below if you want to insert a different format of graphic.)
If you really need interactive output, see the
You may not want to use the
setupKnitr(autoprint = TRUE) method described above. It is very new, and may still have bugs; you may have an older document and not want to edit it to work that way.
In this case, you can insert plots manually. Use setup code
rglwidget() at top level whenever you want to insert a plot.
There are a couple of other differences in default behaviour if you are not using
By default, each code chunk continues the
rgl scene from earlier chunks. You’ll need an explicit
open3d call to get a clean window.
Also by default, the
rgl window is not closed at the end of the chunk. This probably doesn’t matter, but you may find you run out of memory if your scenes are really big.
The original way to insert an
rgl scene in a document was to use the
writeWebGL function to write HTML code to insert in a document. Later,
knitr hooks were added. These are no longer maintained, and it is recommended that you update old documents to use the newer methods. See the
hook_rgl help topics for details on these if you must use them. If you are reading documents that suggest using those methods, let the author know they need updating!
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:
## left right middle wheel ## "trackball" "zoom" "fov" "pull"
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 mouse acts as a virtual trackball. Clicking and dragging rotates the scene|
||The mouse affects rotations by controlling polar coordinates directly|
||The mouse is being used by the
||The mouse zooms the display|
||The mouse affects perspective by changing the field of view|
||Rotating the mouse wheel towards the user “pulls the scene closer”|
||The same rotation “pushes the scene away”|
||A user action set by
The following functions make use of the mouse for selection within a scene.
||like the classic graphics
||returns a function that tests whether a coordinate was selected|
||selects from specific objects|
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:
||Repeatedly call the update function|
||Update the display by rotating at a constant rate|
||Compute new values of some
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.
There are three functions in
rgl that support control of an
rgl scene using the TCL/TK framework.
||Set up buttons in a window to control a scene|
||Embed the control buttons in a separate TCL/TK frame|
||Create a dialog to interactively save mouse actions|
These functions were formerly contained (without the
tk prefixes on their names) in the
tkrgl package. That package is now deprecated.
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:
||Save a scene to an R variable, which can be saved and reloaded|
||Write files for Asymptote|
||Write PLY files (commonly used in 3D printing)|
||Read or write OBJ files (commonly used in 3D graphics)|
||Read or write STL files (also common in 3D printing)|
There are also functions to save snapshots or other recordings of a scene, without any 3D information being saved:
||Save a PNG file bitmap of the scene|
||Save a Postscript, LaTeX, PDF, SVG or PGF vector rendering of the scene|
||Save a series of bitmaps to be assembled into a movie|
||Obtain pixel-level information about the scene in an R variable|
||Driver function for inserting a snapshot into a Sweave document.|
||Function to set up
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 https://www.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.
You should use the following scheme for exporting a scene to a web page. There’s also an older scheme, which is no longer supported.
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:
||set individual properties|
||control a clipping plane|
||control which objects are displayed|
||“age” vertices of an object|
||control properties of vertices|
||WebGL control like
||display and automate controls|
||display a button to toggle some items|
||get or set
||Dimensions of figures in R Markdown document|
||share data using
||change mouse mode in rgl scene|
||arrange multiple objects in an HTML display|
Some functions are mainly for internal use:
registerSceneChange. More details are given in the vignette User Interaction in WebGL. The functions
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
matrixSetter. Use the newer functions instead.
rgl maintains internal structures for all the scenes it displays. The following functions allow users to find information about them and manipulate them. In cases where there are both
rgl.* versions of functions, most users should use the
*3d version: the
rgl.* functions are more primitive and are mainly intended for internal use.
||open a new window|
||close the current window|
||id of the active device|
||set a particular device to be active|
||delete an object from the scene|
||delete all objects of certain classes|
||ids and types of all current objects|
These functions are mainly intended for programming, and have no corresponding
||bring the current window to the top|
||ids of all active devices|
||attributes of objects in the scene|
||return information about the current projection|
||convert between coordinates in the current projection|
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:
||convert between homogeneous and Euclidean coordinates|
||apply a transformation|
||apply a general transformation|
||compute the transformation matrix|
||return a 4 x 4 identity matrix|