unit
¶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:
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
unit.
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.
length
¶unit.
length
(f, type="u", unit=None)¶The constructor of the 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 set()
function of the 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 length
class support addition and substraction either
by another 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 length
in which case a float is returned or by a number in
which case a 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.
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 |
---|---|---|
m |
user | m |
cm |
user | cm |
mm |
user | mm |
inch |
user | inch |
pt |
user | points |
t_m |
true | m |
t_cm |
true | cm |
t_mm |
true | mm |
t_inch |
true | inch |
t_pt |
true | points |
u_m |
user | m |
u_cm |
user | cm |
u_mm |
user | mm |
u_inch |
user | inch |
u_pt |
user | points |
v_m |
visual | m |
v_cm |
visual | cm |
v_mm |
visual | mm |
v_inch |
visual | inch |
v_pt |
visual | points |
w_m |
width | m |
w_cm |
width | cm |
w_mm |
width | mm |
w_inch |
width | inch |
w_pt |
width | points |
x_m |
TeX | m |
x_cm |
TeX | cm |
x_mm |
TeX | mm |
x_inch |
TeX | inch |
x_pt |
TeX | points |
Thus, in order to specify, e.g., a length of 5 width points, just use
5*unit.w_pt
.
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.