Package 'rgl'

Description

3D real-time rendering system.

Details

RGL is a 3D real-time rendering system for R. Multiple windows are managed at a time. Windows may be divided into “subscenes”, where one has the current focus that receives instructions from the R command-line. The device design is oriented towards the R device metaphor. If you send scene management instructions, and there's no device open, it will be opened automatically. Opened devices automatically get the current device focus. The focus may be changed by using set3d() or useSubscene3d().

RGL provides medium to high level functions for 3D interactive graphics, including functions modelled on base graphics (plot3d(), etc.) as well as functions for constructing geometric objects (cube3d(), etc.). Output may be on screen using OpenGL, or to various standard 3D file formats including WebGL, PLY, OBJ, STL as well as 2D image formats, including PNG, Postscript, SVG, PGF.

The open3d() function attempts to open a new RGL window, using default settings specified by the user.

See the first example below to display the ChangeLog.

See Also

r3d for a description of the *3d interface; par3d for a description of scene properties and the rendering pipeline; rgl.useNULL for a description of how to use RGL on a system with no graphics support.

Examples

if (!in_pkgdown_example())
  file.show(system.file("NEWS", package = "rgl"))
example(surface3d)
example(plot3d)

Description

Mostly for internal use, this function returns the current device number if one exists, or opens a new device and returns that.

Usage

.check3d()

Value

The device number of an RGL device.

Author(s)

Duncan Murdoch

See Also

open3d

Examples

rgl.dev.list()
.check3d()
rgl.dev.list()
.check3d()
rgl.dev.list()
close3d()

Description

This adds mathematical lines to a scene. Their intersection with the current bounding box will be drawn.

Usage

abclines3d(x, y = NULL, z = NULL, a, b = NULL, c = NULL, ...)

Arguments

Details

Draws the segment of a line that intersects the current bounding box of the scene using the parametrization $(x, y, z) + (a, b, c) * s$ where $s$ is a real number.

Any reasonable way of defining the coordinates x, y, z and a, b, c is acceptable. See the function xyz.coords for details.

Value

A shape ID of the object is returned invisibly.

See Also

planes3d for mathematical planes.

segments3d draws sections of lines that do not adapt to the bounding box.

Examples

plot3d(rnorm(100), rnorm(100), rnorm(100))
abclines3d(0, 0, 0, a = diag(3), col = "gray")

Description

This generic function adds normals at each of the vertices of a polyhedron by averaging the normals of each incident face. This has the effect of making the surface of the object appear smooth rather than faceted when rendered.

Usage

addNormals(x, ...)
## S3 method for class 'mesh3d'
addNormals(x, angleWeighted = TRUE, ...)

Arguments

Details

Currently methods are supplied for "mesh3d" and "shapelist3d" classes.

These methods work by averaging the normals on the faces incident at each vertex. By default these are weighted according to the angle in the polygon at that vertex. If angleWeighted = FALSE, a slightly faster but less accurate weighting by the triangle area is used.

Prior to rgl version 0.104.12 an incorrect weighting was used; it can be partially reproduced by using angleWeighted = NA, but not all the bugs in that scheme will be kept.

Value

A new object of the same class as x, with normals added.

Author(s)

Duncan Murdoch

Examples

open3d()
y <- subdivision3d(tetrahedron3d(col = "red"), depth = 3)
shade3d(y) # No normals
y <- addNormals(y)
shade3d(translate3d(y, x = 1, y = 0, z = 0)) # With normals

Description

This is a function to produce actions in response to a playwidget or Shiny input control. The mental model is that each of the vertices of some object has a certain birth time; a control sets the current time, so that vertices have ages depending on the control setting. Attributes of those vertices can then be changed.

Usage

ageControl(births, ages, objids = tagged3d(tags), tags, value = 0,
           colors = NULL, alpha = NULL, radii = NULL, vertices = NULL,
           normals = NULL, origins = NULL, texcoords = NULL,
           x = NULL, y = NULL, z = NULL,
           red = NULL, green = NULL, blue = NULL)

Arguments

Details

All attributes must have the same number of entries (rows for the matrices) as the ages vector. The births vector must have the same number of entries as the number of vertices in the object.

Not all objects contain all attributes; if one is chosen that is not a property of the corresponding object, a Javascript alert() will be generated. (This restriction may be removed in the future by attempting to add the attribute when it makes sense.)

If a births entry is NA, no change will be made to that vertex.

Value

A list of class "rglControl" of cleaned up parameter values, to be used in an RGL widget.

Author(s)

Duncan Murdoch

Examples

saveopts <- options(rgl.useNULL = TRUE)

  theta <- seq(0, 4*pi, length.out = 100)
  xyz <- cbind(sin(theta), cos(theta), sin(theta/2))
  lineid <- plot3d(xyz, type="l", alpha = 0, lwd = 5, col = "blue")["data"]

  widget <- rglwidget() %>%
  playwidget(ageControl(births = theta,
                        ages = c(-4*pi, -4*pi, 1-4*pi, 0, 0, 1),
                        objids = lineid,
                        alpha = c(0, 1, 0, 0, 1, 0)),
             start = 0, stop = 4*pi,
             step = 0.1, rate = 4)
  if (interactive() || in_pkgdown_example())
    widget
  options(saveopts)

Description

These functions allow comparison of mesh3d objects, ignoring irrelevant differences.

compare_proxy.mesh3d can function as a compare_proxy method for the waldo package, by stripping out NULL components and ordering other components alphabetically by name.

all.equal.mesh3d compares mesh3d objects by using compare_proxy.mesh3d to standardize them, then using the regular all.equal function to compare them.

Usage

## S3 method for class 'mesh3d'
all.equal(target, current, ...)
compare_proxy.mesh3d(x, path = "x")

Arguments

Value

all.equal.mesh3d returns TRUE, or a character vector describing (some of) the differences.

compare_proxy.mesh3d returns a list containing two components:

object

a copy of x with relevant components in alphabetical order.

path

a modification of the path label for x

Note

waldo is not an installation requirement for rgl and rgl will never cause it to be loaded. The compare_proxy.mesh3d function will only be registered as a method for waldo::compare_proxy if you load waldo before rgl, as would normally happen during testing using testthat, or if you load it before calling mesh3d, as might happen if you are doing manual tests.

Description

Given starting and ending points on a sphere and the center of the sphere, draw the great circle arc between the starting and ending points. If the starting and ending points have different radii, a segment of a logarithmic spiral will join them, unless they are in the same direction, in which case a straight line will join them.

Usage

arc3d(from, to, center, radius, n, circle = 50, base = 0,
plot = TRUE, ...)

Arguments

Details

If any of from, to or center is an n by 3 matrix with n > 1, multiple arcs will be drawn by recycling each of these parameters to the number of rows of the longest one.

If the vector lengths of from - center and to - center differ, then instead of a spherical arc, the function will draw a segment of a logarithmic spiral joining the two points.

By default, the arc is drawn along the shortest great circle path from from to to, but the base parameter can be used to modify this. If base = 1 is used, the longer arc will be followed. Larger positive integer values will result in base - 1 loops in that direction completely around the sphere. Negative values will draw the curve in the same direction as the shortest arc, but with abs(base) full loops. It doesn't make much sense to ask for such loops unless the radii of from and to differ, because spherical arcs would overlap. Normally the base parameter is left at its default value of 0.

When base is non-zero, the curve will be constructed in multiple pieces, between from, to, -from and -to, for as many steps as necessary. If n is specified, it will apply to each of these pieces.

Value

If plot = TRUE, called mainly for the side effect of drawing arcs. Invisibly returns the object ID of the collection of arcs.

If plot = FALSE, returns a 3 column matrix containing the points that would be drawn as the arcs.

Author(s)

Duncan Murdoch

Examples

normalize <- function(v) v/sqrt(sum(v^2))

# These vectors all have the same length

from <- t(apply(matrix(rnorm(9), ncol = 3), 1, normalize))
to <- normalize(rnorm(3))
center <- c(0, 0, 0)

open3d()
spheres3d(center, radius = 1, col = "white", alpha = 0.2)

arc3d(from, to, center, col = "red")
arc3d(from, 2*to, center, col = "blue")

text3d(rbind(from, to, center, 2*to), 
       texts = c(paste0("from", 1:3), "to", "center", "2*to"),
       depth_mask = FALSE, depth_test = "always")

Description

Draws various types of arrows in a scene.

Usage

arrow3d(p0 = c(1, 1, 1), p1 = c(0, 0, 0), 
        barblen, s = 1/3, theta = pi/12, 
        type = c("extrusion", "lines", "flat", "rotation"), 
        n = 3, width = 1/3, thickness = 0.618 * width, 
        spriteOrigin = NULL, 
        plot = TRUE, ...)

Arguments

Details

Four types of arrows can be drawn. The shapes of all of them are affected by p0, p1, barblen, s, theta, material properties in ..., and spriteOrigin. Other parameters only affect some of the types, as shown.

"extrusion"

(default) A 3-dimensional flat arrow, drawn with shade3d. Affected by width, thickness and smooth.

"lines"

Drawn with lines, similar to arrows, drawn with segments3d. Affected by n.

"flat"

A flat arrow, drawn with polygon3d. Affected by width and smooth.

"rotation"

A solid of rotation, drawn with shade3d. Affected by n and width.

Normally this function draws just one arrow from p0 to p1, but if spriteOrigin is given (in any form that xyz.coords(spriteOrigin) can handle), arrows will be drawn for each point specified, with p0 and p1 interpreted relative to those origins. The arrows will be drawn as 3D sprites which will maintain their orientation as the scene is rotated, so this is a good way to indicate particular locations of interest in the scene.

Value

If plot = TRUE (the default), this is called mainly for the side effect of drawing the arrow; invisibly returns the id(s) of the objects drawn.

If plot = FALSE, the data that would be used in the plot (not including material properties) is returned.

Author(s)

Design based on heplots::arrow3d, which contains modifications by Michael Friendly to a function posted by Barry Rowlingson to R-help on 1/10/2010. Additions by Duncan Murdoch.

Examples

xyz <- matrix(rnorm(300), ncol = 3)
plot3d(xyz)
arrow3d(xyz[1,], xyz[2,], type = "extrusion", col = "red")
arrow3d(xyz[3,], xyz[4,], type = "flat",      col = "blue")
arrow3d(xyz[5,], xyz[6,], type = "rotation",  col = "green")
arrow3d(xyz[7,], xyz[8,], type = "lines",     col = "black")
arrow3d(spriteOrigin = xyz[9:12,],            col = "purple")

Description

The as.mesh3d generic function converts various objects to mesh3d objects.

The default method takes takes a matrix of vertices as input and (optionally) merges repeated vertices, producing a mesh3d object as output. It will contain either triangles or quads or segments or points according to the type argument.

If the generic is called without any argument, it will pass all RGL ids from the current scene to the as.mesh3d.rglId method.

Usage

as.mesh3d(x, ...)
## Default S3 method:
as.mesh3d(x, y = NULL, z = NULL, 
             type = c("triangles", "quads", "segments", "points"),
             smooth = FALSE, 
             tolerance = sqrt(.Machine$double.eps), 
             notEqual = NULL, 
             merge = TRUE,
             ...,
             triangles)

Arguments

Details

The motivation for this function is the following problem: I was asked whether RGL could render a surface made up of triangles or quadrilaterals to look smooth. It can do that, but needs normals at each vertex; they should be the average of the normals for each polygon sharing that vertex. Then OpenGL will interpolate the normals across the polygons and give the illusion of smoothness.

To do this, it needs to know which polygons share each vertex. If the surface is described as a list of triangles or quadrilaterals, that means identifying vertices that are in multiple polygons, and converting the representation to a "mesh3d" object (which is a matrix of vertices and a matrix of vertex numbers making up triangles or quads). Then the addNormals function will add the normals.

Sometimes two polygons will share vertices (within numerical tolerance) without the user wanting them to be considered internal to the surface, or might want one sharp edge in an otherwise smooth surface. This means I needed a way to declare that two vertices from the original list of vertices in the triangles or quads are "not equal", even when they test numerically equal. That's what the notEqual matrix specifies.

Value

A "mesh3d" object with the same faces as in the input, but (if merge=TRUE) with vertices that test equal to within tolerance merged.

Author(s)

Duncan Murdoch

Examples

xyz <- matrix(c(-1, -1, -1,
                -1,  1, -1,
                 1,  1, -1,
                 1, -1, -1,
                -1,  1, -1,
                -1,  1,  1,
                 1,  1,  1,
                 1,  1, -1,
                 1, -1, -1,
                 1,  1, -1,
                 1,  1,  1,
                 1, -1,  1), byrow = TRUE, ncol = 3)
mesh <- as.mesh3d(xyz, type = "quads", col = "red")
mesh$vb
mesh$ib
open3d()
shade3d(mesh)

# Stop vertices 2 and 5 from being merged
notEQ <- matrix(FALSE, 12, 12)
notEQ[2, 5] <- TRUE
mesh <- as.mesh3d(xyz, type = "quads", notEqual = notEQ)
mesh$vb
mesh$ib

Description

The alphashape3d::ashape3d function computes the 3D $\alpha$-shape of a cloud of points. This is an approximation to the visual outline of the cloud. It may include isolated points, line segments, and triangular faces: this function converts the triangular faces to an RGL tmesh3d object.

Usage

## S3 method for class 'ashape3d'
as.mesh3d(x, 
                   alpha = x$alpha[1], 
                   tri_to_keep = 2L,
                   col = "gray", 
                   smooth = FALSE, normals = NULL,
                   texcoords = NULL, ...)

Arguments

Details

Edelsbrunner and Mucke's (1994) $\alpha$-shape algorithm is intended to compute a surface of a general cloud of points. Unlike the convex hull, the cloud may have voids, isolated points, and other oddities. This function is designed to work in the case where the surface is made up of simple polygons.

If smooth = TRUE, this method attempts to orient all of the triangles in the surface consistently and add normals at each vertex by averaging the triangle normals. However, for some point clouds, the $\alpha$-shape will contain sheets of polygons with a few solid polyhedra embedded. This does not allow a consistent definition of "inside" and outside. If this is detected, a warning is issued and the resulting mesh will likely contain boundaries where the assumed orientation of triangles changes, resulting in ugly dark lines through the shape. Larger values of alpha in the call to alphashape3d::ashape3d may help.

Methods for plot3d and persp3d are also defined: they call the as.mesh3d method and then plot the result.

Value

A "mesh3d" object, suitable for plotting.

Author(s)

Duncan Murdoch

References

Edelsbrunner, H., Mucke, E. P. (1994). Three-Dimensional Alpha Shapes. ACM Transactions on Graphics, 13(1), pp.43-72.

Lafarge, T. and Pateiro-Lopez, B. (2017). alphashape3d: Implementation of the 3D Alpha-Shape for the Reconstruction of 3D Sets from a Point Cloud. R package version 1.3.

Examples

if (requireNamespace("alphashape3d", quietly = TRUE)) {
  set.seed(123)
  n <- 400    # 1000 gives a nicer result, but takes longer
  xyz <- rbind(cbind(runif(n), runif(n), runif(n)),
               cbind(runif(n/8, 1, 1.5), 
                     runif(n/8, 0.25, 0.75), 
                     runif(n/8, 0.25, 0.75)))
  ash <- suppressMessages(alphashape3d::ashape3d(xyz, alpha = 0.2))
  m <- as.mesh3d(ash, smooth = TRUE)
  open3d()
  mfrow3d(1, 2, sharedMouse = TRUE)
  plot3d(xyz, size = 1)
  plot3d(m, col = "red", alpha = 0.5)
  points3d(xyz, size = 1)
}

Description

This method attempts to read the attributes of objects in the rgl display and construct a mesh3d object to approximate them.

Usage

## S3 method for class 'rglId'
as.mesh3d(x, type = NA, subscene = NA, ...)

Arguments

Details

This function attempts to construct a triangle mesh to approximate one or more objects from the current display. It can handle objects of types from c("points", "lines", "linestrip", "triangles", "quads", "planes", "surface").

Since this method only produces meshes containing points, segments and triangles, they won't necessarily be an exact match to the original object.

If the generic as.mesh3d is called with no x argument, this method will be called with x set to the ids in the current scene.

Value

A mesh object.

Author(s)

Duncan Murdoch

See Also

as.triangles3d.rglId for extracting the triangles, clipMesh3d to apply complex clipping to a mesh object.

Examples

# volcano example taken from "persp"
#
data(volcano)

z <- 2 * volcano        # Exaggerate the relief

x <- 10 * (1:nrow(z))   # 10 meter spacing (S to N)
y <- 10 * (1:ncol(z))   # 10 meter spacing (E to W)

zlim <- range(y)
zlen <- zlim[2] - zlim[1] + 1

colorlut <- terrain.colors(zlen) # height color lookup table

col <- colorlut[ z - zlim[1] + 1 ] # assign colors to heights for each point

open3d(useNULL = TRUE)
surface3d(x, y, z, color = col)
m <- as.mesh3d()
close3d()

open3d()
shade3d(m)

Description

This is a placeholder generic function, to allow other packages to create "rglscene" objects compatible with the objects produced by scene3d.

No methods are currently defined in rgl.

Usage

as.rglscene(x, ...)

Arguments

Description

Converts the quads in a mesh version of an object to triangles by splitting them up. Optionally drops any point or segment components.

Usage

as.tmesh3d(x, ...)
## Default S3 method:
as.tmesh3d(x, drop = FALSE, ...)
## S3 method for class 'mesh3d'
as.tmesh3d(x, drop = FALSE, keepTags = FALSE, ...)

Arguments

Details

The default method simply calls as.mesh3d(x, ...) and passes the result to the "mesh3d" method.

Value

A "mesh3d" object containing no quads. If drop = TRUE, it will only contain triangles.

If keepTags = TRUE, a "tags" element will be added to the result. For details, see the clipMesh3d help page.

Note

Older versions of rgl had a "tmesh3d" class for meshes of triangles. That class is no longer used: as.tmesh3d and tmesh3d both produce "mesh3d" objects.

Author(s)

Duncan Murdoch

See Also

as.triangles3d to get just the coordinates.

Examples

x <- cuboctahedron3d()
x             # has quads and triangles
as.tmesh3d(x) # has only triangles

Description

This generic and its methods extract or creates a matrix of coordinates of triangles from an object, suitable for passing to triangles3d.

Usage

as.triangles3d(obj, ...)
## S3 method for class 'rglId'
as.triangles3d(obj,
               attribute = c("vertices", "normals", "texcoords", "colors"),
               subscene = NA,
               ...)

Arguments

Details

The method for "rglId" objects can extract several different attributes, organizing them as it would organize the vertices for the triangles.

Value

An n x 3 matrix containing the vertices of triangles making up the object. Each successive 3 rows of the matrix corresponds to a triangle.

If the attribute doesn't exist, NULL will be returned.

Author(s)

Duncan Murdoch

See Also

as.mesh3d to also capture material properties.

Examples

open3d()
x <- surface3d(x = 1:10, y = 1:10, z = rnorm(100), col = "red")
tri <- as.triangles3d(x)
open3d()
triangles3d(tri, col = "blue")

Description

This function sets the apparent ratios of the x, y, and z axes of the current bounding box.

Usage

aspect3d(x, y = NULL, z = NULL)

Arguments

Details

If the ratios are all 1, the bounding box will be displayed as a cube approximately filling the display. Values may be set larger or smaller as desired. Aspect "iso" signifies that the coordinates should all be displayed at the same scale, i.e. the bounding box should not be rescaled. (This corresponds to the default display before aspect3d has been called.) Partial matches to "iso" are allowed.

aspect3d works by modifying par3d("scale").

Value

The previous value of the scale is returned invisibly.

Author(s)

Duncan Murdoch

See Also

plot3d, par3d

Examples

x <- rnorm(100)
  y <- rnorm(100)*2
  z <- rnorm(100)*3
  
  open3d()
  plot3d(x, y, z)
  aspect3d(1, 1, 0.5)
  highlevel()  # To trigger display
  open3d()
  plot3d(x, y, z)
  aspect3d("iso")
  highlevel()

Description

The asRow function arranges objects in a row in the display; the getWidgetId function extracts the HTML element ID from an HTML widget.

Usage

asRow(..., last = NA, height = NULL, colsize = 1)
getWidgetId(widget)

Arguments

Details

Using asRow requires that the manipulateWidget package is installed.

asRow produces a "combineWidgets" object which is a single column whose last element is another "combineWidgets" object which is a single row.

If n objects are given as input and last is given a value less than n, the first n - last objects will be displayed in a column above the row containing the last objects.

Value

asRow returns a single "combineWidgets" object suitable for display or nesting within a more complicated display.

getWidgetId returns a character string containing the HTML element ID of the widget.

Author(s)

Duncan Murdoch

See Also

pipe for the %>% operator.

Examples

if (requireNamespace("manipulateWidget", quietly = TRUE) &&
    require("crosstalk", quietly = TRUE)) {
  sd <- SharedData$new(mtcars)
  ids <- plot3d(sd$origData(), col = mtcars$cyl, type = "s")
  # Copy the key and group from existing shared data
  rglsd <- rglShared(ids["data"], key = sd$key(), group = sd$groupName())
  w <- rglwidget(shared = rglsd) %>%
       asRow("Mouse mode: ", rglMouse(getWidgetId(.)), 
             "Subset: ", filter_checkbox("cylinderselector", 
		               "Cylinders", sd, ~ cyl, inline = TRUE),
             last = 4, colsize = c(1,2,1,2), height = 60)
  if (interactive() || in_pkgdown_example())
    w
}

Description

These functions draw axes, boxes and text outside the range of the data. axes3d, box3d and title3d are the higher level functions; normally the others need not be called directly by users.

Usage

axes3d(edges = "bbox", labels = TRUE, tick = TRUE, nticks = 5, 
	box = FALSE, expand = 1.03, ...)
box3d(...) 
title3d(main = NULL, sub = NULL, xlab = NULL, ylab = NULL, 
	zlab = NULL, line = NA, level = NA, floating = NULL, ...) 
axis3d(edge, at = NULL, labels = TRUE, tick = TRUE, line = 0, 
	pos = NULL, nticks = 5, ...) 
mtext3d(text, edge, at = NULL, line = 0, level = 0, 
        floating = FALSE, pos = NA, ...)

Arguments

Details

The rectangular prism holding the 3D plot has 12 edges. They are identified using 3 character strings. The first character (‘x’, ‘y’, or ‘z’) selects the direction of the axis. The next two characters are each ‘-’ or ‘+’, selecting the lower or upper end of one of the other coordinates. If only one or two characters are given, the remaining characters normally default to ‘-’ (but with mtext3d(..., floating = TRUE) the default is ‘+’; see below). For example edge = 'x+' draws an x-axis at the high level of y and the low level of z.

By default, axes3d uses the bbox3d function to draw the axes. The labels will move so that they do not obscure the data. Alternatively, a vector of arguments as described above may be used, in which case fixed axes are drawn using axis3d.

As of rgl version 0.106.21, axis drawing has changed significantly. Text drawn in the margins will adapt to the margins (see bbox3d). The edge and floating parameters will be recorded in the margin and floating material properties for the object.

If floating = FALSE, they will be drawn on the specified edge.

If floating = TRUE, they will move as the axis labels move when the scene is rotated. The signs on the edge specification are interpreted as agreeing with the axis ticks ‘+’ or disagreeing ‘-’. For example, "x++" will draw text on the x axis in the same edge as the ticks, while "x--" will draw on the opposite edge.

The final possible value for floating in mtext3d is NA, which reproduces legacy rgl behaviour. In this case the labels are not tied to the bounding box, so they should be drawn last, or they could appear inside the box, overlapping the data.

In title3d floating = NULL (the default) indicates the main title and subtitle will be fixed while the axis labels will be floating. The default locations for title and subtitle are line = 2 and level = 2 on edges "x++" and "x--" respectively. The axis labels float at line = 4 and level = 1 on the same edge as the ticks.

The at parameter in axis3d is the location of the ticks, defaulting to pretty locations. In mtext3d the at parameter is the location on the specified axis at which to draw the text, defaulting to the middle of the bounding box.

The line parameter is the line counting out from the box in the same direction as the axis ticks, and level is the line out in the orthogonal direction. The ticks run from line = 0 to line = 1, and the tick labels are drawn at line = 2. Both are drawn at level 0.

The pos parameter is only supported in legacy mode. If it is a numeric vector of length 3, edge determines the direction of the axis and the tick marks, and the values of the other two coordinates in pos determine the position. The level parameter is ignored in legacy mode.

For mtext3d in floating = TRUE or floating = FALSE mode, there are 3 special values for the at parameter: it may be -Inf, NA or +Inf, referring to the bottom, middle or top of the given axis respectively.

Value

These functions are called for their side effects. They return the object IDs of objects added to the scene.

Note

mtext3d is a wrapper for text3d that sets the margin and floating material properties. In fact, these properties can be set for many kinds of objects (most kinds where it would make sense), with the effect that the object will be drawn in the margin, with x coordinate corresponding to at, y corresponding to line, and z corresponding to level.

Author(s)

Duncan Murdoch

See Also

Classic graphics functions axis, box, title, mtext are related. See RGL functions bbox3d for drawing the box around the plot, and setAxisCallbacks for customized axes.

Examples

open3d()
  points3d(rnorm(10), rnorm(10), rnorm(10))

  # First add standard axes
  axes3d()  

  # and one in the middle (the NA will be ignored, a number would 
  # do as well)
  axis3d('x', pos = c(NA, 0, 0))

  # add titles
  title3d('main', 'sub', 'xlab', 'ylab', 'zlab')
  
  # Use a log scale for z
    
  open3d()
  
  x <- rnorm(10)
  y <- rnorm(10)
  z <- exp(rnorm(10, mean = 3, sd = 2))
  
  logz <- log10(z)
  zticks <- axisTicks(range(logz), log = TRUE)
  zat <- log10(zticks)
  
  plot3d(x, y, logz, zlab = "z")
  axes3d(zat = zat, zlab = zticks, box = TRUE)

Description

Set up the bounding box decoration.

Usage

bbox3d(xat = NULL, yat = NULL, zat = NULL, 
	xunit = "pretty", yunit = "pretty", zunit = "pretty", 
	expand = 1.03,
	draw_front = FALSE, 
	xlab=NULL, ylab=NULL, zlab=NULL,
  xlen=5, ylen=5, zlen=5,
  marklen=15.0, marklen.rel=TRUE, ...)

Arguments

Details

Four different types of tick mark layouts are possible. This description applies to the X axis; other axes are similar: If xat is not NULL, the ticks are set up at custom positions. If xunit is numeric but not zero, it defines the tick mark base. If it is "pretty" (the default in bbox3d), ticks are set at pretty locations. If xlen is not zero, it specifies the number of ticks (a suggestion if xunit is "pretty").

The first color specifies the bounding box, while the second one specifies the tick mark and font color.

bbox3d defaults to pretty locations for the axis labels and a slightly larger box, whereas rgl.bbox covers the exact range.

axes3d offers more flexibility in the specification of the axes, but they are static, unlike those drawn by bbox3d.

Value

This function is called for the side effect of setting the bounding box decoration. A shape ID is returned to allow pop3d to delete it.

See Also

material3d, axes3d

Examples

open3d()
  points3d(rnorm(100), rnorm(100), rnorm(100))
  bbox3d(color = c("#333377", "black"), emission = "#333377", 
         specular = "#3333FF", shininess = 5, alpha = 0.8)

Description

Set up the background of the scene.

Usage

bg3d(color,
    sphere=FALSE, 
    back="lines",
    fogtype="none",
    fogScale = 1, 
    col, ...)

Arguments

Details

The background color is taken from color or col if color is missing. The first entry is used for background clearing and as the fog color. The second (if present) is used for background sphere geometry.

If color and col are both missing, the default is found in the r3dDefaults$bg list, or "white" is used if nothing is specified there.

If sphere is set to TRUE, an environmental sphere enclosing the whole scene is drawn.

If not, but the material properties include a bitmap as a texture, the bitmap is drawn in the background of the scene. (The bitmap colors modify the general color setting.)

If neither a sphere nor a bitmap background is drawn, the background is filled with a solid color.

The fogScale parameter should be a positive value to change the density of the fog in the plot. For fogtype = "linear" it multiplies the density of the fog; for the exponential fog types it multiplies the density parameter used in the display.

See the OpenGL 2.1 reference for the formulas used in the fog calculations within R (though the "exp2" formula appears to be wrong, at least on my system). In WebGL displays, the following rules are used. They appear to match the rules used in R on my system.

• For "linear" fog, the near clipping plane is taken as $c=0$, and the far clipping plane is taken as $c=1$. The amount of fog is $s * c$ clamped to a 0 to 1 range, where $s = fogScale$.

• For "exp" and "exp2" fog, the observer location is negative at a distance depending on the field of view. The formula for the distance is

  $c = [1-sin(theta)]/[1 + sin(theta)]$

  where $theta = FOV/2$. We calculate

  $c' = d(1-c) + c$

  so $c'$ runs from 0 at the observer to 1 at the far clipping plane.

• For "exp" fog, the amount of fog is $1 - exp(-s * c')$.

• For "exp2" fog, the amount of fog is $1 - exp[-(s * c')^2]$.

See Also

material3d, bgplot3d to add a 2D plot as background.

Examples

open3d()
  
  # a simple white background
  
  bg3d("white")

  # the holo-globe (inspired by star trek):

  bg3d(sphere = TRUE, color = c("black", "green"), lit = FALSE, back = "lines" )

  # an environmental sphere with a nice texture.

  bg3d(sphere = TRUE, texture = system.file("textures/sunsleep.png", package = "rgl"), 
         back = "filled" )
         
  # The same texture as a fixed background
  
  open3d()
  bg3d(texture = system.file("textures/sunsleep.png", package = "rgl"), col = "white")

Description

Add a 2D plot or a legend in the background of an RGL window.

Usage

bgplot3d(expression, bg.color = getr3dDefaults("bg", "color"), 
         magnify = 1, ...)
legend3d(...)

Arguments

Details

The bgplot3d function opens a png device and executes expression, producing a plot there. This plot is then used as a bitmap background for the current RGL subscene.

The legend3d function draws a standard 2D legend to the background of the current subscene by calling bgplot3d to open a device, and setting up a plot region there to fill the whole display.

Value

The bgplot3d function invisibly returns the ID of the background object that was created, with attribute "value" holding the value returned when the expression was evaluated.

The legend3d function does similarly. The "value" attribute is the result of the call to legend. The scaling of the coordinates runs from 0 to 1 in X and Y.

Note

Because the background plots are drawn as bitmaps, they do not resize very gracefully. It's best to size your window first, then draw the background at that size.

Author(s)

Duncan Murdoch

See Also

bg3d for other background options.

Examples

x <- rnorm(100)
y <- rnorm(100)
z <- rnorm(100)
open3d()
# Needs to be a bigger window than the default
par3d(windowRect = c(100, 100, 612, 612))
parent <- currentSubscene3d()
mfrow3d(2, 2)
plot3d(x, y, z)
next3d(reuse = FALSE)
bgplot3d(plot(y, z))
next3d(reuse = FALSE)
bgplot3d(plot(x, z))
next3d(reuse = FALSE)
legend3d("center", c("2D Points", "3D Points"), pch = c(1, 16))
useSubscene3d(parent)

Description

These files typically have one buffer holding all the binary data for a scene.

Methods

Public methods

• Buffer$new()

• Buffer$load()

• Buffer$saveOpenBuffer()

• Buffer$getBuffer()

• Buffer$setBuffer()

• Buffer$openBuffer()

• Buffer$writeBuffer()

• Buffer$closeBuffer()

• Buffer$closeBuffers()

• Buffer$getBufferview()

• Buffer$addBufferView()

• Buffer$openBufferview()

• Buffer$setBufferview()

• Buffer$getAccessor()

• Buffer$setAccessor()

• Buffer$readAccessor()

• Buffer$readAccessor0()

• Buffer$addAccessor()

• Buffer$dataURI()

• Buffer$as.list()

• Buffer$clone()

Method new()

Usage

Buffer$new(json = NULL, binfile = NULL)

Arguments

Method load()

Load from file.

Usage

Buffer$load(uri, buf = 0)

Arguments

Method saveOpenBuffer()

Write open buffer to connection.

Usage

Buffer$saveOpenBuffer(con, buf = 0)

Arguments

Method getBuffer()

Get buffer object.

Usage

Buffer$getBuffer(buf, default = list(byteLength = 0))

Arguments

Returns

A list containing components described here: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-buffer.

Method setBuffer()

Set buffer object.

Usage

Buffer$setBuffer(buf, buffer)

Arguments

Method openBuffer()

Open a connection for the data in a buffer.

Usage

Buffer$openBuffer(buf)

Arguments

Returns

An open binary connection.

Method writeBuffer()

Write data to buffer.

Usage

Buffer$writeBuffer(values, type, size, buf = 0)

Arguments

Returns

Byte offset of start of bytes written.

Method closeBuffer()

Close the connection in a buffer.

If there was a connection open, this will save the contents in the raw vector bytes within the buffer object.

Usage

Buffer$closeBuffer(buf)

Arguments

Method closeBuffers()

Close any open buffers.

Call this after working with a GLTF file to avoid warnings from R about closing unused connections.

Usage

Buffer$closeBuffers()

Method getBufferview()

Get bufferView object.

Usage

Buffer$getBufferview(bufv)

Arguments

Returns

A list containing components described here: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-bufferview.

Method addBufferView()

Add a new buffer view.

Usage

Buffer$addBufferView(values, type, size, target = NULL, buf = 0)

Arguments

Returns

New bufferView number.

Method openBufferview()

Open a connection to a buffer view.

Usage

Buffer$openBufferview(bufv)

Arguments

Returns

A connection.

Method setBufferview()

Set bufferView object.

Usage

Buffer$setBufferview(bufv, bufferView)

Arguments

Method getAccessor()

Get accessor object

Usage

Buffer$getAccessor(acc)

Arguments

Returns

A list containing components described here: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-accessor

Method setAccessor()

Set accessor object.

Usage

Buffer$setAccessor(acc, accessor)

Arguments

Method readAccessor()

Read data given by accessor number.

Usage

Buffer$readAccessor(acc)

Arguments

Returns

A vector or array as specified in the accessor. For the MATn types, the 3rd index indexes the element.

Method readAccessor0()

Read data given by accessor object.

Usage

Buffer$readAccessor0(accessor)

Arguments

Returns

A vector or array as specified in the accessor. For the MATn types, the 3rd index indexes the element.

Method addAccessor()

Write values to accessor, not including min and max.

Usage

Buffer$addAccessor(
  values,
  target = NULL,
  types = "anyGLTF",
  normalized = FALSE
)

Arguments

Returns

New accessor number

Method dataURI()

Convert buffer to data URI.

Usage

Buffer$dataURI(buf = 0)

Arguments

Returns

String containing data URI.

Method as.list()

Convert to list.

Usage

Buffer$as.list()

Returns

List suitable for writing using JSON.

Method clone()

The objects of this class are cloneable with this method.

Usage

Buffer$clone(deep = FALSE)

Arguments

Description

Set and get user callbacks on mouse events.

Usage

rgl.setMouseCallbacks(button, begin = NULL, update = NULL, end = NULL, 
                      dev = cur3d(), subscene = currentSubscene3d(dev))
rgl.getMouseCallbacks(button, 
                      dev = cur3d(), subscene = currentSubscene3d(dev))

rgl.setWheelCallback(rotate, 
                      dev = cur3d(), subscene = currentSubscene3d(dev))

rgl.getWheelCallback(dev = cur3d(), subscene = currentSubscene3d(dev))

Arguments

Details

The set functions set event handlers on mouse events that occur within the current RGL window. The begin and update events should be functions taking two arguments; these will be the mouse coordinates when the event occurs. The end event handler takes no arguments. The rotate event takes a single argument, which will be equal to 1 if the user pushes the wheel away by one click, and 2 if the user pulls the wheel by one click.

Alternatively, the handlers may be set to NULL, the default value, in which case no action will occur.

If a subscene has multiple listeners, the user action will still only be called for the subscene that received the mouse event. It should consult par3d("listeners") if it makes sense to take action on the whole group of subscenes.

The get function retrieves the callbacks that are currently set.

The “no button” mouse handler may be set by specifying button = 0. The begin function will be called the first time the mouse moves within the subscene, and the update function will be called repeatedly as it moves. The end function will never be called.

Value

The set functions are called for the side effect of setting the mouse event handlers.

The rgl.getMouseCallbacks function returns a list containing the callback functions or NULL if no user callback is set. The rgl.getWheelCallback returns the callback function or NULL.

Author(s)

Duncan Murdoch

See Also

par3d to set built-in handlers, setUserCallbacks to work with rglwidget.

Examples

pan3d <- function(button, dev = cur3d(), subscene = currentSubscene3d(dev)) {
   start <- list()
   
   begin <- function(x, y) {
     activeSubscene <- par3d("activeSubscene", dev = dev)
     start$listeners <<- par3d("listeners", dev = dev, subscene = activeSubscene)
     for (sub in start$listeners) {
       init <- par3d(c("userProjection","viewport"), dev = dev, subscene = sub)
       init$pos <- c(x/init$viewport[3], 1 - y/init$viewport[4], 0.5)
       start[[as.character(sub)]] <<- init
     }
   }
   
   update <- function(x, y) {
     for (sub in start$listeners) {
       init <- start[[as.character(sub)]]
       xlat <- 2*(c(x/init$viewport[3], 1 - y/init$viewport[4], 0.5) - init$pos)
       mouseMatrix <- translationMatrix(xlat[1], xlat[2], xlat[3])
       par3d(userProjection = mouseMatrix %*% init$userProjection, dev = dev, subscene = sub )
      }
   }
   rgl.setMouseCallbacks(button, begin, update, dev = dev, subscene = subscene)
   cat("Callbacks set on button", button, "of RGL device", dev, "in subscene", subscene, "\n")
 }
 open3d()
 shade3d(icosahedron3d(), col = "yellow")
 # This only works in the internal display...
 pan3d(1)

Description

Version 1.0-2 of deldir is not compatible with rgl. This allows code to avoid trying to call it.

Usage

checkDeldir(error = FALSE)

Arguments

Value

Returns TRUE if deldir is available in a compatible version.

Examples

checkDeldir()

Description

Modifies a mesh3d object so that values of a function are bounded.

Usage

clipMesh3d(mesh, fn, bound = 0, greater = TRUE, 
           minVertices = 0, plot = FALSE, keepValues = FALSE,
           keepTags = FALSE)
clipObj3d(ids = tagged3d(tags), fn, bound = 0, greater = TRUE,
           minVertices = 0,
           replace = TRUE, tags)

Arguments

Details

These functions transform a mesh3d object or other RGL objects by removing parts where fn violates the bound.

For clipMesh3d the fn argument can be any of the following:

• a character vector naming a function (with special names "x", "y", and "z" corresponding to functions returning those coordinates)

• a function

• a numeric vector with one value per vertex

• NULL, indicating that the numeric values are saved in mesh$values

For clipObj3d any of the above except NULL may be used.

If fn is a numeric vector, with one value per vertex, those values will be used in the test. If it is a function with formal arguments x, y and z, it will receive the coordinates of vertices in those arguments, otherwise it will receive the coordinates in a single n x 3 matrix. The function should be vectorized and return one value per vertex, to check against the bound.

These operations are performed on the mesh:

First, all quads are converted to triangles.

Next, each vertex is checked against the condition.

Modifications to triangles depend on how many of the vertices satisfy the condition (fn >= bound or fn <= bound, depending on greater) for inclusion.

• If no vertices in a triangle satisfy the condition, the triangle is omitted.

• If one vertex satisfies the condition, the other two vertices in that triangle are shrunk towards it by assuming fn is locally linear.

• If two vertices satisfy the condition, the third vertex is shrunk along each edge towards each other vertex, forming a quadrilateral made of two new triangles.

• If all vertices satisfy the condition, they are included with no modifications.

Modifications to line segments are similar: the segment will be shortened if it crosses the boundary, or omitted if it is entirely out of bounds. Points, spheres, text and sprites will just be kept or rejected.

The minVertices argument is used to improve the approximation to the boundary when fn is a non-linear function. In that case, the interpolation described above can be inaccurate. If minVertices is set to a positive number (e.g. 10000), then each object is modified by subdivision to have at least that number of vertices, so that pieces are smaller and the linear interpolation is more accurate. In the clipObj3d function, minVertices can be a vector, with entries corresponding to each of the entries in ids.

Value

If plot = FALSE, clipMesh3d returns new mesh3d object in which all vertices (approximately) satisfy the clipping condition. Note that the order of vertices will likely differ from the original order, and new vertices will be added near the boundary (and if minVertices > 0, in the interior). If in addition keepValues = TRUE, a component named "values" will be added to the mesh containing the values for each vertex. If keepTags = TRUE, the tags component described below will be added to the output mesh.

If plot = TRUE, the result will be plotted with shade3d and its result returned.

clipObj3d is called for the side effect of modifying the scene. It returns a list of new RGL id values corresponding to the ids passed as arguments.

The keepTags argument

If keepTags = TRUE, a "tags" element will be added to the result. It will be a vector with one entry per point, segment, triangle and quad in the output mesh. (These tags are not related to the tags used to identify rgl objects.) The mesh tags may be used to show the correspondence between the parts of the input mesh and output mesh. By default, the tags are constructed as a numerical sequence over points, segments, triangles and quads in the input mesh, in that order, starting from one. This is the same order used for colours when shading with meshColor == "faces".

For example, start with a mesh with one point, two segments, three triangles and four quads, but no tags member. It would implicitly tag the parts from one to ten as

⁠ c(1, # the point 2:3, # the two segments 4:6, # the three triangles 7:10) # the four quads ⁠

If clipping deleted the segments and the first triangle, the output would contain the seven element result

⁠ mesh$tags <- c(1, # the point remains # no segments now 5:6, # the two remaining triangles # were previously items 5 and 6 7:10) # the four quads ⁠

The tags output may contain repetitions. For example, when a triangle is partially clipped and replaced by several smaller triangles, entries for all of them will contain the value corresponding to the original triangle.

The mesh$tags component may be supplied as part of the input mesh as any type of vector; the output will propagate values to the new mesh. The input length must match the total number of points, segments, triangles and quads in the input mesh or an error will be raised.

Author(s)

Duncan Murdoch

References

See https://stackoverflow.com/q/56242470/2554330 and https://laustep.github.io/stlahblog/posts/MeshClipping.html for a motivating example.

See Also

See contourLines3d and filledContour3d for ways to display function values without clipping.

Examples

# Show the problem that minVertices solves:

cube <- cube3d(col = rainbow(6), meshColor = "faces")

# This function only has one argument, so it will 
# be passed x, y and z in columns of a matrix
vecnorm <- function(vals) apply(vals, 1, function(row) sqrt(sum(row^2)))

open3d()
mfrow3d(2, 2, sharedMouse = TRUE)
id1 <- shade3d(cube)
# All vertices have norm sqrt(3), so this clips nothing:
clipObj3d(id1, fn = vecnorm, bound = sqrt(2))
next3d()
id2 <- wire3d(cube, lit = FALSE)
clipObj3d(id2, fn = vecnorm, bound = sqrt(2))

# This subdivides the cube, and does proper clipping:
next3d()
id3 <- shade3d(cube)
clipObj3d(id3, fn = vecnorm, bound = sqrt(2), minVertices = 200)
next3d()
id4 <- wire3d(cube, lit = FALSE)
clipObj3d(id4, fn = vecnorm, bound = sqrt(2), minVertices = 200)

Description

This is a function to produce actions in a web display. A playwidget or Shiny input control (e.g. a sliderInput control) sets a value which controls attributes of one or more clipping planes.

Usage

clipplaneControl(a = NULL, b = NULL, c = NULL, d = NULL, 
                 plane = 1, clipplaneids = tagged3d(tag), tag, ...)

Arguments

Value

A list of class "rglControl" of cleaned up parameter values, to be used in an RGL widget.

Author(s)

Duncan Murdoch

Examples

open3d()
  saveopts <- options(rgl.useNULL = TRUE)
  xyz <- matrix(rnorm(300), ncol = 3)
  id <- plot3d(xyz, type="s", col = "blue", zlim = c(-3,3))["clipplanes"]
  dvals <- c(3, -3)
  widget <- rglwidget() %>%
    playwidget(clipplaneControl(d = dvals, clipplaneids = id),
               start = 0, stop = 1, step = 0.01,
               rate = 0.5)
  if (interactive() || in_pkgdown_example())
    widget
  options(saveopts)

Description

contourLines3d draws contour lines on a surface; filledContour3d draws filled contours on it.

Usage

contourLines3d(obj, ...)
## S3 method for class 'rglId'
contourLines3d(obj, ...)
## S3 method for class 'mesh3d'
contourLines3d(obj, fn = "z", 
    nlevels = 10, 
    levels = NULL, 
    minVertices = 0,
    plot = TRUE, ... )
filledContour3d(obj, ...)
## S3 method for class 'rglId'
filledContour3d(obj, plot = TRUE, replace = plot, ...)
## S3 method for class 'mesh3d'
filledContour3d(obj, fn = "z", 
    nlevels = 20, 
    levels = pretty(range(values), nlevels), 
    color.palette = function(n) hcl.colors(n, "YlOrRd", rev = TRUE),
    col = color.palette(length(levels) - 1),
    minVertices = 0,
    plot = TRUE, 
    keepValues = FALSE, ... )

Arguments

Details

For contourLines3d, the fn argument can be any of the following:

• a character vector naming one or more functions

• a function

• a numeric vector with one value per vertex

• NULL, indicating that the numeric values are saved in obj$values

• a list containing any of the above.

For filledContour3d, only one function can be specified.

The special names "x", "y", "z" may be used in fn to specify functions returning one of those coordinates. (If you have existing functions x(), y() or z() they will be masked by this choice; specify such functions by value rather than name, e.g. fn = x instead of fn = "x".)

Functions in fn with formal arguments x, y and z will receive the coordinates of vertices in those arguments, otherwise they will receive the coordinates in a single n x 3 matrix. They should be vectorized and return one value per vertex.

Each of the functions will be evaluated at each vertex of the surface specified by obj, and contours will be drawn assuming the function is linear between vertices. If contours of a nonlinear function are needed, you may want to increase minVertices as described below.

If levels is not specified, values will be set separately for each entry in fn, using pretty(range(values, na.rm = TRUE), nlevels) where values are the values on the vertices.

The minVertices argument is used to improve the approximation to the contour when the function is non-linear. In that case, the interpolation between vertices can be inaccurate. If minVertices is set to a positive number (e.g. 10000), then the mesh is modified by subdivision to have at least that number of vertices, so that pieces are smaller and the linear interpolation is more accurate.

Value

For both contourLines3d and filledContour3d the "rglId" method converts the given id values to a mesh, and calls the "mesh3d" method.

The "mesh3d" method returns an object of class "rglId" corresponding to what was drawn if plot is TRUE,

If plot is FALSE, contourLines3d returns a dataframe containing columns c("x", "y", "z", "fn", "level") giving the coordinates of the endpoints of each line segment, the name (or index) of the function for this contour, and the level of the contour.

If plot is FALSE, filledContour3d returns a "mesh3d" object holding the result. If keepValues is TRUE, the mesh will contain the values corresponding to each vertex (with linear approximations at the boundaries).

Note

To draw contours on a surface, the surface should be drawn with material property polygon_offset = 1 (or perhaps some larger positive value) so that the lines of the contour are not obscured by the surface.

In R versions prior to 3.6.0, the default color.palette is grDevices::cm.colors.

Author(s)

Duncan Murdoch

See Also

The misc3d package contains the function contour3d to draw contour surfaces in space instead of contour lines on surfaces.

Examples

# Add contourlines in "z" to a persp plot

z <- 2 * volcano        # Exaggerate the relief
x <- 10 * (1:nrow(z))   # 10 meter spacing (S to N)
y <- 10 * (1:ncol(z))   # 10 meter spacing (E to W)

open3d()
id <- persp3d(x, y, z, aspect = "iso",
      axes = FALSE, box = FALSE, polygon_offset = 1)
contourLines3d(id)     # "z" is the default function
filledContour3d(id, polygon_offset = 1, nlevels = 10, replace = TRUE)

# Draw longitude and latitude lines on a globe

lat <- matrix(seq(90, -90, length.out = 50)*pi/180, 50, 50, byrow = TRUE)
long <- matrix(seq(-180, 180, length.out = 50)*pi/180, 50, 50)

r <- 6378.1 # radius of Earth in km
x <- r*cos(lat)*cos(long)
y <- r*cos(lat)*sin(long)
z <- r*sin(lat)

open3d()
ids <- persp3d(x, y, z, col = "white", 
        texture = system.file("textures/worldsmall.png", package = "rgl"), 
        specular = "black", axes = FALSE, box = FALSE, xlab = "", ylab = "", zlab = "",
        normal_x = x, normal_y = y, normal_z = z, polygon_offset = 1)
        
contourLines3d(ids, list(latitude = function(x, y, z) asin(z/sqrt(x^2+y^2+z^2))*180/pi,
                         longitude = function(x, y, z) atan2(y, x)*180/pi))

Description

A collection of sample mesh objects.

Usage

cube3d(trans = identityMatrix(), ...)  
  tetrahedron3d(trans = identityMatrix(), ...)  
  octahedron3d(trans = identityMatrix(), ...)  
  icosahedron3d(trans = identityMatrix(), ...)
  dodecahedron3d(trans = identityMatrix(), ...)
  cuboctahedron3d(trans = identityMatrix(), ...)
  
  oh3d(trans = identityMatrix(), ...)    # an 'o' object

Arguments

Details

These sample objects optionally take a 4x4 matrix transformation trans as an argument. This transformation is applied to all vertices of the default shape. The default is an identity transformation.

Value

Objects of class c("mesh3d", "shape3d").

See Also

mesh3d

Examples

# 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) )

Description

This function converts a description of a space curve into a "mesh3d" object forming a cylindrical tube around the curve.

Usage

cylinder3d(center, radius = 1, twist = 0, e1 = NULL, e2 = NULL, e3 = NULL, 
	sides = 8, section = NULL, closed = 0, 
	rotationMinimizing = is.null(e2) && is.null(e3),
	debug = FALSE, keepVars = FALSE, ...)

Arguments

Details

The number of points in the space curve is determined by the vector lengths in center, after using xyz.coords to convert it to a list. The other arguments radius, twist, e1, e2, and e3 are extended to the same length.

The closed argument controls how the ends of the cylinder are handled. If closed > 0, it represents the number of points of overlap in the coordinates. closed == TRUE is the same as closed = 1. If closed > 0 but the ends don't actually match, a warning will be given and results will be somewhat unpredictable.

Negative values of closed indicate that caps should be put on the ends of the cylinder. If closed == -1, a cap will be put on the end corresponding to center[1, ]. If closed == -2, caps will be put on both ends.

If section is NULL (the default), a regular sides-sided polygon is used, and radius measures the distance from the center of the cylinder to each vertex. If not NULL, sides is ignored (and set internally to nrow(section)), and radius is used as a multiplier to the vertex coordinates. twist specifies the rotation of the polygon. Both radius and twist may be vectors, with values recycled to the number of rows in center, while sides and section are the same at every point along the curve.

The three optional arguments e1, e2, and e3 determine the local coordinate system used to create the vertices at each point in center. If missing, they are computed by simple numerical approximations. e1 should be the tangent coordinate, giving the direction of the curve at the point. The cross-section of the polygon will be orthogonal to e1. When rotationMinimizing is TRUE, e2 and e3 are chosen to give a rotation minimizing frame (see Wang et al., 2008). When it is FALSE, e2 defaults to an approximation to the normal or curvature vector; it is used as the image of the y axis of the polygon cross-section. e3 defaults to an approximation to the binormal vector, to which the x axis of the polygon maps. The vectors are orthogonalized and normalized at each point.

Value

A "mesh3d" object holding the cylinder, possibly with attribute "vars" containing the local environment of the function.

Author(s)

Duncan Murdoch

References

Wang, W., Jüttler, B., Zheng, D. and Liu, Y. (2008). Computation of rotation minimizing frames. ACM Transactions on Graphics, Vol. 27, No. 1, Article 2.

Examples

# A trefoil knot
open3d()
theta <- seq(0, 2*pi, length.out = 25)
knot <- cylinder3d(
      center = cbind(
        sin(theta) + 2*sin(2*theta), 
        2*sin(3*theta), 
        cos(theta) - 2*cos(2*theta)),
      e1 = cbind(
        cos(theta) + 4*cos(2*theta), 
        6*cos(3*theta), 
        sin(theta) + 4*sin(2*theta)),
      radius = 0.8, 
      closed = TRUE,
      color = "green")
                     
shade3d(addNormals(subdivision3d(knot, depth = 2)))

Description

decorate3d adds the usual decorations to a plot: labels, axes, etc.

Usage

decorate3d(xlim = NULL, ylim = NULL, zlim = NULL, 
           xlab = "x", ylab = "y", zlab = "z", 
           box = TRUE, axes = TRUE, 
           main = NULL, sub = NULL, 
           top = TRUE, aspect = FALSE, expand = 1.03, 
           tag = material3d("tag"), ...)

Arguments

Value

The RGL id values for those items.

Examples

open3d()
shade3d(tetrahedron3d(), col = "red")
decorate3d(main = "A Tetrahedron")

Description

Project a line onto the surface in a scene so that it appears to drape itself onto the surface.

Usage

drape3d(obj, ...)
## S3 method for class 'mesh3d'
drape3d(obj, x, y = NULL, z = NULL, plot = TRUE,
                         up = c(0, 0, 1),
                         P = projectDown(up), ...)
## Default S3 method:
drape3d(obj, ...)

Arguments

Details

The default method converts obj to a mesh using as.mesh3d, then uses the "mesh3d" method.

The current implementation constructs the segments to drape across the surface using the same method as lines3d uses: each successive point is joined to the previous one. Use NA coordinates to indicate breaks in the line.

The P matrix is used to project points to a plane as follows: They are transformed by P in homogeneous coordinates, then only first two (Euclidean) coordinates are kept.

Value

If plot = TRUE, plots the result and invisibly returns the object ID of the collection of segments.

If plot = FALSE, returns a matrix containing "x", "y" and "z" values for the line(s) (for use with segments3d),

Author(s)

George Helffrich and Duncan Murdoch

See Also

shadow3d, facing3d

Examples

#
# volcano example taken from "persp"
#

z <- 2 * volcano        # Exaggerate the relief

x <- 10 * (1:nrow(z))   # 10 meter spacing (S to N)
y <- 10 * (1:ncol(z))   # 10 meter spacing (E to W)

zlim <- range(z)
zlen <- zlim[2] - zlim[1] + 1

colorlut <- terrain.colors(zlen) # height color lookup table

col <- colorlut[ z - zlim[1] + 1 ] # assign colors to heights for each point

open3d()
id <- surface3d(x, y, z, color = col, polygon_offset = 1)

segs <- data.frame(x = range(x) + c(100, -100),
                   y = range(y) + c(150, -100), z = 325)
drape3d(id, segs, col = 'yellow', lwd = 3)
lines3d(segs, col='red', lwd=3)

p <- c(350, 205)         # (x,y) of strike & dip reading
off <- 20*c(-1, +1)      # X-marks-the-spot offset
segs <- data.frame(
    x = c(p[1] + off, NA, p[1] + off),
    y = c(p[2] + off, NA, p[2] - off),
    z = rep(350, 5)
    )
drape3d(id, segs, col = "yellow", lwd = 3)

Description

The rglwidget control is designed to work in the htmlwidgets framework. Older RGL web pages that used the deprecated writeWebGL or knitr used a different method of linking the controls to the scene. This is a partial bridge between the two systems. You should adopt the new system, not use this function.

Usage

elementId2Prefix(elementId, prefix = elementId)

Arguments

Value

This function generates Javascript code, so it should be used in an results = "asis" block in a knitr document.

Author(s)

Duncan Murdoch

Description

A generic function and several methods returning an ellipsoid or other outline of a confidence region for three parameters.

Usage

ellipse3d(x, ...)
## Default S3 method:
ellipse3d(x, scale = c(1, 1, 1), centre = c(0, 0, 0), level = 0.95, 
	t = sqrt(qchisq(level, 3)), which = 1:3, subdivide = 3, smooth = TRUE, ...)
## S3 method for class 'lm'
ellipse3d(x, which = 1:3, level = 0.95, t = sqrt(3 * qf(level, 
                                                3, x$df.residual)), ...)     
## S3 method for class 'glm'
ellipse3d(x, which = 1:3, level = 0.95, t, dispersion, ...) 
## S3 method for class 'nls'
ellipse3d(x, which = 1:3, level = 0.95, t = sqrt(3 * qf(level, 
                                                3, s$df[2])), ...)

Arguments

Value

A mesh3d object representing the ellipsoid.

Examples

# Plot a random sample and an ellipsoid of concentration corresponding to a 95% 
# probability region for a
# trivariate normal distribution with mean 0, unit variances and 
# correlation 0.8.
if (requireNamespace("MASS", quietly = TRUE)) {
  Sigma <- matrix(c(10, 3, 0, 3, 2, 0, 0, 0, 1), 3, 3)
  Mean <- 1:3
  x <- MASS::mvrnorm(1000, Mean, Sigma)
  
  open3d()
  
  plot3d(x, box = FALSE)
  
  plot3d( ellipse3d(Sigma, centre = Mean), col = "green", alpha = 0.5, add = TRUE)
}  

# Plot the estimate and joint 90% confidence region for the displacement and cylinder
# count linear coefficients in the mtcars dataset

data(mtcars)
fit <- lm(mpg ~ disp + cyl , mtcars)

open3d()
plot3d(ellipse3d(fit, level = 0.90), col = "blue", alpha = 0.5, aspect = TRUE)

Description

Gets the current scene using scene3d, and compares the result to a saved value, optionally closing the window afterwards.

Usage

expect_known_scene(name, 
                   close = TRUE, 
                   file = paste0("testdata/", name, ".rds"),
                   ...)

Arguments

Details

This function uses expect_known_value to save a representation of the scene. During the comparison, the scene is modified so that non-reproducible aspects are standardized or omitted:

• object ids are changed to start at 1.

• system-specific font names and texture names are deleted.

• the window is shifted to the top left of the screen.

Calls to expect_known_scene() enable testthat::local_edition(2) for the duration of the call, so it will work in testthat “3rd edition”.

Value

A value describing the changes to the saved object, suitable for use in test_that().

Examples

## Not run: 
# These lines can be included in testthat::test_that() code.
plot3d(1:10, 1:10, 1:10)
expect_known_scene("plot")

## End(Not run)

Description

Given a two-dimensional polygon, this generates a three-dimensional extrusion of the shape by triangulating the polygon and creating a cylinder with that shape as the end faces.

Usage

extrude3d(x, y = NULL, thickness = 1, smooth = FALSE, ...)

Arguments

Details

The extrusion is always constructed with the polygon in the xy plane at z = 0 and another copy at z = thickness. Use the transformation functions (e.g. rotate3d) to obtain other orientations and placements.

Value

A mesh object containing a triangulation of the polygon for each face, and quadrilaterals for the sides.

Author(s)

Duncan Murdoch

See Also

polygon3d for a simple polygon, triangulate for the triangulation, turn3d for a solid of rotation.

Examples

x <- c(1:10, 10:1)
y <- rev(c(rep(c(0, 2), 5), rep(c(1.5, -0.5), 5)))
plot(x, y, type = "n")
polygon(x, y)
open3d()
shade3d( extrude3d(x, y), col = "red" )

Description

facing3d subsets an object by converting it to a triangle mesh, then subsetting to those triangles that are counterclockwise (for front = TRUE) when projected into a plane.

projectDown computes a projection that “looks down” the specified direction.

Usage

facing3d(obj, up = c(0, 0, 1), 
         P = projectDown(up), 
         front = TRUE, strict = TRUE)
projectDown(up)

Arguments

Details

By default the returned subset will be those triangles whose upper side matches front. Change up or use an arbitrary projection for different subsets.

drape3d and shadow3d project objects onto meshes; these functions can be used to project only onto the top or front.

Value

facing3d returns a mesh object made of those triangles which face in the desired direction.

projectDown computes a 4x4 matrix. The first two coordinates of asEuclidean(x %*% projectDown(up)) give a projection of x from above into a plane, where up determines which direction is taken to be “up”.

See Also

drape3d, shadow3d

Examples

open3d()
d <- rnorm(3)
d <- d/sqrt(sum(d^2))
shade3d( facing3d( icosahedron3d(), up = d, strict = FALSE), 
         col = "yellow")
wire3d( facing3d( icosahedron3d(), up = d, front = FALSE), 
         col = "black")
# Show the direction:
arrow3d(-2*d , -d)

Description

In an R Markdown document, figure dimensions are normally specified in inches; these are translated into pixel dimensions when HTML output is requested and rglwidget is used. These functions reproduce that translation.

Usage

figWidth()
figHeight()

Value

When used in an R Markdown document, these functions return the requested current dimensions of figures in pixels. Outside such a document, NULL is returned.

Author(s)

Duncan Murdoch

Examples

# No useful return value outside of R Markdown:
figWidth()
figHeight()

Description

Constructs a mesh of line segments corresponding to non-shared (i.e. boundary) edges of triangles or quads in the original mesh.

Usage

getBoundary3d(mesh, sorted = FALSE, simplify = TRUE, ...)

Arguments

Value

A "mesh3d" object containing 0 or more segments.

Author(s)

Duncan Murdoch

See Also

mesh3d

Examples

x <- cube3d(col = "blue")
x$ib <- x$ib[,-(1:2)]
b <- getBoundary3d(x, sorted = TRUE, col = "black")

open3d()
shade3d(x, alpha=0.2)

shade3d(b) 

# Show edge vertices in sequence:
text3d(t(b$vb), texts = 1:ncol(b$vb), adj = 0)
c(b$is[1,1], b$is[2,])

Description

The glTF specification packs data into buffers, labelling the type of each part with an integer. The first six values in gltfTypes are the integers used there, with "int" and "double" added for completeness; those values are taken from OpenGL header files.

Usage

gltfTypes

Format

gltfTypes is simply a named vector containing integer values.

Details

These are used in the Buffer object.

References

https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#_accessor_componenttype

Examples

gltfTypes

Description

Generate a 3x3 orthogonal matrix using the Gram-Schmidt algorithm.

Usage

GramSchmidt(v1, v2, v3, order = 1:3)

Arguments

Details

This function orthogonalizes the matrix rbind(v1, v2, v3) using the Gram-Schmidt algorithm. It can handle rank 2 matrices (returning a rank 3 matrix). If the original is rank 1, it is likely to fail.

The order vector determines the precedence of the original vectors. For example, if it is c(i, j, k), then row i will be unchanged (other than normalization); row j will normally be transformed within the span of rows i and j. Row k will be transformed orthogonally to the span of the others.

Value

A 3x3 matrix whose rows are the orthogonalization of the original row vectors.

Author(s)

Duncan Murdoch

Examples

# Proceed through the rows in order
print(A <- matrix(rnorm(9), 3, 3))
GramSchmidt(A[1, ], A[2, ], A[3, ])

# Keep the middle row unchanged
print(A <- matrix(c(rnorm(2), 0, 1, 0, 0, rnorm(3)), 3, 3, byrow = TRUE))
GramSchmidt(A[1, ], A[2, ], A[3, ], order = c(2, 1, 3))

Description

This function adds a reference grid to an RGL plot.

Usage

grid3d(side, at = NULL, col = "gray", lwd = 1, lty = 1, n = 5)

Arguments

Details

This function is similar to grid in classic graphics, except that it draws a 3D grid in the plot.

The grid is drawn in a plane perpendicular to the coordinate axes. The first letter of the side argument specifies the direction of the plane: "x", "y" or "z" (or uppercase versions) to specify the coordinate which is constant on the plane.

If at = NULL (the default), the grid is drawn at the limit of the box around the data. If the second letter of the side argument is "-" or is not present, it is the lower limit; if "+" then at the upper limit. The grid lines are drawn at values chosen by pretty with n suggested locations. The default locations should match those chosen by axis3d with nticks = n.

If at is a numeric vector, the grid lines are drawn at those values.

If at is a list, then the "x" component is used to specify the x location, the "y" component specifies the y location, and the "z" component specifies the z location. Missing components are handled using the default as for at = NULL.

Multiple grids may be drawn by specifying multiple values for side or for the component of at that specifies the grid location.

Value

A vector or matrix of object ids is returned invisibly.

Note

If the scene is resized, the grid will not be resized; use abclines3d to draw grid lines that will automatically resize.

Author(s)

Ben Bolker and Duncan Murdoch

See Also

axis3d

Examples

x <- 1:10
y <- 1:10
z <- matrix(outer(x - 5, y - 5) + rnorm(100), 10, 10)
open3d()
persp3d(x, y, z, col = "red", alpha = 0.7, aspect = c(1, 1, 0.5))
grid3d(c("x", "y+", "z"))

Description

This adds text to identify points within a plot when the mouse is near them.

Usage

hover3d(x, y = NULL, z = NULL, 
        labeller = NULL, 
        tolerance = 20, 
        persist = c("no", "one", "yes"), 
        labels = seq_along(x),
        adj = c(-0.2, 0.5),
        scene = scene3d(minimal = FALSE),
        applyToScene = TRUE,
        ...)

Arguments

Details

If specified, the labeller argument should specify a function with arguments compatible with function(index, ...). It will be called with index being the index of the point that was selected. It should plot the label, and return the rgl ids of the objects that were plotted.

When applyToScene is TRUE, all labels or labelling objects will be created and attached to the scene. You may want to delete them (using the ids returned in idverts and idtexts) once rglwidget has been called, as they serve no purpose in the current device.

Only one hover handler is supported per scene or device.

Value

A lowlevel vector of ids is returned invisibly. If applyToScene is TRUE, it will contain the ids of the temporary objects created for Javascript. It will also have these attributes:

Author(s)

Duncan Murdoch

See Also

identify3d and selectpoints3d work in the rgl device and return information about the selections. setUserCallbacks is the underlying function used by hover3d.

Examples

# Create a labeller to show the coordinates of the selected point.
labelLocation <- function(x, y = NULL, z = NULL) {
  xyz <- xyz.coords(x, y, z)
  function(sel, ...) {
    p <- with(xyz, matrix(c(x[sel], y[sel], z[sel]), ncol = 3))
    c(text3d(p, texts = sprintf("x:%.2f", p[1]), 
                  adj = c(-0.2, -0.6), ...),
      text3d(p, texts = sprintf("y:%.2f", p[2]),
                  adj = c(-0.2, 0.5), ...),
      text3d(p, texts = sprintf("z:%.2f", p[3]),
                  adj = c(-0.2, 1.6), ...))
  }
}

xyz <- matrix(rnorm(30), ncol = 3)
open3d()
ids <- plot3d(xyz)
hover3d(xyz, labeller = labelLocation(xyz), col = "red", cex = 0.8)
# The same thing using the data id:
# hover3d(ids["data"], 
#         labeller = labelLocation(rgl.attrib(ids["data"], "vertices")), 
#         col = "red", cex = 0.8)