axes3d.Rd
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, ...)
a code to describe which edge(s) of the box to use; see Details below
whether to label the axes, or (for axis3d
) the
labels to use
whether to use tick marks
suggested number of ticks
draw the full box if "bbox"
axes are used
how much to expand the box around the data
the main title for the plot
the subtitle for the plot
the axis labels for the plot
the "line" of the plot margin to draw the label on, and "level" above or below it
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.
the position at which to draw the axis or text
the text to draw
the value of a coordinate at which to draw the axis or labels.
additional parameters which are passed to bbox3d
or material3d
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.
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
.
These functions are called for their side effects. They return the object IDs of objects added to the scene.
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