texts                  package:rgl                  R Documentation

_a_d_d _t_e_x_t

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     rgl.texts(x, y = NULL, z = NULL, text, adj = 0.5, justify, family = par3d("family"), font = par3d("font"), 
                 cex = par3d("cex"), useFreeType=par3d("useFreeType"), ...)
     text3d(x, y = NULL, z = NULL, texts, adj = 0.5, justify, ...) 
     texts3d(x, y = NULL, z = NULL, texts, adj = 0.5, justify, ...) 
     rglFonts(...)

_A_r_g_u_m_e_n_t_s:

 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. 

 justify: (deprecated, please use adj instead) character string
          specifying the horizontal adjustment; options are '"left"',
          '"right"', '"center"'. 

 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.)

    ... : 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'.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     The text drawing functions return the object ID of the text object
     i invisibly.

     'rglFonts' returns the current set of font definitions.

_F_o_n_t_s:

     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 <URL: 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
     resizeable.  Currently MacOSX defaults to the bitmapped font, as
     our font library appears unable to read fonts properly on that
     platform.

_S_e_e _A_l_s_o:

     'r3d'

_E_x_a_m_p_l_e_s:

     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) 

