path
¶The path
module defines several important classes which are documented in
the present section.
path
— PostScript-like paths¶path.
path
(*pathitems)¶This class represents a PostScript like path consisting of the path elements pathitems.
All possible path items are described in Sect. Path elements. Note that
there are restrictions on the first path element and likewise on each path
element after a closepath
directive. In both cases, no current point is
defined and the path element has to be an instance of one of the following
classes: moveto
, arc
, and arcn
.
Instances of the class path
provide the following methods (in
alphabetic order):
path.
append
(pathitem)¶Appends a pathitem to the end of the path.
path.
arclentoparam
(lengths)¶Returns the parameter value(s) corresponding to the arc length(s) lengths. [1]
path.
at
(params)¶Returns the coordinates (as 2-tuple) of the path point(s) corresponding to the parameter value(s) params. [1] [2]
path.
bbox
()¶Returns the bounding box of the path.
path.
begin
()¶Returns the parameter value (a normpathparam
instance) of the first
point in the path.
path.
curveradius
(params)¶Returns the curvature radius/radii (or None if infinite) at parameter value(s) params. [2] This is the inverse of the curvature at this parameter. Note that this radius can be negative or positive, depending on the sign of the curvature. [1]
path.
end
()¶Returns the parameter value (a normpathparam
instance) of the last
point in the path.
path.
extend
(pathitems)¶Appends the list pathitems to the end of the path.
path.
intersect
(opath)¶Returns a tuple consisting of two lists of parameter values corresponding to the intersection points of the path with the other path opath, respectively. [1] For intersection points which are not farther apart then epsilon (defaulting to \(10^{-5}\) PostScript points), only one is returned.
path.
joined
(opath)¶Appends opath to the end of the path, thereby merging the last subpath (which
must not be closed) of the path with the first sub path of opath and returns
the resulting new path. [1] Instead of using the
joined()
method, you can also join two paths together with help of the
<<
operator, for instance p = p1 << p2
.
path.
normpath
(epsilon=None)¶Returns the equivalent normpath
. For the conversion and for later
calculations with this normpath
an accuracy of epsilon is used.
If epsilon is None, the global epsilon of the path
module is
used.
path.
paramtoarclen
(params)¶Returns the arc length(s) corresponding to the parameter value(s) params. [2] [1]
path.
range
()¶Returns the maximal parameter value param that is allowed in the path methods.
path.
rotation
(params)¶Returns a transformation or a list of transformations, which rotate the x-direction to the tangent vector and the y-direction to the normal vector at the parameter value(s) params. [2] [1]
path.
split
(params)¶Splits the path at the parameter values params, which have to be sorted in
ascending order, and returns a corresponding list of normpath
instances. [1]
path.
tangent
(params, length=1)¶Return a line
instance or a list of line
instances,
corresponding to the tangent vectors at the parameter value(s) params.
[2] The tangent vector will be scaled to the length length.
[1]
path.
trafo
(params)¶Returns a transformation or a list of tranformations, which translate the origin to a point on the path corresponding to parameter value(s) params and rotate the x-direction to the tangent vector and the y-direction to the normal vector. [1]
path.
transformed
(trafo)¶Returns the path transformed according to the linear transformation trafo.
Here, trafo
must be an instance of the trafo.trafo
class.
[1]
[1] | (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16) This method requires a prior conversion of the path into a normpath
instance. This is done automatically (using the precision epsilon set
globally using path.set() ). If you need a different epsilon for a
normpath, you also can perform the conversion manually. |
[2] | (1, 2, 3, 4, 5) In these methods, params may either be a single value or a
list. In the latter case, the result of the method will be a list consisting of
the results for each parameter. The parameter itself may either be a length
(or a number which is then interpreted as a user length) or an instance of the
class normpathparam . In the former case, the length refers to the arc
length along the path. |
The class pathitem
is the superclass of all PostScript path
construction primitives. It is never used directly, but only by instantiating
its subclasses, which correspond one by one to the PostScript primitives.
Except for the path elements ending in _pt
, all coordinates passed to the
path elements can be given as number (in which case they are interpreted as user
units with the currently set default type) or in PyX lengths.
The following operation move the current point and open a new subpath:
path.
moveto
(x, y)¶Path element which sets the current point to the absolute coordinates (x, y). This operation opens a new subpath.
path.
rmoveto
(dx, dy)¶Path element which moves the current point by (dx, dy). This operation opens a new subpath.
Drawing a straight line can be accomplished using:
path.
lineto
(x, y)¶Path element which appends a straight line from the current point to the point with absolute coordinates (x, y), which becomes the new current point.
path.
rlineto
(dx, dy)¶Path element which appends a straight line from the current point to the point with relative coordinates (dx, dy), which becomes the new current point.
For the construction of arc segments, the following three operations are available:
path.
arc
(x, y, r, angle1, angle2)¶Path element which appends an arc segment in counterclockwise direction with absolute coordinates (x, y) of the center and radius r from angle1 to angle2 (in degrees). If before the operation, the current point is defined, a straight line from the current point to the beginning of the arc segment is prepended. Otherwise, a subpath, which thus is the first one in the path, is opened. After the operation, the current point is at the end of the arc segment.
path.
arct
(x1, y1, x2, y2, r)¶Path element consisting of a line followed by an arc of radius r. The arc is part of the circle inscribed to the angle at x1, y1 given by lines in the directions to the current point and to x2, y2. The initial line connects the current point to the point where the circle touches the line through the current point and x1, y1. The arc then continues to the point where the circle touches the line through x1, y1 and x2, y2.
Bézier curves can be constructed using:
path.
curveto
(x1, y1, x2, y2, x3, y3)¶Path element which appends a Bézier curve with the current point as first control point and the other control points (x1, y1), (x2, y2), and (x3, y3).
path.
rcurveto
(dx1, dy1, dx2, dy2, dx3, dy3)¶Path element which appends a Bézier curve with the current point as first control point and the other control points defined relative to the current point by the coordinates (dx1, dy1), (dx2, dy2), and (dx3, dy3).
Note that when calculating the bounding box (see Sect. bbox
) of Bézier
curves, PyX uses for performance reasons the so-called control box, i.e., the
smallest rectangle enclosing the four control points of the Bézier curve. In
general, this is not the smallest rectangle enclosing the Bézier curve.
Finally, an open subpath can be closed using:
path.
closepath
¶Path element which closes the current subpath.
For performance reasons, two non-PostScript path elements are defined, which perform multiple identical operations:
path.
multilineto_pt
(points_pt)¶Path element which appends straight line segments starting from the current point and going through the list of points given in the points_pt argument. All coordinates have to be given in PostScript points.
path.
multicurveto_pt
(points_pt)¶Path element which appends Bézier curve segments starting from the current point. points_pt is a sequence of 6-tuples containing the coordinates of the two control points and the end point of a multicurveto segment.
normpath
¶The normpath
class is used internally for all non-trivial path
operations, cf. footnote [1] in Sect. Class path — PostScript-like paths.
It represents a path as a list of subpaths, which are
instances of the class normsubpath
. These normsubpath
s
themselves consist of a list of normsubpathitems
which are either
straight lines (normline
) or Bézier curves (normcurve
).
A given path p
can easily be converted to the corresponding
normpath
np
by:
np = p.normpath()
Additionally, the accuracy that is used in all normpath
calculations can be
specified by means of the argument epsilon, which defaults to
\(10^{-5}\), where units of PostScript points are understood. This default
value can also be changed using the module function path.set()
.
To construct a normpath
from a list of normsubpath
instances,
they are passed to the normpath
constructor:
path.
normpath
(normsubpaths=[])¶Construct a normpath
consisting of subnormpaths, which is a list of
subnormpath
instances.
Instances of normpath
offer all methods of regular path
instances,
which also have the same semantics. An exception are the methods append()
and extend()
. While they allow for adding of instances of
subnormpath
to the normpath
instance, they also keep the
functionality of a regular path and allow for regular path elements to be
appended. The latter are converted to the proper normpath representation during
addition.
In addition to the path
methods, a normpath
instance also
offers the following methods, which operate on the instance itself, i.e., modify
it in place.
normpath.
transform
(trafo)¶Transforms the normpath
instance according to the linear transformation
trafo.
Finally, we remark that the sum of a normpath
and a path
always yields a normpath
.
normsubpath
¶path.
normsubpath
(normsubpathitems=[], closed=0, epsilon=1e-5)¶Construct a normsubpath
consisting of normsubpathitems, which is a
list of normsubpathitem
instances. If closed is set, the
normsubpath
will be closed, thereby appending a straight line segment
from the first to the last point, if it is not already present. All calculations
with the normsubpath
are performed with an accuracy of epsilon
(in units of PostScript points).
Most normsubpath
methods behave like the ones of a path
.
Exceptions are:
normsubpath.
append
(anormsubpathitem)¶Append the normsubpathitem to the end of the normsubpath
instance.
This is only possible if the normsubpath
is not closed, otherwise an
NormpathException
is raised.
normsubpath.
extend
(normsubpathitems)¶Extend the normsubpath
instances by normsubpathitems, which has to be
a list of normsubpathitem
instances. This is only possible if the
normsubpath
is not closed, otherwise an NormpathException
is
raised.
normsubpath.
close
()¶Close the normsubpath
instance by appending a straight line
segment from the first to the last point, if not already present.
For convenience, some often used paths are already predefined. All of them are
subclasses of the path
class.
path.
line
(x0, y0, x1, y1)¶A straight line from the point (x0, y0) to the point (x1, y1).
path.
curve
(x0, y0, x1, y1, x2, y2, x3, y3)¶A Bézier curve with control points (x0, y0), \(\dots\), (x3, y3).
path.
rect
(x, y, w, h)¶A closed rectangle with lower left point (x, y), width w, and height h.
path.
circle
(x, y, r)¶A closed circle with center (x, y) and radius r.