Movatterモバイル変換

3D visualization device system

Description

3D real-time rendering system.

Details

RGL is a 3D real-time rendering system for R.Multiple windows are managed at a time. Windowsmay be divided into “subscenes”, where one has the current focusthat receives instructions from the R command-line. The device design is oriented towards the R device metaphor. If you sendscene management instructions, and there's no device open, it will be openedautomatically.Opened devices automatically get the current device focus. The focus may bechanged by usingset3d() oruseSubscene3d().

RGL provides medium to high level functions for 3D interactive graphics, includingfunctions modelled on base graphics (plot3d(), etc.) as well as functions for constructing geometric objects (cube3d(), etc.). Outputmay 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.

Theopen3d() 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 renderingpipeline;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)

Check for an open RGL window.

Description

Mostly for internal use, this function returns the current devicenumber 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()

R6 Class for binary buffers in glTF files.

Description

These files typically have one buffer holding all thebinary 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()

Methodnew()

Usage

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

Arguments

Methodload()

Load from file.

Usage

Buffer$load(uri, buf = 0)

Arguments

MethodsaveOpenBuffer()

Write open buffer to connection.

Usage

Buffer$saveOpenBuffer(con, buf = 0)

Arguments

MethodgetBuffer()

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.

MethodsetBuffer()

Set buffer object.

Usage

Buffer$setBuffer(buf, buffer)

Arguments

MethodopenBuffer()

Open a connection for the data in a buffer.

Usage

Buffer$openBuffer(buf)

Arguments

Returns

An open binary connection.

MethodwriteBuffer()

Write data to buffer.

Usage

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

Arguments

Returns

Byte offset of start of bytes written.

MethodcloseBuffer()

Close the connection in a buffer.

If there was a connection open, this will save thecontents in the raw vectorbytes within the buffer object.

Usage

Buffer$closeBuffer(buf)

Arguments

MethodcloseBuffers()

Close any open buffers.

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

Usage

Buffer$closeBuffers()

MethodgetBufferview()

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

MethodaddBufferView()

Add a new buffer view.

Usage

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

Arguments

Returns

NewbufferView number.

MethodopenBufferview()

Open a connection to a buffer view.

Usage

Buffer$openBufferview(bufv)

Arguments

Returns

A connection.

MethodsetBufferview()

SetbufferView object.

Usage

Buffer$setBufferview(bufv, bufferView)

Arguments

MethodgetAccessor()

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

MethodsetAccessor()

Set accessor object.

Usage

Buffer$setAccessor(acc, accessor)

Arguments

MethodreadAccessor()

Read data given by accessor number.

Usage

Buffer$readAccessor(acc)

Arguments

Returns

A vector or array as specified in the accessor. For theMATn types, the 3rd indexindexes the element.

MethodreadAccessor0()

Read data given by accessor object.

Usage

Buffer$readAccessor0(accessor)

Arguments

Returns

A vector or array as specified in the accessor. For theMATn types, the 3rd indexindexes the element.

MethodaddAccessor()

Write values to accessor, not includingmin andmax.

Usage

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

Arguments

Returns

New accessor number

MethoddataURI()

Convert buffer to data URI.

Usage

Buffer$dataURI(buf = 0)

Arguments

Returns

String containing data URI.

Methodas.list()

Convert to list.

Usage

Buffer$as.list()

Returns

List suitable for writing using JSON.

Methodclone()

The objects of this class are cloneable with this method.

Usage

Buffer$clone(deep = FALSE)

Arguments

The Gram-Schmidt algorithm

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 matrixrbind(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 likelyto fail.

Theorder vector determines the precedence of the originalvectors. For example, if it isc(i, j, k), then rowi will be unchanged (other than normalization); rowj willnormally be transformed within the span of rowsi andj. Rowk will be transformed orthogonally to the span ofthe others.

Value

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

Author(s)

Duncan Murdoch

Examples

# Proceed through the rows in orderprint(A <- matrix(rnorm(9), 3, 3))GramSchmidt(A[1, ], A[2, ], A[3, ])# Keep the middle row unchangedprint(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))

Lines intersecting the bounding box

Description

This adds mathematical lines to a scene. Their intersection with the currentbounding 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 currentbounding box of the scene using the parametrization (x, y, z) + (a, b, c) * s wheres is a real number.

Any reasonable way of defining thecoordinatesx, y, z anda, b, c is acceptable. See the functionxyz.coordsfor details.

Value

A shape ID of the object is returned invisibly.

See Also

planes3d for mathematical planes.

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

Examples

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

Add normal vectors to objects so they render more smoothly

Description

This generic function adds normals at each of the verticesof a polyhedron by averaging the normals of each incident face. This has theeffect of making the surface of the object appear smooth rather than facetedwhen 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.IfangleWeighted = FALSE, a slightly fasterbut less accurate weighting by the triangle area is used.

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

Value

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

Author(s)

Duncan Murdoch

Examples

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

Set attributes of vertices based on their age

Description

This is a function to produce actions in response toaplaywidget or Shiny input control. Themental model is that each of the vertices of some object hasa certain birth time; a control sets the current time, so thatvertices 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 asthe number of vertices in the object.

Not all objects contain all attributes; if one is chosen that isnot a property of the corresponding object, a Javascriptalert() will begenerated. (This restriction may be removed in the future by attemptingto add the attribute when it makes sense.)

If abirths entry isNA, no change will be made to thatvertex.

Value

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

Author(s)

Duncan Murdoch

See Also

TheUser Interaction in WebGL vignettegives more details.

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)

Compare mesh3d objects in a meaningful way.

Description

These functions allow comparison of mesh3d objects, ignoringirrelevant differences.

compare_proxy.mesh3d can function as acompare_proxy method for thewaldo package, by stripping outNULL componentsand ordering other components alphabetically by name.

all.equal.mesh3d compares mesh3d objects by usingcompare_proxy.mesh3d to standardize them, thenusing the regularall.equal function tocompare them.

Usage

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

Arguments

Value

all.equal.mesh3d returnsTRUE, or a charactervector describing (some of) the differences.

compare_proxy.mesh3d returns a list containing twocomponents:

object

a copy ofx withrelevant components in alphabetical order.

path

a modification of the path label forx

Note

waldo is not an installation requirement forrglandrgl will never cause it to be loaded.Thecompare_proxy.mesh3d function will only be registered as a method forwaldo::compare_proxyif you loadwaldo beforergl, as would normally happen during testing usingtestthat, or if you loadit before callingmesh3d,as might happen if you are doing manual tests.

Draw arcs

Description

Given starting and ending points on a sphere and the center of thesphere, draw thegreat circle arc between the starting and ending points. Ifthe starting and ending points have different radii, a segment of alogarithmic spiral will join them, unless they are in the samedirection, 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 offrom,to orcenter is an n by 3matrix with n > 1, multiple arcs will be drawn by recyclingeach of these parameters to the number of rows of the longestone.

If the vector lengths offrom - center andto - center differ, then instead of a sphericalarc, the function will draw a segment of a logarithmic spiral joiningthe two points.

By default, the arc is drawn along the shortest great circle path fromfrom toto, but thebase parameter can be used to modify this. Ifbase = 1 is used, the longer arc will be followed.Larger positive integer values will result inbase - 1loops in that direction completely around the sphere. Negative values will draw the curve in the same directionas the shortest arc, but withabs(base) full loops.It doesn't make much sense to ask for such loops unlessthe radii offrom andto differ, becausespherical arcs would overlap.Normally thebase parameter is left at its defaultvalue of0.

Whenbase is non-zero, the curve will be constructed in multiplepieces, betweenfrom,to,-from and-to,for as many steps as necessary. Ifn is specified, itwill apply to each of these pieces.

Value

Ifplot = TRUE, called mainly for the side effect of drawing arcs. Invisiblyreturns the object ID of the collection of arcs.

Ifplot = FALSE, returns a 3 column matrix containingthe 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 lengthfrom <- 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")

Draw an arrow

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 shapesof all of them are affected byp0,p1,barblen,s,theta, material propertiesin..., andspriteOrigin. Other parameters only affect some of the types, as shown.

"extrusion"

(default) A 3-dimensionalflat arrow, drawn withshade3d. Affected bywidth,thickness andsmooth.

"lines"

Drawn with lines, similar toarrows, drawn withsegments3d. Affected byn.

"flat"

A flat arrow, drawn withpolygon3d. Affected bywidth andsmooth.

"rotation"

A solid of rotation, drawn withshade3d. Affected byn andwidth.

Normally this function draws just one arrow fromp0 top1, butifspriteOrigin is given (in any formthatxyz.coords(spriteOrigin) canhandle), arrows will be drawn for each pointspecified, withp0 andp1 interpreted relative to those origins. Thearrows will be drawn as 3D sprites which willmaintain their orientation as the scene is rotated, so this is a good way to indicateparticular locations of interest in the scene.

Value

Ifplot = TRUE (the default), this iscalled mainly for the side effect of drawingthe arrow; invisibly returns the id(s) of the objects drawn.

Ifplot = FALSE, the data that would beused in the plot (not including materialproperties) is returned.

Author(s)

Design based onheplots::arrow3d, which contains modifications by Michael Friendlyto 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")

Convert object to mesh object

Description

Theas.mesh3d generic function converts various objectstomesh3d objects.

The default method takes takes a matrix of vertices as input and (optionally) merges repeated vertices, producing amesh3dobject as output. It will contain either triangles or quads or segments or pointsaccording to thetype argument.

If the generic is called without any argument, it will passall RGL ids from the current scene to theas.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 wasasked 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 theaddNormals 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 thenotEqual matrix specifies.

Value

A"mesh3d" object with the same faces as in the input, but (ifmerge=TRUE) with vertices that test equal towithintolerance 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$vbmesh$ibopen3d()shade3d(mesh)# Stop vertices 2 and 5 from being mergednotEQ <- matrix(FALSE, 12, 12)notEQ[2, 5] <- TRUEmesh <- as.mesh3d(xyz, type = "quads", notEqual = notEQ)mesh$vbmesh$ib

Convert alpha-shape surface of a cloud of points toRGL mesh object

Description

Thealphashape3d::ashape3dfunction computes the3D\alpha-shape of a cloud of points. This is an approximationto the visual outline of the cloud. It may include isolatedpoints, line segments, and triangular faces: this functionconverts the triangular faces to an RGLtmesh3d 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.

Ifsmooth = TRUE, this method attempts to orient allof the triangles in the surface consistently and add normalsat 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 issuedand the resulting mesh will likely contain boundarieswhere the assumed orientation of triangles changes, resultingin ugly dark lines through the shape. Larger valuesofalpha in the call toalphashape3d::ashape3d may help.

Methods forplot3d andpersp3dare also defined: they call theas.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-Shapefor 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)}

Convert object in plot to RGL mesh object

Description

This method attempts to read the attributes of objects in thergl 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 fromc("points", "lines", "linestrip", "triangles", "quads", "planes", "surface").

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

If the genericas.mesh3d is called with noxargument, this method will be called withx 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 reliefx <- 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] + 1colorlut <- terrain.colors(zlen) # height color lookup tablecol <- colorlut[ z - zlim[1] + 1 ] # assign colors to heights for each pointopen3d(useNULL = TRUE)surface3d(x, y, z, color = col)m <- as.mesh3d()close3d()open3d()shade3d(m)

Convert an object to anrglscene object.

Description

This is a placeholder generic function, to allow otherpackages to create"rglscene" objects compatible withthe objects produced byscene3d.

No methods are currently defined inrgl.

Usage

as.rglscene(x, ...)

Arguments

Convert object to a triangular mesh

Description

Converts the quads in a mesh version of an object totriangles by splitting them up. Optionally drops anypoint 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 callsas.mesh3d(x, ...)and passes the result to the"mesh3d" method.

Value

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

IfkeepTags = TRUE, a"tags" element will be added to the result. For details, see theclipMesh3dhelp page.

Note

Older versions ofrgl had a"tmesh3d" classfor meshes of triangles. That class is no longer used:as.tmesh3d andtmesh3d both produce"mesh3d" objects.

Author(s)

Duncan Murdoch

See Also

as.triangles3d to get just the coordinates.

Examples

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

Convert an object to triangles

Description

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

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 differentattributes, organizing them as it would organize the vertices forthe triangles.

Value

Ann x 3 matrix containing the vertices of triangles makingup the object. Each successive 3 rows of the matrix corresponds toa 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")

Convenience functions for RGL HTML layouts

Description

TheasRow function arranges objects in a row in the display;thegetWidgetId function extracts the HTML element IDfrom an HTML widget.

Usage

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

Arguments

Details

UsingasRow requires that themanipulateWidgetpackage is installed.

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

Ifn objects are given as input andlast is given a valueless thann, the firstn - last objects will be displayedin a column above the row containing thelast objects.

Value

asRow returns a single"combineWidgets" object suitable for display or nestingwithin 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. TheUser Interaction in WebGL vignettegives more details.

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}

Set the aspect ratios of the current plot

Description

This function sets the apparent ratios of the x, y, and z axesof 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 thecoordinates should all be displayed at the same scale, i.e. the bounding box should not berescaled. (This corresponds to the default display beforeaspect3d has been called.)Partial matches to"iso" are allowed.

aspect3d works by modifyingpar3d("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()

Draw boxes, axes and other text outside the data

Description

These functions draw axes, boxes and text outside the range of the data.axes3d,box3d andtitle3d 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 identifiedusing 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 onlyone or two characters are given, the remaining characters normally default to ‘-’ (but withmtext3d(..., floating = TRUE) the default is ‘+’; see below). For exampleedge = 'x+' draws an x-axis at the high level of y and thelow level of z.

By default,axes3d uses thebbox3d 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 casefixed axes are drawn usingaxis3d.

As ofrgl version 0.106.21, axis drawing has changedsignificantly. Text drawn in the margins willadapt to the margins (seebbox3d). Theedge andfloating parameters will be recordedin themargin andfloating materialproperties for the object.

Iffloating = FALSE, they will be drawn on thespecified edge.

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

The final possible value forfloating inmtext3d isNA, which reproduces legacyrglbehaviour. Inthis case the labels are not tied to the bounding box,so they should be drawn last, or they could appear insidethe box, overlapping the data.

Intitle3dfloating = NULL (the default) indicates the main title and subtitle will be fixed while the axis labels will befloating. The default locations for title and subtitleareline = 2 andlevel = 2 on edges"x++" and"x--"respectively. The axis labels float atline = 4 andlevel = 1 on the same edge as the ticks.

Theat parameter inaxis3d is the locationof the ticks, defaulting topretty locations.Inmtext3d theat parameter is the locationon the specified axisat which to draw the text, defaulting to the middle of thebounding box.

Theline parameter is the line counting outfrom the box in the same direction as the axis ticks,andlevel is the line out in the orthogonaldirection. The ticks run fromline = 0 toline = 1, and thetick labels are drawn atline = 2. Both are drawn at level 0.

Thepos parameter is only supported in legacy mode. If it is a numeric vector of length 3,edge determinesthe direction of the axis and the tick marks, and the values of theother two coordinates inpos determine the position. Thelevel parameter is ignored in legacy mode.

Formtext3d infloating = TRUE orfloating = FALSE mode,there are 3 special values for theat parameter: it maybe-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 ofobjects added to the scene.

Note

mtext3d is a wrapper fortext3dthat sets themargin andfloating materialproperties. In fact, these properties can be set for manykinds of objects (most kinds where it would make sense), with the effect that the object will be drawnin the margin, withx coordinate corresponding toat,y corresponding toline, andzcorresponding tolevel.

Author(s)

Duncan Murdoch

See Also

Classic graphics functionsaxis,box,title,mtext are related.See RGL functionsbbox3d for drawing the box around the plot, andsetAxisCallbacks 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)

Set up bounding box decoration

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:Ifxat is notNULL, the ticks are set up at custom positions.Ifxunit is numeric but not zero, it defines the tick mark base. Ifit is"pretty" (the default inbbox3d), ticks are set atprettylocations.Ifxlen is not zero, it specifies the number of ticks(a suggestion ifxunit is"pretty").

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

bbox3d defaults topretty locations for the axis labels and a slightly largerbox, whereasrgl.bbox covers the exact range.

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

Value

This function is called for the side effect of setting the bounding box decoration.A shape ID is returned to allowpop3d 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)

Set up background

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 fromcolor orcolifcolor is missing.The first entryis used for background clearing and as the fog color.The second (if present) is used for background sphere geometry.

Ifcolor andcol are both missing, the default is found in ther3dDefaults$bg list, or"white" is usedif nothing is specified there.

Ifsphere is set toTRUE, an environmentalsphere 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.

ThefogScale parameter should be a positive valueto change the density of the fog in the plot. Forfogtype = "linear" it multiplies the density of thefog; for the exponential fog types it multiplies the densityparameter used in the display.

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

• For"linear" fog, the near clipping plane istaken asc=0, and the far clipping plane is taken asc=1. Theamount of fog iss * c clamped to a 0 to 1range, wheres = fogScale.

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

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

  wheretheta = FOV/2.We calculate

  c' = d(1-c) + c

  soc' runs from 0 at the observer to1 at the far clipping plane.

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

• For"exp2" fog, the amount of fog is1 - 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")

Use base graphics for RGL background

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

Thebgplot3d function opens apng device and executesexpression,producing a plot there. This plot is then used as a bitmap background for the currentRGL subscene.

Thelegend3d function draws a standard 2D legend to the background of the currentsubscene by callingbgplot3d to open a device, and setting up a plot region there to fill the whole display.

Value

Thebgplot3d function invisibly returns the ID of the background object that was created,with attribute"value" holding the value returned when theexpression wasevaluated.

Thelegend3d function does similarly. The"value" attribute is the resultof the call tolegend. 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 defaultpar3d(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)

User callbacks on mouse events

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.Thebegin andupdate events should be functions taking two arguments; thesewill be the mouse coordinates when the event occurs. Theend event handlertakes no arguments. Therotate event takes a single argument, which will be equal to1 if the user pushes the wheel away by one click, and2 if the user pulls the wheel by one click.

Alternatively, the handlers may be set toNULL, the default value, in which caseno action will occur.

If a subscene has multiple listeners, the user action will still only be called for thesubscene that received the mouse event. It should consultpar3d("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 byspecifyingbutton = 0. Thebeginfunction will be called the first time the mousemoves within the subscene, and theupdatefunction will be called repeatedly as it moves. Theend function will never be called.

Value

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

Thergl.getMouseCallbacks function returns a list containing the callback functions orNULL if no user callback is set.Thergl.getWheelCallback returns the callback function orNULL.

Author(s)

Duncan Murdoch

See Also

par3d to set built-in handlers,setUserCallbacks to work withrglwidget.

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)

Check for a compatible version ofdeldir

Description

Version 1.0-2 ofdeldir is not compatible withrgl.This allows code to avoid trying to call it.

Usage

checkDeldir(error = FALSE)

Arguments

Value

ReturnsTRUE ifdeldir is available in a compatibleversion.

Examples

checkDeldir()

Clip mesh or RGL object to general region

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 otherRGL objects by removing parts wherefn violatesthe bound.

ForclipMesh3d thefn argument can be anyof the following:

• a character vector naming a function (with specialnames"x","y", and"z" correspondingto functions returning those coordinates)

• a function

• a numeric vector with one value per vertex

• NULL, indicating that the numeric valuesare saved inmesh$values

ForclipObj3d any of the above exceptNULLmay be used.

Iffnis a numeric vector, with one value per vertex, those values will beused in the test.If it is a function with formal argumentsx,y andz, it will receive the coordinates of vertices in those arguments, otherwise it will receive the coordinates in a single n x 3 matrix. The functionshould 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 dependon how many of the vertices satisfy the condition (fn >= bound orfn <= bound, depending ongreater)for inclusion.

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

• If one vertex satisfies the condition, the other two verticesin that triangle are shrunk towards it by assumingfnis locally linear.

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

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

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

TheminVertices argument is used to improve the approximation to the boundary whenfn is a non-linearfunction. In that case, the interpolation described abovecan be inaccurate. IfminVertices is set to apositivenumber (e.g.10000), then each object is modifiedby subdivision to have at least that number of vertices, so that pieces are smaller and the linear interpolationis more accurate. In theclipObj3d function,minVertices can be a vector, with entries correspondingto each of the entries inids.

Value

Ifplot = FALSE,clipMesh3d returns new mesh3d object in which all vertices (approximately) satisfy theclipping condition. Note that the order of vertices will likelydiffer from the original order, and new vertices will be added nearthe boundary (and ifminVertices > 0, in the interior). If in additionkeepValues = TRUE,a component named"values" will be added to the mesh containing the values for each vertex.IfkeepTags = TRUE, thetags componentdescribed below will be added to the output mesh.

Ifplot = TRUE, the result will be plotted withshade3d and its result returned.

clipObj3d is called for the side effect of modifyingthe scene. It returns a list of new RGL id valuescorresponding to theids passed as arguments.

ThekeepTags argument

IfkeepTags = TRUE, a"tags" element will be added to the result. It will be a vector with one entry perpoint, segment, triangle and quad in the output mesh. (These tags are not relatedto the tags used to identifyrgl objects.)The mesh tags may be used to show the correspondence betweenthe parts of the input mesh and output mesh.By default, the tags are constructed as a numerical sequenceover points,segments, triangles andquads in the input mesh, in that order, starting from one. This is the same order used for colours when shading withmeshColor == "faces".

For example, start with a mesh with one point, two segments, threetriangles and fourquads, but notags 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 segmentsand the first triangle, the output would contain the sevenelement 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⁠

Thetags output may contain repetitions. For example,when a triangle is partially clipped and replaced by severalsmaller triangles, entries for all of them will contain the valuecorresponding to the original triangle.

Themesh$tags component may be supplied as part of the inputmesh as any type of vector; the output will propagate values to the new mesh. The input lengthmust 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

Seehttps://stackoverflow.com/q/56242470/2554330 andhttps://laustep.github.io/stlahblog/posts/MeshClipping.html for amotivating example.

See Also

SeecontourLines3d andfilledContour3d 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 matrixvecnorm <- 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)

Sets attributes of a clipping plane

Description

This is a function to produce actions in a web display. Aplaywidget or Shinyinput control (e.g. asliderInput control)sets a value which controls attributes of one or more clippingplanes.

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 parametervalues, to be used in an RGL widget.

Author(s)

Duncan Murdoch

See Also

TheUser Interaction in WebGL vignettegives more details.

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)

Draw contours on a surface

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

ForcontourLines3d, thefn argument can be anyof the following:

• a character vector namingone or more functions

• a function

• a numeric vector with one value per vertex

• NULL, indicating that the numeric valuesare saved inobj$values

• a list containing any of the above.

ForfilledContour3d, only one function can be specified.

The special names"x", "y", "z" may be used infn to specify functions returning one of thosecoordinates. (If you have existing functionsx(),y()orz() they will be masked by this choice; specifysuch functions by value rather than name, e.g.fn = xinstead offn = "x".)

Functions infn with formal argumentsx,y andz will receive the coordinates of vertices in those arguments, otherwise they will receive the coordinates in a single n x 3 matrix. They shouldbe vectorized and return one value per vertex.

Each of the functions will be evaluated at each vertexof the surface specified byobj, and contours willbe drawn assuming the function is linear between vertices.If contours of a nonlinear function are needed, you maywant to increaseminVertices as described below.

Iflevels is not specified, values will be setseparately for each entry infn, usingpretty(range(values, na.rm = TRUE), nlevels) wherevalues are the values on the vertices.

TheminVertices 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. IfminVertices is set to apositivenumber (e.g.10000), then the mesh is modifiedby subdivision to have at least that number of vertices, so that pieces are smaller and the linear interpolationis more accurate.

Value

For bothcontourLines3d andfilledContour3dthe"rglId" method converts the given id values toa mesh, and calls the"mesh3d" method.

The"mesh3d" method returns an object of class"rglId" corresponding to what wasdrawn ifplot isTRUE,

Ifplot isFALSE,contourLines3d returns a dataframe containing columnsc("x", "y", "z", "fn", "level") givingthe coordinates of the endpoints of each line segment, the name (or index) of the function for this contour, and the level of the contour.

Ifplot isFALSE,filledContour3dreturns a"mesh3d" object holding the result.IfkeepValues isTRUE, the meshwill contain the values corresponding to each vertex(with linear approximations at the boundaries).

Note

To draw contours on a surface, the surface should be drawnwith material propertypolygon_offset = 1 (or perhapssome larger positive value) so that the lines of the contour are notobscured by the surface.

In R versions prior to 3.6.0, the defaultcolor.paletteisgrDevices::cm.colors.

Author(s)

Duncan Murdoch

See Also

Themisc3d package contains the functioncontour3dto draw contour surfaces in space instead of contour lineson surfaces.

Examples

# Add contourlines in "z" to a persp plotz <- 2 * volcano        # Exaggerate the reliefx <- 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 functionfilledContour3d(id, polygon_offset = 1, nlevels = 10, replace = TRUE)# Draw longitude and latitude lines on a globelat <- 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 kmx <- 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))

Sample 3D mesh objects

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 transformationtrans as an argument. This transformation is applied to all vertices of the default shape.The default is an identity transformation.

Value

Objects of classc("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) )

Create cylindrical or "tube" plots

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 incenter,after usingxyz.coords to convert it to a list. The other argumentsradius,twist,e1,e2, ande3 are extended to the samelength.

Theclosed argument controls how the ends of the cylinder arehandled. Ifclosed > 0, it represents the number of points ofoverlap in the coordinates.closed == TRUE is the same asclosed = 1. Ifclosed > 0 but the ends don't actually match, a warning will be given and results will be somewhat unpredictable.

Negative values ofclosed indicate that caps should be put on theends of the cylinder. Ifclosed == -1, a cap will be put on theend corresponding tocenter[1, ]. Ifclosed == -2, capswill be put on both ends.

Ifsection isNULL (the default), a regularsides-sided polygon is used, andradius measures thedistance from the center of the cylinder to each vertex. If notNULL,sides is ignored (and set internally tonrow(section)), andradius is used as a multiplier tothe vertex coordinates.twist specifies the rotation of thepolygon. Bothradius andtwist may be vectors, withvalues recycled to the number of rows incenter, whilesides andsection are the same at every point along thecurve.

The three optional argumentse1,e2, ande3determine the local coordinate system used to create the vertices ateach point incenter. If missing, they are computed by simplenumerical approximations.e1 should be the tangent coordinate,giving the direction of the curve at the point. The cross-section ofthe polygon will be orthogonal toe1. WhenrotationMinimizing isTRUE,e2 ande3 are chosen to givea rotation minimizing frame (see Wang et al., 2008). When it isFALSE,e2 defaults to anapproximation to the normal or curvature vector; it is used as theimage of they axis of the polygon cross-section.e3defaults to an approximation to the binormal vector, to which thex axis of the polygon maps. The vectors are orthogonalized andnormalized at each point.

Value

A"mesh3d" object holding the cylinder, possibly withattribute"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 knotopen3d()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)))

Add decorations to a 3D plot

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

Drape lines over a scene.

Description

Project a line onto the surface in a scene so that it appears to drape itselfonto 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 convertsobj to a meshusingas.mesh3d, then uses the"mesh3d"method.

The current implementation constructs the segments to drapeacross the surface using the same method aslines3d uses: each successive point isjoined to the previous one. UseNA coordinates toindicate breaks in the line.

TheP matrix is used to project points to a plane asfollows: They are transformed byP in homogeneous coordinates, then only first two (Euclidean)coordinates are kept.

Value

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

Ifplot = FALSE, returns a matrix containing "x", "y" and "z"values for the line(s) (for use withsegments3d),

Author(s)

George Helffrich and Duncan Murdoch

See Also

shadow3d,facing3d

Examples

## volcano example taken from "persp"#z <- 2 * volcano        # Exaggerate the reliefx <- 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] + 1colorlut <- terrain.colors(zlen) # height color lookup tablecol <- colorlut[ z - zlim[1] + 1 ] # assign colors to heights for each pointopen3d()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 readingoff <- 20*c(-1, +1)      # X-marks-the-spot offsetsegs <- 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)

Use widget with old-style controls

Description

Therglwidget control is designed to work in thehtmlwidgets framework. Older RGL web pages thatused the deprecatedwriteWebGL orknitr used a differentmethod of linking the controls to the scene. This is a partialbridge 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 beused in anresults = "asis" block in aknitr document.

Author(s)

Duncan Murdoch

Make an ellipsoid

Description

A generic function and several methodsreturning an ellipsoid or other outline of a confidence regionfor 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

Amesh3d 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 datasetdata(mtcars)fit <- lm(mpg ~ disp + cyl , mtcars)open3d()plot3d(ellipse3d(fit, level = 0.90), col = "blue", alpha = 0.5, aspect = TRUE)

Helper fortestthat testing.

Description

Gets the current scene usingscene3d, andcompares the result to a saved value, optionally closingthe window afterwards.

Usage

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

Arguments

Details

This function usesexpect_known_value to save a representation of the scene. During the comparison, the sceneis modified so that non-reproducible aspects are standardizedor 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 toexpect_known_scene() enabletestthat::local_edition(2) for the duration of the call, so it will work intestthat “3rd edition”.

Value

A value describing the changes to the saved object,suitable for use intest_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)

Generate extrusion mesh

Description

Given a two-dimensional polygon, this generates a three-dimensional extrusionof the shape by triangulating the polygon and creating a cylinder withthat 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 atz = 0 and another copy atz = thickness. Usethe transformation functions (e.g.rotate3d) to obtain other orientations and placements.

Value

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

Author(s)

Duncan Murdoch

See Also

polygon3d for a simple polygon,triangulate forthe 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" )

Subset an object to parts facing in a particular direction

Description

facing3d subsets an object by converting it to a triangle mesh,then subsetting to those triangles that are counterclockwise(forfront = 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 sidematchesfront. Changeup or use anarbitrary projection for different subsets.

drape3d andshadow3d project objects onto meshes; these functions can be used toproject 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 twocoordinates ofasEuclidean(x %*% projectDown(up)) give a projection ofx from above into a plane, whereup 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)

Get R Markdown figure dimensions in pixels

Description

In an R Markdown document, figure dimensions are normallyspecified in inches; these are translated into pixeldimensions when HTML output is requested andrglwidget is used. These functions reproduce thattranslation.

Usage

figWidth()figHeight()

Value

When used in an R Markdown document, these functionsreturn the requested current dimensions of figures in pixels. Outside such a document,NULLis returned.

Author(s)

Duncan Murdoch

Examples

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

Extract the boundary of a mesh

Description

Constructs a mesh of line segments corresponding tonon-shared (i.e. boundary) edges of triangles or quadsin 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,])

Names of glTF types.

Description

The glTF specification packs data into buffers, labellingthe type of each part with an integer. The first six valuesingltfTypes are theintegers used there, with"int" and"double"added for completeness; those values are taken fromOpenGL header files.

Usage

gltfTypes

Format

gltfTypes is simply a named vector containing integer values.

Details

These are used in theBuffer object.

References

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

Examples

gltfTypes

Add a grid to a 3D plot

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 togrid 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. Thefirst letter of theside argument specifies the direction ofthe plane:"x","y" or"z" (or uppercaseversions) to specify the coordinate which is constant on the plane.

Ifat = NULL (the default), the grid is drawn at the limit of the box around the data. If the second letter of theside argumentis"-" or is not present, it is the lower limit; if"+"then at the upper limit. The grid lines are drawn at valueschosen bypretty withn suggested locations.The default locations should match those chosen byaxis3dwithnticks = n.

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

Ifat is a list, then the"x" component is used tospecify the x location, the"y" component specifies the y location, andthe"z" component specifies the z location. Missing componentsare handled using the default as forat = NULL.

Multiple grids may be drawn by specifying multiple values forsideor for the component ofat 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; useabclines3dto draw grid lines that will automatically resize.

Author(s)

Ben Bolker and Duncan Murdoch

See Also

axis3d

Examples

x <- 1:10y <- 1:10z <- 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"))

Display hover info in plot.

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, thelabeller argument should specify afunction with argumentscompatible withfunction(index, ...). It will be called withindex being the index of the point that was selected. It shouldplot the label, and return thergl ids of the objects that were plotted.

WhenapplyToScene isTRUE, all labelsor labelling objects will be created and attached to the scene. You may want todelete them (using the ids returned inidverts andidtexts) oncerglwidget has been called,as they serve no purpose in the current device.

Only one hover handler is supported per scene or device.

Value

Alowlevel vector of ids is returned invisibly.IfapplyToScene isTRUE, it will contain theids of the temporary objects created for Javascript.It will also have these attributes:

Author(s)

Duncan Murdoch

See Also

identify3d andselectpoints3dwork in thergl device and return informationabout the selections.setUserCallbacksis the underlying function used byhover3d.

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)

Identify points in plot

Description

Identify points in a plot, similarly to theidentify functionin base graphics.

Usage

identify3d(x, y = NULL, z = NULL, labels = seq_along(x), n = length(x), plot = TRUE, adj = c(-0.1, 0.5), tolerance = 20, buttons = c("right", "middle"))

Arguments

Details

Ifbuttons is length 1, the user can quit by reachingnselections, or by hitting the escape key, but the result will be lost if escape is used.

Value

A vector of selected indices.

Author(s)

Duncan Murdoch

See Also

identify for base graphics,select3d for selecting regions.

Imported from magrittr

Description

This object is imported frommagrittr. Follow the link to its documentation.

magrittr

%>%

Pipes can be used to string togetherrglwidget calls andplaywidgetcalls. SeeageControl for an example.

Are we running inpkgdown or apkgdown example?

Description

This is mainly for internal use to decide whether resultsshould be automatically included in apkgdown webpage.

See theUsing RGL in pkgdown web sitesvignette for details about usingpkgdown.

Usage

in_pkgdown()in_pkgdown_example()

Value

TRUE orFALSE

Examples

in_pkgdown_example()

Add light source

Description

add a light source to the scene.

Usage

light3d(theta=0, phi=15,        x=NULL, y = NULL, z = NULL,        viewpoint.rel = TRUE,         ambient = "#FFFFFF",         diffuse = "#FFFFFF",         specular = "#FFFFFF")

Arguments

Details

Up to 8 light sources are supported. They are positioned either inworld space or relative to the camera. By providing polarcoordinates totheta andphi a directional light source is used. Ifnumerical values are given to x, y and z, a point-like light source withfinite distance to the objects in the scene is set up.

Ifx is non-null,xyz.coords willbe used to form the location values, so all three coordinatescan be specified inx.

If no lights have been added to a subscene, lights from the parentsubscene will be used.

Seematerial3d for a discussion of howthe components of the light affect the display of objects.

Value

This function is called for the side effect of adding a light. A light ID isreturned to allowpop3d to remove it.

See Also

clear3dpop3d

Examples

## a lightsource moving through the scene#data(volcano)z <- 2 * volcano # Exaggerate the reliefx <- 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] + 1colorlut <- terrain.colors(zlen) # height color lookup tablecol <- colorlut[ z - zlim[1] + 1 ] # assign colors to heights for each pointopen3d()bg3d("gray50")surface3d(x, y, z, color = col, back = "lines")r <- max(y) - mean(y)lightid <- spheres3d(1, 1, 1, alpha = 0)frame <- function(time) {    a <- pi*(time - 1)    save <- par3d(skipRedraw = TRUE)    clear3d(type = "lights")    pop3d(id = lightid)    xyz <- matrix(c(r*sin(a) + mean(x), r*cos(a) + mean(y), max(z)), ncol = 3)    light3d(x = xyz, diffuse = "gray75",             specular = "gray75", viewpoint.rel = FALSE)     light3d(diffuse = "gray10", specular = "gray25")    lightid <<- spheres3d(xyz, emission = "white", radius = 4)    par3d(save)    Sys.sleep(0.02)    NULL}play3d(frame, duration = 2)

Process Javascript for HTML dependency

Description

A utility function to help in development of internal Javascript code, this function processes the Javascriptto minify it and report on errors and bad style.

Usage

makeDependency(name, src, script = NULL, package,                version = packageVersion(package),               minifile = paste0(basename(src), ".min.js"),               debugging = FALSE, ...)

Arguments

Details

This is a utility function used by RGL to process its Javascript code used when displayingrglwidget values. It may be helpful in other packages to usein their own installation.

If thejs package version 1.2 or greater is installed,the Javascript code will be minified and stored in the file namedbyminifile in thesrc directory. Syntax errorsin the code will stop the process; unused variables will bereported.

Ifdebugging isTRUE, the locations of Javascript syntaxerrors will be reported, along with hints about improvements,and the original files will be used in the dependency objectthat is created.

Ifdebugging isFALSE (the default), the minified file will be used in the dependency object,hints won't be given, and syntax errors will lead to anuninformative failure to minify.

Value

An object that can be included in a list of dependencies passed tohtmltools::attachDependencies.

Note

The usual way to usemakeDependency is to call it in a ‘.R’ file in a package, savingthe result in a variable that will be used when anHTML widget is created. This way it is only runduring package installation, when it is safe towrite to the R library holding the package.

Do not call it to write to the R library from code the user can run, as that is not allowed ingeneral.

If your package uses Roxygen, you may have problemsbecause by default Roxygen will run the code, and itis likely to fail. The current workaround is tospecify Roxygen optionload = "installed"which prevents it from running your ‘.R’ code.

Author(s)

Duncan Murdoch

Examples

## Not run: # This is a slightly simplified version of the code used to # produce one of the dependencies for rglwidget().  # It writes to the system library copy of rgl so # has been marked not to run in the example code.makeDependency("rglwidgetClass",                src = "htmlwidgets/lib/rglClass",               script = c("rglClass.src.js",                          "utils.src.js",                          "buffer.src.js",                          "subscenes.src.js",                          "shaders.src.js",                          "textures.src.js",                          "projection.src.js",                          "mouse.src.js",                          "init.src.js",                          "pieces.src.js",                          "draw.src.js",                          "controls.src.js",                          "selection.src.js",                          "rglTimer.src.js",                          "pretty.src.js",                          "axes.src.js",                          "animation.src.js"),               stylesheet = "rgl.css",               package = "rgl",               debugging = isTRUE(as.logical(Sys.getenv("RGL_DEBUGGING", "FALSE"))))## End(Not run)

Get or set material properties

Description

Get or set material properties for geometry appearance.

Usage

material3d(..., id = NULL)rgl.material.namesrgl.material.readonly

Arguments

Details

In anrgl scene, each object has “material properties” that control how it is rendered and (in the case oftag) that can be used to store a label or other information.material3d sets defaultsfor these properties and queries the defaults or specificvalues for an individual object.

To set values, usename = value settings, e.g.material3d(color = "red"). To query values, specify the property or properties in a character vector,e.g.material3d("color").

Only one side at a time can be culled.

Thematerial member of ther3dDefaults list may be used to set default values for material properties.

Value

material3d() returns values similarlytopar3d:When setting properties, it returns the previous valuesinvisibly in a named list. When querying multiple values, anamed list is returned. When a single value is queried it isreturned directly.

Material Properties

Thergl.material.names variable contains thefull list of material names.The following read-write material properties controlthe appearanceof objects in anrgl scene.

color

vector of R color characters. Represents the diffuse component in case of lighting calculation (lit = TRUE),otherwise it describes the solid color characteristics.

lit

logical, specifying if lighting calculation should take place on geometry

ambient, specular, emission, shininess

properties for lighting calculation. ambient, specular, emission are R color character string values; shininess represents anumerical.

alpha

vector of alpha values between 0.0 (fully transparent) and 1.0 (opaque). SeeA Note on Transparency for a discussion of some issues with transparency.

smooth

logical, specifying whether smooth shading or flat shadingshould be used. For smooth shading, Gouraud shading isused inrgl windows, while Phong shading is used in WebGL.

texture

path to a texture image specification. See the Textures sectionbelow for details.

textype

specifies what is defined with the pixmap

"alpha"

alpha values

"luminance"

luminance

"luminance.alpha"

luminance and alpha

"rgb"

color

"rgba"

color and alpha texture

Note that support for these modes is slightly differentin the display within R versus the WebGL display usingrglwidget(). In particular, in WebGLtextype = "alpha" will always take the alpha value fromthe luminance (i.e. the average of the R, G and B channels) of the texture, whereas the R display basesthe choice on the internal format of the texture file.

texmode

specifies how the texture interacts with the existingcolor

"replace"

texture value replaces existing value

"modulate"

default; texture value multiplies existing value

"decal"

fortextype = "rgba", textureis mixed with existing value

"blend"

uses the texture to blend the existingvalue with black

"add"

adds the texture value to the existing.May not be available in the R display with very oldOpenGL drivers.

texmipmap

Logical, specifies if the texture should be mipmapped.

texmagfilter

specifies the magnification filtering type (sorted by ascending quality):

"nearest"

texel nearest to the center of the pixel

"linear"

weighted linear average of a 2x2 array of texels

texminfilter

specifies the minification filtering type (sorted by ascending quality):

"nearest"

texel nearest to the center of the pixel

"linear"

weighted linear average of a 2x2 array of texels

"nearest.mipmap.nearest"

low quality mipmapping

"nearest.mipmap.linear"

medium quality mipmapping

"linear.mipmap.nearest"

medium quality mipmapping

"linear.mipmap.linear"

high quality mipmapping

texenvmap

logical, specifies if auto-generated texture coordinates for environment-mapping should be performed on geometry.

front, back

Determines the polygon mode for the specified side:

"filled"

filled polygon

"lines"

wireframed polygon

"points"

point polygon

"culled"

culled (hidden) polygon

size

numeric, specifying the size of points in pixels

lwd

numeric, specifying the line width in pixels

fog

logical, specifying if fog effect should be applied on the corresponding shape. Fog type is set inbg3d.

point_antialias, line_antialias

logical, specifying if points should be round and lines should be antialiased, but see Note below.

depth_mask

logical, specifying whether the object's depthshould be stored.

depth_test

Determines which depth test is used to see if thisobject is visible, depending on its apparent depth in the scenecompared to the stored depth. Possible values are"never","less" (the default),"equal","lequal"(less than or equal),"greater","notequal","gequal" (greater than or equal),"always".

polygon_offset

A one or two elementvector giving the ‘⁠factor⁠’ and ‘⁠units⁠’ valuesto use in aglPolygonOffset() call in OpenGL. Ifonly one value is given, it is used for both elements.The ‘⁠units⁠’ value is added to the depth of all pixels ina filled polygon,and the ‘⁠factor⁠’ value is multiplied by an estimate ofthe slope of the polygon and then added to the depth. Positive values “push” polygons back slightly for the purposeof depth testing, to allow points, lines or other polygonsto be drawn on the surface without being obscured due to rounding error. Negative values pull the object forward.A typical value to use is1 (whichis automatically expanded toc(1,1)).If values are too large, objects which should be behindthe polygon will show through, and if values are too small,the objects on the surface will be partially obscured. Experimentation may be needed to get it right. The firstexample in?persp3d uses this property to add grid lines to a surface.

margin, floating

Used mainly for text todraw annotations in the margins, but supported bymost kinds of objects: seemtext3d.

tag

A length 1 string value. Thesemay be used to identify objects, or encode other metadata about the object.

blend

Two string values from the list belowdescribing how transparent objects are blended withcolors behind them.The first determines the coefficient applied to the color of the current object (the source); the second determinesthe coefficient applied to the existing color (the destination). The resultingcolor will be the sum of the two resulting colors.The allowed stringscorrespond to OpenGL constants:

"zero"

Zero; color has no effect.

"one"

One; color is added to the other term.

"src_color", "one_minus_src_color"

Multiply by source color or its opposite.

"dst_color", "one_minus_dst_color"

Multiply by destination color or its opposite.

"src_alpha", "one_minus_src_alpha"

Multiply bysource alpha or its opposite. Default values.

"dst_alpha", "one_minus_dst_alpha"

Multiply bydestination alpha or its opposite.

"constant_color", "one_minus_constant_color","constant_alpha", "one_minus_constant_alpha","src_alpha_saturate"

These are allowed, but to be usefulthey require other settings whichrgl doesn'tsupport.

col

An allowed abbreviation ofcolor.

Thergl.material.readonly variable containsthe subset of material properties that are read-onlyso they can be queriedbut not set.Currently there is only one:

isTransparent

Is the current color transparent?

Textures

Thetexture material property may beNULL or the name ofa bitmap file to be displayed on the surface being rendered.Currently PNG and JPEG format files are supported. It mayalso be any other object for whichas.raster() works, e.g. a matrix.

By default, the colors in the bitmap will modify the color of theobject being plotted. If the color is black (a common default), youwon't see anything, so a warning may be issued. You cansuppress the warning by specifying the color explicitly, or callingoptions{rgl.warnBlackTexture = FALSE}.

Other aspects of texture display are controlled by the materialpropertiestextype, texmode, texmipmap, texmagfilter,texminfilter andtexenvmap described above.

For an extensive discussion of textures, see theTextures section of thergl Overviewvignette.

Display of objects

Object display colors are determined as follows:

• Iflit = FALSE, an element of thecolor vector property is displayed without modification. See documentation for individual objects for information on which element is chosen.

• Iflit = TRUE, the color is determined as follows.

  1. The color is set to theemission propertyof the object.

  2. For each defined light, the following are added:

     • the product of theambient colorof the light and theambient color of the object is added.

     • thecolor of theobject is multiplied by thediffuse colorof the light and by a constant depending onthe angle between the surface and the direction to the light, and added.

     • thespecular color of the objectis multiplied by thespecular color of the light and a constant depending on theshininessof the object and the direction to the light, andadded. Theshininess property mainlydetermines the size of the shiny highlight; adjustone or both of thespecular colors to changeits brightness.

Ifpoint_antialias isTRUE, points will be drawn as circles in WebGL; otherwise, theywill be drawn as squares. Within R, the behaviour dependson your graphics hardware: for example, I see circles for both settings on my laptop.

Within R, lines tend to appear heavier withline_antialias == TRUE. There's no difference at allin WebGL.

See Also

bbox3d,bg3d,light3d

Examples

save <- material3d("color")material3d(color = "red")material3d("color")material3d(color = save)# this illustrates the effect of depth_testx <- c(1:3); xmid <- mean(x)y <- c(2, 1, 3); ymid <- mean(y)z <- 1open3d()tests <- c("never", "less", "equal", "lequal", "greater",                   "notequal", "gequal", "always")for (i in 1:8) {  triangles3d(x, y, z + i, col = heat.colors(8)[i])  texts3d(xmid, ymid, z + i, paste(i, tests[i], sep = ". "), depth_test = tests[i]) }highlevel()  # To trigger display# this illustrates additive blendingopen3d()bg3d("darkgray")quad <- cbind(c(-1, 1, 1, -1), 1, c(-1, -1, 1, 1))quads3d(rbind(translate3d(quad, -0.5, 0, -0.5),              translate3d(quad, 0.5,  0.5, -0.5),              translate3d(quad, 0, 1, 0.5)),         col = rep(c("red", "green", "blue"), each = 4),        alpha = 0.5,         blend = c("src_alpha", "one"))

Work with homogeneous coordinates

Description

These functions construct 4x4 matrices for transformationsin the homogeneous coordinate system used by OpenGL, and translatevectors between homogeneous and Euclidean coordinates.

Usage

identityMatrix()scaleMatrix(x, y, z)translationMatrix(x, y, z)rotationMatrix(angle, x, y, z, matrix)asHomogeneous(x)asEuclidean(x)asHomogeneous2(x)asEuclidean2(x)scale3d(obj, x, y, z, ...)translate3d(obj, x, y, z, ...)rotate3d(obj, angle, x, y, z, matrix, ...)transform3d(obj, matrix, ...)

Arguments

Details

OpenGL uses homogeneous coordinates to handle perspective and affinetransformations. The homogeneous point(x, y, z, w) correspondsto the Euclidean point(x/w, y/w, z/w). The matrices produced bythe functionsscaleMatrix,translationMatrix, androtationMatrixare to be left-multiplied by a row vector of homogeneous coordinates; alternatively, the transpose of the resultcan be right-multiplied by a column vector. The generic functionsscale3d,translate3d androtate3d apply these transformationsto theobj argument. Thetransform3d function is a synonym forrotate3d(obj, matrix = matrix).

By default, it is assumed thatobj is a row vector(or a matrix of row vectors) which will be multiplied on the right bythe corresponding matrix, but users may write methods for these genericswhich operate differently. Methods are supplied formesh3dobjects.

To compose transformations, use matrix multiplication. The effect isto apply the matrix on the left first, followed by the one on the right.

identityMatrix returns an identity matrix.

scaleMatrix scales each coordinate by the given factor. In Euclideancoordinates,(u, v, w) is transformed to(x*u, y*v, z*w).

translationMatrix translates each coordinate by the given translation, i.e.(u, v, w) is transformed to(u + x, v + y, w + z).

rotationMatrix can be called in three ways. With argumentsangle, x, y, z it represents a rotation ofangle radians about the axisx, y, z. Ifmatrix is a 3x3 rotation matrix,it will be converted into the corresponding matrix in 4x4 homogeneouscoordinates. Finally, if a 4x4 matrix is given, it will be returned unchanged.(The latter behaviour is used to allowtransform3d to act like a generic function, even though it is not.)

UseasHomogeneous(x) to convert the Euclidean vectorx tohomogeneous coordinates, andasEuclidean(x) for the reverse transformation. These functions accept the followinginputs:

• n x 3 matrices: rows are assumed to be Euclidean

• n x 4 matrices: rows are assumed to be homogeneous

• vectors of length 3n or 4n: assumed to be vectorsconcatenated. For the ambiguous caseof vectors that are length 12n (so both 3n and 4n are possible),the assumption is that the conversion is necessary:asEuclidean assumes the vectors are homogeneous,andasHomogeneous assumes the vectors are Euclidean.

Outputs are n x 4 or n x 3 matrices forasHomogeneousandasEuclidean respectively.

The functionsasHomogeneous2 andasEuclidean2act similarly, but they assume inputs are 3 x n or 4 x nand outputs are in similar shapes.

Value

identityMatrix,scaleMatrix,translationMatrix, androtationMatrix producea 4x4 matrix representing the requested transformationin homogeneous coordinates.

scale3d,translate3d androtate3d transform the objectand produce a new object of the same class.

Author(s)

Duncan Murdoch

See Also

par3d for a description of how RGL uses matrices inrendering.

Examples

# A 90 degree rotation about the x axis:rotationMatrix(pi/2, 1, 0, 0)# Find what happens when you rotate (2, 0, 0) by 45 degrees about the y axis:x <- asHomogeneous(c(2, 0, 0))y <- x %*% rotationMatrix(pi/4, 0, 1, 0)asEuclidean(y)# or more simply...rotate3d(c(2, 0, 0), pi/4, 0, 1, 0)

Merge RGL mesh objects

Description

Attempts to merge"mesh3d" objects. Objects needto be similar enough; see Details.

Usage

## S3 method for class 'mesh3d'merge(x, y, ..., attributesMustMatch = FALSE)

Arguments

Details

To allow objects to be merged, they need to be similar enoughin terms of having the same list of material properties,normals, texture coordinates, etc.

IfattributesMustMatch isTRUE, it is an errorto have attributes in one mesh but not in another, and those attributes that only specify a single value must have equalvalues in all meshes.

IfattributesMustMatch isFALSE, any non-matchingattributes will be dropped from the final result.

Value

A single"mesh3d" object merging the contentsof the arguments.

Author(s)

Duncan Murdoch

Examples

open3d()# Notice that the alpha setting for the cube is dropped, because# the other shapes don't specify alpha.shade3d(merge(cube3d(col="red", alpha = 0.5),              translate3d(tetrahedron3d(col="green"), 2, 0, 0),              translate3d(octahedron3d(col="blue"), 4, 0, 0)))

Merge duplicate vertices in mesh object

Description

A mesh object can have the same vertex listed twice. Each copy isallowed to have separate normals, texture coordinates, and color.However, it is more efficient to have just a single copy if thosedifferences aren't needed. For automatic smoothing usingaddNormals, triangles and quads need to share vertices.This function merges identical (or similar) vertices to achieve this.

Usage

mergeVertices(mesh,               notEqual = NULL,               attribute = "vertices",               tolerance = sqrt(.Machine$double.eps))

Arguments

Value

A new mesh object.

Author(s)

Duncan Murdoch

See Also

as.mesh3d.rglId, which often constructs meshobjects containing a lot of duplication.

Examples

open3d()(mesh1 <- cuboctahedron3d(col = rainbow(14), meshColor = "face"))id <- shade3d(mesh1)(mesh2 <- as.mesh3d(id))shade3d(translate3d(mesh2, 3, 0, 0))(mesh3 <- mergeVertices(mesh2))shade3d(translate3d(mesh3, 6, 0, 0))

Construct 3D mesh objects

Description

Creates meshes containing points, segments, triangles and quads.

Usage

  mesh3d( x, y = NULL, z = NULL, vertices,                    material = NULL,                    normals = NULL, texcoords = NULL,                    points = NULL, segments = NULL,                    triangles = NULL, quads = NULL,                    meshColor = c("vertices", "edges", "faces", "legacy"))  qmesh3d(vertices, indices, homogeneous = TRUE, material = NULL,          normals = NULL, texcoords = NULL,         meshColor = c("vertices", "edges", "faces", "legacy"))  tmesh3d(vertices, indices, homogeneous = TRUE, material = NULL,          normals = NULL, texcoords = NULL,         meshColor = c("vertices", "edges", "faces", "legacy"))

Arguments

Details

These functions createmesh3d objects, which consist of a matrixof vertex coordinates together with a matrices of indices indicating how the vertices should be displayed, and material properties.

The"shape3d" class is a general class for shapes that can be plottedbydot3d,wire3d orshade3d.

The"mesh3d" class is a class of objects that form meshes: the verticesare in membervb, as a 4 byn matrix usinghomogeneous coordinates. Indices of these vertices arecontained in optional componentsip for points,is for line segments,it for triangles, andib for quads.Individual meshes may have any combination of these.

The functionstmesh3d andqmesh3d are includedfor back-compatibility; they produce meshes of triangles andquads respectively.

Value

Objects of classc("mesh3d", "shape3d").

Seepoints3d for a discussion of texture coordinates.

See Also

shade3d,shapelist3d for multiple shapes

Examples

  # generate a quad mesh object  vertices <- c(      -1.0, -1.0, 0,      1.0, -1.0, 0,      1.0,  1.0, 0,     -1.0,  1.0, 0  )  indices <- c( 1, 2, 3, 4 )    open3d()    wire3d( mesh3d(vertices = vertices, quads = indices) )

Set up multiple figure layouts

Description

Themfrow3d andlayout3d functions provide functionality in RGLsimilar topar("mfrow") andlayout in classic R graphics.

Usage

subsceneList(value, window = cur3d())mfrow3d(nr, nc, byrow = TRUE, parent = NA, sharedMouse = FALSE, ...)layout3d(mat, widths = rep.int(1, ncol(mat)),               heights = rep.int(1, nrow(mat)),              parent = NA, sharedMouse = FALSE,              ...)next3d(current = NA, clear = TRUE, reuse = TRUE)clearSubsceneList(delete = currentSubscene3d() %in% subsceneList(),                   window = cur3d())

Arguments

Details

rgl can maintain a list of subscenes; themfrow3d andlayout3d functions create that list.When the list is in place,next3d causes RGL to move to the next scene in the list, or cycleback to the first one.

Unlike the classic R graphics versions of these functions, these functions are completely compatible witheach other. You can mix them within a single RGL window.

In the default case whereparent is missing,mfrow3d andlayout3d willcallclearSubsceneList() at the start.

By defaultclearSubsceneList() checkswhether the current subscene is in the current subscene list; if so, it will deleteall subscenes in the list, and callgc3d to delete any objects that are nolonger shown. The subscene list will be set to a previous value if one was recorded,orNULL if not.

Ifparent is specified inmfrow3d orlayout3d (even asNA), the new subscenes will be created within the parent.

Thenext3d() function first finds out if the currentsubscene is in the current list. If not, it moves to theprevious list, and looks there. Once it finds a list containing the current subscene, it moves to the next entryin that list. If it can't find one, it creates a lengthone list containing just the current subscene.

Value

mfrow3d andlayout3d return a vector of subscene id values that have just beencreated. If a previous subscene list was in effect and was not automatically cleared,it is attached as an attribute"prev".

Author(s)

Duncan Murdoch

See Also

newSubscene3d,par,layout.

Examples

shapes <- list(Tetrahedron = tetrahedron3d(), Cube = cube3d(), Octahedron = octahedron3d(),               Icosahedron = icosahedron3d(), Dodecahedron = dodecahedron3d(),               Cuboctahedron = cuboctahedron3d())col <- rainbow(6)open3d()mfrow3d(3, 2)for (i in 1:6) {  next3d()   # won't advance the first time, since it is empty  shade3d(shapes[[i]], col = col[i])}highlevel(integer()) # To trigger display as rglwidgetopen3d()mat <- matrix(1:4, 2, 2)mat <- rbind(mat, mat + 4, mat + 8)layout3d(mat, height = rep(c(3, 1), 3), sharedMouse = TRUE)for (i in 1:6) {  next3d()  shade3d(shapes[[i]], col = col[i])  next3d()  text3d(0, 0, 0, names(shapes)[i])}highlevel(integer())

Set the observer location

Description

This function sets the location of the viewer.

Usage

observer3d(x, y = NULL, z = NULL, auto = FALSE)

Arguments

Details

This functionsets the location of the viewer relative to the scene, after the model transformations(scaling, rotation) have been done, but before lighting or projection have been applied. (Seepar3d for details on the rendering pipeline.)

The coordinate system is a slightly strange one: the X coordinatemoves the observer location from left to right, and the Y coordinate moves upand down. The Z coordinate changes the depth from the viewer. All are measuredrelative to the center of the bounding box (par("bbox")) of the subscene.The observer always looks in the positive Z directionafter the model rotation have been done. The coordinates are in post-scalingunits.

Value

Invisibly returns the previous value.

Note

This function is likely to change in future versions of RGL, to allow more flexibility in the specification of the observer's location and orientation.

Author(s)

Duncan Murdoch

Examples

example(surface3d)  # The volcano dataobserver3d(0, 0, 440) # Viewed from very close up

Work with RGL windows

Description

open3d opens a new RGL window;cur3d returns the device number of the currentwindow;close3d closes one or more windows.

Usage

open3d(..., params = getr3dDefaults(),     useNULL = rgl.useNULL(), silent = FALSE)    close3d(dev = cur3d(), silent = TRUE)    cur3d()rgl.dev.list()set3d(dev, silent = FALSE)getr3dDefaults(class = NULL, value = NULL)r3dDefaultsrgl.quit()

Arguments

Details

open3d opens a new RGL device, and sets the parameters asrequested. Ther3dDefaults list returned by thegetr3dDefaults function will be used as defaultvalues for parameters. As installed this sets the point of view to'world coordinates' (i.e. x running from left to right, y from frontto back, z from bottom to top), themouseMode to(zAxis, zoom, fov), and the field of view to 30 degrees.useFreeType defaults toFALSE on Windows; on other systems it indicates the availabilityof FreeType.Users may create their own variable namedr3dDefaults in the globalenvironment and it will override the installed one. If thereis abg element in the list or the arguments, it should bea list of arguments to pass to thebg3d function to set the background.

The arguments toopen3d may includematerial, a listof material properties as inr3dDefaults, but notethat high level functions such asplot3d normally usether3dDefaults values in preference to this setting.

IfuseNULL isTRUE, RGL will use a “null”device. This device records objects as they are plotted, but displays nothing. It is intended for use withrglwidget.

Value

Theopen3d function returns the device that was opened. Ifsilent = TRUE, it is returned invisibly.

Thecur3d function returns the current device,or the value 0 if there isn't one.rgl.dev.listreturns a vector of all open devices. Items are namedaccording to the type of device:null for a hiddennull device,wgl for a Windows device, andglX for an X windows device.

set3d returns the device number of thepreviously active device.

Theclose3d function returns the new currentdevice, invisibly.

Ther3dDefaults variable is a list containing defaultsettings. Thegetr3dDefaults function searches the user'sglobal environment forr3dDefaults and returns the one in the RGL namespace if it was not found there.The components of the list may include any settablepar3dparameter, or"material", which should include a listof defaultmaterial3d properties, or"bg", which is alist of defaults to pass to thebg3d function.

rgl.quit attempts to unloadrgl and then returnsNULL invisibly.

See Also

rgl.useNULL for default usage of null device.

Examples

    r3dDefaults    open3d()    shade3d(cube3d(color = rainbow(6), meshColor = "faces"))    cur3d()

Set or query RGL parameters

Description

par3d can be used to set or query graphical parameters in RGL.Parameters can be set by specifying them as arguments topar3d inname = value form, or by passing them as a list of namedvalues.

Usage

par3d(..., no.readonly = FALSE, dev = cur3d(),       subscene = currentSubscene3d(dev))rgl.par3d.namesrgl.par3d.readonly

Arguments

Details

Parameters are queried by giving one or more character vectors topar3d.

par3d() (no arguments) orpar3d(no.readonly = TRUE) is used togetall the graphical parameters (as a named list).

By default, queries and modifications apply to the current subsceneon the current device; specifydev and/orsubscene to change this. Some parameters apply to the device as a whole;these are marked in the list below.

Value

When parameters are set, their former values are returned in aninvisible named list. Such a list can be passed as an argument topar3d to restore the parameter values.Usepar3d(no.readonly = TRUE) for the full list of parametersthat can be restored.

When just one parameter is queried, its value is returned directly.When two or more parameters are queried, the result is a list ofvalues, with the list names giving the parameters.

Note the inconsistency: setting one parameter returns a list, butquerying one parameter returns an object.

Parameters

Thergl.par3d.names variable contains thefull list of names ofpar3d properties.rgl.par3d.readonly contains the list ofread-only properties.

In the list below,R.O. indicates theread-only arguments: These may only be used inqueries, they do not set anything.

activeSubscene

R.O. integer. Usedwithrgl.setMouseCallbacks: during a callback, indicates the id of the subscene that was clicked.

antialias

R.O. inpar3d, may beset inopen3d. The (requested) number of hardwareantialiasing planes to use (with multisample antialiasing). TheOpenGL driver may not support the requested number, in which casepar3d("antialias") will report what was actually set. Applies to the whole device.

cex

real. The default size for text.

family

character. The default device independent family name; seetext3d.Applies to the whole device.

font

integer. The default font number (from 1 to 4; seetext3d).Applies to the whole device.

useFreeType

logical. Should FreeType fonts be used?Applies to the whole device.

fontname

R.O.; the system-dependent name of the current font.Applies to the whole device.

FOV

real. The field of view, from 0 to 179 degrees. This controlsthe degree of parallax in the perspective view.Isometric perspective corresponds toFOV = 0.

ignoreExtent

logical. Set toTRUE so that subsequently plotted objectswill be ignored in calculating the bounding box of the scene. Applies to thewhole device.

maxClipPlanes

R.O.; an integer giving the maximumnumber of clip planes that can be defined in the current system. Applies to the whole device.

modelMatrix

R.O.; a 4 by 4 matrix describing the positionof the user data. See the Note below.

listeners

integer. A vector of subscene id values. If a subscene receivesa mouse event (seemouseMode just below), the same action will be carried outon all subscenes in this list. (The subscene itself is normally listed as a listener.If it is not listed, it will not respond to its own mouse events.)

mouseMode

character. A vector of 5 strings describingmouse actions. The 5 entries are namedc("none", "left", "right", "middle", "wheel"), corresponding to actions for no button, the left, right or middle button, and the mouse wheel.Partial matching to action names is used. Possible values for the actions are:

"none"

No action for this button.

"trackball"

Mouse acts as a virtual trackball, rotating the scene.

"xAxis"

Similar to"trackball", but restricted to X axis rotation.

"yAxis"

Y axis rotation.

"zAxis"

Z axis rotation.

"polar"

Mouse rotates the scene by moving in polar coordinates.

"selecting"

Mouse is used for selection. This is not normally set by theuser, but is used internally by theselect3d function.

"zoom"

Mouse is used to zoom the display.

"fov"

Mouse changes the field of view of the display.

"user"

Used when a user handler is set byrgl.setMouseCallbacks.

Possible values for the last entry corresponding to the mouse wheel also include

"pull"

Pulling on the mouse wheel increases magnification, i.e. “pulls the scene closer”.

"push"

Pulling on the mouse wheel decreases magnification, i.e. “pushes the scene away”.

"user2"

Used when a user handler is set byrgl.setWheelCallback.

A common default on Mac OSX is to convert a two finger drag on a trackpad to a mouse wheel rotation.

The first entry is for actions to take whenno mouse button is pressed. Legal values are the sameas for the mouse buttons.

The first entry was added afterrgl version 0.106.8. For back compatibility, if the vectorof actions is less than 5 entries,"none"will be added at the start of it.

observer

R.O.; the position of the observer relative tothe model. Set byobserver3d. See the Note below.

projMatrix

R.O.; a 4 by 4 matrix describing the currentprojection of the scene.

scale

real. A vector of 3 values indicating the amount by which torescale each axis before display. Set byaspect3d.

skipRedraw

whether to update the display. Set toTRUE to suspendupdating while making multiple changes to the scene. Seedemo(hist3d) for an example.Applies to the whole device.

userMatrix

a 4 by 4 matrix describing user actions todisplay the scene.

userProjection

a 4 by 4 matrix describingchanges to the projection.

viewport

real. A vector giving the dimensions of thewindow in pixels. The entries are taken to bec(x, y, width, height) wherec(x, y) are the coordinates in pixels of the lower left corner within the window.

zoom

real. A positive value indicating the currentmagnification of the scene.

bbox

R.O.; real. A vector of six values indicating the current values of thebounding box of the scene (xmin, xmax, ymin, ymax, zmin, zmax)

windowRect

integer. A vector of four values indicating the left, top, right and bottom of the displayed window (in pixels). Applies to the whole device.

Rendering

The parameters returned bypar3d are sufficient to determine where RGL would rendera point on the screen. Given a column vector(x, y, z) in a subscenes, it performs the equivalent of the following operations:

1. It converts the point to homogeneous coordinates by appendingw = 1, givingthe vectorv = (x, y, z, 1).

2. It calculates theM = par3d("modelMatrix") as a product from right to leftof several matrices:

   • A matrix to translate the centre of the bounding box to the origin.

   • A matrix to rescale according topar3d("scale").

   • Thepar3d("userMatrix") as set by the user.

   • A matrix which may be set by mouse movements.

   • The description above applies to the usual case where there is just one subscene, or where the subscene's"model" is set to"replace". If it is set to"modify", the first step isskipped, and at the end the procedure is followed for the parent subscene. If it is set to"inherit" only the parent settingsare used.

3. It multiplies the point byM givingu = M %*% v.

4. It multiplies that point by a matrix based on the observer positionto translate the origin to the centre of the viewing region.

5. Using this location and information on thenormals (which have been similarly transformed), it performs lighting calculations.

6. It obtains the projection matrixP = par3d("projMatrix") based on the bounding box and field of viewor observer location, multiplies that by theuserProjection matrix to giveP. It multiplies the pointby it givingP %*% u = (x2, y2, z2, w2).

7. It converts back to Euclidean coordinates by dividing the first 3 coordinates byw2.

8. The new valuez2/w2 represents the depth into the scene of the point. Dependingon what has already been plotted, this depth might be obscured, in which case nothing more is plotted.

9. If the point is not culled due to depth, thex2 andy2 values are usedto determine the point in the image. Thepar3d("viewport") values are used to translatefrom the range(-1, 1) to pixel locations, and the point is plotted.

10. If hardware antialiasing is enabled, then the whole process isrepeated multiple times (at least conceptually) with differentlocations in each pixel sampled to determine what is plotted there,and then the images are combined into what is displayed.

See ?matrices for more information on homogeneous and Euclidean coordinates.

Note that many of these calculations are done on the graphics card using single precision;you will likely see signs of rounding error if your scene requires more than 4 or 5 digit precision to distinguish values in any coordinate.

Note

The"xAxis","yAxis" and"zAxis" mouse modes rotate relative to the coordinate system of the data, regardless of the current orientation of the scene.

When multiple parameters are set, they are set in the order given. In some cases this may lead to warnings and ignored values; for example, some font families only supportcex = 1, so changing bothcex andfamily needs to be done in the right order. For example, when using the"bitmap" family on Windows,par3d(family = "sans", cex = 2)will work, butpar3d(cex = 2, family = "sans") will leavecexat 1 (with a warning that the"bitmap" family only supports that size).

Althoughpar3d("viewport") names the entries of the reported vector,names are ignored when setting the viewport and entries must be specifiedin the standard order.

Inrgl versions 0.94.x themodelMatrix entry had a changed meaning; before and after that it contains a copy of the OpenGL MODELVIEW matrix.

As of version 0.100.32, when changing the"windowRect" parameter, the"viewport" for the root (or specified) subsceneis changed immediately. This fixes a bug where in earlierversions it would only be changed when the window was redrawn, potentially after another command making use of the value.

Default values are not described here, as several of themare changed by ther3dDefaults variable whenthe window is opened byopen3d.

References

OpenGL Architecture Review Board (1997). OpenGL Programming Guide. Addison-Wesley.

See Also

view3d to setFOV andzoom.

open3d for how to open a new windowwith default settings for these parameters.

Examples

    open3d()    shade3d(cube3d(color = rainbow(6), meshColor = "faces"))    save <- par3d(userMatrix = rotationMatrix(90*pi/180, 1, 0, 0))    highlevel()  # To trigger display    save    par3d("userMatrix")        par3d(save)    highlevel()    par3d("userMatrix")

Interpolator for par3d parameters

Description

Returns a function which interpolatespar3d parameter values,suitable for use in animations.

Usage

par3dinterp(times = NULL, userMatrix, scale, zoom, FOV,             method = c("spline", "linear"),             extrapolate = c("oscillate", "cycle", "constant", "natural"),            dev = cur3d(), subscene = par3d("listeners", dev = dev))

Arguments

Details

This function is intended to be used in constructing animations. It producesa function that returns a list suitable to pass topar3d, to set the viewpoint at a given point in time.

All of the parameters are optional. Only thosepar3d parameters that are specified will be returned.

The input values other thantimes may each be specified aslists, giving the parameter value settings at a fixed time, or asmatrices or arrays. If not lists, the following formats should beused:userMatrix can be a4 x 4 x n array, or a4x 4n matrix;scale should be ann x 3 matrix;zoom andFOV should be lengthn vectors.

An alternative form of input is to put all of the above arguments intoa list (i.e. a list of lists, or a list of arrays/matrices/vectors),and pass it as the first argument. This is the most convenient way touse this function with the functiontkpar3dsave.

Interpolation is by cubic spline or linear interpolation in an appropriatecoordinate-wise fashion. Extrapolation may oscillate(repeat the sequence forward, backward, forward, etc.), cycle (repeatit forward), be constant (no repetition outside the specified timerange), or be natural (linear on an appropriate scale). In the case of cycling, the first and last specified valuesshould be equal, or the last one will be dropped. Natural extrapolationis only supported with spline interpolation.

Value

A function is returned. The function takes one argument, and returns a list ofpar3d settings interpolated to that time.

Note

Prior torgl version 0.95.1476, thesubscene argument defaulted to thecurrent subscene, and any additional entries wouldbe ignored byplay3d. The currentdefault value ofpar3d("listeners", dev = dev) means that all subscenes that share mouse responses will also share modificationsby this function.

Author(s)

Duncan Murdoch

See Also

play3d to play the animation.

Examples

f <- par3dinterp( zoom = c(1, 2, 3, 1) )f(0)f(1)f(0.5)## Not run: play3d(f)## End(Not run)

Control RGL widget like par3dinterp()

Description

This control works withplaywidget to change settings in a WebGL display in the same wayaspar3dinterp does within R.

Usage

par3dinterpControl(fn, from, to, steps, subscene = NULL, omitConstant = TRUE, ...)

Arguments

Details

par3dinterpSetter sets parameters corresponding to values produced by the result ofpar3dinterp.

Value

Returns controller data in a list of class "rglControl".

Author(s)

Duncan Murdoch

See Also

TheUser Interaction in WebGL vignettegives more details.

Examples

example(plot3d)M <- r3dDefaults$userMatrixfn <- par3dinterp(times = (0:2)*0.75, userMatrix = list(M,                                      rotate3d(M, pi/2, 1, 0, 0),                                      rotate3d(M, pi/2, 0, 1, 0)),                                      scale = c(0.5, 1, 2))control <- par3dinterpControl(fn, 0, 3, steps = 15)control      if (interactive() || in_pkgdown_example())   rglwidget(width = 500, height = 250) %>%  playwidget(control,       step = 0.01, loop = TRUE, rate = 0.5)

Plot symbols similar to base graphics

Description

This function plots symbols similarly to what the base graphics functionpoints does whenpch is specified.

Usage

pch3d(x, y = NULL, z = NULL, pch = 1,       bg = material3d("color")[1], cex = 1, radius,       color = "black", lit = FALSE, ...)

Arguments

Details

The list of symbols encoded by numericalpch values is given in thepoints help page.

Value

A vector of object id values is returned invisibly. Separate objects will be drawnfor each different combination ofpch value from 0 to 25,color andbg, and another holding all the charactersymbols.

Note

This function is not a perfect match to how thepoints function works dueto limitations in RGL and OpenGL. Inparticular:

Symbols with numbers from 1 to 25 are drawnas 3D sprites (seesprites3d),so they will resize as the window is zoomed.Letters and numbers from 32 to 255 (which aremapped to letters) are drawn usingtext3d, so they maintain a fixed size.

A calculation somewhat like the one inplot3d that sets the sizeof spheres is used to choose the size ofsprites based oncex and the current scaling. This will likely need manualtweaking. Use theradius argumentfor a fixed size.

No special handling is done for the case ofpch = ".". Usepoints3d for small dots.

As ofrgl version 0.100.10, background and foreground colors can vary from symbol to symbol.

Author(s)

Duncan Murdoch

See Also

points3d,text3d andsprites3d for other ways to label points,points for the base graphics symboldefinitions.

Examples

open3d()i <- 0:25; x <- i %% 5; y <- rep(0, 26); z <- i %/% 5pch3d(x, y, z, pch = i, bg = "gray", color = rainbow(26))text3d(x, y, z + 0.3, i)pch3d(x + 5, y, z, pch = i+65)text3d(x + 5, y, z + 0.3, i+65)

Surface plots

Description

This function draws plots of surfaces in 3-space.persp3d is a generic function.

Usage

persp3d(x, ...)## Default S3 method:persp3d(x = seq(0, 1, length.out = nrow(z)),    y = seq(0, 1, length.out = ncol(z)), z,    xlim = NULL, ylim = NULL, zlim = NULL,    xlab = NULL, ylab = NULL, zlab = NULL, add = FALSE, aspect = !add,     forceClipregion = FALSE, ...)

Arguments

Details

The default method plots a surface defined as a grid of(x,y,z) locations in space. The grid may be specified in several ways:

• As withpersp,x andy may be given as vectors in ascending order, withz given as a matrix. Thereshould be onex value for each row ofz andoney value for each column. The surface drawn willhavex constant across rows andy constantacross columns. This is the most convenient format whenz is a function ofx andy which aremeasured on a regular grid.

• x andy may also be given as matrices, in whichcase they should have the same dimensions asz. Thesurface will combine corresponding points in each matrixinto locations(x,y,z) and draw the surface through those. Thisallows general surfaces to be drawn, as in the example of a spherical Earth shown below.

• Ifx is alist, its componentsx$x,x$y andx$z are used forx,y andz respectively, though an explicitly specifiedz value will have priority.

One difference frompersp is that colors are specified on eachvertex, rather than on each facet of the surface. To emulate theperspcolor handling, you need to do the following. First, convert the color vector to an(nx - 1) by(ny - 1) matrix; then add an extra row before row 1, and an extra column after the last column, to convert it tonx byny.(These extra colors will not be used). For example,col <- rbind(1, cbind(matrix(col, nx - 1, ny - 1), 1)).Finally, callpersp3d with material propertysmooth = FALSE.

See the “Clipping” section inplot3dfor more details onxlim, ylim, zlim andforceClipregion.

Value

This function is called for the side effect of drawing the plot. A vector of shape IDs is returned invisibly.

Author(s)

Duncan Murdoch

See Also

plot3d,persp. There isapersp3d.function method for drawing functions, andpersp3d.deldir can be usedto draw surfaces defined by an irregular collection of points. A formula methodpersp3d.formula draws surfaces using this method.

Thesurface3d function is used to draw the surface without the axes etc.

Examples

# (1) The Obligatory Mathematical surface.#     Rotated sinc function.x <- seq(-10, 10, length.out = 20)y <- xf <- function(x, y) { r <- sqrt(x^2 + y^2); 10 * sin(r)/r }z <- outer(x, y, f)z[is.na(z)] <- 1open3d()# Draw the surface twice:  the first draws the solid part, # the second draws the grid.  Offset the first so it doesn't# obscure the lines.persp3d(x, y, z, aspect = c(1, 1, 0.5), col = "lightblue",        xlab = "X", ylab = "Y", zlab = "Sinc( r )",         polygon_offset = 1)persp3d(x, y, z, front = "lines", back = "lines",         lit = FALSE, add = TRUE)highlevel()   # trigger the plot# (2) Add to existing persp plot:xE <- c(-10, 10); xy <- expand.grid(xE, xE)points3d(xy[, 1], xy[, 2], 6, col = "red")lines3d(x, y = 10, z = 6 + sin(x), col = "green")phi <- seq(0, 2*pi, length.out = 201)r1 <- 7.725 # radius of 2nd maximumxr <- r1 * cos(phi)yr <- r1 * sin(phi)lines3d(xr, yr, f(xr, yr), col = "pink", lwd = 2)# (3) Visualizing a simple DEM modelz <- 2 * volcano        # Exaggerate the reliefx <- 10 * (1:nrow(z))   # 10 meter spacing (S to N)y <- 10 * (1:ncol(z))   # 10 meter spacing (E to W)open3d()invisible(bg3d("slategray")) # suppress displaymaterial3d(col = "black")persp3d(x, y, z, col = "green3", aspect = "iso",      axes = FALSE, box = FALSE)# (4) A globelat <- 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 kmx <- r*cos(lat)*cos(long)y <- r*cos(lat)*sin(long)z <- r*sin(lat)open3d()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)## Not run: # This looks much better, but is slow because the texture is very bigpersp3d(x, y, z, col = "white",        texture = system.file("textures/world.png", package = "rgl"),        specular = "black", axes = FALSE, box = FALSE, xlab = "", ylab = "", zlab = "",       normal_x = x, normal_y = y, normal_z = z)## End(Not run)

Plot a Delaunay triangulation

Description

Thedeldir() function in thedeldir package computes a Delaunay triangulation of a setof points. These functions display it as a surface.

Usage

## S3 method for class 'deldir'plot3d(x, ...)## S3 method for class 'deldir'persp3d(x, ..., add = FALSE)## S3 method for class 'deldir'as.mesh3d(x, col = "gray", coords = c("x", "y", "z"),     smooth = TRUE, normals = NULL, texcoords = NULL, ...)

Arguments

Details

These functions construct amesh3d objectcorresponding to the triangulation inx. Theplot3d andpersp3d methods plot it.

Thecoords parameter allows surfaces to be plotted over any coordinate plane. It should bea permutation of the column namesc("x", "y", "z")from the"deldir" object. The first will be usedas the x coordinate, the second as the y coordinate, and the third as the z coordinate.

The... parameters inplot3d.deldir are passed topersp3d.deldir; inpersp3d.deldir they arepassed to bothas.mesh3d.deldir andpersp3d.mesh3d; inas.mesh3d.deldir they are used as material parametersin atmesh3d call.

Examples

x <- rnorm(200, sd = 5)y <- rnorm(200, sd = 5)r <- sqrt(x^2 + y^2)z <- 10 * sin(r)/rcol <- cm.colors(20)[1 + round(19*(z - min(z))/diff(range(z)))]save <- options(rgl.meshColorWarning = FALSE)# This code is awkward:  to work with demo(rglExamples),# we need auto-printing of the plots.  This means we# have to repeat the test for deldir.haveDeldir <- checkDeldir()              if (haveDeldir) {  dxyz <- deldir::deldir(x, y, z = z, suppressMsge = TRUE)  persp3d(dxyz, col = col)}if (haveDeldir) {  open3d()  # Do it without smoothing and with a different orientation.  persp3d(dxyz, col = col, coords = c("z", "x", "y"), smooth = FALSE)}options(save)

Plot a function of two variables

Description

Plot a functionz(x, y) or a parametric function(x(s, t), y(s, t), z(s, t)).

Usage

## S3 method for class ''function''persp3d(x,   xlim = c(0, 1), ylim = c(0, 1),   slim = NULL, tlim = NULL,   n = 101,   xvals = seq.int(min(xlim), max(xlim), length.out = n[1]),   yvals = seq.int(min(ylim), max(ylim), length.out = n[2]),   svals = seq.int(min(slim), max(slim), length.out = n[1]),   tvals = seq.int(min(tlim), max(tlim), length.out = n[2]),   xlab, ylab, zlab,   col = "gray", otherargs = list(),   normal = NULL, texcoords = NULL, ...)## S3 method for class ''function''plot3d(x, ...)

Arguments

Details

The"function" method forplot3d simply passesall arguments topersp3d. Thus this description appliesto both.

The first argumentx is required to be a function. Itis namedx only because of the requirements of the S3system; in the remainder of this help page, we will assumethat the assignmentf <- x has been made, and will refer to the functionf().

persp3d.function evaluatesf() on a two-dimensionalgrid of values, and displays the resulting surface. The valueson the grid will be passed in as vectors in the first two arguments to the function, sof() needsto be vectorized. Other optional arguments tof()can be specified in theotherargs list.

In the default form whereslim andtlim are bothNULL, it is assumed thatf(x, y) returns heights,which will be plotted in the z coordinate. The default axis labelswill be taken from the argument names tof() and theexpression passed as argumentx to this function.

Ifslim ortlim is specified, a parametricsurface is plotted. The functionf(s, t) must return a 3-column matrix, giving x, y and z coordinates of points on the surface. The default axislabels will be the column names if those are present.In this casexlim,ylim andzlimare used to define a clipping region only if specified;the defaults are ignored.

The color of the surface may be specified as the name of acolor, or a vector or matrix of color names. In this casethe colors will be recycled across the points on the gridof values.

Alternatively, a function may be given: it should be a functionlikerainbow that takes an integer argument andreturns a vector of colors. In this case the colors are mappedto z values.

Thenormal argument allows specification of a functionto compute normal vectors to the surface. This function ispassed the same arguments asf() (includingotherargsif present), and should produce a 3-column matrix containing thex, y and z coordinates of the normals.

Thetexcoords argument is a function similar tonormal, butit produces a 2-column matrix containing texture coordinates.

Bothnormal andtexcoords may also contain matrices,with 3 and 2 columns respectively, and rows corresponding to thepoints that were passed tof().

Value

This function constructs a call topersp3dand returns the value from that function.

Author(s)

Duncan Murdoch

See Also

Thecurve function in base graphics doessomething similar for functions of one variable. See theexample below for space curves.

Examples

# (1) The Obligatory Mathematical surface.#     Rotated sinc function, with colorsf <- function(x, y) {   r <- sqrt(x^2 + y^2)  ifelse(r == 0, 10, 10 * sin(r)/r)}open3d()plot3d(f, col = colorRampPalette(c("blue", "white", "red")),        xlab = "X", ylab = "Y", zlab = "Sinc( r )",        xlim = c(-10, 10), ylim = c(-10, 10),       aspect = c(1, 1, 0.5))       # (2) A cylindrical plotf <- function(s, t) {  r <- 1 + exp( -pmin( (s - t)^2,                        (s - t - 1)^2,                        (s - t + 1)^2 )/0.01 )  cbind(r*cos(t*2*pi), r*sin(t*2*pi), s)}open3d()plot3d(f, slim = c(0, 1), tlim = c(0, 1), col = "red", alpha = 0.8)# Add a curve to the plot, fixing s at 0.5.plot3d(f(0.5, seq.int(0, 1, length.out = 100)), type = "l", add = TRUE,        lwd = 3, depth_test = "lequal")

Plot an interp Delaunay triangulation

Description

Thetri.mesh() function in theinterp package computes a Delaunay triangulation of a setof points. These functions display it as a surface.

Usage

## S3 method for class 'triSht'plot3d(x, z, ...)## S3 method for class 'triSht'persp3d(x, z, ..., add = FALSE)## S3 method for class 'triSht'as.mesh3d(x, z, col = "gray", coords = c("x", "y", "z"),     smooth = TRUE, normals = NULL, texcoords = NULL, ...)

Arguments

Details

These functions construct amesh3d objectcorresponding to the triangulation inx. Theplot3d andpersp3d methods plot it.

Thecoords parameter allows surfaces to be plotted over any coordinate plane. It should bea permutation of the column namesc("x", "y", "z").The first will be usedas the x coordinate, the second as the y coordinate, and the third as the z coordinate.

The... parameters inplot3d.triSht andplot3d.tri are passed topersp3d; inpersp3d.triShtandpersp3d.tri they arepassed to bothas.mesh3d andpersp3d.mesh3d; inas.mesh3d.triSht andas.mesh3d.tri they are used as material parametersin atmesh3d call.

"tri" objects may contain constraints. These appearinternally as extra nodes, representing either the insideor outside of boundaries on the region being triangulated.Each of these nodes should also have az value, but triangles corresponding entirely to constraint nodes will notbe drawn. In this way complex, non-convex regions canbe triangulated. See the second example below.

Note

If there are duplicate points, thetri.mesh() functionswill optionally delete some of them. If you choose this option,thez values must correspond to the nodesafterdeletion, not before.

Examples

x <- rnorm(200, sd = 5)y <- rnorm(200, sd = 5)r <- sqrt(x^2 + y^2)z <- 10 * sin(r)/rcol <- cm.colors(20)[1 + round(19*(z - min(z))/diff(range(z)))]save <- NULLif ((haveinterp <- requireNamespace("interp", quietly = TRUE))) {  save <- options(rgl.meshColorWarning = FALSE)  dxy <- interp::tri.mesh(x, y)  open3d()  persp3d(dxy, z, col = col, meshColor = "vertices")}if (haveinterp) {  open3d()  # Do it without smoothing and with a different orientation.  persp3d(dxy, z, col = col, coords = c("z", "x", "y"), smooth = FALSE)}options(save)

Add planes

Description

planes3d adds mathematical planes to a scene. Their intersection with the currentbounding box will be drawn.clipplanes3d adds clipping planes to a scene.

Usage

planes3d(a, b = NULL, c = NULL, d = 0, ...)clipplanes3d(a, b = NULL, c = NULL, d = 0)

Arguments

Details

planes3d draws planes using the parametrizationa x + b y + c z + d = 0. Multiple planes may be specifiedby giving multiple values for any ofa, b, c, d; the other values will be recycled as necessary.

clipplanes3d defines clipping planesusing the same equations. Clipping planes suppress the display ofother objects (or parts of them) in the subscene, based on their coordinates.Points (or parts of lines or surfaces) where the coordinatesx, y, zsatisfya x + b y + c z + d < 0 will be suppressed.

The number of clipping planessupported by the OpenGL driver is implementation dependent; usepar3d("maxClipPlanes") to find the limit.

Value

A shape ID of the planes or clipplanes object is returned invisibly.

See Also

abclines3d for mathematical lines.

triangles3d or the correspondingfunctions for quadrilaterals may be used to draw sections of planes thatdo not adapt to the bounding box.

The example insubscene3d shows how to combine clipping planesto suppress complex shapes.

Examples

# Show regression plane with z as dependent variableopen3d()x <- rnorm(100)y <- rnorm(100)z <- 0.2*x - 0.3*y + rnorm(100, sd = 0.3)fit <- lm(z ~ x + y)plot3d(x, y, z, type = "s", col = "red", size = 1)coefs <- coef(fit)a <- coefs["x"]b <- coefs["y"]c <- -1d <- coefs["(Intercept)"]planes3d(a, b, c, d, alpha = 0.5)open3d()ids <- plot3d(x, y, z, type = "s", col = "red", size = 1, forceClipregion = TRUE) oldid <- useSubscene3d(ids["clipregion"])clipplanes3d(a, b, c, d)useSubscene3d(oldid)

Play animation of RGL scene

Description

play3d calls a function repeatedly, passing it the elapsedtime in seconds, and using the result of the function toreset the viewpoint.movie3d does the same, butrecords each frame to a file to make a movie.

Usage

play3d(f, duration = Inf, dev = cur3d(), ..., startTime = 0)movie3d(f, duration, dev = cur3d(), ..., fps = 10,                     movie = "movie", frames = movie, dir = tempdir(),                     convert = NULL, clean = TRUE, verbose = TRUE,                    top = !rgl.useNULL(), type = "gif", startTime = 0,                    webshot = TRUE)

Arguments

Details

The functionf will be called in a loop with the first argumentbeing thestartTime plus the time in seconds since the start (where the start is measured after all arguments have been evaluated).

play3d is likely to place a high loadon the CPU; if this is a problem, calls toSys.sleepshould be made within the function to release time to other processes.

play3d will run for the specifiedduration (in seconds), butcan be interrupted by pressingESC while the RGL window has the focus.

movie3d saves each frame to disk in a filename of the form ‘framesXXX.png’, whereXXX is the frame number, starting from 0. Ifconvert isNULL (the default) and themagick package is installed, it will be usedto convert the frames to a GIF movie (or other format if supported). Ifmagick is not installed orconvert isTRUE,movie3d will attemptto use the externalImageMagick program to convert theframes to a movie. The newermagick executable is triedfirst, thenconvert if that fails.Thetype argument will be passed toImageMagick to use as a file extensionto choose the file type.

Finally,convert can be a template for a command toexecute in the standard shell (wildcards are allowed). The template isconverted to a command using
sprintf(convert, fps, frames, movie, type, duration, dir)
For example,convert = TRUEuses the template"magick -delay 1x%d %s*.png %s.%s". All workis done in the directorydir, so paths should not be needed inthe command. (Note thatsprintf does not require allarguments to be used, and supports formats that use them in anarbitrary order.)

Thetop = TRUE default is designed to work around an OpenGL limitation:in some implementations,rgl.snapshot will fail if the windowis not topmost.

As ofrgl version 0.94, thedev argument is not needed: thefunctionf can specify its device, asspin3d does, for example. However, ifdev is specified, it will be selectedas the current device as each update is played.

As ofrgl version 0.95.1476,f can include multiple values in a"subscene"component, andpar3d() will be calledfor each of them.

Value

play3d is called for the side effect of its repeated calls tof.It returnsNULL invisibly.

movie3d is also normally called for the side effectof producing the output movie. It invisibly returns

Author(s)

Duncan Murdoch, based on code by Michael Friendly

See Also

spin3d andpar3dinterp return functions suitable to use asf. Seedemo(flag) for an example that modifies thescene inf.

Examples

open3d()plot3d( cube3d(col = "green") )M <- par3d("userMatrix")if (!rgl.useNULL() && interactive())  play3d( par3dinterp(times = (0:2)*0.5, userMatrix = list(M,                                     rotate3d(M, pi/2, 1, 0, 0),                                     rotate3d(M, pi/2, 0, 1, 0) ) ),         duration = 2 )## Not run: movie3d( spin3d(), duration = 5 )## End(Not run)

Add a widget to play animations

Description

This is a widget that can be put in a web page to allowanimations with or without Shiny.

Usage

playwidget(sceneId, controls,            start = 0, stop = Inf, interval = 0.05, rate = 1,            components = c("Reverse", "Play", "Slower", "Faster",                           "Reset", "Slider", "Label"),            loop = TRUE,            step = 1, labels = NULL,            precision = 3,            elementId = NULL, respondTo = NULL,            reinit = NULL,            buttonLabels = components, pause = "Pause",            height = 40,            ...)

Arguments

Details

Thecomponents are buttons to control the animation,a slider for manual control, and a label to show the currentvalue. They will be displayed in the order given incomponents. Not all need be included.

The buttons have the following behaviour:

Reverse

Reverse the direction.

Play

Play the animation.

Slower

Decrease the playing speed.

Faster

Increase the playing speed.

Reset

Stop the animation and reset to the start value.

IfrespondTo is used, nocomponents are shown, as it is assumed Shiny (or whatever control is being referenced) will provide the UI components.

ThesceneId component can be anotherplaywidget, arglwidget result, or a result ofhtmltools::tags orhtmltools::tagList. This allows youto use amagrittr-style“pipe” command to join anrglwidget with one or moreplaywidgets. If aplaywidget comesfirst,sceneId should be set toNA. Iftherglwidget does not come first,previous values should be piped into itscontrollersargument. Other HTML code (including other widgets)can be used in the chain if wrapped inhtmltools::tagList.

Each control should inherit from"rglControl". Theycan have the following components in addition to any private ones:

labels

default labels for the slider.

param

values to include on the slider.

dependencies

additional HTML dependencies toinclude, after the defaultrglwidgetClass.

Value

A widget suitable for use in anRmarkdown-generated webpage, or elsewhere.

Appearance

The appearance of the controls is set by the stylesheetinsystem.file("htmlwidgets/lib/rglClass/rgl.css").

The overall widget is of classrglPlayer, with idset according toelementId.

The buttons are of HTML classrgl-button, theslider is of classrgl-slider, and the label is ofclassrgl-label. Each element has an id prefixedby the widget id, e.g.elementId-button-Reverse,elementId-slider, etc. (whereelementIdshould be replaced by the actual id).

Thereinit parameter handles the case wherean object needs re-initialization after each change. Forexample, plane objects may need this if their intersectionwith the bounding box changes shape. Note thatre-initialization is generally incompatible withthevertexControl as it modifies valueswhich are set during initialization.

Author(s)

Duncan Murdoch

See Also

subsetControl,propertyControl,ageControl andvertexControl are possible controls to use.

toggleWidget is a wrapper forplaywidget andsubsetControlto insert a single button to toggle some elements in a display.

Examples

saveopts <- options(rgl.useNULL = TRUE)objid <- plot3d(1:10, 1:10, rnorm(10), col=c("red", "red"), type = "s")["data"]control <- ageControl(value=0,             births=1:10,             ages = c(-5,0,5),             colors = c("green", "yellow", "red"),             objids = objid)# This example uses explicit namesrglwidget(elementId = "theplot", controllers = "theplayer",          height = 300, width = 300)playwidget("theplot", control, start = -5, stop = 5,           rate = 3, elementId = "theplayer",           components = c("Play", "Slider"))# This example uses pipes, and can skip the nameswidget <- rglwidget(height = 300, width = 300) %>%playwidget(control, start = -5, stop = 5,           rate = 3, components = c("Play", "Slider"))if (interactive() || in_pkgdown_example())  widgetoptions(saveopts)

3D scatterplot

Description

Draws a 3D scatterplot.

Usage

plot3d(x, ...)## Default S3 method:plot3d(x, y, z,  xlab, ylab, zlab, type = "p", col, size, lwd, radius,add = FALSE, aspect = !add, xlim = NULL, ylim = NULL, zlim = NULL, forceClipregion = FALSE, decorate = !add, ...)## S3 method for class 'mesh3d'plot3d(x, xlab = "x", ylab = "y", zlab = "z", type = c("shade", "wire", "dots"),add = FALSE, aspect = !add, ...)

Arguments

Details

plot3d is a partial 3D analogue of plot.default.

Missing values in the data are skipped, as in standard graphics.

Ifaspect isTRUE, aspect ratios ofc(1, 1, 1) are passed toaspect3d. IfFALSE, no aspect adjustment is done. In othercases, the value is passed toaspect3d.

Withtype = "s", spheres are drawn centered at the specified locations.The radius may be controlled bysize (specifying the size relativeto the plot display, with the defaultsize = 3 giving a radius about 1/20 of the plot region) orradius (specifying it on the data scaleif an isometric aspect ratio is chosen, or on an average scaleif not).

Value

plot3d is called for the side effect of drawing the plot; a vectorof object IDs is returned.

Clipping

If any ofxlim,ylim orzlim are specified,they should be length two vectors giving lower and upper clipping limits for the corresponding coordinate.NAlimits will be ignored.

If any clipping limits are given, then the data will beplotted in a newly created subscene within the current one;otherwise plotting will take place directly in the currentsubscene. This subscene is named"clipregion"in the results. This may affect the appearance of transparentobjects if some are drawn in theplot3d call and others after, as RGL will not attempt to depth-sort objects if they arein different subscenes. It is best to draw all overlapping transparent objects in the same subscene. See the example inplanes3d. It will also affect the useofclipplanes3d; clipping planes need to be in the same subscene as the objects being clipped.

UseforceClipregion = TRUE to force creation of this subscene even without specifying limits.

Author(s)

Duncan Murdoch

See Also

plot.default,open3d,par3d.There areplot3d.function andplot3d.deldir methods for plotting surfaces.

Examples

  open3d()  x <- sort(rnorm(1000))  y <- rnorm(1000)  z <- rnorm(1000) + atan2(x, y)  plot3d(x, y, z, col = rainbow(1000))

Methods for formulas

Description

These functions provide a simple formula-based interfacetoplot3d andpersp3d.

Usage

## S3 method for class 'formula'plot3d(x, data = NULL, xlab, ylab, zlab, ...)## S3 method for class 'formula'persp3d(x, data = NULL, xlab, ylab, zlab, ...)

Arguments

Details

Only simple formulas (the ones handled by thexyz.coords function) are supported: a single variable on the left hand side (which will be plotted on the Z axis),and a sum of two variables on the right hand side (whichwill be the X and Y axis variables in the plot.)

Value

These functions are called for the side effect of drawingthe plots. Theplot3d method draws a scatterplot. Thepersp3d method draws a surface plot.

Return values are as given by theplot3d.default method or thepersp3d.deldir methods.

Note

Thepersp3d method requires that the suggested packagedeldir is installed.

Author(s)

Duncan Murdoch

Examples

open3d()mfrow3d(1, 2, sharedMouse = TRUE)plot3d(mpg ~ wt + qsec, data = mtcars)if (checkDeldir())  persp3d(mpg ~ wt + qsec, data = mtcars)

Method for plotting simple linear fit

Description

This function provides several plots of the result offitting a two-predictor model.

Usage

## S3 method for class 'lm'plot3d(x,        which = 1,        plane.col = "gray", plane.alpha = 0.5,       sharedMouse = TRUE,        use_surface3d,        do_grid = TRUE,       grid.col = "black",        grid.alpha = 1,       grid.steps = 5,       sub.steps = 4,       vars = get_all_vars(terms(x), x$model),       clip_to_density = 0,       ...)

Arguments

Details

Three plots are possible, depending on the value(s) inwhich:

1. (default) Show the points and the fitted plane or surface.

2. Show the residuals and the plane atz = 0.

3. Show the predicted values on the fitted plane or surface.

Ifclip_to_density is positive, then thesurface, plane or grid will be clipped to the region where a non-parametric density estimate(usingMASS::kde2d), normalized to have amaximum value of 1, is greater than the given value.This will suppress parts of the plot that aren't supported by the observed data.

Value

Called for the side effect of drawing one or more plots.

Invisibly returns a high-level vector of object ids. Names ofobject ids have the plot number (in drawing order) appended.

Note

The default value for thevars argument will handlesimple linear models with a response and two predictors, andsome models with functions of those two predictors. For models that fail (e.g. models usingpoly), youcan include the observed values as in the third example below.

Ifclip_to_density > 0,

1. The clipping isapproximate, so it may not agree perfectly betweensurfaces, planes and grids.

2. This option requires the suggested packagesMASS andinterp, and will be ignored witha warning if either is not installed.

Author(s)

Duncan Murdoch

Examples

open3d()ids <- plot3d(lm(mpg ~ wt + qsec, data = mtcars), which = 1:3)names(ids)open3d()plot3d(lm(mpg ~ wt + I(wt^2) + qsec, data = mtcars))open3d()# Specify vars in the order:  response, pred1, pred2.plot3d(lm(mpg ~ poly(wt, 3) + qsec, data = mtcars),        vars = mtcars[,c("mpg", "wt", "qsec")])       open3d()# Clip parts of the plot with few (wt, qsec) pointsplot3d(lm(mpg ~ poly(wt, 3) + qsec, data = mtcars),        vars = mtcars[,c("mpg", "wt", "qsec")],       clip_to_density = 0.1)

Draw text using base graphics math plotting or LaTeX

Description

To plot mathematical text,plotmath3d uses base graphicsfunctions to plot it to a ‘.png’ file, then uses thatfile as a texture in a sprite.latex3d uses thexdvir package to render LaTeX code, then usesthe same approach to display it inrgl.

Usage

plotmath3d(x, y = NULL, z = NULL, text, cex = par3d("cex"),           adj = 0.5, pos = NULL, offset = 0.5,           fixedSize = TRUE, startsize = 480, initCex = 5,            margin = "", floating = FALSE, tag = "",           polygon_offset = material3d("polygon_offset"), ...)latex3d(x, y = NULL, z = NULL, text, cex = par3d("cex"),            adj = 0.5, pos = NULL, offset = 0.5,           fixedSize = TRUE, startsize = 480, initCex = 5,            margin = "", floating = FALSE, tag = "",           polygon_offset = material3d("polygon_offset"),            verbose = FALSE, ...)

Arguments

Value

Called for the side effect of displaying the sprites.The shape ID of the displayed object is returned.

Note

Thetext3d function passes calls toplotmath3d if itsusePlotmath argument isTRUE.This is the default value if itstexts argument looks like an expression.

Thelatex3d function produces nicer looking resultsthanplotmath3d, but it is much slower, especially on the first run.

Author(s)

Duncan Murdoch

See Also

text3d

Examples

open3d()plotmath3d(1:3, 1:3, 1:3, expression(x[1] == 1, x[2] == 2, x[3] == 3))# This lets the text resize with the plottext3d(4, 4, 4, "resizeable text", usePlotmath = TRUE, fixedSize = FALSE)if (requireNamespace("xdvir")) {# Do the same plot using latex3d(). This example runs slowly!    open3d()  latex3d(1:3, 1:3, 1:3, c("$x_1 = 1$", "$x_2 = 2$", "$x_3 = 3$"))  latex3d(4, 4, 4, "resizeable text", fixedSize = FALSE)}

Draw a polygon in three dimensions

Description

This function takes a description of a flat polygon in x, y and z coordinates,and draws it in three dimensions.

Usage

polygon3d(x, y = NULL, z = NULL, fill = TRUE, plot = TRUE,           coords, random = TRUE, ...)

Arguments

Details

The function triangulates the two dimensional polygon described bycoords, thenapplies the triangulation to all three coordinates. No check is made that the polygonis actually all in one plane, but the results may be somewhat unpredictable(especially ifrandom = TRUE) if it is not.

Polygons need not be simple; useNA to indicate separate closed pieces. Forfill = FALSE there are no other restrictions on the pieces, but forfill = TRUE the resulting two-dimensional polygon needs to be one thattriangulate can handle.

Value

Ifplot = TRUE, the id number of the lines (forfill = FALSE) or triangles(forfill = TRUE) that have been plotted.

Ifplot = FALSE, then forfill = FALSE, a vector of indices intothe XYZ matrix that could be used to draw the polygon. Forfill = TRUE, a triangular mesh object representing the triangulation.

Author(s)

Duncan Murdoch

See Also

extrude3d for a solid extrusion of a polygon,triangulate forthe triangulation.

Examples

theta <- seq(0, 4*pi, length.out = 50)r <- theta + 1r <- c(r[-50], rev(theta*0.8) + 1)theta <- c(theta[-50], rev(theta))x <- r*cos(theta)y <- r*sin(theta)open3d()plot(x, y, type = "n")polygon(x, y)polygon3d(x, y, x + y, col = "blue")

Add primitive shape

Description

Adds a shape node to the current scene.

Usage

points3d(x, y = NULL, z = NULL,  ...)lines3d(x, y = NULL, z = NULL,  ...)segments3d(x, y = NULL, z = NULL, ...)triangles3d(x, y = NULL, z = NULL, ...)quads3d(x, y = NULL, z = NULL, ...)

Arguments

Details

The functionspoints3d,lines3d,segments3d,triangles3d andquads3d add points, joined lines, line segments,filled triangles or quadrilaterals to the plots. They correspond to the OpenGL typesGL_POINTS, GL_LINE_STRIP, GL_LINES, GL_TRIANGLES andGL_QUADS respectively.

Points are taken in pairs bysegments3d, triplets as the verticesof the triangles, and quadruplets for the quadrilaterals. Colors are applied vertex by vertex; if different at each end of a line segment, or each vertex of a polygon, the colorsare blended over the extent of the object. Polygonsmust be non-degenerate and quadrilaterals must be entirely in one plane and convex, or the results are undefined.

The appearance of the new objects are defined by the material properties.Seematerial3d for details.

For triangles and quads, the normals at each vertex may be specifiedusingnormals. These may be given in any way that would beacceptable as a single argument toxyz.coords. These need not match the actual normals to the polygon:curved surfaces can be simulated by using other choices of normals.

Texture coordinates may also be specified. These may be given inany way that would be acceptable as a single argument toxy.coords, and are interpreted in termsof the bitmap specified as the material texture, with(0, 0) at the lower left,(1, 1) at the upper right. The textureis used to modulate the color of the polygon.

All of these functions support an argument calledindices, which allows vertices (and other attributes)to be re-used, as they are in objects created bymesh3d and related functions. This isintended to be used on smooth surfaces, where each sharedvertex has just one value for normals, colors and texturecoordinates.

For shapes with flat-looking faces (e.g. polyhedra likecube3d),the verticesmust be duplicatedto be rendered properly.

Value

Each function returns the integer object ID of the shape thatwas added to the scene. These can be passed topop3dto remove the object from the scene.

Author(s)

Ming Chen and Duncan Murdoch

Examples

# Show 12 random vertices in various ways. M <- matrix(rnorm(36), 3, 12, dimnames = list(c('x', 'y', 'z'),                                        rep(LETTERS[1:4], 3)))# Force 4-tuples to be convex in planes so that quads3d works.for (i in c(1, 5, 9)) {    quad <- as.data.frame(M[, i + 0:3])    coeffs <- runif(2, 0, 3)    if (mean(coeffs) < 1) coeffs <- coeffs + 1 - mean(coeffs)    quad$C <- with(quad, coeffs[1]*(B - A) + coeffs[2]*(D - A) + A)    M[, i + 0:3] <- as.matrix(quad)}open3d()# Rows of M are x, y, z coords; transpose to plotM <- t(M)shift <- matrix(c(-3, 3, 0), 12, 3, byrow = TRUE)points3d(M)lines3d(M + shift)segments3d(M + 2*shift)triangles3d(M + 3*shift, col = 'red')quads3d(M + 4*shift, col = 'green')  text3d(M + 5*shift, texts = 1:12)# Add labelsshift <- outer(0:5, shift[1, ])shift[, 1] <- shift[, 1] + 3text3d(shift,        texts = c('points3d', 'lines3d', 'segments3d',         'triangles3d', 'quads3d', 'text3d'),       adj = 0) rgl.bringtotop()

Controls to use with playwidget()

Description

These are setter functions to produce actions in a Shiny app,or in an animation.

Usage

subsetControl(value = 1, subsets, subscenes = NULL,                         fullset = Reduce(union, subsets),                         accumulate = FALSE)propertyControl(value = 0, entries, properties,                 objids = tagged3d(tags), tags, values = NULL,                param = seq_len(NROW(values)) - 1, interp = TRUE)

Arguments

Details

subsetControl produces data forplaywidget todisplay subsets of the object in one or more subscenes. This code will nottouch objects in thesubscenes if theyare not infullset.fullset defaults to the union ofall the object ids mentioned insubsets, so by default if an id isnot mentioned in one of the subsets, it will not be controlled by the slider. Ifvalue is specified in R code, it will be a 1-basedindex into thesubsets list; when specified internallyin Javascript, 0-based indexing into the corresponding arraywill be used.

propertyControl sets individual properties. Here the rowofvalues is determined by the position ofvalueinparam.

Value

These functions return controller data in a list of class"rglControl".

Author(s)

Duncan Murdoch

See Also

subsetSetter for a way to embed a pure Javascriptcontrol, andplaywidget for a way to use thesein animations (including Shiny),rglSharedfor linking using thecrosstalk package. TheUser Interaction in WebGL vignettegives more details.

Generic 3D interface

Description

Generic 3D interface for 3D rendering and computational geometry.

Details

R3d is a design for an interface for 3d rendering and computation without dependencyon a specific rendering implementation. R3d includes a collectionof 3D objects and geometry algorithms.All r3d interface functions are named*3d. They represent generic functions that delegate to implementation functions.

The interface can be grouped into 8 categories: Scene Management, Primitive Shapes,High-level Shapes, Geometry Objects, Visualization, Interaction, Transformation,Subdivision.

The rendering interface gives an abstraction to the underlying rendering model. It canbe grouped into four categories:

Scene Management:

A 3D scene consists of shapes, lights and background environment.

Primitive Shapes:

Generic primitive 3D graphics shapes such as points, lines, triangles, quadrangles and texts.

High-level Shapes:

Generic high-level 3D graphics shapes such as spheres, sprites and terrain.

Interaction:

Generic interface to select points in 3D space using the pointer device.

In this package we include an implementation of r3d using the underlyingrgl.* functions.

3D computation is supported through the use of object structures that live entirely in R.

Geometry Objects:

Geometry and mesh objects allow to define high-level geometry for computational purpose such as triangle or quadrangle meshes (seemesh3d).

Transformation:

Generic interface to transform 3d objects.

Visualization:

Generic rendering of 3d objects such as dotted, wired or shaded.

Computation:

Generic subdivision of 3d objects.

At present, the main practical differences between the r3d functionsand thergl.* functions are as follows.

The r3d functions callopen3d if there is no device open, and thergl.* functions callrgl.open. By defaultopen3d sets the initial orientation of the coordinatesystem in 'world coordinates', i.e. a right-handed coordinate systemin which the x-axis increases from left to right, the y-axisincreases with depth into the scene, and the z-axis increases frombottom to top of the screen.rgl.* functions, on the otherhand, use a right-handed coordinate system similar to that used inOpenGL. The x-axis matches that of r3d, but the y-axis increasesfrom bottom to top, and the z-axis decreases with depth into thescene. Since the user can manipulate the scene, either system canbe rotated into the other one.

The r3d functions also preserve thergl.material setting acrosscalls (except for texture elements, in the current implementation), whereasthe deprecatedrgl.* functions leave it as set by the last call.

The example code below illustrates the two coordinate systems.

See Also

points3d,lines3d,segments3d,triangles3d,quads3d,text3d,spheres3d,sprites3d,terrain3d,select3d,dot3d,wire3d,shade3d,transform3d,rotate3d,subdivision3d,mesh3d,cube3d,rgl

Examples

         x <- c(0, 1, 0, 0)     y <- c(0, 0, 1, 0)     z <- c(0, 0, 0, 1)     labels <- c("Origin", "X", "Y", "Z")     i <- c(1, 2, 1, 3, 1, 4)     # *3d interface          open3d()     text3d(x, y, z, labels)     text3d(1, 1, 1, "*3d coordinates")     segments3d(x[i], y[i], z[i])

Read and write STL (stereolithography) format files

Description

These functions read and write STL files. This is a simple file format thatis commonly used in 3D printing. It does not represent text,only triangles. ThewriteSTL function converts some RGL objecttypes to triangles.

Usage

readSTL(con, ascii = NA, plot = TRUE, ...)writeSTL(con, ascii = FALSE,          pointRadius = 0.005,          pointShape = icosahedron3d(),         lineRadius = pointRadius,         lineSides = 20,         ids = tagged3d(tags),         tags = NULL)

Arguments

Details

The current implementation is limited. For reading, it ignores normalsand color information. For writing, it only outputs triangles, quads, planes, spheres,points, line segments, line strips and surfaces, and does not write color information.Lines and points are rendered in an isometric scale: if your data scales vary, theywill look strange.

Since the STL format only allows one object per file, all RGL objectsare combined into a single object when output.

The output file is readable by Blender and Meshlab; the latter can write ina number of other formats, including U3D, suitable for import into a PDF document.

Value

readSTL invisibly returns the object id ifplot = TRUE, or (visibly) a matrix of vertices of the triangles if not.

writeSTL invisibly returns the name of the connection to which the data was written.

Author(s)

Duncan Murdoch

References

The file format was found on Wikipedia on October 25, 2012. I learnedabout the STL file format from David Smith's blog reporting on Ian Walker'sr2stl function.

See Also

scene3d saves a copy of a scene to an R variable;rglwidget,writeASY,writePLY,writeOBJ andwriteSTLwrite the scene to a file in various other formats.

Examples

filename <- tempfile(fileext = ".stl")open3d()shade3d( icosahedron3d(col = "magenta") )writeSTL(filename)open3d()readSTL(filename, col = "red")

Defunct functions inrgl

Description

These functions have been removed fromrgl.

Usage

# Removed in version 1.0.0:subsetSlider(subsets, labels = names(subsets),              fullset = Reduce(union, subsets),             subscenes = currentSubscene3d(), prefixes = "",             accumulate = FALSE, ...)             subsetSetter(subsets, subscenes = currentSubscene3d(), prefixes = "",  fullset = Reduce(union, subsets),                         accumulate = FALSE)             clipplaneSlider(a=NULL, b=NULL, c=NULL, d=NULL,                 plane = 1, clipplaneids, prefixes = "",                 labels = signif(values[,1],3), ...)             toggleButton(subset, subscenes = currentSubscene3d(), prefixes = "",              label = deparse(substitute(subset)),              id = paste0(basename(tempfile("input"))), name = id) propertySlider(setter = propertySetter,             minS = NULL, maxS = NULL, step = 1, init = NULL,      labels,      id = basename(tempfile("input")), name = id,     outputid = paste0(id, "text"),     index = NULL,     ...)      propertySetter(values = NULL, entries, properties, objids, prefixes = "",               param = seq_len(NROW(values)), interp = TRUE, digits = 7)                par3dinterpSetter(fn, from, to, steps, subscene, omitConstant = TRUE,                   rename = character(), ...)matrixSetter(fns, from, to, steps, subscene = currentSubscene3d(),              matrix = "userMatrix", omitConstant = TRUE, prefix = "", ...)              vertexSetter(values, vertices = 1, attributes, objid, prefix = "",     param = seq_len(NROW(values)), interp = TRUE,     digits = 7)

See Also

Defunct

Deprecated functions inrgl

Description

These functions are provided for compatibility with older versions ofrgl only, and may be defunct as soon as the next release. See the comments for the replacements.

Usage

rgl.bbox(xat = NULL, xlab = NULL, xunit = 0, xlen = 5,          yat = NULL, ylab = NULL, yunit = 0, ylen = 5,          zat = NULL, zlab = NULL, zunit = 0, zlen = 5,          marklen = 15, marklen.rel = TRUE,          expand = 1, draw_front = FALSE, ...)  # bbox3drgl.bg( sphere = FALSE, fogtype = "none", color = c("black", "white"), back = "lines", fogScale = 1, ...)           # bg3drgl.clear( type = "shapes", subscene = 0 )     # clear3drgl.close()                                    # close3drgl.light( theta = 0, phi = 0, viewpoint.rel = TRUE,            ambient = "#FFFFFF", diffuse = "#FFFFFF", specular = "#FFFFFF",            x = NULL, y = NULL, z = NULL)       # light3drgl.lines(x, y = NULL, z = NULL, ... )         # segments3drgl.linestrips(x, y = NULL, z = NULL, ...)     # lines3drgl.open(useNULL = rgl.useNULL())              # open3drgl.points(x, y = NULL, z = NULL, ... )        # points3drgl.primitive(...)                             rgl.quads(x, y = NULL, z = NULL,           normals = NULL,           texcoords = NULL, ... )              # quads3drgl.select3d(button = c("left", "middle", "right"),            dev = cur3d(),             subscene = currentSubscene3d(dev)) # select3drgl.set(which, silent = FALSE)                 # set3drgl.setAxisCallback(axis, draw = NULL,             dev = cur3d(),             subscene = currentSubscene3d(dev)) # setAxisCallbackrgl.surface(x, z, y, coords = 1:3, ...,             normal_x = NULL, normal_y = NULL, normal_z = NULL,            texture_s = NULL, texture_t = NULL) # surface3drgl.texts(x, y = NULL, z = NULL, text,           adj = 0.5, pos = NULL, offset = 0.5,           family = par3d("family"),           font = par3d("font"),           cex = par3d("cex"),           useFreeType = par3d("useFreeType"),           ...)                                  # text3drgl.triangles(x, y = NULL, z = NULL,               normals = NULL, texcoords = NULL,               ... )                             # triangles3drgl.viewpoint( theta = 0, phi = 15,                fov = 60, zoom = 1,                scale = par3d("scale"),                interactive = TRUE,                userMatrix,                type = c("userviewpoint",                        "modelviewpoint") )     # view3dwriteWebGL(dir = "webGL",            filename = file.path(dir, "index.html"),            template = system.file(file.path("WebGL", "template.html"), package = "rgl"),           prefix = "",           snapshot = TRUE,            commonParts = TRUE,            reuse = NULL,            font = "Arial",            width, height)                       # rglwidget

See Also

Deprecated,bbox3d,bg3d,clear3d,close3d,light3d,lines3d,open3d,points3d,quads3d,rglwidget,segments3d,select3d,set3d,surface3d,text3d,triangles3d,view3d

Duplicated functions inrgl

Description

These functions are provided for compatibility with older versions ofrgl. See the functions in the comments for the full documentation.

Usage

rgl.cur()                             # cur3d      rgl.ids(type = "shapes",         subscene = NA, tags = FALSE)  # ids3d rgl.pop(type = "shapes",         id = 0, tag = NULL)           # pop3dterrain3d(x, y = NULL, z = NULL, ...,          normal_x = NULL, normal_y = NULL, normal_z = NULL,          texture_s = NULL, texture_t=NULL,          flip = FALSE)               # surface3d

See Also

cur3d,ids3d,pop3d,surface3d

Internal RGL functions and data

Description

Internal RGL functions

Usage

rgl.bool(x)rgl.numeric(x)rgl.vertex(x, y = NULL, z = NULL)rgl.nvertex(vertex)rgl.color(color)rgl.mcolor(colors)rgl.clamp(value, low, high)rgl.attr(vattr, nvertex) rgl.enum(name, ..., multi = FALSE)rgl.enum.gl2ps(postscripttype) rgl.enum.nodetype(type)rgl.enum.pixfmt(fmt)rgl.enum.polymode(mode)rgl.enum.textype(textype)rgl.enum.fogtype(fogtype)rgl.enum.primtype(primtype)rgl.enum.texmagfilter(magfiltertype)rgl.enum.texminfilter(minfiltertype)rgl.selectstate(dev, subscene)rgl.setselectstate(state, dev, subscene)edgemap(size)edgeindex(from, to, size, row, col)

Details

These are not to be called by the user.

Integrating RGL with Sweave

Description

As ofR 2.13.0, it is possible to include RGL graphics intoaSweave document. These functions support thatintegration.

Usage

Sweave.snapshot()rgl.Sweave(name, width, height, options, ...)rgl.Sweave.off()

Arguments

Details

Thergl.Sweave function is not normally called by the user. The userspecifies it as the graphics driver when opening the code chunk, e.g. byusing

<<fig = TRUE, pdf = FALSE, grdevice = rgl.Sweave, resolution = 100>>=

When the RGL device is closed at the end of the code chunk,rgl.Sweave.off() will be called automatically. Itwill save a snapshotof the last image (by default in ‘.png’ format) for inclusion in the Sweave document and (by default) close the device. Alternatively, theSweave.snapshot() functioncan be called to save the image before the end of the chunk. Only onesnapshot will be taken per chunk.

Several chunk options are used by thergl.Sweave device:

stayopen

(defaultFALSE). IfTRUE then the RGLdevice willnot be closed at the end of the chunk,instead a call toSweave.snapshot()will be used if it has not been called explicitly. Subsequent chunks can addto the scene.

outputtype

(defaultpng). The output may be specified asoutputtype = pdf oroutputtype = eps instead, in which casethergl.postscript function will be used to write output in thespecified format. Note thatrgl.postscript has limitationsand does not always render scenes correctly.

delay

(default 0.1). After creating the display window,Sys.sleepwill be called to delay this many seconds, to allow the display system to initialize. This is needed in X11 systems which open the displayasynchronously. If the default time is too short,rgl.Sweave mayfalsely report that the window is too large to open.

Value

These functions are called for their side effects.

Note

We recommend turning off all other graphics drivers in a chunk that usesgrdevice = rgl.Sweave. The RGL functions do not write toa standard graphics device.

Note

Thergl package relies on your graphics hardware to render OpenGL scenes,and the default ‘.png’ output copies a bitmap from the hardware device. All such devices have limitations on the size of the bitmap, but they do not always signal these limitations in a way that RGL will detect. If you findthat images are not being produced properly, try reducing the size using theresolution,width orheight chunk options.

Author(s)

Duncan Murdoch

See Also

RweaveLatex for a description of alternate graphics driversin Sweave, and standard options that can be used in code chunks.

hook_rglandhook_webgl allow fixed or interactive RGLscenes to be embedded inknitr documents.

Get information about shapes

Description

Retrieves information about the shapes in a scene.

Usage

rgl.attrib(id, attrib, first = 1, last = rgl.attrib.count(id, attrib))

Arguments

Details

If the identifier is not found or is not a shape that has the given attribute, zero will be returned byrgl.attrib.count, and an empty matrixwill be returned byrgl.attrib.

The first fourattrib names correspond to the usual OpenGLproperties;"dim" is used just for surfaces, defining the rowsand columns in the rectangular grid;"cex","adj","family","font" and"pos" apply only to text objects.

Value

rgl.attribreturns the values of the attribute. Attributesare mostly real-valued, with the following sizes:

The"texts","types" and"family"attributes are character-valued; the"flags"attribute is logical valued, with named rows.

These are returned as matrices with the row count equal to the count for the attribute,and the columns as listed above.

Author(s)

Duncan Murdoch

See Also

ids3d,rgl.attrib.info

Examples

p <- plot3d(rnorm(100), rnorm(100), rnorm(100), type = "s", col = "red")rgl.attrib(p["data"], "vertices", last = 10)

Get information about attributes of objects

Description

These functions give information about the attributes ofRGL objects.rgl.attrib.info is the more “user-friendly” function;rgl.attrib.count is a lower-level function more likely to be used in programming.

Usage

rgl.attrib.info(id = ids3d("all", 0)$id, attribs = NULL, showAll = FALSE)rgl.attrib.count(id, attrib)

Arguments

Details

See the first example below to get the full list of attributenames.

Value

A dataframe containing the following columns:

Author(s)

Duncan Murdoch

See Also

rgl.attrib to obtain the attribute values.

Examples

open3d()id <- points3d(rnorm(100), rnorm(100), rnorm(100), col = "green")rgl.attrib.info(id, showAll = TRUE)rgl.attrib.count(id, "vertices")merge(rgl.attrib.info(), ids3d("all"))

Assign focus to an RGL window

Description

'rgl.bringtotop' brings the current RGL window to thefront of the window stack (and gives it focus).

Usage

rgl.bringtotop(stay = FALSE)

Arguments

Details

Ifstay isTRUE, then the window will stay on topof normal windows.

Note

not completely implemented for X11 graphics (stay not implemented;window managers such as KDE may block this action(set "Focus stealing prevention level" to None in Control Center/Window Behavior/Advanced)).Not currently implemented under OS/X.

Author(s)

Ming Chen/Duncan Murdoch

Examples

open3d()points3d(rnorm(1000), rnorm(1000), rnorm(1000), color = heat.colors(1000))rgl.bringtotop(stay = TRUE)

Low level functions that should not be called by users.

Description

These functions provide the implementation for various*3d functions designed for users to call.

Usage

rgl.abclines(x, y = NULL, z = NULL, a, b = NULL, c = NULL, ...)rgl.planes(a, b = NULL, c = NULL, d = 0, ...)rgl.clipplanes(a, b = NULL, c = NULL, d = 0)rgl.sprites(x, y = NULL, z = NULL, radius = 1,             shapes = NULL, userMatrix, fixedSize = FALSE,            adj = 0.5, pos = NULL, offset = 0.25,             rotating = FALSE, ...)rgl.spheres(x, y = NULL, z = NULL, radius, fastTransparency = TRUE, ...)

Arguments

Details

See the corresponding*3d function:abclines3d,planes3d,clipplanes3d,sprites3d,spheres3d.

Get user-defined axis labelling callbacks.

Description

This function gets a user-defined axis labelling callback in R.

Usage

rgl.getAxisCallback(axis, dev = cur3d(), subscene = currentSubscene3d(dev))

Arguments

Value

The callback function.

Author(s)

Duncan Murdoch

See Also

setAxisCallbacks towork withrglwidget.

Increment ID

Description

This function is mainly for internal use. It simply increments the internal object ID number and returnsthe new value. Negative values have no effect.

Usage

rgl.incrementID(n = 1L)

Arguments

Value

The resulting ID value.

Examples

# Get the current ID valuergl.incrementID(0)# Increment itrgl.incrementID()

Initializing RGL

Description

Initializing the RGL system.

Usage

rgl.init(initValue = 0, onlyNULL = FALSE,          debug = getOption("rgl.debug", FALSE))

Arguments

Details

IfuseNULL isTRUE, RGL will use a “null”device. This device records objects as they are plotted, but displays nothing. It is intended for use withrglwidgetand similar functions.

Currentlydebug only controls messages printed by the OpenGLlibrary during initialization. In futuredebug = TRUE maybecome more verbose.

For display within an OpenGL window in R, RGL requires the OpenGLsystem to be installed and available. If there is a problem initializing it, you may see the message⁠'rgl.init' failed, running with 'rgl.useNULL = TRUE'.⁠ Thereare several causes and remedies:

• On any system, the OpenGL libraries need to be present for RGL to be able to start an OpenGL device.

  • On macOS, you need to install XQuartz. It is available fromhttps://www.xquartz.org.

  • On Linux, you need to install Mesa 3D. One of these commandsmay work, depending on your system:⁠ zypper source-install --build-deps-only Mesa # openSUSE/SLED/SLES yum-builddep mesa # yum Fedora, OpenSuse(?) dnf builddep mesa # dnf Fedora apt-get build-dep mesa # Debian, Ubuntu and related ⁠

  • Windows should have OpenGL installed by default.

• On Unix-alike systems (macOS and Linux, for example), RGLnormallyuses the GLX system for creating displays. If the graphic is createdon a remote machine, it may need to use “Indirect GLX” (IGLX). Dueto security concerns, this is often disabled by default. Seehttps://www.x.org/wiki/Development/Security/Advisory-2014-12-09/for a discussion of the security issues, andhttps://unix.stackexchange.com/q/317954for ways to re-enable IGLX.

• Thehttps://www.virtualgl.org project is intended to be a way to avoid IGLX, by rendering remotely and sending bitmapsto the local machine. It's not a simple install...

• If you don't need to see RGL displays on screen, youcan use the “NULL device”. Seergl.useNULL.

• If you can't build thergl package with OpenGLsupport, you candisable it and use the NULL device. (This may happen automaticallyduring configuration, but you'll get a tested result if youspecify it explicitly.) See the instructions in the‘README’ file in the source tarball.

Value

Normally the user doesn't callrgl.init at all: itis called when the package is loaded. It returns nouseful value.

Extract pixel information from window

Description

This function extracts single components of the pixel information from the topmost window.

Usage

rgl.pixels(component = c("red", "green", "blue"),         viewport = par3d("viewport"), top = TRUE)

Arguments

Details

The possible components are"red","green","blue","alpha","depth", and"luminance" (the sum of the threecolors). All are scaled from 0 to 1.

Note that the luminance is kept below 1 by truncating the sum; this is the definition used for theGL_LUMINANCE component in OpenGL.

Value

A vector, matrix or array containing the desired components. If one componentis requested, a vector or matrix will be returned depending on the size ofblock requested (length 1 dimensions are dropped); if more, an array, whose last dimensionis the list of components.

Author(s)

Duncan Murdoch

See Also

rgl.snapshot to write a copy to a file,demo("stereo") for functions that make use of this to drawa random dot stereogram and an anaglyph.

Examples

example(surface3d)depth <- rgl.pixels(component = "depth")if (length(depth) && is.matrix(depth)) # Protect against empty or single pixel windows    contour(depth)