Add a categorical legend to an 'rgl' plot

Splits the active rgl device into two subscenes (the main plot and a legend) and draws, in the legend subscene, a colored categorical legend together with its corresponding labels.

Usage

fplot3d(
  labels,
  col = hcld.colors(length(labels)),
  type = c("s", "c", "p", "l"),
  legend.zoom = 0.6,
  legend.width = 0.2,
  legend.size = 4,
  legend.dim = 0.2,
  legend.lab = NULL,
  lab.dist = 2.5,
  lab.rev = FALSE,
  ...
)

Arguments

labels: vector with the legend labels (levels/categories). Defaults to seq_along(col).
col: vector of colors associated with each label (defaults to hcld.colors(length(labels))).
type: character; symbol/object used to represent each label in the legend: "s" for spheres (default), "c" for cubes, "p" for points, or "l" for (horizontal) line segments.
legend.zoom: zoom factor applied to the legend subscene/panel.
legend.width: relative size of the legend symbols (spheres, cubes or line segments), as a fraction of the corresponding dimension of the legend subscene.
legend.size: point size, if type = "p", or line width, if type = "l" (in pixels; see size and lwd graphical parameters in rgl::par3d(); ignored in all other cases).
legend.dim: relative dimension of the legend panel, as a fraction of the full width (or height) of the device.
legend.lab: legend title.
lab.dist: distance between the legend symbols and their text labels, as a multiple of the symbol size (legend.width).
lab.rev: logical; if TRUE the order of the levels in the legend is reversed (by default they are shown from top to bottom).
...: material properties (see material3d()) used to draw the legend symbols.

Value

Invisibly returns the identifiers of the created subscenes (see rgl::layout3d()).

Details

Mouse rotation is disabled in the legend subscene. Furthermore, since rgl::layout3d(..., mouseMode = "replace") does not copy the user's mouse handlers (which are therefore disabled), the first one is set up for trackball with double click to reset view (via dbltrack3d()), and the second one (if any) for panning (via pan3d()).

Examples

library(rgl)
open3d()
# Plot equivalent to fpoints():
f <- as.factor(mtcars$cyl)
fplot3d(levels(f), legend.lab = "cyl")
with( mtcars, plot3d(hp, qsec, mpg, type = "s", col = fcolor(f)))
3D plot


# Using cubes instead of spheres in the legend
fplot3d(levels(f), legend.lab = "cyl", type = "c")
with( mtcars, plot3d(hp, qsec, mpg, type = "p", col = fcolor(f)))
3D plot