Module path

Section author: Jörg Lehmann <joergl@users.sourceforge.net>

The path module defines several important classes which are documented in the present section.

Class path — PostScript-like paths

class 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.arclen()

Returns the total arc length of the path.:math:`^\dagger`

path.arclentoparam(lengths)

Returns the parameter value(s) corresponding to the arc length(s) lengths.:math:`^\dagger`

path.at(params)

Returns the coordinates (as 2-tuple) of the path point(s) corresponding to the parameter value(s) params.:math:`^\ddagger` :math:`^\dagger`

path.atbegin()

Returns the coordinates (as 2-tuple) of the first point of the path.:math:`^\dagger`

path.atend()

Returns the coordinates (as 2-tuple) of the end point of the path.:math:`^\dagger`

path.bbox()

Returns the bounding box of the path. Note that this returned bounding box may be too large, if the path contains any curveto elements, since for these the control box, i.e., the bounding box enclosing the control points of the Bézier curve is returned.

path.begin()

Returns the parameter value (a normpathparam instance) of the first point in the path.

path.curveradius(param=None, arclen=None)

Returns the curvature radius/radii (or None if infinite) at parameter value(s) params.:math:`^\ddagger` 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.:math:`^\dagger`

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.:math:`^\dagger` For intersection points which are not farther apart then epsilon 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.:math:`^\dagger`

path.normpath(epsilon=None)

Returns the equivalent normpath. For the conversion and for later calculations with this normpath and accuracy of epsilon points 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.:math:`^\ddagger` :math:`^\dagger`

path.range()

Returns the maximal parameter value param that is allowed in the path methods.

path.reversed()

Returns the reversed path.:math:`^\dagger`

path.rotation(params)

Returns (a) rotations(s) which (each), which rotate the x-direction to the tangent and the y-direction to the normal at that param.:math:`^\dagger`

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.:math:`^\dagger`

path.tangent(params, length=1)

Return (a) line instance(s) corresponding to the tangent vector(s) to the path at the parameter value(s) params.:math:`^\ddagger` The tangent vector will be scaled to the length length.:math:`^\dagger`

path.trafo(params)

Returns (a) trafo(s) which (each) translate to a point on the path corresponding to the param, rotate the x-direction to the tangent and the y-direction to the normal in that point.:math:`^\dagger`

path.transformed(trafo)

Returns the path transformed according to the linear transformation trafo. Here, trafo must be an instance of the trafo.trafo class.:math:`^\dagger`

Some notes on the above:

  • The :math:`\dagger` denotes methods which require 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.
  • Instead of using the joined() method, you can also join two paths together with help of the << operator, for instance p = p1 << p2.
  • :math:`^\ddagger` 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 every 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.

Path elements

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:

class path.moveto(x, y)

Path element which sets the current point to the absolute coordinates (x, y). This operation opens a new subpath.

class 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:

class 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.

class path.rlineto(dx, dy)

Path element which appends a straight line from the current point to the a point with relative coordinates (dx, dy), which becomes the new current point.

For the construction of arc segments, the following three operations are available:

class 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 is 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.

class path.arcn(x, y, r, angle1, angle2)

Path element which appends an arc segment in clockwise 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 is 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.

class path.arct(x1, y1, x2, y2, r)

Path element which appends an arc segment of radius r connecting between (x1, y1) and (x2, y2). —

Bézier curves can be constructed using:

class 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).

class 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:

class path.closepath

Path element which closes the current subpath.

For performance reasons, two non-PostScript path elements are defined, which perform multiple identical operations:

class 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.

class path.multicurveto_pt(points_pt)

Path element which appends Bézier curve segments starting from the current point and going through the list of each three control points given in the points_pt argument. Thus, points_pt must be a sequence of 6-tuples.

Class normpath

The normpath class is used internally for all non-trivial path operations, i.e. the ones marked by a :math:`\dagger` in the description of the path above. It represents a path as a list of subpaths, which are instances of the class normsubpath. These normsubpaths themselves consist of a list of normsubpathitems which are either straight lines (normline) or Bézier curves (normcurve).

A given path can easily be converted to the corresponding normpath using the method with this name:

np = p.normpath()

Additionally, you can specify the accuracy (in points) which is used in all normpath calculations by means of the argument epsilon, which defaults to to :math:`10^{-5}` points. This default value can be changed using the module function path.set().

To construct a normpath from a list of normsubpath instances, you pass them to the normpath constructor:

class path.normpath(normsubpaths=[])

Construct a normpath consisting of subnormpaths, which is a list of subnormpath instances.

Instances of normpath offers all methods of regular paths, 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 later 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.join(other)

Join other, which has to be a path instance, to the normpath instance.

normpath.reverse()

Reverses the normpath instance.

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.

Class normsubpath

class 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.

Most normsubpath methods behave like the ones of a path.

Exceptions are:

normsubpath.append(anormsubpathitem)

Append the anormsubpathitem to the end of the normsubpath instance. This is only possible if the normsubpath is not closed, otherwise an exception 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 exception is raised.

normsubpath.close()

Close the normsubpath instance, thereby appending a straight line segment from the first to the last point, if it is not already present.

Predefined paths

For convenience, some oft-used paths are already predefined. All of them are subclasses of the path class.

class path.line(x0, y0, x1, y1)

A straight line from the point (x0, y0) to the point (x1, y1).

class path.curve(x0, y0, x1, y1, x2, y2, x3, y3)

A Bézier curve with control points (x0, y0), :math:`\dots`, (x3, y3).

class path.rect(x, y, w, h)

A closed rectangle with lower left point (x, y), width w, and height h.

class path.circle(x, y, r)

A closed circle with center (x, y) and radius r.

Table Of Contents

Previous topic

Basic graphics

Next topic

Module deformer: Path deformers

This Page