Description Usage Arguments Details Value Parameters Rendering Note References See Also Examples
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.
1 2 | par3d(..., no.readonly = FALSE, dev = cur3d(),
subscene = currentSubscene3d(dev))
|
... |
arguments in |
no.readonly |
logical; if |
dev |
integer; the rgl device. |
subscene |
integer; the subscene. |
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).
By default, queries and modifications apply to the current subscene
on the current device; specify dev
and/or subscene
to
change this. Some parameters apply to the device as a whole;
these are marked in the list below.
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.
R.O. indicates read-only arguments: These may only be used in queries, i.e., they do not set anything.
activeSubscene
R.O. integer. Used
with rgl.setMouseCallbacks
: during a
callback, indicates the id of the subscene that was clicked.
antialias
R.O. in par3d
, may be
set in open3d
. The (requested) number of hardware
antialiasing planes to use (with multisample antialiasing). The
OpenGL driver may not support the requested number, in which case
par3d("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; see text3d
.
Applies to the whole device.
font
integer. The default font number (from 1 to 5; see text3d
).
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 controls
the degree of parallax in the perspective view.
Isometric perspective corresponds to FOV = 0
.
ignoreExtent
logical. Set to TRUE
so that subsequently plotted objects
will be ignored in calculating the bounding box of the scene. Applies to the
whole device.
maxClipPlanes
R.O.; an integer giving the maximum number 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 position of the user data. See the Note below.
listeners
integer. A vector of subscene id values. If a subscene receives
a mouse event (see mouseMode
just below), the same action will be carried out
on 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 4 strings describing
what the 3 mouse buttons and the mouse wheel do.
Partial matching is used. Possible values for the first 3 entries of mouseMode
(corresponding
to the mouse buttons) 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.
"user"
Used when a user handler is set by
rgl.setMouseCallbacks
.
Possible values for the 4th entry corresponding to the mouse wheel are
"none"
No action.
"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”.
"user"
Used when a user handler is set by
rgl.setWheelCallback
.
A common default on Mac OSX is to convert a two finger drag on a trackpad to a mouse wheel rotation.
observer
R.O.; the position of the observer relative to
the model. Set by observer3d
. See the Note below.
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.
Applies to the whole device.
userMatrix
a 4 by 4 matrix describing user actions to display the scene.
userProjection
a 4 by 4 matrix describing changes to the projection.
viewport
real. A vector giving the dimensions of the
window in pixels. The entries are taken to be c(x, y, width, height)
where
c(x, y)
are the coordinates in pixels of the lower left corner within the window.
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). Applies to the whole device.
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 s
,
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.
If s
has the "model"
set to "modify"
, a similar collection of
matrices using parameters from the parent subscene.
It multiplies the point by M
giving 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")
based on the bounding box and field of view
or observer location, multiplies that by the userProjection
matrix to give P
. It 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.
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.
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.
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 support cex = 1
, so changing both cex
and
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 cex
at 1 (with a warning that the "bitmap"
family only supports that size).
Although 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.
In rgl versions 0.94.x the modelMatrix
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) subscene
is changed immediately. This fixes a bug where in earlier
versions it would only be changed when the window was redrawn, potentially after another command making use of the value.
OpenGL Architecture Review Board (1997). OpenGL Programming Guide. Addison-Wesley.
rgl.viewpoint
to set FOV
and zoom
.
open3d
for how to open a new window
with default settings for these parameters.
1 2 3 4 5 6 7 8 9 |
Warning messages:
1: In rgl.init(initValue, onlyNULL) : RGL: unable to open X11 display
2: 'rgl.init' failed, running with 'rgl.useNULL = TRUE'.
null
1
$userMatrix
[,1] [,2] [,3] [,4]
[1,] 1 0.0000000 0.0000000 0
[2,] 0 0.3420201 0.9396926 0
[3,] 0 -0.9396926 0.3420201 0
[4,] 0 0.0000000 0.0000000 1
$.position
[1] 0 -70
[,1] [,2] [,3] [,4]
[1,] 1 0.000000e+00 0.000000e+00 0
[2,] 0 6.123234e-17 -1.000000e+00 0
[3,] 0 1.000000e+00 6.123234e-17 0
[4,] 0 0.000000e+00 0.000000e+00 1
[,1] [,2] [,3] [,4]
[1,] 1 0.0000000 0.0000000 0
[2,] 0 0.3420201 0.9396926 0
[3,] 0 -0.9396926 0.3420201 0
[4,] 0 0.0000000 0.0000000 1
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.