manual/path.tex

   1 \chapter{Module path: PostScript like paths}
   2
   3 \label{path}
   4
   5 With the help of the path module it is possible to construct PostScript like
   6 paths, which are one of the main building blocks for the generation of
   7 drawings. To that end it provides
   8 \begin{itemize}
   9 \item classes (derived from \verb|pathel|) for the primitives \verb|moveto|, \verb|lineto|, etc.
  10 \item the class \verb|path| (and derivatives thereof) representing an
  11   entire PostScript path
  12 \item the class \verb|normpath| (and derivatives thereof) which is a
  13   path consisting only of a certain subset of \verb|pathel|s, namely
  14   the four \verb|normpathel|s \verb|moveto|, \verb|lineto|,
  15   \verb|curveto| and \verb|closepath|.
  16 \end{itemize}
  17
  18 \section{Class pathel}
  19
  20 The class \verb|pathel| is the superclass of all PostScript path
  21 construction primitives. It is never used directly, but only by
  22 instantiating its subclasses, which correspond one by one to the
  23 PostScript primitives.
  24
  25 \medskip
  26 \begin{tabularx}{\linewidth}{>{\hsize=.7\hsize}X>{\raggedright\arraybackslash\hsize=1.3\hsize}X}
  27 Subclass of \texttt{pathel} & function \\
  28 \hline
  29 \texttt{closepath()} & closes current subpath \\
  30 \texttt{moveto(x, y)} & sets current point to (\texttt{x},
  31 \texttt{y})\\
  32 \texttt{rmoveto(dx, dy)} & moves current point by (\texttt{dx},
  33 \texttt{dy})\\
  34 \texttt{lineto(x, y)} & moves current point to (\texttt{x}, \texttt{y})
  35 while drawing a straight line\\
  36 \texttt{rlineto(dx, dy)} & moves current point by by (\texttt{dx}, \texttt{dy})
  37 while drawing a straight line\\
  38 \texttt{arc(x, y, r, \newline\phantom{arc(}angle1, angle2)} & appends arc segment in
  39 counterclockwise direction with center (\texttt{x}, \texttt{y}) and
  40 radius~\texttt{r} from \texttt{angle1} to \texttt{angle2} (in degrees).\\
  41 \texttt{arcn(x, y, r, \newline\phantom{arcn(}angle1, angle2)} & appends arc segment in
  42 clockwise direction with center (\texttt{x}, \texttt{y}) and
  43 radius~\texttt{r} from \texttt{angle1} to \texttt{angle2} (in degrees). \\
  44 \texttt{arct(x1, y1, x2, y2, r)} & appends arc segment of radius \texttt{r}
  45 connecting between (\texttt{x1}, \texttt{y1}) and (\texttt{x2}, \texttt{y2}).\\
  46 \texttt{rcurveto(dx1, dy1, \newline\phantom{rcurveto(}dx2, dy2,\newline\phantom{rcurveto(}dx3, dy3)} & appends a B\'ezier curve with
  47 the following four control points: current point and the points defined
  48 relative to the current point by (\texttt{dx1}, \texttt{dy1}),
  49 (\texttt{dx2}, \texttt{dy2}), and (\texttt{dx3}, \texttt{dy3})
  50 \end{tabularx}
  51 \medskip
  52
  53 Some notes on the above:
  54 \begin{itemize}
  55 \item All coordinates are in \PyX\ lengths
  56 \item If the current point is defined before an \verb|arc| or
  57   \verb|arcn| command, a straight line from current point to the
  58   beginning of the arc is prepended.
  59 \item The bounding box (see below) of B\'ezier curves is actually
  60   the box enclosing the control points, \textit{i.e.}\ not neccesarily the
  61   smallest rectangle enclosing the B\'ezier curve.
  62 \end{itemize}
  63
  64
  65 \section{Class path}
  66
  67 The class path represents PostScript like paths in \PyX. The \verb|path|
  68 constructor allows the creation of such a path out of a series of
  69 \verb|pathel|s. The following simple example generates a triangle:
  70 looks like:
  71 \begin{quote}
  72 \begin{verbatim}
  73 from pyx import *
  74 from pyx.path import *
  75
  76 p = path(moveto(0, 0),
  77          lineto(0, 1),
  78          lineto(1, 1),
  79          closepath())
  80 \end{verbatim}
  81 \end{quote}
  82 In section~\ref{chap:canvas}, we shall see, how it is possible to output such
  83 a path on a canvas. For the moment, we only want to discuss the methods
  84 provided by the \verb|path| class. These range from standard operations like
  85 the determination of the length of a path via \verb|len(p)|, fetching of
  86 items using \verb|p[index]| and the possibility to concatenate two
  87 paths, \verb|p1 + p2|, append further \verb|pathel|s using
  88 \verb|p.append(pathel)| to more advanced methods, which are summarized
  89 in the following table.
  90
  91 XXX terminology: subpath, \dots
  92
  93 \medskip
  94 \begin{tabularx}{\linewidth}{>{\hsize=.7\hsize}X>{\raggedright\arraybackslash\hsize=1.3\hsize}X}
  95   \texttt{path} method & function \\
  96   \hline \texttt{\_\_init\_\_(*pathels)} & construct new \texttt{path}
  97   consisting of \texttt{pathels}\\
  98   \texttt{append(pathel)} & appends \texttt{pathel} to the end of
  99   \texttt{path}\\
 100   \texttt{arclength(epsilon=1e-5)} & returns the total arc length of
 101   all \texttt{path} segments in PostScript points with accuracy
 102   \texttt{epsilon}.$^\dagger$\\
 103   \texttt{at(t)} & returns the coordinates of the point of
 104   \texttt{path} corresponding to the parameter value
 105   \texttt{t}.$^\dagger$\\
 106   \texttt{lentopar(l, \newline\phantom{lentopar(}epsilon=1e-5)} & returns the
 107   parameter value corresponding to the lengths \texttt{l} (one or a list of
 108   lengths). This uses arclength-calculations with accuracy
 109   \texttt{epsilon}.$^\dagger$\\
 110   \texttt{bbox()} & returns the bounding box of the \texttt{path}\\
 111   \texttt{begin()} & return first point of first subpath of
 112   \texttt{path}.$^\dagger$\\
 113   \texttt{end()} & return last point of last subpath of
 114   \texttt{path}.$^\dagger$\\
 115   \texttt{glue(opath)} & returns the \texttt{path} glued together with
 116   \texttt{opath}, \textit{i.e.}\ the last subpath of \texttt{path}
 117   and the first one of \texttt{opath} are joined.$^\dagger$\\
 118   \texttt{intersect(opath, \newline\phantom{intersect(}epsilon=1e-5)}
 119   & returns tuple consisting of two lists of parameter values
 120   corresponding to the
 121   intersection points of \texttt{path} and \texttt{opath}, respectively.$^\dagger$\\
 122   \texttt{reversed()} & returns the normalized reversed
 123   \texttt{path}.$^\dagger$\\
 124   \texttt{split(t)} & returns a tuple consisting of two
 125   \texttt{normpath}s corresponding to the \texttt{path} split at
 126   the parameter value \texttt{t}.$^\dagger$\\
 127   \texttt{transformed(trafo)} & returns the normalized and accordingly
 128   to the linear transformation \texttt{trafo} transformed path. Here,
 129   \texttt{trafo} must be an instance of the \texttt{trafo.trafo}
 130   class.$^\dagger$
 131 \end{tabularx}
 132 \medskip
 133
 134 Some notes on the above:
 135 \begin{itemize}
 136 \item The bounding box may be too large, if the path contains any
 137   \texttt{curveto} elements, since for these the control box,
 138   \textit{i.e.}, the bounding box enclosing the control points of
 139   the B\'ezier curve is returned.
 140 \item The $\dagger$ denotes methods which require a prior
 141   conversion of the path into a \verb|normpath| instance. This is
 142   done automatically, but if you need to call such methods often,
 143   it is a good idea to do the conversion once for performance reasons.
 144 \item Instead of using the \verb|glue| method, you can also glue two
 145 paths together with help of the \verb|<<| operator, for instance
 146 \verb|p = p1 << p2|.
 147 \end{itemize}
 148
 149 \section{Class normpath}
 150
 151 The \texttt{normpath} class represents a specialized form of a
 152 \texttt{path} containing only the elements \verb|moveto|,
 153 \verb|lineto|, \verb|curveto| and \verb|closepath|. Such normalized
 154 paths are used during all of the more sophisticated path operations
 155 which are denoted by a $\dagger$ in the above table.
 156
 157
 158 Any path can
 159 easily be converted to its normalized form by passing it as parameter
 160 to the \texttt{normpath} constructor,
 161 \begin{quote}
 162 \begin{verbatim}
 163 np = normpath(p)
 164 \end{verbatim}
 165 \end{quote}
 166 Alternatively, by passing a series of \texttt{pathel}s to the constructor, a
 167 \texttt{normpath} can be constructed like a generic \texttt{path}.
 168 The sum of a \verb|normpath| and a \verb|path| always yields a
 169 \verb|normpath|.
 170
 171 \section{Subclasses of path}
 172
 173 For your convenience, some special PostScript paths are already defined, which
 174 are given in the following table.
 175
 176 \medskip
 177 \begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
 178 Subclass of \texttt{path} & function \\
 179 \hline
 180 \texttt{line(x1, y1, x2, y2)} & a line from the point
 181   (\texttt{x1}, \texttt{y1}) to the point (\texttt{x2}, \texttt{y2})\\
 182 \texttt{curve(x0, y0, x1, y1, x2, y2, x3, y3)} & a B\'ezier curve with
 183 control points  (\texttt{x0}, \texttt{y0}), $\dots$, (\texttt{x3}, \texttt{y3}).\\
 184 \texttt{rect(x, y, w, h)} &  a rectangle with the
 185   lower left point (\texttt{x}, \texttt{y}), width~\texttt{w}, and
 186   height~\texttt{h}. \\
 187 \texttt{circle(x, y, r)} & a circle with
 188   center (\texttt{x}, \texttt{y}) and radius~\texttt{r}.
 189 \end{tabularx}
 190 \medskip
 191 Note that besides the \verb|circle| class all classes are actually
 192 subclasses of \verb|normpath|.
 193
 194
 195 % \section{Examples}
 196
 197
 198
 199 %%% Local Variables:
 200 %%% mode: latex
 201 %%% TeX-master: "manual.tex"
 202 %%% End: