rgl: show2d – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

show2d

Draw a 2D plot on a rectangle in a 3D scene

Description

This function uses a bitmap of a standard 2D graphics plot as a texture on a quadrilateral. Default arguments are set up so that it will appear on the face of the bounding box of the current 3D plot, but optional arguments allow it to be placed anywhere in the scene.

Usage

show2d(expression, 
  face = "z-", line = 0, 
  reverse = FALSE, rotate = 0, 
  x = NULL, y = NULL, z = NULL, 
  width = 480, height = 480, 
  filename = NULL, 
  ignoreExtent = TRUE, 
  color = "white", specular = "black", lit = FALSE, 
  texmipmap = TRUE, texminfilter = "linear.mipmap.linear",
  expand = 1.03,
  texcoords = matrix(c(0, 1, 1, 0, 0, 0, 1, 1), ncol = 2),  ...)

Arguments

`expression`	Any plotting commands to produce a plot in standard graphics. Ignored if `filename` is not `NULL`.
`face`	A character string defining which face of the bounding box to use. See Details below.
`line`	How far out from the bounding box should the quadrilateral be placed? Uses same convention as `mtext3d`: not lines of text, but fraction of the bounding box size.
`reverse, rotate`	Should the image be reversed or rotated? See Details below.
`x, y, z`	Specific values to use to override `face`.
`width,height`	Parameters to pass to `png` when creating the bitmap. See Details below.
`filename`	A ‘.png’ file image to use as the texture.
`ignoreExtent`	Whether the quadrilateral should be ignored when computing the bounding box of the scene.
`color, specular, lit, texmipmap, texminfilter, ...`	Material properties to use for the quadrilateral.
`expand`	Amount by which the quadrilateral is expanded outside the bounding box of the data.
`texcoords`	Coordinates on the image. Lower left of the bitmap is `c(0,0)`, upper right is `c(1,1)`.

Details

The default arguments are chosen to make it easy to place a 2D image on the face of the bounding box. If x, y and z are NULL (the defaults), face will be used as a code for one of the six faces of the bounding box. The first letter should be "x", "y" or "z"; this defines the axis perpendicular to the desired face. If the second letter is "-" or is missing, the face will be chosen to be the face with the lower value on that axis. Any other letter will use the opposite face.

If any of x, y or z is given, the specified value will be used to replace the value calculated above. Usually four values should be given, corresponding to the coordinates of the lower left, lower right, upper right and upper left of the destination for the image before reverse and rotate are used. Fewer values can be used for one or two coordinates; cbind will be used to put together all 3 coordinates into a 4 by 3 matrix (which will be returned as an attribute of the result).

The bitmap plot will by default be oriented so that it is properly oriented when viewed from the direction of the higher values of the perpendicular coordinate, and its lower left corner is at the lower value of the two remaining coordinates. The argument reverse causes the orientation to be mirrored, and rotate causes it to be rotated by multiples of 90 degrees. rotate should be an integer, with 0 for no rotation, 1 for a 90 degree counter-clockwise rotation, etc.

The width and height arguments control the shape and resolution of the bitmap. The defaults give a square bitmap, which is appropriate with the usual c(1,1,1) aspect ratios (see aspect3d). Some tuning may be needed to choose the resolution. The plot will look best when displayed at its original size; shrinking it smaller tends to make it look faded, while expanding it bigger will make it look blurry. If filename is given, the width and height will be taken from the file, and width and height arguments will be ignored.

Value

Invisibly returns the id value of the quadrilateral, with the following attributes:

`value`	The value returned by `expression`.
`xyz`	A 4 by 3 matrix giving the coordinates of the corners as used in plotting.
`texcoords`	A 4 by 2 matrix giving the texture coordinates of the image.
`filename`	The filename for the temporary file holding the bitmap image.

Author(s)

Duncan Murdoch

Examples

example(plot3d, ask = FALSE)
show2d({
  par(mar=c(0,0,0,0))
  plot(x, y, col = rainbow(1000), axes=FALSE)
  })

rgl

3D Visualization Using OpenGL

v0.106.8

GPL

Authors

Duncan Murdoch [aut, cre], Daniel Adler [aut], Oleg Nenadic [ctb], Simon Urbanek [ctb], Ming Chen [ctb], Albrecht Gebhardt [ctb], Ben Bolker [ctb], Gabor Csardi [ctb], Adam Strzelecki [ctb], Alexander Senger [ctb], The R Core Team [ctb, cph], Dirk Eddelbuettel [ctb], The authors of Shiny [cph], The authors of knitr [cph], Jeroen Ooms [ctb], Yohann Demont [ctb], Joshua Ulrich [ctb], Xavier Fernandez i Marin [ctb], George Helffrich [ctb], Ivan Krylov [ctb]

Initial release