rgl (version 0.95.1367)

par3d: 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, dev = rgl.cur(), 
      subscene = currentSubscene3d(dev))

open3d(..., params = getr3dDefaults(), useNULL = rgl.useNULL()) getr3dDefaults()

r3dDefaults

Arguments

...
arguments in tag = value form, or a list of tagged values. The tags must come from the graphical parameters described below.
no.readonly
logical; if TRUE and there are no other arguments, only those parameters which can be set by a subsequent par3d() call are returned.
dev
integer; the rgl device.
subscene
integer; the subscene.
params
a list of graphical parameters
useNULL
whether to use the null graphics device

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. The r3dDefaults variable is a list containing default settings. The getr3dDefaults function searches the user's global environment for r3dDefaults and returns the one in the rgl namespace if it was not found there. The components of the list may include any settable par3d parameter, or "material", which should include a list of default material3d properties, or "bg", which is a list of defaults to pass to the bg3d function.

concept

  • antialias
  • bbox
  • cex
  • family
  • font
  • fontname
  • FOV
  • ignoreExtent
  • maxClipPlanes
  • modelMatrix
  • listeners
  • mouseMode
  • projMatrix
  • scale
  • skipRedraw
  • useFreeType
  • userMatrix
  • viewport
  • windowRect
  • zoom

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) in a subscene s, it performs the equivalent of the following operations:
  1. It converts the point to homogeneous coordinates by appendingw = 1, giving the vectorv = (x, y, z, 1).
  2. It calculates theM = 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 topar3d("scale").
    • Thepar3d("userMatrix")as set by the user.
    • A matrix which may be set by mouse movements.
    • Ifshas the"model"set to"modify", a similar collection of matrices using parameters from the parent subscene.
  3. It multiplies the point byMgivingu = M %*% v.
  4. It multiplies that point by a matrix based on the observer position to translate the origin to the centre of the viewing region.
  5. Using this location and information on the normals (which have been similarly transformed), it performs lighting calculations.
  6. It obtains the projection matrixP = par3d("projMatrix")and multiplies the point by it givingP %*% u = (x2, y2, z2, w2).
  7. It converts back to Euclidean coordinates by dividing the first 3 coordinates byw2.
  8. The new valuez2/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.
  9. If the point is not culled due to depth, thex2andy2values are used to determine the point in the image. Thepar3d("viewport")values are used to translate from the range(-1, 1)to pixel locations, and the point is plotted.
  10. 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.

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

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.

open3d opens a new rgl device, and sets the parameters as requested. The 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 mouseMode to (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 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. If useNULL is TRUE, rgl will use a null device. This device records objects as they are plotted, but displays nothing. It is intended for use with writeWebGL and similar functions.

References

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

See Also

rgl.viewpoint to set FOV and zoom.

rgl.useNULL for default usage of null device.

Examples

Run this code
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")

Run the code above in your browser using DataCamp Workspace