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

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.

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

Examples

Run this code

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