manual/unit.tex

   1 \chapter{Module unit}
   2 \label{unit}
   3
   4 With the \verb|unit| module \PyX{} makes available classes and
   5 functions for the specification and manipulation of lengths. As usual,
   6 lengths consist of a number together with a measurement unit,
   7 \textit{e.g.}\ \unit[1]{cm}, \unit[50]{points}, \unit[0.42]{inch}.  In
   8 addition, lengths in \PyX{} are composed of the four types ``true'',
   9 ``user'', ``visual'' and ``width'', \textit{e.g.}\ \unit[1]{user cm},
  10 \unit[50]{true points}, $(0.42\ \mathrm{visual} + 0.2\ \mathrm{width})$ inch.
  11 As their names indicate, they serve different purposes. True lengths are not
  12 scalable and serve mainly for return values of \PyX{} functions.  The
  13 other length types allow a rescaling by the user and differ with
  14 respect to the type of object they are applied to:
  15
  16 \begin{description}
  17 \item[user length:] used for lengths of graphical objects like
  18   positions etc.
  19 \item[visual length:] used for sizes of visual elements, like arrows,
  20   graph symbols, axis ticks, etc.
  21 \item[width length:] used for line widths
  22 \end{description}
  23
  24 For instance, if you only want thicker lines for a publication
  25 version of your figure, you can just rescale the width lengths. How
  26 this all works, is described in the following sections.
  27
  28 \section{Class length}
  29
  30 The constructor of the \verb|length| class accepts as first argument
  31 either a number or a string:
  32 \begin{itemize}
  33 \item \verb|length(number)| means a user length in units of the default
  34 unit, defined via \verb|unit.set(defaultunit=defaultunit)|.
  35 \item For \verb|length(string)|, the \verb|string| has to consist of a
  36   maximum of three parts separated by one or more whitespaces:
  37 \begin{description}
  38 \item[quantifier:] integer/float value. Optional, defaults to \verb|1|.
  39 \item[type:] \verb|"t"| (true), \verb|"u"| (user), \verb|"v"| (visual), or \verb|"w"| (width).
  40   Optional, defaults to \verb|"u"|.
  41 \item[unit:] \verb|"m"|, \verb|"cm"|, \verb|"mm"|, \verb|"inch"|, or
  42   \verb|"pt"|. Optional, defaults to the default unit.
  43 \end{description}
  44 \end{itemize}
  45 The default for the first argument is chosen in such a way that
  46 \texttt{5*length()==length(5)}.  Note that the default unit  is
  47 initially set to \verb|"cm"|, but can be changed at any time by the
  48 user. For instance, use
  49 \begin{quote}
  50 \begin{verbatim}
  51 unit.set(defaultunit="inch")
  52 \end{verbatim}
  53 \end{quote}
  54 if you want to specify per default every length in inches.
  55 Furthermore, the scaling of the user, visual and width types can be
  56 changed with the \verb|set| function, as well. To this end, \verb|set|
  57 accepts the named arguments \verb|uscale|, \verb|vscale|, and
  58 \verb|wscale|. For example, if you like to change the thickness of all
  59 lines (with predefined linewidths) by a factor of two, just insert
  60 \begin{quote}
  61 \begin{verbatim}
  62 unit.set(wscale = 2)
  63 \end{verbatim}
  64 \end{quote}
  65 at the beginning of your program.
  66
  67 To complete the discussion of the \verb|length| class, we mention,
  68 that as expected \PyX{} lengths can be added, subtracted, multiplied by
  69 a numerical factor and converted to a string.
  70
  71 \section{Subclasses of length}
  72
  73 A number of subclasses of \verb|length| are already predefined.  They
  74 only differ in their defaults for \verb|type| and \verb|unit|. Note
  75 that again the default value for the quantifier is \verb|1|, such
  76 that, for instance, \texttt{5*m(1)==m(5)}.
  77
  78 \medskip
  79 \begin{center}
  80 \begin{tabular}{lll|lll}
  81 Subclass of \texttt{length} & Type & Unit & Subclass of \texttt{length} & Type & Unit\\
  82 \hline
  83 \texttt{m(x)} & user & m & \texttt{v\_m(x)} & visual & m\\
  84 \texttt{cm(x)} & user & cm & \texttt{v\_cm(x)} & visual & cm\\
  85 \texttt{mm(x)} & user & mm & \texttt{v\_mm(x)} & visual & mm\\
  86 \texttt{inch(x)} & user & inch & \texttt{v\_inch(x)} & visual & inch\\
  87 \texttt{pt(x)} & user & points & \texttt{v\_pt(x)} & visual & points\\
  88 \texttt{t\_m(x)} & true & m & \texttt{w\_m(x)} & width & m\\
  89 \texttt{t\_cm(x)} & true & cm & \texttt{w\_cm(x)} & width & cm\\
  90 \texttt{t\_mm(x)} & true & mm & \texttt{w\_mm(x)} & width & mm\\
  91 \texttt{t\_inch(x)} & true & inch & \texttt{w\_inch(x)} & width & inch\\
  92 \texttt{t\_pt(x)} & true & points & \texttt{w\_pt(x)} & width & points\\
  93 \texttt{u\_m(x)} & user & m & \\
  94 \texttt{u\_cm(x)} & user & cm & \\
  95 \texttt{u\_mm(x)} & user & mm & \\
  96 \texttt{u\_inch(x)} & user & inch & \\
  97 \texttt{u\_pt(x)} & user & points & \\
  98
  99 \end{tabular}
 100 \end{center}
 101 \medskip
 102 Here, \verb|x| is either a number or a string, which, as mentioned
 103 above, defaults to \texttt{1}.
 104
 105 \section{Conversion functions}
 106 If you want to know the value of a \PyX{} length in certain units, you
 107 may use the predefined conversion functions which are given in the
 108 following table
 109 \begin{center}
 110 \begin{tabular}{ll}
 111 function & result \\
 112 \hline
 113 \texttt{to\_m(l)} & \texttt{l} in units of m\\
 114 \texttt{to\_cm(l)} & \texttt{l} in units of cm\\
 115 \texttt{to\_mm(l)} & \texttt{l} in units of mm\\
 116 \texttt{to\_inch(l)} & \texttt{l} in units of inch\\
 117 \texttt{to\_pt(l)} & \texttt{l} in units of points\\
 118 \end{tabular}
 119 \end{center}
 120 If \verb|l| is not yet a \verb|length| instance, it is converted first
 121 into one, as described above. You can also specify a tuple, if you
 122 want to convert multiple lengths at once.
 123
 124
 125 %\section{Examples}
 126
 127
 128 %\subsection{Example 1}
 129
 130
 131
 132 %%% Local Variables:
 133 %%% mode: latex
 134 %%% TeX-master: "manual.tex"
 135 %%% End: