manual/path.tex

   1 \section{Module \module{path}}
   2
   3 \sectionauthor{J\"org Lehmann}{joergl@users.sourceforge.net}
   4
   5 \label{path}
   6
   7 The \module{path} module defines several important classes which are
   8 documented in the present section.
   9
  10 \subsection{Class \class{path} --- PostScript-like paths}
  11
  12 \label{path:path}
  13
  14 \declaremodule{}{path}
  15
  16 \begin{classdesc}{path}{*pathitems}
  17 This class represents a PostScript like path consisting of the
  18 path elements \var{pathitems}.
  19
  20 All possible path items are described in Sect.~\ref{path:pathitem}.
  21 Note that there are restrictions on the first path element and likewise
  22 on each path element after a \class{closepath} directive. In both cases,
  23 no current point is defined and the path element has to be an instance
  24 of one of the following classes: \class{moveto}, \class{arc}, and
  25 \class{arcn}.
  26 \end{classdesc}
  27
  28 Instances of the class \class{path} provide the following
  29 methods (in alphabetic order):
  30
  31 \begin{methoddesc}{append}{pathitem}
  32 Appends a \var{pathitem} to the end of the path.
  33 \end{methoddesc}
  34
  35 \begin{methoddesc}{arclen}{}
  36 Returns the total arc length of the path.$^\dagger$
  37 \end{methoddesc}
  38
  39 \begin{methoddesc}{arclentoparam}{lengths}
  40   Returns the parameter value(s) corresponding to the arc length(s)
  41   \var{lengths}.$^\dagger$
  42 \end{methoddesc}
  43
  44 \begin{methoddesc}{at}{params}
  45   Returns the coordinates (as 2-tuple) of the path point(s)
  46   corresponding to the parameter value(s) \var{params}.$^\ddagger$
  47   $^\dagger$
  48 \end{methoddesc}
  49
  50 \begin{methoddesc}{atbegin}{}
  51   Returns the coordinates (as 2-tuple) of the first point of the path.$^\dagger$
  52 \end{methoddesc}
  53
  54 \begin{methoddesc}{atend}{}
  55   Returns the coordinates (as 2-tuple) of the end point of the path.$^\dagger$
  56 \end{methoddesc}
  57
  58 \begin{methoddesc}{bbox}{}
  59   Returns the bounding box of the path. Note that this returned
  60   bounding box may be too large, if the path contains any
  61   \class{curveto} elements, since for these the control box, i.e., the
  62   bounding box enclosing the control points of the B\'ezier curve is
  63   returned.
  64 \end{methoddesc}
  65
  66 \begin{methoddesc}{begin}{}
  67   Returns the parameter value (a \class{normpathparam} instance) of
  68   the first point in the path.
  69 \end{methoddesc}
  70
  71 \begin{methoddesc}{curveradius}{param=None, arclen=None}
  72   Returns the curvature radius/radii (or None if infinite) at parameter
  73   value(s) params.$^\ddagger$ This is the inverse of the curvature at
  74   this parameter. Note that this radius can be negative or positive,
  75   depending on the sign of the curvature.$^\dagger$
  76 \end{methoddesc}
  77
  78 \begin{methoddesc}{end}{}
  79   Returns the parameter value (a \class{normpathparam} instance) of
  80   the last point in the path.
  81 \end{methoddesc}
  82
  83 \begin{methoddesc}{extend}{pathitems}
  84 Appends the list \var{pathitems} to the end of the path.
  85 \end{methoddesc}
  86
  87 \begin{methoddesc}{intersect}{opath}
  88   Returns a tuple consisting of two lists of parameter values
  89   corresponding to the intersection points of the path with the other
  90   path \var{opath}, respectively.$^\dagger$ For intersection points which
  91   are not farther apart then \var{epsilon} points, only one is returned.
  92 \end{methoddesc}
  93
  94 \begin{methoddesc}{joined}{opath}
  95   Appends \var{opath} to the end of the path, thereby merging the last
  96   subpath (which must not be closed) of the path with the first sub
  97   path of \var{opath} and returns the resulting new path.$^\dagger$
  98 \end{methoddesc}
  99
 100 \begin{methoddesc}{normpath}{epsilon=None}
 101   Returns the equivalent \class{normpath}. For the conversion and for later
 102   calculations with this \class{normpath} and accuracy of
 103   \var{epsilon} points is used. If \var{epsilon} is \var{None}, the
 104   global \var{epsilon} of the \module{path} module is used.
 105 \end{methoddesc}
 106
 107 \begin{methoddesc}{paramtoarclen}{params}
 108   Returns the arc length(s) corresponding to the parameter value(s)
 109   \var{params}.$^\ddagger$ $^\dagger$
 110 \end{methoddesc}
 111
 112
 113 \begin{methoddesc}{range}{}
 114   Returns the maximal parameter value \var{param} that is allowed in the
 115   path methods.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}{reversed}{}
 119   Returns the reversed path.$^\dagger$
 120 \end{methoddesc}
 121
 122 \begin{methoddesc}{split}{params}
 123   Splits the path at the parameter values \var{params}, which have to
 124   be sorted in ascending order, and returns a corresponding list of
 125   \class{normpath} instances.$^\dagger$
 126 \end{methoddesc}
 127
 128 \begin{methoddesc}{tangent}{params, length=None}
 129   Return (a) \class{line} instance(s) corresponding to the tangent
 130   vector(s) to the path at the parameter value(s)
 131   \var{params}.$^\ddagger$ If \var{length} is not \texttt{None}, the
 132   tangent vector will be scaled correspondingly.$^\dagger$
 133 \end{methoddesc}
 134
 135
 136 \begin{methoddesc}{trafo}{params}
 137   Returns (a) trafo(s) which maps a point $(0, 1)$ to the tangent vector to
 138   the path at the parameter value(s) \var{params}.$^\ddagger$ $^\dagger$
 139 \end{methoddesc}
 140
 141 \begin{methoddesc}{transformed}{trafo}
 142   Returns the path transformed according to the linear transformation
 143   \var{trafo}. Here, \texttt{trafo} must be an instance of the
 144   \class{trafo.trafo} class.$^\dagger$
 145 \end{methoddesc}
 146
 147 Some notes on the above:
 148 \begin{itemize}
 149 \item The $\dagger$ denotes methods which require a prior
 150   conversion of the path into a \class{normpath} instance. This is
 151   done automatically (using the precision \var{epsilon} set globally
 152   using \method{path.set}). If you need a different \var{epsilon} for
 153   a normpath, you also can perform the conversion manually.
 154 \item Instead of using the \method{joined()} method, you can also join two
 155 paths together with help of the \verb|<<| operator, for instance
 156 \samp{p = p1 << p2}.
 157 \item $^\ddagger$ In these methods, \var{params} may either be a
 158   single value or a list. In the latter case, the result of the method
 159   will be a list consisting of the results for every parameter.  The
 160   parameter itself may either be a length (or a number which is then
 161   interpreted as a user length) or an instance of the class
 162   \class{normpathparam}. In the former case, the length refers to the
 163   arc length along the path.
 164 \end{itemize}
 165
 166 \subsection{Path elements}
 167
 168 \label{path:pathitem}
 169
 170 The class \class{pathitem} is the superclass of all PostScript path
 171 construction primitives. It is never used directly, but only by
 172 instantiating its subclasses, which correspond one by one to the
 173 PostScript primitives.
 174
 175 Except for the path elements ending in \code{_pt}, all coordinates
 176 passed to the path elements can be given as number (in which case they
 177 are interpreted as user units with the currently set default type) or in
 178 \PyX\ lengths.
 179
 180 The following operation move the current point and open a new subpath:
 181
 182 \begin{classdesc}{moveto}{x, y}
 183 Path element which sets the current point to the absolute coordinates (\var{x},
 184 \var{y}). This operation opens a new subpath.
 185 \end{classdesc}
 186
 187 \begin{classdesc}{rmoveto}{dx, dy}
 188 Path element which moves the current point by (\var{dx}, \var{dy}).
 189 This operation opens a new subpath.
 190 \end{classdesc}
 191
 192 Drawing a straight line can be accomplished using:
 193
 194 \begin{classdesc}{lineto}{x, y}
 195 Path element which appends a straight line from the current point to the
 196 point with absolute coordinates (\var{x}, \var{y}), which becomes
 197 the new current point.
 198 \end{classdesc}
 199
 200 \begin{classdesc}{rlineto}{dx, dy}
 201 Path element which appends a straight line from the current point to the
 202 a point with relative coordinates (\var{dx}, \var{dy}), which becomes
 203 the new current point.
 204 \end{classdesc}
 205
 206 For the construction of arc segments, the following three operations
 207 are available:
 208
 209 \begin{classdesc}{arc}{x, y, r, angle1, angle2}
 210 Path element which appends an arc segment in counterclockwise direction
 211 with absolute coordinates (\var{x}, \var{y}) of the center and
 212 radius \var{r} from \var{angle1} to \var{angle2} (in degrees).
 213 If before the operation, the current point is defined, a straight line
 214 is from the current point to the beginning of the arc segment is
 215 prepended. Otherwise, a subpath, which thus is the first one in the
 216 path, is opened. After the operation, the current point is at the end
 217 of the arc segment.
 218 \end{classdesc}
 219
 220 \begin{classdesc}{arcn}{x, y, r, angle1, angle2}
 221 Path element which appends an arc segment in clockwise direction
 222 with absolute coordinates (\var{x}, \var{y}) of the center and
 223 radius \var{r} from \var{angle1} to \var{angle2} (in degrees).
 224 If before the operation, the current point is defined, a straight line
 225 is from the current point to the beginning of the arc segment is
 226 prepended. Otherwise, a subpath, which thus is the first one in the
 227 path, is opened. After the operation, the current point is at the end
 228 of the arc segment.
 229 \end{classdesc}
 230
 231 \begin{classdesc}{arct}{x1, y1, x2, y2, r}
 232 Path element which appends an arc segment of radius \var{r}
 233 connecting between (\var{x1}, \var{y1}) and (\var{x2}, \var{y2}).\\
 234 \end{classdesc}
 235
 236 B\'ezier curves can be constructed using: \
 237
 238 \begin{classdesc}{curveto}{x1, y1, x2, y2, x3, y3}
 239 Path element which appends a B\'ezier curve with
 240 the current point as first control point and the other control points
 241 (\var{x1}, \var{y1}), (\var{x2}, \var{y2}), and (\var{x3}, \var{y3}).
 242 \end{classdesc}
 243
 244 \begin{classdesc}{rcurveto}{dx1, dy1, dx2, dy2, dx3, dy3}
 245 Path element which appends a B\'ezier curve with
 246 the current point as first control point and the other control points
 247 defined relative to the current point by the coordinates
 248 (\var{dx1}, \var{dy1}), (\var{dx2}, \var{dy2}), and (\var{dx3}, \var{dy3}).
 249 \end{classdesc}
 250
 251 Note that when calculating the bounding box (see Sect.~\ref{bbox}) of
 252 B\'ezier curves, \PyX{} uses for performance reasons the so-called
 253 control box, i.e., the smallest rectangle enclosing the four control
 254 points of the B\'ezier curve. In general, this is not the smallest
 255 rectangle enclosing the B\'ezier curve.
 256
 257 Finally, an open subpath can be closed using:
 258
 259 \begin{classdesc}{closepath}{}
 260 Path element which closes the current subpath.
 261 \end{classdesc}
 262
 263 For performance reasons, two non-PostScript path elements are defined,
 264 which perform multiple identical operations:
 265
 266 \begin{classdesc}{multilineto_pt}{points_pt}
 267 Path element which appends straight line segments starting from
 268 the current point and going through the list of points given
 269 in the \var{points_pt} argument. All coordinates have to
 270 be given in PostScript points.
 271 \end{classdesc}
 272
 273 \begin{classdesc}{multicurveto_pt}{points_pt}
 274 Path element which appends B\'ezier curve segments starting from
 275 the current point and going through the list of each three control
 276 points given in the \var{points_pt} argument.
 277 \end{classdesc}
 278
 279
 280 \subsection{Class \class{normpath}}
 281
 282 \label{path:normpath}
 283
 284 The \class{normpath} class is used internally for all non-trivial path
 285 operations, i.e. the ones marked by a $\dagger$ in the description of
 286 the \class{path} above. It represents a path as a list of subpaths, which are
 287 instances of the class \class{normsubpath}. These \class{normsubpath}s
 288 themselves consist of a list of \class{normsubpathitems} which are
 289 either straight lines (\class{normline}) or B\'ezier curves
 290 (\class{normcurve}).
 291
 292 A given path can easily be converted to the corresponding \class{normpath}
 293 using the method with this name:
 294 \begin{verbatim}
 295 np = p.normpath()
 296 \end{verbatim}
 297 Additionally, you can specify the accuracy (in points) which is used
 298 in all \class{normpath} calculations by means of the argument
 299 \var{epsilon}, which defaults to to $10^{-5}$ points. This default
 300 value can be changed using the module function \function{path.set}.
 301
 302 To construct a \class{normpath} from a list of \class{normsubpath}
 303 instances, you pass them to the \class{normpath} constructor:
 304
 305 \begin{classdesc}{normpath}{normsubpaths=[]}
 306   Construct a \class{normpath} consisting of \var{subnormpaths}, which
 307   is a list of \class{subnormpath} instances.
 308 \end{classdesc}
 309
 310 Instances of \class{normpath} offers all methods of regular
 311 \class{path}s, which also have the same semantics. An exception are
 312 the methods \method{append} and \method{extend}. While they allow for
 313 adding of instances of \class{subnormpath} to the \class{normpath}
 314 instance, they also keep the functionality of a regular path and allow
 315 for regular path elements to be appended. The later are converted to
 316 the proper normpath representation during addition.
 317
 318 In addition to the \class{path} methods, a \class{normpath} instance
 319 also offers the following methods, which operate on the instance
 320 itself, i.e., modify it in place.
 321
 322 \begin{methoddesc}{join}{other}
 323   Join \var{other}, which has to be a \class{path} instance, to
 324   the \class{normpath} instance.
 325 \end{methoddesc}
 326
 327 \begin{methoddesc}{reverse}{}
 328   Reverses the \class{normpath} instance.
 329 \end{methoddesc}
 330
 331 \begin{methoddesc}{transform}{trafo}
 332   Transforms the \class{normpath} instance according to the linear
 333   transformation \var{trafo}.
 334 \end{methoddesc}
 335
 336 Finally, we remark that the sum of a \class{normpath} and a \class{path}
 337 always yields a \class{normpath}.
 338
 339
 340 \subsection{Class \class{normsubpath}}
 341
 342 \begin{classdesc}{normsubpath}{normsubpathitems=[], closed=0,
 343     epsilon=1e-5}
 344   Construct a \class{normsubpath} consisting of
 345   \var{normsubpathitems}, which is a list of \class{normsubpathitem}
 346   instances. If \var{closed} is set, the \class{normsubpath} will be
 347   closed, thereby appending a straight line segment from the first to
 348   the last point, if it is not already present. All calculations with
 349   the \class{normsubpath} are performed with an accuracy of \var{epsilon}.
 350 \end{classdesc}
 351
 352 Most \class{normsubpath} methods behave like the ones of a
 353 \class{path}.
 354
 355 Exceptions are:
 356
 357 \begin{methoddesc}{append}{anormsubpathitem}
 358   Append the \var{anormsubpathitem} to the end of the
 359   \class{normsubpath} instance. This is only possible if the
 360   \class{normsubpath} is not closed, otherwise an exception is raised.
 361 \end{methoddesc}
 362
 363 \begin{methoddesc}{extend}{normsubpathitems}
 364   Extend the \class{normsubpath} instances by \var{normsubpathitems},
 365   which has to be a list of \class{normsubpathitem} instances. This is
 366   only possible if the \class{normsubpath} is not closed, otherwise an
 367   exception is raised.
 368 \end{methoddesc}
 369
 370 \begin{methoddesc}{close}{}
 371   Close the \class{normsubpath} instance, thereby appending a straight
 372   line segment from the first to the last point, if it is not already
 373   present.
 374 \end{methoddesc}
 375
 376 \subsection{Predefined paths}
 377
 378 \label{path:predefined}
 379
 380 For convenience, some oft-used paths are already predefined. All
 381 of them are subclasses of the \class{path} class.
 382
 383 \begin{classdesc}{line}{x0, y0, x1, y1}
 384 A straight line from the point (\var{x0}, \var{y0}) to the point (\var{x1}, \var{y1}).
 385 \end{classdesc}
 386
 387 \begin{classdesc}{curve}{x0, y0, x1, y1, x2, y2, x3, y3}
 388 A B\'ezier curve with
 389 control points  (\var{x0}, \var{y0}), $\dots$, (\var{x3}, \var{y3}).\
 390 \end{classdesc}
 391
 392 \begin{classdesc}{rect}{x, y, w, h}
 393 A closed rectangle with lower left point (\var{x}, \var{y}), width \var{w}, and
 394   height \var{h}.
 395 \end{classdesc}
 396
 397 \begin{classdesc}{circle}{x, y, r}
 398 A closed circle with center (\var{x}, \var{y}) and radius \var{r}.
 399 \end{classdesc}
 400
 401 %%% Local Variables:
 402 %%% mode: latex
 403 %%% TeX-master: "manual.tex"
 404 %%% ispell-dictionary: "british"
 405 %%% End: