manual/unit.rst

   1
   2 .. _unit:
   3
   4 ***********
   5 Module unit
   6 ***********
   7
   8 .. sectionauthor:: Jörg Lehmann <joergl@users.sourceforge.net>
   9
  10
  11 .. module:: unit
  12
  13
  14 With the ``unit`` module PyX makes available classes and functions for the
  15 specification and manipulation of lengths. As usual, lengths consist of a number
  16 together with a measurement unit, e.g., 1 cm, 50 points, 0.42 inch.  In
  17 addition, lengths in PyX are composed of the five types "true", "user",
  18 "visual", "width", and "TeX", e.g., 1 user cm, 50 true points, 0.42 visual + 0.2
  19 width inch.  As their names indicate, they serve different purposes. True
  20 lengths are not scalable and are mainly used for return values of PyX functions.
  21 The other length types can be rescaled by the user and differ with respect to
  22 the type of object they are applied to:
  23
  24 user length:
  25    used for lengths of graphical objects like positions etc.
  26
  27 visual length:
  28    used for sizes of visual elements, like arrows, graph symbols, axis ticks, etc.
  29
  30 width length:
  31    used for line widths
  32
  33 TeX length:
  34    used for all TeX and LaTeX output
  35
  36 When not specified otherwise, all types of lengths are interpreted in terms of a
  37 default unit, which, by default, is 1 cm. You may change this default unit by
  38 using the module level function
  39
  40
  41 .. function:: set(uscale=None, vscale=None, wscale=None, xscale=None, defaultunit=None)
  42
  43    When *uscale*, *vscale*, *wscale*, or *xscale* is not :keyword:`None`, the
  44    corresponding scaling factor(s) is redefined to the given number. When
  45    *defaultunit* is not :keyword:`None`,  the default unit is set to the given
  46    value, which has to be one of ``"cm"``, ``"mm"``, ``"inch"``, or ``"pt"``.
  47
  48 For instance, if you only want thicker lines for a publication version of your
  49 figure, you can just rescale all width lengths using  ::
  50
  51    unit.set(wscale=2)
  52
  53 Or suppose, you are used to specify length in imperial units. In this,
  54 admittedly rather unfortunate case, just use  ::
  55
  56    unit.set(defaultunit="inch")
  57
  58 at the beginning of your program.
  59
  60
  61 Class length
  62 ============
  63
  64
  65 .. class:: length(f, type="u", unit=None)
  66
  67    The constructor of the :class:`length` class expects as its first argument a
  68    number *f*, which represents the prefactor of the given length. By default this
  69    length is interpreted as a user length (``type="u"``) in units of the current
  70    default unit (see :func:`set` function of the :mod:`unit` module). Optionally, a
  71    different *type* may be specified, namely ``"u"`` for user lengths, ``"v"`` for
  72    visual lengths, ``"w"`` for width lengths, ``"x"`` for TeX length, and ``"t"``
  73    for true lengths. Furthermore, a different unit may be specified using the
  74    *unit* argument. Allowed values are ``"cm"``, ``"mm"``, ``"inch"``, and
  75    ``"pt"``.
  76
  77 Instances of the :class:`length` class support addition and substraction either
  78 by another :class:`length` or by a number which is then interpeted as being a
  79 user length in  default units, multiplication by a number and division either by
  80 another :class:`length` in which case a float is returned or by a number in
  81 which case a :class:`length` instance is returned. When two lengths are
  82 compared, they are first converted to meters (using the currently set scaling),
  83 and then the resulting values are compared.
  84
  85
  86 Predefined length instances
  87 ===========================
  88
  89 A number of ``length`` instances are already predefined, which only differ in
  90 there values for ``type`` and ``unit``. They are summarized in the following
  91 table
  92
  93 +-----------------+--------+--------+
  94 | name            | type   | unit   |
  95 +=================+========+========+
  96 | :const:`m`      | user   | m      |
  97 +-----------------+--------+--------+
  98 | :const:`cm`     | user   | cm     |
  99 +-----------------+--------+--------+
 100 | :const:`mm`     | user   | mm     |
 101 +-----------------+--------+--------+
 102 | :const:`inch`   | user   | inch   |
 103 +-----------------+--------+--------+
 104 | :const:`pt`     | user   | points |
 105 +-----------------+--------+--------+
 106 | :const:`t_m`    | true   | m      |
 107 +-----------------+--------+--------+
 108 | :const:`t_cm`   | true   | cm     |
 109 +-----------------+--------+--------+
 110 | :const:`t_mm`   | true   | mm     |
 111 +-----------------+--------+--------+
 112 | :const:`t_inch` | true   | inch   |
 113 +-----------------+--------+--------+
 114 | :const:`t_pt`   | true   | points |
 115 +-----------------+--------+--------+
 116 | :const:`u_m`    | user   | m      |
 117 +-----------------+--------+--------+
 118 | :const:`u_cm`   | user   | cm     |
 119 +-----------------+--------+--------+
 120 | :const:`u_mm`   | user   | mm     |
 121 +-----------------+--------+--------+
 122 | :const:`u_inch` | user   | inch   |
 123 +-----------------+--------+--------+
 124 | :const:`u_pt`   | user   | points |
 125 +-----------------+--------+--------+
 126 | :const:`v_m`    | visual | m      |
 127 +-----------------+--------+--------+
 128 | :const:`v_cm`   | visual | cm     |
 129 +-----------------+--------+--------+
 130 | :const:`v_mm`   | visual | mm     |
 131 +-----------------+--------+--------+
 132 | :const:`v_inch` | visual | inch   |
 133 +-----------------+--------+--------+
 134 | :const:`v_pt`   | visual | points |
 135 +-----------------+--------+--------+
 136 | :const:`w_m`    | width  | m      |
 137 +-----------------+--------+--------+
 138 | :const:`w_cm`   | width  | cm     |
 139 +-----------------+--------+--------+
 140 | :const:`w_mm`   | width  | mm     |
 141 +-----------------+--------+--------+
 142 | :const:`w_inch` | width  | inch   |
 143 +-----------------+--------+--------+
 144 | :const:`w_pt`   | width  | points |
 145 +-----------------+--------+--------+
 146 | :const:`x_m`    | TeX    | m      |
 147 +-----------------+--------+--------+
 148 | :const:`x_cm`   | TeX    | cm     |
 149 +-----------------+--------+--------+
 150 | :const:`x_mm`   | TeX    | mm     |
 151 +-----------------+--------+--------+
 152 | :const:`x_inch` | TeX    | inch   |
 153 +-----------------+--------+--------+
 154 | :const:`x_pt`   | TeX    | points |
 155 +-----------------+--------+--------+
 156
 157 Thus, in order to specify, e.g., a length of 5 width points, just use
 158 ``5*unit.w_pt``.
 159
 160
 161 Conversion functions
 162 ====================
 163
 164 If you want to know the value of a PyX length in certain units, you may use the
 165 predefined conversion functions which are given in the following table
 166
 167 +---------------+--------------------------+
 168 | function      | result                   |
 169 +===============+==========================+
 170 | ``tom(l)``    | ``l`` in units of m      |
 171 +---------------+--------------------------+
 172 | ``tocm(l)``   | ``l`` in units of cm     |
 173 +---------------+--------------------------+
 174 | ``tomm(l)``   | ``l`` in units of mm     |
 175 +---------------+--------------------------+
 176 | ``toinch(l)`` | ``l`` in units of inch   |
 177 +---------------+--------------------------+
 178 | ``topt(l)``   | ``l`` in units of points |
 179 +---------------+--------------------------+
 180
 181 If ``l`` is not yet a ``length`` instance but a number, it first is interpreted
 182 as a user length in the default units.
 183
 184 .. % %% Local Variables:
 185 .. % %% mode: latex
 186 .. % %% TeX-master: "manual.tex"
 187 .. % %% End:
 188