1% File src/library/grid/man/grid.convert.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2013 R Core Team 4% Distributed under GPL 2 or later 5 6\name{grid.convert} 7\alias{convertUnit} 8\alias{convertX} 9\alias{convertY} 10\alias{convertWidth} 11\alias{convertHeight} 12\title{ Convert Between Different grid Coordinate Systems } 13\description{ 14 These functions take a unit object and convert it to an 15 equivalent 16 unit object in a different coordinate system. 17} 18\usage{ 19convertX(x, unitTo, valueOnly = FALSE) 20convertY(x, unitTo, valueOnly = FALSE) 21convertWidth(x, unitTo, valueOnly = FALSE) 22convertHeight(x, unitTo, valueOnly = FALSE) 23convertUnit(x, unitTo, 24 axisFrom = "x", typeFrom = "location", 25 axisTo = axisFrom, typeTo = typeFrom, 26 valueOnly = FALSE) 27} 28\arguments{ 29 \item{x}{ A unit object. } 30 \item{unitTo}{ The coordinate system to convert the unit to. 31 See the \code{\link{unit}} function for valid coordinate systems.} 32 \item{axisFrom}{ Either \code{"x"} or \code{"y"} to indicate 33 whether the unit object represents a value in the x- or 34 y-direction. } 35 \item{typeFrom}{ Either \code{"location"} or \code{"dimension"} 36 to indicate whether the unit object represents a location or a 37 length. } 38 \item{axisTo}{ Same as \code{axisFrom}, but applies to the unit object 39 that is to be created. } 40 \item{typeTo}{ Same as \code{typeFrom}, but applies to the unit object 41 that is to be created. } 42 \item{valueOnly}{ A logical indicating. If \code{TRUE} then 43 the function does not return a unit object, but rather only the 44 converted numeric values. } 45} 46\details{ 47 The \code{convertUnit} function allows for general-purpose 48 conversions. The other four functions are just more convenient 49 front-ends to it for the most common conversions. 50 51 The conversions occur within the current viewport. 52 53 It is not currently possible to convert to all valid coordinate systems 54 (e.g., "strwidth" or "grobwidth"). I'm not sure if all of these 55 are impossible, they just seem implausible at this stage. 56 57 In normal usage of grid, these functions should not be necessary. 58 If you want to express a location or dimension in inches rather 59 than user coordinates then you should simply do something like 60 \code{unit(1, "inches")} rather than something like 61 \code{unit(0.134, "native")}. 62 63 In some cases, however, it is necessary for the user to 64 perform calculations on a unit value and this function becomes 65 necessary. In such cases, please take note of the warning below. 66} 67\value{ 68 A unit object in the specified coordinate system 69 (unless \code{valueOnly} is \code{TRUE} in which case 70 the returned value is a numeric). 71} 72\author{ Paul Murrell } 73 74\section{Warning}{ 75 The conversion is only valid for the current device size. 76 If the device is resized then at least some conversions will 77 become invalid. For example, suppose that I create a unit 78 object as follows: \code{oneinch <- convertUnit(unit(1, "inches"), 79 "native")}. Now if I resize the device, the unit object in 80 oneinch no longer corresponds to a physical length of 1 inch. 81 } 82\seealso{ \code{\link{unit}} } 83\examples{ 84## A tautology 85convertX(unit(1, "inches"), "inches") 86## The physical units 87convertX(unit(2.54, "cm"), "inches") 88convertX(unit(25.4, "mm"), "inches") 89convertX(unit(72.27, "points"), "inches") 90convertX(unit(1/12*72.27, "picas"), "inches") 91convertX(unit(72, "bigpts"), "inches") 92convertX(unit(1157/1238*72.27, "dida"), "inches") 93convertX(unit(1/12*1157/1238*72.27, "cicero"), "inches") 94convertX(unit(65536*72.27, "scaledpts"), "inches") 95convertX(unit(1/2.54, "inches"), "cm") 96convertX(unit(1/25.4, "inches"), "mm") 97convertX(unit(1/72.27, "inches"), "points") 98convertX(unit(1/(1/12*72.27), "inches"), "picas") 99convertX(unit(1/72, "inches"), "bigpts") 100convertX(unit(1/(1157/1238*72.27), "inches"), "dida") 101convertX(unit(1/(1/12*1157/1238*72.27), "inches"), "cicero") 102convertX(unit(1/(65536*72.27), "inches"), "scaledpts") 103 104pushViewport(viewport(width=unit(1, "inches"), 105 height=unit(2, "inches"), 106 xscale=c(0, 1), 107 yscale=c(1, 3))) 108 ## Location versus dimension 109 convertY(unit(2, "native"), "inches") 110 convertHeight(unit(2, "native"), "inches") 111 ## From "x" to "y" (the conversion is via "inches") 112 convertUnit(unit(1, "native"), "native", 113 axisFrom="x", axisTo="y") 114 ## Convert several values at once 115 convertX(unit(c(0.5, 2.54), c("npc", "cm")), 116 c("inches", "native")) 117popViewport() 118## Convert a complex unit 119convertX(unit(1, "strwidth", "Hello"), "native") 120} 121\keyword{dplot} 122