rgl.*. What do I need to do?
Since at least 2004,
rgl has had two interfaces for many
of the primitive functions:
example, to draw points you could use
points3d(). With the upcoming version 1.0.0 release of
rgl, most of the duplication will be removed. The first
step will be to deprecate a large number of
so they give warnings when they are called, and a few months later they
will be removed from the package exports.
This document describes the differences and changes needed by users
rgl.open() function has a single argument,
useNULL. If set to
TRUE, the NULL
rgl device will be used. The
will be set to their defaults.
open3d() function has arguments
function(..., params = getr3dDefaults(), useNULL = rgl.useNULL(), silent = FALSE )
par3d() values to be specified, and uses the
r3dDefaults variable to set default values for
r3dDefaults is defined
list(userMatrix = rotationMatrix(290*pi/180, 1, 0, 0), mouseMode = c("none", "trackball", "zoom", "fov", "pull"), FOV = 30, family = "sans", bg = list(color="white", fogtype = "none"), material = list(color="black", fog = TRUE) )
Users can create their own default lists; e.g. to get the same result
rgl.open() would give, use
open3d(params = list())
<- list() r3dDefaults open3d()
rgl.material() function has a large number of
parameters. The pre-deprecation arguments were:
function( color = "white", alpha = 1.0, lit = TRUE, ambient = "black", specular = "white", emission = "black", shininess = 50.0, smooth = TRUE, texture = NULL, textype = "rgb", texmipmap = FALSE, texminfilter = "linear", texmagfilter = "linear", texenvmap = FALSE, front = "filled", back = "filled", size = 3.0, lwd = 1.0, fog = TRUE, point_antialias = FALSE, line_antialias = FALSE, depth_mask = TRUE, depth_test = "less", polygon_offset = c(0.0, 0.0), margin = "", floating = FALSE, tag = "", blend = c("src_alpha", "one_minus_src_alpha"), col, ...)
Thus a call like
rgl.material(color = "black") will set
the color to black, and will also set all of the other parameters to the
default values listed above.
On the other hand, the arguments to
function (..., id = NULL)
material3d(color = "black") will set the color
to black and leave all other parameters unchanged.
The primitive shapes (points etc.) can be set using calls like
rgl.points(x, y, z, color = "black") or
points3d(x, y, z, color = "black").
The first difference is that
rgl.* primitives will call
rgl.material() to set the material properties: in this
color will be set to
black, and all
other parameters will be set to their defaults. The
versions of the primitives use
material3d() to set material
properties, so only those that were specified will be changed, and the
original values will be restored afterwards.
The second difference is what happens if there is no window already
rgl.* functions will call
r3dDefaults), whereas the
functions will call
Both of the systems worked, but they do not work together. For
rgl.points() will have carry-on effects on
points3d() calls, whereas each
points3d() call will just draw the points, it won’t affect
Users have found this confusing, and it makes their code hard to
debug, and the
rgl package hard to maintain. The
*3d interface is more flexible, and more similar to the
base graphics interface in R, so I’ve decided it will be the only one
available going forward.
rgl.*functions are not deprecated
There will still be some
rgl.* functions in the package.
These are functions that are mainly intended for programming, such as
rgl.user2window(), and a few
legacy functions like
rgl.Sweave() supporting older
approaches of using
In a few cases both function versions are identical
are identical to
pop3d respectively), and for those the
versions will be kept, but the documentation will concentrate on the
rgl.*. What do I need to do?
If your package is using
rgl.* functions, the first step
is to just make the substitutions suggested by the deprecation warning
message. For example, if you use
rgl.points(rnorm(10), rnorm(10), rnorm(10)) try using
points3d(rnorm(10), rnorm(10), rnorm(10)) instead. In most
cases this will give you what you want. In some cases more changes will
See above if you were using these.
The default color after
rgl.open() was white, whereas
open3d() the default color is black, with a white
background. Textures multiplicatively modify the color of the object, so
open3d(), a texture on an object will still appear
black. Explicitly specifying
color = "white" when a texture
is used will fix this.
The arguments to
surface3d() functions are different. The argument lists
rgl.surface( x, z, y, coords = 1:3, ..., normal_x = NULL, normal_y = NULL, normal_z = NULL, texture_s = NULL, texture_t = NULL) surface3d(x, y = NULL, z = NULL, ...,normal_x = NULL, normal_y = NULL, normal_z = NULL, texture_s = NULL, texture_t=NULL)
Notice that the arguments are in a different order. Another
difference is that
rgl.surface() expects the surface to be
defined in the
y coordinate and viewed in the orientation
rgl.open(), not the one produced by
open3d(). Up until very recently,
didn’t allow both
z to be vectors.
rayshader package used
the convention that the
y argument held the surface, so the
y direction should point up. Using
view3d(theta = 45, phi = 45) (which it was already doing)
gives a reasonable view.
Many functions in
rgl and other packages use
... to set material or
par3d properties in a
call, and for some,
... will contain other optional
arguments. Some packages used the argument list of
rgl.material() to identify the material property names.
Going forward, packages should use the variables
These are character variables holding all the material property
rgl.material.names contains all names;
rgl.material.readonly is the read-only subset of that
list.) There are also variables
which give the same information for
Since these variables are recently added, you will need to add a
rgl (>= 0.111.5) if you use them.
If you have particular problems adapting other
*3d interface, please post them as issues on https://github.com/dmurdoch/rgl/issues . I’ll explain
how to get what you want or fix things in
rgl so you can do