updates to the manual, some comments on TODOs for 0.6

[PyX.git] / manual / path.tex

\chapter{Basic graphics}

\label{path}

\section{Introduction}

The path module allows one to construct PostScript-like
\textit{paths}, which are one of the main building blocks for the
generation of drawings. A PostScript path is an arbitrary shape built
up of straight lines, arc segments and cubic Bezier curves. Such a
path does not have to be connected but may also consist of multiple
connected segments, which will be called \textit{sub paths} in the
following.

Usually, a path is constructed by passing a list of the path
primitives \verb|moveto|, \verb|lineto|, \verb|curveto|, etc., to the
constructor of the \verb|path| class. The following code snippet, for
instance, defines a path \verb|p| that consists of a straight line
from the point $(0, 0)$ to the point $(1, 1)$
\begin{verbatim}
from pyx import *
p = path.path(path.moveto(0, 0), path.lineto(1, 1))
\end{verbatim}
Equivalently, one can also use the predefined \verb|path| subclass
\verb|line| and write
\begin{verbatim}
p = path.line(0, 0, 1, 1)
\end{verbatim}

While you can already do some geometrical operations with the
just create path (see next section), we need another \PyX{} object
in order to produce the output corresponding to the path, namely
an instance of the \verb|canvas| class. By convetion, we use
the name \verb|c| for this instance:
\begin{verbatim}
c = canvas.canvas()
\end{verbatim}
In order to draw the path on the canvas, we use the \verb|stroke| method
of the \verb|canvas| class, i.e.,
\begin{verbatim}
c.stroke(p)
c.writeEPSfile("line")
\end{verbatim}
To complete the example, we have added a \verb|writeEPSfile| call,
which writes the contents of the canvas into the given file.

Let us as second example define a path which consists of more than 
one sub path:
\begin{verbatim}
cross = path.path(path.moveto(0, 0), path.rlineto(1, 1),
                  path.moveto(1, 0), path.rlineto(-1, 1))
\end{verbatim}
The first sub path is again a straight line from $(0, 0)$ to $(1, 1)$,
with the only difference that we now have used the \verb|rlineto|
class, whose arguments count relative from the last point in the path.
The second \verb|moveto| instance opens a new sub path starting at the
point $(1, 0)$ and ending at $(0, 1)$. Note that although both lines
intersect at the point $(1/2, 1/2)$, they count as separate sub paths.
The general rule is that each occurence of \verb|moveto| opens a new
sub path. This means that if one wants to draw a rectangle, one should
not use
\begin{verbatim}
# wrong: do not use moveto when you want a single sub path
rect1 = path.path(path.moveto(0, 0), path.lineto(0, 1),
                  path.moveto(1, 0), path.lineto(1, 1),
                  path.moveto(1, 1), path.lineto(1, 1),
                  path.moveto(0, 1), path.lineto(0, 0))
\end{verbatim}
which would construct a rectangle consisting of four disconnected
sub paths. Instead the correct way of defining a rectangle is 
\begin{verbatim}
# correct: a rectangle consisting of a single closed sub path
rect2 = path.path(path.moveto(0, 0), path.lineto(0, 1), 
                  path.lineto(1, 1), path.lineto(1, 0),
                  path.closepath())
\end{verbatim}
%
\begin{figure}
\centerline{\includegraphics{rects}}
\caption{Not closed (left) and closed (midlle) rectangle. Filling a
  path (right) always closes it automatically.}
\label{fig:rects}
\end{figure}
Note that for the last straight line of the rectangle (from $(0, 1)$
back to the origin at $(0, 0)$)) we have used \verb|closepath|.  This
directive adds a straight line from the current point to the first
point of the current sub path and furthermore \textit{closes} the sub
path, i.e., it joins the beginning and the end of the line segment.
The difference can be appreciated in Fig.~\ref{fig:rects}, where
also a filled (and at the same time stroked) rectangle is shown.
The corresponding code looks like
\begin{verbatim}
c.stroke(rect1, [deco.filled([color.grey(0.95)])])
\end{verbatim}
The important point to remember here is that when filling a path, PostScript
automatically closes it.

Of course, rectangles are also predefined in \PyX{}, so above we could
have as well written
\begin{verbatim}
rect2 = path.rect(0, 0, 1, 1)
\end{verbatim}
Here, the first two arguments specify the origin of the rectangle
while the second two arguments define its width and height,
respectively.

XXX arc, bezier example

\section{Path operations}

Often, one not only wants to stroke or fill a path on the canvas
but before do some geometrical operations with it. For instance, one
might want to intersect one path with another one and the split the
paths at the intersection points and then join the segments together
in a new way. \PyX{} supports such tasks by means of a number
of path methods, which we will introduce in the following.

Suppose you want to draw the radii to the intersection points of a
circle with a straight line. This task can be done using the following
code which gives the result shown in Fig.~\ref{fig:radii}
\verbatiminput{radii.py}
\begin{figure}
\centerline{\includegraphics{radii}}
%\caption{}
\label{fig:radii}
\end{figure}
Passing another path, here \verb|line|, to the \verb|intersect| method
of \verb|circle|, we obtain a tuple of parameter values of the
intersection points. The first element of the tuple is a list of
parameter values for the path whose \verb|intersect| method we have
called, the second element is the corresponding list for the path
passed as argument to this method. In the present example, we only
need one list of parameter values, namely \verb|isects_circle|.
Iterating over the elements of this list, we draw the radii, using the
\verb|at| path method to obtain the point corresponding to the
parameter value.

Another powerful feature of \PyX{} is its ability to split paths at a
given set of parameters. For instance, in order to fill in the
previous example the segment of the circle delimited by the straight
line (cf.\ Fig.~\ref{fig:radii2}), you first have to construct a path
corresponding to the outline of this segment. The following code
snippet does yield this \verb|segment|
\begin{verbatim}
arc1, arc2 = circle.split(isects_circle)
arc = arc1.arclen()<arc2.arclen() and arc1 or arc2

isects_line.sort()
line1, line2, line3 = line.split(isects_line)

segment = line2 << arc
\end{verbatim}
\begin{figure}
\centerline{\includegraphics{radii2}}
%\caption{}
\label{fig:radii2}
\end{figure}
Here, we first split the circle using the \verb|split| method passing
the list of parameters obtained above. Since the circle is closed,
this yields two arc segments. We then use the \verb|arclen|, which
returns the arc length of the path, to find the shorter of the two
arcs. Before splitting the line, we have to take into account that
the \verb|split| method only accepts a sorted list of parameters.
Finally, we join the straight line and the arc segment. For
this, we make use of the \verb|<<| operator, which not only adds
the paths (which could be done using \verb|line2 + arc|), but also
joins the last sub path of \verb|line2| and the first one of
\verb|arc|. Thus, \verb|segment| consists of only a single sub path
and filling works as expected.

XXX reverse, reversed, parametrisation, arclen parameters


\section{Module path}

\subsection{Class pathel}

The class \verb|pathel| is the superclass of all PostScript path
construction primitives. It is never used directly, but only by
instantiating its subclasses, which correspond one by one to the
PostScript primitives.

\medskip
\begin{tabularx}{\linewidth}{>{\hsize=.7\hsize}X>{\raggedright\arraybackslash\hsize=1.3\hsize}X}
Subclass of \texttt{pathel} & function \\
\hline
\texttt{closepath()} & closes current subpath \\
\texttt{moveto(x, y)} & sets current point to (\texttt{x},
\texttt{y})\\
\texttt{rmoveto(dx, dy)} & moves current point by (\texttt{dx},
\texttt{dy})\\
\texttt{lineto(x, y)} & moves current point to (\texttt{x}, \texttt{y})
while drawing a straight line\\
\texttt{rlineto(dx, dy)} & moves current point by by (\texttt{dx}, \texttt{dy})
while drawing a straight line\\
\texttt{arc(x, y, r, \newline\phantom{arc(}angle1, angle2)} & appends arc segment in
counterclockwise direction with center (\texttt{x}, \texttt{y}) and
radius~\texttt{r} from \texttt{angle1} to \texttt{angle2} (in degrees).\\
\texttt{arcn(x, y, r, \newline\phantom{arcn(}angle1, angle2)} & appends arc segment in
clockwise direction with center (\texttt{x}, \texttt{y}) and
radius~\texttt{r} from \texttt{angle1} to \texttt{angle2} (in degrees). \\
\texttt{arct(x1, y1, x2, y2, r)} & appends arc segment of radius \texttt{r}
connecting between (\texttt{x1}, \texttt{y1}) and (\texttt{x2}, \texttt{y2}).\\
\texttt{rcurveto(dx1, dy1, \newline\phantom{rcurveto(}dx2, dy2,\newline\phantom{rcurveto(}dx3, dy3)} & appends a B\'ezier curve with
the following four control points: current point and the points defined 
relative to the current point by (\texttt{dx1}, \texttt{dy1}), 
(\texttt{dx2}, \texttt{dy2}), and (\texttt{dx3}, \texttt{dy3})
\end{tabularx}
\medskip

Some notes on the above:
\begin{itemize}
\item All coordinates are in \PyX\ lengths
\item If the current point is defined before an \verb|arc| or
  \verb|arcn| command, a straight line from current point to the
  beginning of the arc is prepended.
\item The bounding box (see below) of B\'ezier curves is actually 
  the box enclosing the control points, \textit{i.e.}\ not neccesarily the 
  smallest rectangle enclosing the B\'ezier curve.
\end{itemize}


\subsection{Class path}

The methods provided by instance of the class \verb|path| are
summarized in the following table:

\medskip
\begin{tabularx}{1.04\linewidth}{>{\hsize=.7\hsize}X>{\raggedright\arraybackslash\hsize=1.3\hsize}X}
  \texttt{path} method & function \\
  \hline \texttt{\_\_init\_\_(*pathels)} & construct new \texttt{path}
  consisting of \texttt{pathels}\\
  \texttt{append(pathel)} & appends \texttt{pathel} to the end of 
  \texttt{path}\\
  \texttt{arclen(epsilon=1e-5)} & returns the total arc length of
  all \texttt{path} segments in PostScript points with accuracy
  \texttt{epsilon}.$^\dagger$\\
  \texttt{arclentoparam(lengths, \newline\phantom{arclentoparam(}epsilon=1e-5)} & returns the
  parameter value corresponding to the lengths \texttt{lengths} (one or a list of
  lengths). This uses arclen-calculations with accuracy
  \texttt{epsilon}.$^\dagger$\\
  \texttt{at(param=None,
    \newline\phantom{at(}arclen=None)} & returns the coordinates of the point of
  \texttt{path} corresponding to the parameter value
  \texttt{param} or the arc length \verb|arclen|.$^\dagger$\\
  \texttt{bbox()} & returns the bounding box of the \texttt{path}\\
  \texttt{begin()} & return first point of first subpath of
  \texttt{path}.$^\dagger$\\
   \texttt{curvradius(self, 
    \newline\phantom{curvradius(}param=None,
    \newline\phantom{curvradius(}arclen=None)} &
        Returns the curvature radius (or None if infinite) at parameter param.
        This is the inverse of the curvature at this parameter
        Please note that this radius can be negative or positive,
        depending on the sign of the curvature.
        $^\dagger$
        \\
  \texttt{end()} & return last point of last subpath of
  \texttt{path}.$^\dagger$\\
  \texttt{glue(opath)} & returns the \texttt{path} glued together with
  \texttt{opath}, \textit{i.e.}\ the last subpath of \texttt{path}
  and the first one of \texttt{opath} are joined.$^\dagger$\\
  \texttt{intersect(opath, \newline\phantom{intersect(}epsilon=1e-5)}
  & returns tuple consisting of two lists of parameter values
  corresponding to the
  intersection points of \texttt{path} and \texttt{opath},
  respectively.$^\dagger$\\
  \texttt{range()} & returns the maximal value of the parameter value
  \texttt{param} in the path methods\\
  \texttt{reversed()} & returns the normalized reversed
  \texttt{path}.$^\dagger$\\
  \texttt{split(parameters)} & splits the path at the given list of
  parameters (which have to be sorted in ascending order) and returns
  a corresponding list of 
  \texttt{normpath}s.$^\dagger$\\
  \texttt{tangent(param=None, 
      \newline\phantom{tangent(}arclen=None,
      \newline\phantom{tangent(}length=None)} & return the tuple corresponding to
    the tangent vector to the path at the parameter value
  \texttt{param} or the arc length \texttt{arclen}.
    \texttt{param} (\texttt{arclen}) has to be
    smaller or equal to \texttt{self.range()} (\texttt{self.arclen()}), 
    otherwise an exception is raised.  At discontinuities in the path, the
    limit from below is returned. If \texttt{length} is not
    \texttt{None}, the tangent vector will be scaled correspondingly.
  \\
  \texttt{trafo(param=None, 
      \newline\phantom{trafo(}arclen=None} & return a trafo which maps 
    a point $(0, 1)$ to the tangent vector to the path at the parameter value
    \texttt{param} or the arc length \texttt{arclen}.
    \texttt{param} (\texttt{arclen}) has to be
    smaller or equal to \texttt{self.range()} (\texttt{self.arclen()}), 
    otherwise an exception is raised.  At discontinuities in the path, the
    limit from below is returned.
  \\
  \texttt{transformed(trafo)} & returns the normalized and accordingly
  to the linear transformation \texttt{trafo} transformed path. Here,
  \texttt{trafo} must be an instance of the \texttt{trafo.trafo}
  class.$^\dagger$
\end{tabularx} 
\medskip

Some notes on the above:
\begin{itemize}
\item The bounding box may be too large, if the path contains any
  \texttt{curveto} elements, since for these the control box,
  \textit{i.e.}, the bounding box enclosing the control points of
  the B\'ezier curve is returned.
\item The $\dagger$ denotes methods which require a prior
  conversion of the path into a \verb|normpath| instance. This is
  done automatically, but if you need to call such methods often,
  it is a good idea to do the conversion once for performance reasons.
\item Instead of using the \verb|glue| method, you can also glue two
paths together with help of the \verb|<<| operator, for instance
\verb|p = p1 << p2|.
\item In the methods accepting both a parameter value \verb|param| and
  an arc length \verb|arclen|, exactly one of these arguments has to
  provided.
\end{itemize}

\subsection{Class normpath}

The \texttt{normpath} class represents a specialized form of a
\texttt{path} containing only the elements \verb|moveto|,
\verb|lineto|, \verb|curveto| and \verb|closepath|. Such normalized
paths are used during all of the more sophisticated path operations
which are denoted by a $\dagger$ in the above table.


Any path can easily be converted to its normalized form by passing it
as parameter to the \texttt{normpath} constructor,
\begin{verbatim}
np = normpath(p)
\end{verbatim}
Additionally, you can specify the accuracy (in points) which is used
in all \verb|normpath| calculations by means of the keyword argument
\verb|epsilon|, which defaults to $10^{-5}$.  Note that the sum of a
\verb|normpath| and a \verb|path| always yields a \verb|normpath|.

\subsection{Subclasses of path}

For your convenience, some special PostScript paths are already defined, which
are given in the following table.

\medskip
\begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
Subclass of \texttt{path} & function \\
\hline
\texttt{line(x1, y1, x2, y2)} & a line from the point
  (\texttt{x1}, \texttt{y1}) to the point (\texttt{x2}, \texttt{y2})\\
\texttt{curve(x0, y0, x1, y1, x2, y2, x3, y3)} & a B\'ezier curve with 
control points  (\texttt{x0}, \texttt{y0}), $\dots$, (\texttt{x3}, \texttt{y3}).\\
\texttt{rect(x, y, w, h)} &  a rectangle with the
  lower left point (\texttt{x}, \texttt{y}), width~\texttt{w}, and
  height~\texttt{h}. \\
\texttt{circle(x, y, r)} & a circle with 
  center (\texttt{x}, \texttt{y}) and radius~\texttt{r}.
\end{tabularx}
\medskip


% \section{Examples}



%%% Local Variables:
%%% mode: latex
%%% TeX-master: "manual.tex"
%%% End: