Set or Query RGL Parameters
par3d can be used to set or query graphical parameters in rgl.
Parameters can be set by specifying them as arguments to
tag = value form, or by passing them as a list of tagged
par3d(..., no.readonly = FALSE, dev = rgl.cur(), subscene = currentSubscene3d(dev))
open3d(..., params = getr3dDefaults(), useNULL = rgl.useNULL()) getr3dDefaults()
- arguments in
tag = valueform, or a list of tagged values. The tags must come from the graphical parameters described below.
- logical; if
TRUEand there are no other arguments, only those parameters which can be set by a subsequent
par3d()call are returned.
- integer; the rgl device.
- integer; the subscene.
- a list of graphical parameters
- whether to use the null graphics device
Parameters are queried by giving one or more character vectors to
par3d() (no arguments) or
par3d(no.readonly = TRUE) is used to
get all the graphical parameters (as a named list).
By default, queries and modifications apply to the current subscene
on the current device; specify
change this. Some parameters apply to the device as a whole;
these are marked in the list below.
open3d opens a new rgl device, and sets the parameters as
r3dDefaults list returned by the
getr3dDefaults function will be used as default
values for parameters. As installed this sets the point of view to
'world coordinates' (i.e. x running from left to right, y from front
to back, z from bottom to top), the
(zAxis, zoom, fov), and the field of view to 30 degrees.
Users may create their own variable named
r3dDefaults in the global
environment and it will override the installed one. If there
bg element in the list or the arguments, it should be
a list of arguments to pass to the
bg3d function to
set the background.
The arguments to
open3d may include
material, a list
of material properties as in
r3dDefaults, but note
that high level functions such as
plot3d normally use
r3dDefaults values in preference to this setting.
and similar functions.
- When parameters are set, their former values are returned in an
invisible named list. Such a list can be passed as an argument to
par3dto restore the parameter values. Use
par3d(no.readonly = TRUE)for the full list of parameters that 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 of values, with the list names giving the parameters.
Note the inconsistency: setting one parameter returns a list, but querying one parameter returns an object. The
r3dDefaultsvariable is a list containing default settings. The
getr3dDefaultsfunction searches the user's global environment for
r3dDefaultsand returns the one in the
rglnamespace if it was not found there. The components of the list may include any settable
"material", which should include a list of default
"bg", which is a list of defaults to pass to the
"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 support
cex = 1, so changing both
family needs to be done in the right order. For example, when using the
"bitmap" family on Windows,
par3d(family = "sans", cex = 2)
will work, but
par3d(cex = 2, family = "sans") will leave
at 1 (with a warning that the
"bitmap" family only supports that size).
par3d("viewport") names the entries of the reported vector,
names are ignored when setting the viewport and entries must be specified
in the standard order.
modelMatrix entry had a changed meaning;
before and after that it contains a copy of the OpenGL MODELVIEW matrix.
The parameters returned by
par3d are sufficient to determine where rgl would render
a point on the screen. Given a column vector
(x, y, z) in a subscene
it performs the equivalent of
the following operations:
- It converts the point to homogeneous coordinates by appending
w = 1, giving the vector
v = (x, y, z, 1).
- It calculates the
M = par3d("modelMatrix")as a product from right to left of the following matrices:
- A matrix to translate the centre of the bounding box to the origin.
- A matrix to rescale according to
par3d("userMatrix")as set by the user.
- A matrix which may be set by mouse movements.
"modify", a similar collection of matrices using parameters from the parent subscene.
- It multiplies the point by
u = M %*% v.
- It multiplies that point by a matrix based on the observer position to translate the origin to the centre of the viewing region.
- Using this location and information on the normals (which have been similarly transformed), it performs lighting calculations.
- It obtains the projection matrix
P = par3d("projMatrix")and multiplies the point by it giving
P %*% u = (x2, y2, z2, w2).
- It converts back to Euclidean coordinates by dividing the first 3 coordinates by
- The new value
z2/w2represents the depth into the scene of the point. Depending on what has already been plotted, this depth might be obscured, in which case nothing more is plotted.
- If the point is not culled due to depth, the
y2values are used to determine the point in the image. The
par3d("viewport")values are used to translate from the range
(-1, 1)to pixel locations, and the point is plotted.
- If hardware antialiasing is enabled, then the whole process is repeated multiple times (at least conceptually) with different locations in each pixel sampled to determine what is plotted there, and then the images are combined into what is displayed.
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.
OpenGL Architecture Review Board (1997). OpenGL Programming Guide. Addison-Wesley.
rgl.viewpoint to set
rgl.useNULL for default usage of null device.
r3dDefaults open3d() shade3d(cube3d(color = rep(rainbow(6), rep(4, 6)))) save <- par3d(userMatrix = rotationMatrix(90*pi/180, 1, 0, 0)) save par3d("userMatrix") par3d(save) par3d("userMatrix")