manual/path.tex

   1 \chapter{Module path: PostScript like paths}
   2
   3 \label{path}
   4
   5 With 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 relative by (\texttt{dx},
  33 \texttt{dy})\\
  34 \texttt{lineto(x, y)} & appends straight line from current point to
  35 (\texttt{x}, \texttt{y})\\
  36 \texttt{rlineto(dx, dy)} & appends straight line from current point
  37 relative by (\texttt{dx}, \texttt{dy})\\
  38 \texttt{arc(x, y, r, \newline\phantom{arc(}angle1, angle2)} & appends arc segment in
  39 counterclockwise direction with center (\verb|x|, \verb|y|) and
  40 radius~\verb|r| from \verb|angle1| to \verb|angle2| (in degrees).\\
  41 \texttt{arcn(x, y, r, \newline\phantom{arcn(}angle1, angle2)} & appends arc segment in
  42 clockwise direction with center (\verb|x|, \verb|y|) and
  43 radius~\verb|r| from \verb|angle1| to \verb|angle2| (in degrees). \\
  44 \texttt{arct(x1, y1, x2, y2, r)} & appends arc segment with radius \verb|r|
  45 which connects between (\verb|x1|, \verb|y1|) and (\verb|x2|,
  46 \verb|y2|).\\
  47 \texttt{rcurveto(dx1, dy1, \newline\phantom{rcurveto(}dx2, dy2,\newline\phantom{rcurveto(}dx3, dy3)} & appends a B\'ezier curve with
  48 the control points current point, and the points defined relative to
  49 the current point by (\verb|dx1|, \verb|dy1|),
  50 (\verb|dx2|, \verb|dy2|), and (\verb|dx3|, \verb|dy3|)
  51 \end{tabularx}
  52 \medskip
  53
  54 Some notes on the above:
  55 \begin{itemize}
  56 \item All coordinates are in \PyX\ lengths
  57 \item If the current point is defined before an \verb|arc| or
  58   \verb|arcn| command, a straight line from current point to the
  59   beginning of the arc is prepended.
  60 \item The bounding box (see below) of B\'ezier curves is actually only
  61   the control box, \textit{i.e.}\ not neccesarily the smallest
  62   enclosing rectangle.
  63 \end{itemize}
  64
  65
  66 \section{Class path}
  67
  68 The class path represents PostScript like paths in \PyX. The \verb|path| constructor allows the
  69 creation of such a path out of series of \verb|pathel|s. A simple example, which generates a triangle,
  70 looks like:
  71 \begin{quote}
  72 \begin{verbatim}
  73 from pyx import *
  74 from 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 Later on, we shall see, how it is possible to output such a path on a
  83 canvas. For the moment, we only want to discuss the methods provided
  84 by the \verb|path| class. This range from standard operation like the
  85 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 end of \texttt{path}\\
  99   \texttt{arclength(epsilon=1e-5)} & returns the total arc length of
 100   all \texttt{path} segments in PostScript points with accuracy
 101   \texttt{epsilon}.$^\dagger$\\
 102   \texttt{at(t)} & returns the coordinates of the point of
 103   \texttt{path} corresponding to the parameter value
 104   \texttt{t}.$^\dagger$\\
 105   \texttt{bbox()} & returns the bounding box of the \texttt{path}\\
 106   \texttt{begin()} & return first point of first subpath of
 107   \texttt{path}.$^\dagger$\\
 108   \texttt{end()} & return last point of last subpath of
 109   \texttt{path}.$^\dagger$\\
 110   \texttt{glue(opath)} & returns the \texttt{path} glued together with
 111   \texttt{opath}, \textit{i.e.}\ the last subpath of \texttt{path}
 112   and the first one of \texttt{opath} are joined.$^\dagger$\\
 113   \texttt{intersect(opath, \newline\phantom{intersect(}epsilon=1e-5)}
 114   & returns tuple consisting of two list of parameter values
 115   corresponding to the
 116   intersection points of \texttt{path} and \texttt{opath}, respectively.$^\dagger$\\
 117   \texttt{reversed()} & returns the normalized reversed
 118   \texttt{path}.$^\dagger$\\
 119   \texttt{split(t)} & returns a tuple consisting of two
 120   \texttt{normpath}s corresponding to the \texttt{path} split at
 121   the parameter value \texttt{t}.$^\dagger$\\
 122   \texttt{transformed(trafo)} & returns the normalized and accordingly
 123   to the linear transformation \texttt{trafo} transformed path. Here,
 124   \texttt{trafo} must be an instance of the \texttt{trafo.trafo}
 125   class.$^\dagger$
 126 \end{tabularx}
 127 \medskip
 128
 129 Some notes on the above:
 130 \begin{itemize}
 131 \item The bounding box may be too large, if the path contains any
 132   \texttt{curveto} elements, since for these the control box,
 133   \textit{i.e.}, the bounding box enclosing the control points of
 134   the B\'ezier curve is returned.
 135 \item The $\dagger$ denotes methods which require a prior
 136   conversion of the path into a \verb|normpath| instance. This is
 137   done automatically, but if you need many to call such methods often,
 138   it is a good idea to do the conversion once for performance reasons.
 139 \item Instead of using the \verb|glue| method, you can also glue two
 140 paths together with help of the \verb|<<| opertor, for instance
 141 \verb|p = p1 << p2|.
 142 \end{itemize}
 143
 144 \section{Class normpath}
 145
 146 The \texttt{normpath} class represents a specialized form of a
 147 \texttt{path} containing only the elements \verb|moveto|,
 148 \verb|lineto|, \verb|curveto| and \verb|closepath|. Such normalized
 149 paths are used during all of the more sophisticated path operations,
 150 namely precisely those which are denoted by a $\dagger$ in the above table.
 151
 152
 153 Any path can
 154 easily be converted to its normalized form by passing it as parameter
 155 to the \texttt{normpath} constructor,
 156 \begin{quote}
 157 \begin{verbatim}
 158 np = normpath(p)
 159 \end{verbatim}
 160 \end{quote}
 161 Alternatively, by passing a series of \texttt{pathel}s to the constructor, a
 162 \texttt{normpath} can be constructed like a generic \texttt{path}.
 163 Addition of a \verb|normpath| and a \verb|path| always yields a
 164 \verb|normpath|.
 165
 166 \section{Subclasses of path}
 167
 168 For your convenience, some special PostScript paths are already defined, which
 169 are given in the following table.
 170
 171 \medskip
 172 \begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
 173 Subclass of \texttt{path} & function \\
 174 \hline
 175 \texttt{line(x1, y1, x2, y2)} & a line from the point
 176   (\texttt{x1}, \texttt{y1}) to the point (\texttt{x2}, \texttt{y2})\\
 177 \texttt{curve(x0, y0, x1, y1, x2, y2, x3, y3)} & a B\'ezier curve with
 178 control points  (\texttt{x0}, \texttt{y0}), $\dots$, (\texttt{x3}, \texttt{y3}).\\
 179 \texttt{rect(x, y, w, h)} &  a rectangle with the
 180   lower left point (\texttt{x}, \texttt{y}), width~\texttt{w}, and
 181   height~\texttt{h}. \\
 182 \texttt{circle(x, y, r)} & a circle with
 183   center (\texttt{x}, \texttt{y}) and radius~\texttt{r}.
 184 \end{tabularx}
 185 \medskip
 186 Note that besides the \verb|circle| class all classes are actually
 187 subclasses of \verb|normpath|.
 188
 189
 190 \section{Examples}
 191
 192
 193
 194 %%% Local Variables:
 195 %%% mode: latex
 196 %%% TeX-master: "manual.tex"
 197 %%% End: