par3d {rgl} | R Documentation

## 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

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

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

### Parameters

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.

### 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 appending `w = 1`, giving the vector `v = (x, y, z, 1)`.

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

3. It multiplies the point by `M` giving `u = 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 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)`.

7. It converts back to Euclidean coordinates by dividing the first 3 coordinates by `w2`.

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

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

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.

### Note

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.

### 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

        r3dDefaults
        open3d()
        shade3d(cube3d(color = rep(rainbow(6), rep(4, 6))))
        save <- par3d(userMatrix = rotationMatrix(90*pi/180, 1, 0, 0))
        highlevel()  # To trigger display
        save
        par3d("userMatrix")
        par3d(save)
        highlevel()
        par3d("userMatrix")

[Package rgl version 0.100.19 Index]