Draw boxes, axes and other text outside the data

These functions draw axes, boxes and text outside the range of the data. axes3d, box3d and title3d are the higher level functions; normally the others need not be called directly by users.

axes3d(edges = "bbox", labels = TRUE, tick = TRUE, nticks = 5, 
  box = FALSE, expand = 1.03, ...)
box3d(...) 
title3d(main = NULL, sub = NULL, xlab = NULL, ylab = NULL, 
  zlab = NULL, line = NA, level = NA, floating = NULL, ...) 
axis3d(edge, at = NULL, labels = TRUE, tick = TRUE, line = 0, 
  pos = NULL, nticks = 5, ...) 
mtext3d(text, edge, at = NULL, line = 0, level = 0, 
        floating = FALSE, pos = NA, ...)

Arguments

edges: a code to describe which edge(s) of the box to use; see Details below
labels: whether to label the axes, or (for axis3d) the labels to use
tick: whether to use tick marks
nticks: suggested number of ticks
box: draw the full box if "bbox" axes are used
expand: how much to expand the box around the data
main: the main title for the plot
sub: the subtitle for the plot
xlab, ylab, zlab: the axis labels for the plot
line, level: the "line" of the plot margin to draw the label on, and "level" above or below it
floating: which mode of axis labels? One of TRUE, FALSE or NA. (NULL may also be used in title3d calls). See Details for how these are handled.
edge, pos: the position at which to draw the axis or text
text: the text to draw
at: the value of a coordinate at which to draw the axis or labels.
...: additional parameters which are passed to bbox3d or material3d

Details

The rectangular prism holding the 3D plot has 12 edges. They are identified using 3 character strings. The first character (`x', `y', or `z') selects the direction of the axis. The next two characters are each `-' or `+', selecting the lower or upper end of one of the other coordinates. If only one or two characters are given, the remaining characters normally default to `-' (but with mtext3d(..., floating = TRUE) the default is `+'; see below). For example edge = 'x+' draws an x-axis at the high level of y and the low level of z.

By default, axes3d uses the bbox3d function to draw the axes. The labels will move so that they do not obscure the data. Alternatively, a vector of arguments as described above may be used, in which case fixed axes are drawn using axis3d.

As of rgl version 0.106.21, axis drawing has changed significantly. Text drawn in the margins will adapt to the margins (see bbox3d). The edge and floating parameters will be recorded in the margin and floating material properties for the object.

If floating = FALSE, they will be drawn on the specified edge.

If floating = TRUE, they will move as the axis labels move when the scene is rotated. The signs on the edge specification are interpreted as agreeing with the axis ticks `+' or disagreeing `-'. For example, "x++" will draw text on the x axis in the same edge as the ticks, while "x--" will draw on the opposite edge.

The final possible value for floating in mtext3d is NA, which reproduces legacy rgl behaviour. In this case the labels are not tied to the bounding box, so they should be drawn last, or they could appear inside the box, overlapping the data.

In title3d floating = NULL (the default) indicates the main title and subtitle will be fixed while the axis labels will be floating. The default locations for title and subtitle are line = 2 and level = 2 on edges "x++" and "x--" respectively. The axis labels float at line = 4 and level = 1 on the same edge as the ticks.

The at parameter in axis3d is the location of the ticks, defaulting to pretty locations. In mtext3d the at parameter is the location on the specified axis at which to draw the text, defaulting to the middle of the bounding box.

The line parameter is the line counting out from the box in the same direction as the axis ticks, and level is the line out in the orthogonal direction. The ticks run from line = 0 to line = 1, and the tick labels are drawn at line = 2. Both are drawn at level 0.

The pos parameter is only supported in legacy mode. If it is a numeric vector of length 3, edge determines the direction of the axis and the tick marks, and the values of the other two coordinates in pos determine the position. The level parameter is ignored in legacy mode.

For mtext3d in floating = TRUE or floating = FALSE mode, there are 3 special values for the at parameter: it may be -Inf, NA or +Inf, referring to the bottom, middle or top of the given axis respectively.

Note

mtext3d is a wrapper for text3d that sets the margin and floating material properties. In fact, these properties can be set for many kinds of objects (most kinds where it would make sense), with the effect that the object will be drawn in the margin, with x coordinate corresponding to at, y corresponding to line, and z corresponding to level.

Value

These functions are called for their side effects. They return the object IDs of objects added to the scene.

Author

Duncan Murdoch

Examples

  open3d()
  points3d(rnorm(10), rnorm(10), rnorm(10))

  # First add standard axes
  axes3d()  

  # and one in the middle (the NA will be ignored, a number would 
  # do as well)
  axis3d('x', pos = c(NA, 0, 0))

  # add titles
  title3d('main', 'sub', 'xlab', 'ylab', 'zlab')
3D plot


  rgl.bringtotop()
  
  open3d()
  points3d(rnorm(10), rnorm(10), rnorm(10))
  
  # Use fixed axes
  
  axes3d(c('x', 'y', 'z'))
         
  # Put 4 x-axes on the plot
  axes3d(c('x--', 'x-+', 'x+-', 'x++'))         
  
  axis3d('x', pos = c(NA, 0, 0))     
  title3d('main', 'sub', 'xlab', 'ylab', 'zlab')
3D plot