37
40
.. method:: path.arclen()
39
Returns the total arc length of the path.\ :math:`^\dagger`
42
Returns the total arc length of the path. [#normpathconvert]_
42
45
.. method:: path.arclentoparam(lengths)
44
Returns the parameter value(s) corresponding to the arc length(s) *lengths*.\
47
Returns the parameter value(s) corresponding to the arc length(s) *lengths*.
48
51
.. method:: path.at(params)
50
53
Returns the coordinates (as 2-tuple) of the path point(s) corresponding to the
51
parameter value(s) *params*.\ :math:`^\ddagger` :math:`^\dagger`
54
parameter value(s) *params*. [#normpathconvert]_ [#value_or_list]_
54
57
.. method:: path.atbegin()
56
Returns the coordinates (as 2-tuple) of the first point of the path.\
59
Returns the coordinates (as 2-tuple) of the first point of the path. [#normpathconvert]_
60
62
.. method:: path.atend()
62
Returns the coordinates (as 2-tuple) of the end point of the path.\
64
Returns the coordinates (as 2-tuple) of the end point of the path. [#normpathconvert]_
66
67
.. method:: path.bbox()
68
Returns the bounding box of the path. Note that this returned bounding box may
69
be too large, if the path contains any :class:`curveto` elements, since for
70
these the control box, i.e., the bounding box enclosing the control points of
71
the Bézier curve is returned.
69
Returns the bounding box of the path.
74
72
.. method:: path.begin()
99
97
.. method:: path.intersect(opath)
101
99
Returns a tuple consisting of two lists of parameter values corresponding to the
102
intersection points of the path with the other path *opath*, respectively.\
103
:math:`^\dagger` For intersection points which are not farther apart then
104
*epsilon* points, only one is returned.
100
intersection points of the path with the other path *opath*, respectively.
101
[#normpathconvert]_ For intersection points which are not farther apart then
102
*epsilon* (defaulting to :math:`10^{-5}` PostScript points), only one is returned.
107
105
.. method:: path.joined(opath)
109
107
Appends *opath* to the end of the path, thereby merging the last subpath (which
110
108
must not be closed) of the path with the first sub path of *opath* and returns
111
the resulting new path.\ :math:`^\dagger`
109
the resulting new path. [#normpathconvert]_ Instead of using the
110
:meth:`joined` method, you can also join two paths together with help of the
111
``<<`` operator, for instance ``p = p1 << p2``.
114
114
.. method:: path.normpath(epsilon=None)
116
116
Returns the equivalent :class:`normpath`. For the conversion and for later
117
calculations with this :class:`normpath` and accuracy of *epsilon* points is
118
used. If *epsilon* is *None*, the global *epsilon* of the :mod:`path` module is
117
calculations with this :class:`normpath` an accuracy of *epsilon* is used.
118
If *epsilon* is *None*, the global *epsilon* of the :mod:`path` module is
122
122
.. method:: path.paramtoarclen(params)
124
Returns the arc length(s) corresponding to the parameter value(s) *params*.\
125
:math:`^\ddagger` :math:`^\dagger`
124
Returns the arc length(s) corresponding to the parameter value(s) *params*.
125
[#value_or_list]_ [#normpathconvert]_
128
128
.. method:: path.range()
133
133
.. method:: path.reversed()
135
Returns the reversed path.\ :math:`^\dagger`
135
Returns the reversed path. [#normpathconvert]_
138
138
.. method:: path.rotation(params)
140
Returns (a) rotations(s) which (each), which rotate the x-direction to the
141
tangent and the y-direction to the normal at that param.\ :math:`^\dagger`
140
Returns a transformation or a list of transformations, which rotate the
141
x-direction to the tangent vector and the y-direction to the normal vector
142
at the parameter value(s) *params*. [#value_or_list]_ [#normpathconvert]_
144
145
.. method:: path.split(params)
146
147
Splits the path at the parameter values *params*, which have to be sorted in
147
148
ascending order, and returns a corresponding list of :class:`normpath`
148
instances.\ :math:`^\dagger`
149
instances. [#normpathconvert]_
151
152
.. method:: path.tangent(params, length=1)
153
Return (a) :class:`line` instance(s) corresponding to the tangent vector(s) to
154
the path at the parameter value(s) *params*.\ :math:`^\ddagger` The tangent
155
vector will be scaled to the length *length*.\ :math:`^\dagger`
154
Return a :class:`line` instance or a list of :class:`line` instances,
155
corresponding to the tangent vectors at the parameter value(s) *params*.
156
[#value_or_list]_ The tangent vector will be scaled to the length *length*.
158
160
.. method:: path.trafo(params)
160
Returns (a) trafo(s) which (each) translate to a point on the path corresponding
161
to the param, rotate the x-direction to the tangent and the y-direction to the
162
normal in that point.\ :math:`^\dagger`
162
Returns a transformation or a list of tranformations, which translate the
163
origin to a point on the path corresponding to parameter value(s) *params*
164
and rotate the x-direction to the tangent vector and the y-direction to the
165
normal vector. [#normpathconvert]_
165
168
.. method:: path.transformed(trafo)
167
170
Returns the path transformed according to the linear transformation *trafo*.
168
Here, ``trafo`` must be an instance of the :class:`trafo.trafo` class.\
171
Some notes on the above:
173
* The :math:`\dagger` denotes methods which require a prior conversion of the
174
path into a :class:`normpath` instance. This is done automatically (using the
175
precision *epsilon* set globally using :meth:`path.set`). If you need a
176
different *epsilon* for a normpath, you also can perform the conversion
179
* Instead of using the :meth:`joined` method, you can also join two paths
180
together with help of the ``<<`` operator, for instance ``p = p1 << p2``.
182
* :math:`^\ddagger` In these methods, *params* may either be a single value or a
183
list. In the latter case, the result of the method will be a list consisting of
184
the results for every parameter. The parameter itself may either be a length
185
(or a number which is then interpreted as a user length) or an instance of the
186
class :class:`normpathparam`. In the former case, the length refers to the arc
187
length along the path.
171
Here, ``trafo`` must be an instance of the :class:`trafo.trafo` class.
175
.. [#normpathconvert]
176
This method requires a prior conversion of the path into a :class:`normpath`
177
instance. This is done automatically (using the precision *epsilon* set
178
globally using :meth:`path.set`). If you need a different *epsilon* for a
179
normpath, you also can perform the conversion manually.
182
In these methods, *params* may either be a single value or a
183
list. In the latter case, the result of the method will be a list consisting of
184
the results for each parameter. The parameter itself may either be a length
185
(or a number which is then interpreted as a user length) or an instance of the
186
class :class:`normpathparam`. In the former case, the length refers to the arc
187
length along the path.
190
190
.. _path_pathitem:
237
237
Path element which appends an arc segment in counterclockwise direction with
238
238
absolute coordinates (*x*, *y*) of the center and radius *r* from *angle1* to
239
239
*angle2* (in degrees). If before the operation, the current point is defined, a
240
straight line is from the current point to the beginning of the arc segment is
240
straight line from the current point to the beginning of the arc segment is
241
241
prepended. Otherwise, a subpath, which thus is the first one in the path, is
242
242
opened. After the operation, the current point is at the end of the arc segment.
245
245
.. class:: arcn(x, y, r, angle1, angle2)
247
Path element which appends an arc segment in clockwise direction with absolute
248
coordinates (*x*, *y*) of the center and radius *r* from *angle1* to *angle2*
249
(in degrees). If before the operation, the current point is defined, a straight
250
line is from the current point to the beginning of the arc segment is prepended.
251
Otherwise, a subpath, which thus is the first one in the path, is opened. After
252
the operation, the current point is at the end of the arc segment.
247
Same as :class:`arc` but in clockwise direction.
255
250
.. class:: arct(x1, y1, x2, y2, r)
257
Path element which appends an arc segment of radius *r* connecting between
258
(*x1*, *y1*) and (*x2*, *y2*). ---
260
Bézier curves can be constructed using: \
252
Path element consisting of a line followed by an arc of radius *r*. The arc
253
is part of the circle inscribed to the angle at *x1*, *y1* given by lines in
254
the directions to the current point and to *x2*, *y2*. The initial line
255
connects the current point to the point where the circle touches the line
256
through the current point and *x1*, *y1*. The arc then continues to the
257
point where the circle touches the line through *x1*, *y1* and *x2*, *y2*.
259
Bézier curves can be constructed using:
263
261
.. class:: curveto(x1, y1, x2, y2, x3, y3)
292
290
.. class:: multilineto_pt(points_pt)
294
292
Path element which appends straight line segments starting from the current
295
point and going through the list of points given in the *points_pt* argument.
296
All coordinates have to be given in PostScript points.
293
point and going through the list of points given in the *points_pt*
294
argument. All coordinates have to be given in PostScript points.
299
297
.. class:: multicurveto_pt(points_pt)
301
Path element which appends Bézier curve segments starting from the current point
302
and going through the list of each three control points given in the *points_pt*
303
argument. Thus, *points_pt* must be a sequence of 6-tuples.
299
Path element which appends Bézier curve segments starting from the current
300
point. *points_pt* is a sequence of 6-tuples containing the coordinates of
301
the two control points and the end point of a multicurveto segment.
306
304
.. _path_normpath:
309
307
-----------------------
311
309
The :class:`normpath` class is used internally for all non-trivial path
312
operations, i.e. the ones marked by a :math:`\dagger` in the description of the
313
:class:`path` above. It represents a path as a list of subpaths, which are
310
operations, cf. footnote [#normpathconvert]_ in Sect. :ref:`postscript_like_paths`.
311
It represents a path as a list of subpaths, which are
314
312
instances of the class :class:`normsubpath`. These :class:`normsubpath`\ s
315
313
themselves consist of a list of :class:`normsubpathitems` which are either
316
314
straight lines (:class:`normline`) or Bézier curves (:class:`normcurve`).
318
A given path can easily be converted to the corresponding :class:`normpath`
319
using the method with this name::
316
A given path ``p`` can easily be converted to the corresponding
317
:class:`normpath` ``np`` by::
321
319
np = p.normpath()
323
Additionally, you can specify the accuracy (in points) which is used in all
324
:class:`normpath` calculations by means of the argument *epsilon*, which
325
defaults to to :math:`10^{-5}` points. This default value can be changed using
326
the module function :func:`path.set`.
321
Additionally, the accuracy is used in all :class:`normpath` calculations can be
322
specified by means of the argument *epsilon*, which defaults to to
323
:math:`10^{-5}` where units of PostScript points are understood. This default
324
value can be changed using the module function :func:`path.set`.
328
326
To construct a :class:`normpath` from a list of :class:`normsubpath` instances,
329
you pass them to the :class:`normpath` constructor:
327
they are passed to the :class:`normpath` constructor:
332
329
.. class:: normpath(normsubpaths=[])
334
331
Construct a :class:`normpath` consisting of *subnormpaths*, which is a list of
335
332
:class:`subnormpath` instances.
337
Instances of :class:`normpath` offers all methods of regular :class:`path`\ s,
334
Instances of :class:`normpath` offer all methods of regular :class:`path` instances,
338
335
which also have the same semantics. An exception are the methods :meth:`append`
339
336
and :meth:`extend`. While they allow for adding of instances of
340
337
:class:`subnormpath` to the :class:`normpath` instance, they also keep the
341
338
functionality of a regular path and allow for regular path elements to be
342
appended. The later are converted to the proper normpath representation during
339
appended. The latter are converted to the proper normpath representation during
345
342
In addition to the :class:`path` methods, a :class:`normpath` instance also
387
385
.. method:: normsubpath.append(anormsubpathitem)
389
Append the *anormsubpathitem* to the end of the :class:`normsubpath` instance.
387
Append the *normsubpathitem* to the end of the :class:`normsubpath` instance.
390
388
This is only possible if the :class:`normsubpath` is not closed, otherwise an
389
:exc:`NormpathException` is raised.
394
392
.. method:: normsubpath.extend(normsubpathitems)
396
394
Extend the :class:`normsubpath` instances by *normsubpathitems*, which has to be
397
395
a list of :class:`normsubpathitem` instances. This is only possible if the
398
:class:`normsubpath` is not closed, otherwise an exception is raised.
396
:class:`normsubpath` is not closed, otherwise an :exc:`NormpathException` is
401
400
.. method:: normsubpath.close()
403
Close the :class:`normsubpath` instance, thereby appending a straight line
404
segment from the first to the last point, if it is not already present.
402
Close the :class:`normsubpath` instance by appending a straight line
403
segment from the first to the last point, if not already present.
407
406
.. _path_predefined:
added
removed
manual/path.rst
