Display hover info in plot.

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

Duncan Murdoch

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)
3D plot

# The same thing using the data id:
# hover3d(ids["data"], 
#         labeller = labelLocation(rgl.attrib(ids["data"], "vertices")), 
#         col = "red", cex = 0.8)