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