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.}\ $1$ cm, $50$ points, $0.42$ inch.  In addition, lengths
   8 in \PyX{} are composed of the four types ``true'', ``user'',
   9 ``visual'' and ``width'', \textit{e.g.}\ $1$ user cm, $50$ true
  10 points, $(0.42\ \mathrm{visual} + 0.2\ \mathrm{width})$ inch.  As
  11 their name tells, 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 are differ with
  14 respect to the type of object they are applied:
  15
  16 \begin{description}
  17 \item[user length:] used for lengths of graphical objects like
  18   positions, distances, etc.
  19 \item[visual length:] used for sizes of visual elements, like arrows,
  20   text, etc.
  21 \item[width length:] used for line widths
  22 \end{description}
  23
  24 For instance, if you just 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 \verb|unit.default_unit|.
  34 \item For \verb|length(string)| the \verb|string| has to consist of a
  35   maximum of three parts separated by one or more whitespaces:
  36 \begin{description}
  37 \item[quantifier:] integer/float value
  38 \item[type:] \verb|"t"| (true), \verb|"u"| (user), \verb|"v"| (visual), or \verb|"w"| (width).
  39   Optional, defaults to \verb|"u"|.
  40 \item[unit:] \verb|"m"|, \verb|"cm"|, \verb|"mm"|, \verb|"inch"|, or
  41   \verb|"pt"|. Optional, defaults to \verb|default_unit|
  42 \end{description}
  43 \end{itemize}
  44 Note that \verb|default_unit| is initially set to \verb|"cm"|,
  45 but can be changed at any time by the user. For instance, use
  46 \begin{quote}
  47 \begin{verbatim}
  48 unit.default_unit = "inch"
  49 \end{verbatim}
  50 \end{quote}
  51 if you want to specify per default every length in inches.
  52 Furthermore, the scaling of the user, visual and width types can be
  53 changed with the \verb|set| function, which accepts the name arguments
  54 \verb|uscale|, \verb|vscale|, and \verb|wscale|. For example, if you
  55 like to change the thickness of all lines by a factor of two, just
  56 insert
  57 \begin{quote}
  58 \begin{verbatim}
  59 unit.set(wscale = 2)
  60 \end{verbatim}
  61 \end{quote}
  62 at the beginning of your program.
  63
  64 To complete the discussion of the \verb|length| class, we mention,
  65 that as expected \PyX{} length can be added, subtracted, multiplied by
  66 a numerical factor and converted to a string.
  67
  68 \section{Subclasses of length}
  69
  70 A number of subclasses of \verb|length| are already predefined. They
  71 only differ in their defaults for \verb|type| and \verb|unit|.
  72
  73 \medskip
  74 \begin{center}
  75 \begin{tabular}{lll|lll}
  76 Subclass of \texttt{length} & Type & Unit & Subclass of \texttt{length} & Type & Unit\\
  77 \hline
  78 \texttt{m(x)} & user & m & \texttt{t\_m(x)} & true & m\\
  79 \texttt{cm(x)} & user & cm & \texttt{t\_cm(x)} & true & cm\\
  80 \texttt{mm(x)} & user & mm & \texttt{t\_mm(x)} & true & mm\\
  81 \texttt{inch(x)} & user & inch & \texttt{t\_inch(x)} & true & inch\\
  82 \texttt{pt(x)} & user & points & \texttt{t\_pt(x)} & true & points\\
  83 \end{tabular}
  84 \end{center}
  85 \medskip
  86 Here, \verb|x| is either a number or a string.
  87
  88 \section{Conversion functions}
  89 If you want to know the value of a \PyX{} length in certain units, you
  90 can use the predefined conversion functions which are given in the
  91 following table
  92 \begin{center}
  93 \begin{tabular}{ll}
  94 function & result \\
  95 \hline
  96 \texttt{to\_m(l)} & \texttt{l} in units of m\\
  97 \texttt{to\_cm(l)} & \texttt{l} in units of cm\\
  98 \texttt{to\_mm(l)} & \texttt{l} in units of mm\\
  99 \texttt{to\_inch(l)} & \texttt{l} in units of inch\\
 100 \texttt{to\_pt(l)} & \texttt{l} in units of points\\
 101 \end{tabular}
 102 \end{center}
 103 If \verb|l| is not yet a \verb|length| instance, it is converted first
 104 to a such, as described above. You can also specify a tuple, if you
 105 want to convert multiple lengths at once.
 106
 107
 108 \section{Examples}
 109
 110
 111 \subsection{Example 1}
 112
 113
 114
 115 %%% Local Variables:
 116 %%% mode: latex
 117 %%% TeX-master: "manual.tex"
 118 %%% End: