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 to par3d in tag = value form, or by passing them as a list of tagged values.

Usage

par3d(..., no.readonly = FALSE)

open3d(..., params=get("r3dDefaults", envir=.GlobalEnv))

Arguments

Details

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 (trackball, 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.

Value

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.

Parameters

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

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.

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

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)

Rendering

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:

1. It converts the point to homogeneous coordinates by appending w=1, giving the vector v = (x,y,z,1).
2. It obtains the model matrix M = par3d("modelMatrix") and multiplies the point by this giving u = M %*% v. Using this location and information on the normals (which have been similarly transformed), it performs lighting calculations.
3. It obtains the projection matrix P = par3d("projMatrix") and multiplies the point by it giving P %*% u = (x2, y2, z2, w2).
4. It converts back to Euclidean coordinates by dividing the first 3 coordinates by w2.
5. 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.
6. 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.

References

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

See Also

rgl.viewpoint to set FOV and zoom.

Examples

    open3d()
    
    save <- par3d(userMatrix = rotationMatrix(90*pi/180, 1,0,0))
    save
    par3d("userMatrix")    
    par3d(userMatrix = save)
    par3d("userMatrix")