text3d {rgl} | R Documentation

## add text

### Description

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

### Usage

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

### Arguments

`x, y, z` | point coordinates. Any reasonable way of defining the coordinates is acceptable. See the function `xyz.coords` for details.
`text` | text character vector to draw
`texts` | text character vector to draw
`adj` | one value specifying the horizontal adjustment, or two, specifying horizontal and vertical adjustment respectively.

.

`pos` | a position specifier for the text. If specified, this overrides any `adj` value given. Values of 1, 2, 3 and 4, respectively indicate positions below, to the left of, above and to the right of 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.
`family` | A device-independent font family name, or ""
`font` | A numeric font number from 1 to 5
`cex` | A numeric character expansion value
`useFreeType` | logical. Should FreeType be used to draw text? (See details below.)
`usePlotmath` | logical. Should `plotmath3d` be used for the text?
`...` | In `rgl.texts`, material properties; see `rgl.material` for details. In `rglFonts`, device dependent font definitions for use with FreeType. In the other functions, additional parameters to pass to `rgl.texts`.

### 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 instead of `rgl.texts`. 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.

`rglFonts` returns the current set of font definitions.

### 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; with font 5 recoded as family `"symbol"` font 1.

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 if rgl was built to support FreeType.

FreeType fonts are specified using the `rglFonts` function. This function takes a vector of four filenames of TrueType font files which will be used for the four styles regular, bold, italic and bold italic. The vector is passed with a name to be used as the family name, e.g. `rglFonts(sans = c("/path/to/FreeSans.ttf", ...))`. In order to limit the file size, `rgl` ships with just 3 font files, for regular versions of the `serif`, `sans` and `mono` families. Additional free font files are available from the Amaya project at http://dev.w3.org/cvsweb/Amaya/fonts/. See the example below for how to specify a full set of fonts.

Full pathnames should normally be used to specify font files. If relative paths are used, they are interpreted differently by platform. Currently Windows fonts are looked for in the Windows fonts folder, while other platforms use the current working directory.

If FreeType fonts are not used, then bitmapped fonts will be used instead. On Windows these will be based on the fonts specified using the `windowsFonts` function, and are resizable. Other platforms will use the default bitmapped font which is not resizable.

Bitmapped fonts have a limited number of characters supported; if any unsupported characters are used, an error will be thrown.

### See Also

`r3d`, `plotmath3d`

### Examples

    open3d()
    famnum <- rep(1:4, 8)
    family <- c("serif", "sans", "mono", "symbol")[famnum]
    font <- rep(rep(1:4, each = 4), 2)
    cex <- rep(1:2, each = 16)
    text3d(font, cex, famnum, text = paste(family, font), adj = 0.5,
           color = "blue", family = family, font = font, cex = cex)
    ## Not run:
    # These FreeType fonts are available from the Amaya project, and are not shipped
    # with rgl.  You would normally install them to the rgl/fonts directory
    # and use fully qualified pathnames, e.g.
    # system.file("fonts/FreeSerif.ttf", package = "rgl")

    rglFonts(serif = c("FreeSerif.ttf", "FreeSerifBold.ttf", "FreeSerifItalic.ttf",
                     "FreeSerifBoldItalic.ttf"),
             sans  = c("FreeSans.ttf", "FreeSansBold.ttf", "FreeSansOblique.ttf",
                     "FreeSansBoldOblique.ttf"),
             mono  = c("FreeMono.ttf", "FreeMonoBold.ttf", "FreeMonoOblique.ttf",
                     "FreeMonoBoldOblique.ttf"),
             symbol= c("ESSTIX10.TTF", "ESSTIX12.TTF", "ESSTIX9_.TTF",
                     "ESSTIX11.TTF"))

    ## End(Not run)

[Package rgl version 0.100.19 Index]