par3d {rgl} | R Documentation |
par3d
can be used to set or query graphical parameters in rgl.
Parameters can be set by specifying them as arguments to par3d
in
tag = value
form, or by passing them as a list of tagged
values.
par3d(..., no.readonly = FALSE) open3d(..., params=get("r3dDefaults", envir=.GlobalEnv))
... |
arguments in |
no.readonly |
logical; if |
params |
a list of graphical parameters |
Parameters are queried by giving one or more character vectors to
par3d
.
par3d()
(no arguments) or par3d(no.readonly=TRUE)
is used to
get all the graphical parameters (as a named list).
R.O. indicates read-only arguments: These may only be used in queries, i.e., they do not set anything.
open3d
opens a new rgl device, and sets the parameters as
requested. The r3dDefaults
list 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 mouseMode
to
(zAxis, zoom, fov)
, and the field of view to 30 degrees.
Users may create their own variable of that name in the global
environment and it will override the installed one. If there
is a 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
the r3dDefaults
values in preference to this setting.
When parameters are set, their former values are returned in an
invisible named list. Such a list can be passed as an argument to
par3d
to 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.
cex
real. The default size for text.
family
character. The default device independent family name; see text3d
.
font
integer. The default font number (from 1 to 5; see text3d
.
useFreeType
logical. Should FreeType fonts be used?
fontname
R.O.; the system-dependent name of the current font.
FOV
real. The field of view, from 1 to 179 degrees. This controls
the degree of parallax in the perspective view.
Isometric perspective (which would
correspond to FOV=0
) is not currently possible, but one can
approximate it by specifying par3d(FOV=1)
.
ignoreExtent
logical. Set to TRUE
so that subsequently plotted objects
will be ignored in calculating the bounding box of the scene.
modelMatrix
R.O.; a 4 by 4 matrix describing the position of the user data.
mouseMode
character. A vector of 3 strings describing
what the 3 mouse buttons do. Partial matching is used. Possible values for mouseMode
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 the
user, but is used internally by the select3d
function.
"zoom"
Mouse is used to zoom the display.
"fov"
Mouse changes the field of view of the display.
projMatrix
R.O.; a 4 by 4 matrix describing the current projection of the scene.
scale
real. A vector of 3 values indicating the amount by which to
rescale each axis before display. Set by aspect3d
.
skipRedraw
whether to update the display. Set to TRUE
to suspend
updating while making multiple changes to the scene. See demo(hist3d)
for an example.
userMatrix
a 4 by 4 matrix describing user actions to display the scene.
viewport
R.O.; real. A vector giving the dimensions of the window in pixels.
zoom
real. A positive value indicating the current magnification of the scene.
bbox
R.O.; real. A vector of six values indicating the current values of the bounding 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).
The "xAxis"
, "yAxis"
and "zAxis"
mouse modes rotate relative to the coordinate
system of the data, regardless of the current orientation of the scene.
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)
, 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("scale")
.
The par3d("userMatrix")
as set by the user.
A matrix which may be set by mouse movements.
A matrix to translate the origin to the centre of the viewing region.
It multiplies the point by M
giving u = M %*% v
. 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 w2
.
The new value z2/w2
represents 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 x2
and y2
values 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.
See ?matrices for more information on homogeneous and Euclidean coordinates.
OpenGL Architecture Review Board (1997). OpenGL Programming Guide. Addison-Wesley.
rgl.viewpoint
to set FOV
and zoom
.
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")