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{arclen(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{arclentoparam(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 arclen-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(parameters)} & splits the path at the given list of
 125   parameters (which have to be sorted in ascending order) and returns
 126   a corresponding list of
 127   \texttt{normpath}s.$^\dagger$\\
 128     \texttt{tangent(t, length=None)} & return the tuple corresponding to
 129     the tangent vector to the path at the parameter value \texttt{t}.
 130     Negative values of \texttt{t} count
 131     from the end of the path. The absolute value of \texttt{t} must be
 132     smaller or equal to the number of segments in the normpath,
 133     otherwise None is returned.  At discontinuities in the path, the
 134     limit from below is returned. If \texttt{length} is not
 135   \texttt{None}, the tangent vector will be scaled correspondingly.
 136   \\
 137   \texttt{transformed(trafo)} & returns the normalized and accordingly
 138   to the linear transformation \texttt{trafo} transformed path. Here,
 139   \texttt{trafo} must be an instance of the \texttt{trafo.trafo}
 140   class.$^\dagger$
 141 \end{tabularx}
 142 \medskip
 143
 144 Some notes on the above:
 145 \begin{itemize}
 146 \item The bounding box may be too large, if the path contains any
 147   \texttt{curveto} elements, since for these the control box,
 148   \textit{i.e.}, the bounding box enclosing the control points of
 149   the B\'ezier curve is returned.
 150 \item The $\dagger$ denotes methods which require a prior
 151   conversion of the path into a \verb|normpath| instance. This is
 152   done automatically, but if you need to call such methods often,
 153   it is a good idea to do the conversion once for performance reasons.
 154 \item Instead of using the \verb|glue| method, you can also glue two
 155 paths together with help of the \verb|<<| operator, for instance
 156 \verb|p = p1 << p2|.
 157 \end{itemize}
 158
 159 \section{Class normpath}
 160
 161 The \texttt{normpath} class represents a specialized form of a
 162 \texttt{path} containing only the elements \verb|moveto|,
 163 \verb|lineto|, \verb|curveto| and \verb|closepath|. Such normalized
 164 paths are used during all of the more sophisticated path operations
 165 which are denoted by a $\dagger$ in the above table.
 166
 167
 168 Any path can
 169 easily be converted to its normalized form by passing it as parameter
 170 to the \texttt{normpath} constructor,
 171 \begin{quote}
 172 \begin{verbatim}
 173 np = normpath(p)
 174 \end{verbatim}
 175 \end{quote}
 176 Alternatively, by passing a series of \texttt{pathel}s to the constructor, a
 177 \texttt{normpath} can be constructed like a generic \texttt{path}.
 178 The sum of a \verb|normpath| and a \verb|path| always yields a
 179 \verb|normpath|.
 180
 181 \section{Subclasses of path}
 182
 183 For your convenience, some special PostScript paths are already defined, which
 184 are given in the following table.
 185
 186 \medskip
 187 \begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
 188 Subclass of \texttt{path} & function \\
 189 \hline
 190 \texttt{line(x1, y1, x2, y2)} & a line from the point
 191   (\texttt{x1}, \texttt{y1}) to the point (\texttt{x2}, \texttt{y2})\\
 192 \texttt{curve(x0, y0, x1, y1, x2, y2, x3, y3)} & a B\'ezier curve with
 193 control points  (\texttt{x0}, \texttt{y0}), $\dots$, (\texttt{x3}, \texttt{y3}).\\
 194 \texttt{rect(x, y, w, h)} &  a rectangle with the
 195   lower left point (\texttt{x}, \texttt{y}), width~\texttt{w}, and
 196   height~\texttt{h}. \\
 197 \texttt{circle(x, y, r)} & a circle with
 198   center (\texttt{x}, \texttt{y}) and radius~\texttt{r}.
 199 \end{tabularx}
 200 \medskip
 201 Note that besides the \verb|circle| class all classes are actually
 202 subclasses of \verb|normpath|.
 203
 204
 205 % \section{Examples}
 206
 207
 208
 209 %%% Local Variables:
 210 %%% mode: latex
 211 %%% TeX-master: "manual.tex"
 212 %%% End: