text3d {rgl}

Add text to plot

Description

Adds text to the scene. The text is positioned in 3D space. Text is always oriented towards the camera.

Usage

text3d(x, y = NULL, z = NULL, texts, adj = 0.5, pos = NULL, offset = 0.5,
       usePlotmath = is.language(texts), 
       family = par3d("family"), font = par3d("font"), 
			 cex = par3d("cex"), useFreeType = par3d("useFreeType"),
			...) 
texts3d(x, y = NULL, z = NULL, texts, adj = 0.5, pos = NULL, offset = 0.5,
       usePlotmath = is.language(texts),
       family = par3d("family"), font = par3d("font"), 
			 cex = par3d("cex"), useFreeType = par3d("useFreeType"),
			...)       

Arguments

x, y, z

point coordinates. Any reasonable way of defining the coordinates is acceptable. See the function xyz.coords for details.

texts

text character vector to draw

adj

one value specifying the horizontal adjustment, or two, specifying horizontal and vertical adjustment respectively, or three, specifying adjustment in all three directions.

pos

a position specifier for the text. If specified, this overrides any adj value given. Values of 0, 1, 2, 3, 4, 5, 6 respectively indicate positions at, below, to the left of, above, to the right of, in front of, and behind the specified coordinates.

offset

when pos is specified, this value gives the offset of the label from the specified coordinate in fractions of a character width.

usePlotmath

logical. Should plotmath3d be used for the text?

family

A device-independent font family name, or ""

font

A numeric font number from 1 to 4

cex

A numeric character expansion value

useFreeType

logical. Should FreeType be used to draw text? (See details below.)

...

Material properties; see material3d for details.

Details

The adj parameter determines the position of the text relative to the specified coordinate. Use adj = c(0, 0) to place the left bottom corner at (x, y, z), adj = c(0.5, 0.5) to center the text there, and adj = c(1, 1) to put the right top corner there. The optional second coordinate for vertical adjustment defaults to 0.5. Placement is done using the "advance" of the string and the "ascent" of the font relative to the baseline, when these metrics are known.

text3d and texts3d draw text using the r3d conventions. These are synonyms; the former is singular to be consistent with the classic 2-D graphics functions, and the latter is plural to be consistent with all the other graphics primitives. Take your choice!

If any coordinate or text is NA, that text is not plotted.

If usePlotmath is TRUE, the work will be done by the plotmath3d function. This is the default if the texts parameter is “language”, e.g. the result of a call to expression or quote.

Value

The text drawing functions return the object ID of the text object (or sprites, in case of usePlotmath = TRUE) invisibly.

Fonts

Fonts are specified using the family, font, cex, and useFreeType arguments. Defaults for the currently active device may be set using par3d, or for future devices using r3dDefaults.

The family specification is the same as for standard graphics, i.e. families
c("serif", "sans", "mono", "symbol")
are normally available, but users may add additional families. font numbers are restricted to the range 1 to 4 for standard, bold, italic and bold italic respectively. Font 5 is recoded as family "symbol" font 1, but that is not supported unless specifically installed, so should be avoided.

Using an unrecognized value for "family" will result in the system standard font as used in RGL up to version 0.76. That font is not resizable and font values are ignored.

If useFreeType is TRUE, then RGL will use the FreeType anti-aliased fonts for drawing. This is generally desirable, and it is the default on non-Windows systems if RGL was built to support FreeType.

FreeType fonts are specified using the rglFonts function.

See Also

r3d, plotmath3d, rglExtrafonts for adding fonts

Examples

open3d()
famnum <- rep(1:3, 8)
family <- c("serif", "sans", "mono")[famnum]
font <- rep(rep(1:4, each = 3), 2)
cex <- rep(1:2, each = 12)
text3d(font, cex, famnum, texts = paste(family, font), adj = 0.5, 
       color = "blue", family = family, font = font, cex = cex)