hover3d {rgl}

Display hover info in plot.

Description

This adds text to identify points within a plot when the mouse is near them.

Usage

hover3d(x, y = NULL, z = NULL, 
        labeller = NULL, 
        tolerance = 20, 
        persist = c("no", "one", "yes"), 
        labels = seq_along(x),
        adj = c(-0.2, 0.5),
        scene = scene3d(minimal = FALSE),
        applyToScene = TRUE,
        ...)

Arguments

x, y, z

Coordinates of point to identify. Any reasonable way of defining the coordinates is acceptable. See the function xyz.coords for details. Alternatively, x may be the id of a single existing object, and its vertices will be used.

labeller

A function to display information about identified points. NULL indicates the default function, described in Details.

tolerance

How close (in pixels) the mouse should be to a point to display the information.

persist

Should the label persist? If "no" (the default), it will be removed when the mouse moves away. If "one", it will be removed when another point is closer to the mouse. If "yes", it will not be removed.

labels

If the default labeller is used, these labels will be displayed.

adj

If the default labeller is used, this adjustment will be passed to text3d to display the labels.

scene, applyToScene

Arguments to pass to setUserCallbacks. The applyToDev argument to that function is always TRUE.

...

Additional arguments that will be passed to the labeller.

Details

If specified, the labeller argument should specify a function with arguments compatible with function(index, ...). It will be called with index being the index of the point that was selected. It should plot the label, and return the rgl ids of the objects that were plotted.

When applyToScene is TRUE, all labels or labelling objects will be created and attached to the scene. You may want to delete them (using the ids returned in idverts and idtexts) once rglwidget has been called, as they serve no purpose in the current device.

Only one hover handler is supported per scene or device.

Value

A lowlevel vector of ids is returned invisibly. If applyToScene is TRUE, it will contain the ids of the temporary objects created for Javascript. It will also have these attributes:

oldPar

Values of par3d parameters that were changed. Currently only "mouseMode".

oldDev

The value of cur3d() at the time of calling, so that oldPar can be restored to the right device.

Author(s)

Duncan Murdoch

See Also

identify3d and selectpoints3d work in the rgl device and return information about the selections. setUserCallbacks is the underlying function used by hover3d.

Examples

# Create a labeller to show the coordinates of the selected point.
labelLocation <- function(x, y = NULL, z = NULL) {
  xyz <- xyz.coords(x, y, z)
  function(sel, ...) {
    p <- with(xyz, matrix(c(x[sel], y[sel], z[sel]), ncol = 3))
    c(text3d(p, texts = sprintf("x:%.2f", p[1]), 
                  adj = c(-0.2, -0.6), ...),
      text3d(p, texts = sprintf("y:%.2f", p[2]),
                  adj = c(-0.2, 0.5), ...),
      text3d(p, texts = sprintf("z:%.2f", p[3]),
                  adj = c(-0.2, 1.6), ...))
  }
}

xyz <- matrix(rnorm(30), ncol = 3)
open3d()
ids <- plot3d(xyz)
hover3d(xyz, labeller = labelLocation(xyz), col = "red", cex = 0.8)
# The same thing using the data id:
# hover3d(ids["data"], 
#         labeller = labelLocation(rgl.attrib(ids["data"], "vertices")), 
#         col = "red", cex = 0.8)