grid.convert              package:grid              R Documentation

_C_o_n_v_e_r_t _B_e_t_w_e_e_n _D_i_f_f_e_r_e_n_t _g_r_i_d _C_o_o_r_d_i_n_a_t_e _S_y_s_t_e_m_s

_D_e_s_c_r_i_p_t_i_o_n:

     These functions take a unit object and convert it to an equivalent
     unit object in a different coordinate system.

_U_s_a_g_e:

     convertX(x, unitTo, valueOnly = FALSE) 
     convertY(x, unitTo, valueOnly = FALSE) 
     convertWidth(x, unitTo, valueOnly = FALSE) 
     convertHeight(x, unitTo, valueOnly = FALSE) 
     convertUnit(x, unitTo,
                  axisFrom = "x", typeFrom = "location",
                  axisTo = axisFrom, typeTo = typeFrom,
                  valueOnly = FALSE)
     grid.convertX(x, unitTo, valueOnly = FALSE) 
     grid.convertY(x, unitTo, valueOnly = FALSE) 
     grid.convertWidth(x, unitTo, valueOnly = FALSE) 
     grid.convertHeight(x, unitTo, valueOnly = FALSE) 
     grid.convert(x, unitTo,
                  axisFrom = "x", typeFrom = "location",
                  axisTo = axisFrom, typeTo = typeFrom,
                  valueOnly = FALSE)

_A_r_g_u_m_e_n_t_s:

       x: A unit object. 

  unitTo: The coordinate system to convert the unit to. See the 'unit'
          function for valid coordinate systems.

axisFrom: Either '"x"' or '"y"' to indicate whether the unit object
          represents a value in the x- or y-direction. 

typeFrom: Either '"location"' or '"dimension"' to indicate whether the
          unit object represents a location or a length. 

  axisTo: Same as 'axisFrom', but applies to the unit object that is to
          be created. 

  typeTo: Same as 'typeFrom', but applies to the unit object that is to
          be created. 

valueOnly: A logical indicating.  If 'TRUE' then the function does not
          return a unit object, but rather only the converted numeric
          values. 

_D_e_t_a_i_l_s:

     The 'convertUnit' function allows for general-purpose conversions.
      The other four functions are just more convenient front-ends to
     it for the most common conversions.

     The conversions occur within the current viewport.

     It is not currently possible to convert to all valid coordinate
     systems (e.g., "strwidth" or "grobwidth").  I'm not sure if all of
     these are impossible, they just seem implausible at this stage.

     In normal usage of grid, these functions should not be necessary.
     If you want to express a location or dimension in inches rather
     than user coordinates then you should simply do something like
     'unit(1, "inches")' rather than something like 'unit(0.134,
     "native")'.

     In some cases, however, it is necessary for the user to perform
     calculations on a unit value and this function becomes necessary. 
     In such cases, please take note of the warning below.

     The grid.* versions are just previous incarnations which have been
     deprecated.

_V_a_l_u_e:

     A unit object in the specified coordinate system (unless
     'valueOnly' is 'TRUE' in which case the returned value is a
     numeric).

_W_a_r_n_i_n_g:

     The conversion is only valid for the current device size. If the
     device is resized then at least some conversions will become
     invalid.  For example, suppose that I create a unit object as
     follows: 'oneinch <- convertUnit(unit(1, "inches"), "native"'. 
     Now if I resize the device, the unit object in oneinch no longer
     corresponds to a physical length of 1 inch.

_A_u_t_h_o_r(_s):

     Paul Murrell

_S_e_e _A_l_s_o:

     'unit'

_E_x_a_m_p_l_e_s:

     ## A tautology
     convertX(unit(1, "inches"), "inches")
     ## The physical units
     convertX(unit(2.54, "cm"), "inches")
     convertX(unit(25.4, "mm"), "inches")
     convertX(unit(72.27, "points"), "inches")
     convertX(unit(1/12*72.27, "picas"), "inches")
     convertX(unit(72, "bigpts"), "inches")
     convertX(unit(1157/1238*72.27, "dida"), "inches")
     convertX(unit(1/12*1157/1238*72.27, "cicero"), "inches")
     convertX(unit(65536*72.27, "scaledpts"), "inches")
     convertX(unit(1/2.54, "inches"), "cm")
     convertX(unit(1/25.4, "inches"), "mm")
     convertX(unit(1/72.27, "inches"), "points")
     convertX(unit(1/(1/12*72.27), "inches"), "picas")
     convertX(unit(1/72, "inches"), "bigpts")
     convertX(unit(1/(1157/1238*72.27), "inches"), "dida")
     convertX(unit(1/(1/12*1157/1238*72.27), "inches"), "cicero")
     convertX(unit(1/(65536*72.27), "inches"), "scaledpts")

     pushViewport(viewport(width=unit(1, "inches"),
                            height=unit(2, "inches"),
                            xscale=c(0, 1),
                            yscale=c(1, 3)))
       ## Location versus dimension
       convertY(unit(2, "native"), "inches")
       convertHeight(unit(2, "native"), "inches")
       ## From "x" to "y" (the conversion is via "inches")
       convertUnit(unit(1, "native"), "native",
                    axisFrom="x", axisTo="y")
       ## Convert several values at once
       convertX(unit(c(0.5, 2.54), c("npc", "cm")),
                     c("inches", "native"))
     popViewport()
     ## Convert a complex unit
     convertX(unit(1, "strwidth", "Hello"), "native")

