converted more docs to new style

[PyX/mjg.git] / manual / path.tex

\chapter{Basic graphics}

\sectionauthor{J\"org Lehmann}{joergl@users.sourceforge.net} 

\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 created path (see next section), we need another \PyX{} object
in order to be actually able to draw the path, namely
an instance of the \verb|canvas| class. By convention, 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}

The \module{path} module defines several important classes which are
documented in the present section.

\subsection{Class \class{path} --- PostScript-like paths}

\declaremodule{}{path}

\begin{classdesc}{path}{*pathels}
This class represents a PostScript like path consisting of the
elements \var{pathels}.
\end{classdesc}

Instances of the class \class{path} provide the following
methods (in alphabetic order):

\begin{methoddesc}{append}{pathel}
Appends a \var|pathel| to the end of the path.
\end{methoddesc}

\begin{methoddesc}{arclen}{}
Returns the total arc length of the path.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{arclentoparam}{lengths}
  Returns the parameter values corresponding to the arc lengths
  \var{lengths}.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{at}{param=None, arclen=None}
  Returns the coordinates (as 2-tuple) of the path point corresponding to the
  parameter value \var{param} or, alternatively, the arc length
  \var{arclen}. The parameter value \var{param} (\var{arclen}) has to be smaller
  or equal to \method{self.range()} (\method{self.arclen()}),
  otherwise an exception is raised.  At discontinuities in the path,
  the limit from below is returned.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{bbox}{}
  Returns the bounding box of the path. Note that this returned
  bounding box may be too large, if the path contains any
  \class{curveto} elements, since for these the control box, i.e., the
  bounding box enclosing the control points of the B\'ezier curve is
  returned.
\end{methoddesc}

\begin{methoddesc}{begin}{}
  Returns the coordinates (as 2-tuple) of the first point of the path.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{curvradius}{param=None, arclen=None}
  Returns the curvature radius (or None if infinite) at parameter
  param or, alternatively, arc length \var{arclen}.  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$
\end{methoddesc}

\begin{methoddesc}{end}{}
  Returns the coordinates (as 2-tuple) of the end point of the path.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{intersect}{opath}
  Returns a tuple consisting of two lists of parameter values
  corresponding to the intersection points of the path with the other
  path \var{opath}, respectively.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{joined}{opath}
  Appends \var{opath} to the end of the path, thereby merging the last
  sub path (which must not be closed) of the path with the first sub
  path of \var{opath} and returns the resulting new path.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{range}{}
  Returns the maximal parameter value \var{param} that is allowed in the
  path methods.
\end{methoddesc}

\begin{methoddesc}{reversed}{}
  Returns the reversed path.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{split}{params}
  Splits the path at the parameters \var{params}, which have to be
  sorted in ascending order, and returns a corresponding list of
  \class{normpath} instances.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{tangent}{param=None, arclen=None, length=None}
  Return a \class{line} instance corresponding to the tangent vector
  to the path at the parameter value \var{param} or, alternatively, the arc length
  \var{arclen}. The parameter value \var{param} (\var{arclen}) has to be smaller
  or equal to \method{self.range()} (\method{self.arclen()}),
  otherwise an exception is raised.  At discontinuities in the path,
  the limit from below is returned. If \var{length} is not
  \texttt{None}, the tangent vector will be scaled correspondingly.$^\dagger$
\end{methoddesc}


\begin{methoddesc}{trafo}{param=None, arclen=None}
  Returns a trafo which maps a point $(0, 1)$ to the tangent vector to
  the path at the parameter value \var{param} or, alternatively, the
  arc length \var{arclen}.  The parameter value \var{param} (\var{arclen}) has to
  be smaller or equal to \method{self.range()}
  (\method{self.arclen()}), otherwise an exception is raised.  At
  discontinuities in the path, the limit from below is returned.$^\dagger$
\end{methoddesc}

\begin{methoddesc}{tranformed}{trafo}
  Returns the path tranformed according to the linear transformation
  \var{trafo}. Here, \texttt{trafo} must be an instance of the
  \class{trafo.trafo} class.$^\dagger$
\end{methoddesc}

Some notes on the above:
\begin{itemize}
\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{Path elements}

The class \class{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.

The following operation move the current point and open a new
sub path:

\begin{classdesc}{moveto}{x, y}
Path element which sets the current point to the absolute coordinates (\var{x},
\var{y}). This operation opens a new subpath.
\end{classdesc}

\begin{classdesc}{rmoveto}{dx, dy}
Path element which moves the current point by (\var{dx}, \var{dy}).
This operation opens a new subpath.
\end{classdesc}

Drawing a straight line can be accomplished using:

\begin{classdesc}{lineto}{x, y}
Path element which appends a straight line from the current point to the
point with absolute coordinates (\var{x}, \var{y}), which becomes
the new current point.
\end{classdesc}

\begin{classdesc}{rlineto}{dx, dy}
Path element which appends a straight line from the current point to the
a point with relative coordinates (\var{dx}, \var{dy}), which becomes
the new current point.
\end{classdesc}

For the construction of arc segment, the following three operations
are available:

\begin{classdesc}{arc}{x, y, r, angle1, angle2}
Path element which appends an arc segment in counterclockwise direction
with absolute coordinates (\var{x}, \var{y}) of the center and 
radius \var{r} from \var{angle1} to \var{angle2} (in degrees).
If before the operation, the current point is defined, a straight line
is from the current point to the beginning of the arc segment is
prepended. Otherwise, a subpath, which thus is the first one in the
path, is opened. After the operation, the current point is at the end
of the arc segment.
\end{classdesc}

\begin{classdesc}{arcn}{x, y, r, angle1, angle2}
Path element which appends an arc segment in clockwise direction
with absolute coordinates (\var{x}, \var{y}) of the center and 
radius \var{r} from \var{angle1} to \var{angle2} (in degrees).
If before the operation, the current point is defined, a straight line
is from the current point to the beginning of the arc segment is
prepended. Otherwise, a subpath, which thus is the first one in the
path, is opened. After the operation, the current point is at the end
of the arc segment.
\end{classdesc}

\begin{classdesc}{arct}{x1, y1, x2, y2, r}
Path element which appends an arc segment of radius \var{r}
connecting between (\var{x1}, \var{y1}) and (\var{x2}, \var{y2}).\\
\end{classdesc}

B\'ezier curves can be constructed using: \

\begin{classdesc}{curveto}{x1, y1, x2, y2, x3, y3}
Path element which appends a B\'ezier curve with
the current point as first control point and the other control points
(\var{x1}, \var{y1}), (\var{x2}, \var{y2}), and (\var{x3}, \var{y3}).
\end{classdesc}

\begin{classdesc}{rcurveto}{dx1, dy1, dx2, dy2, dx3, dy3}
Path element which appends a B\'ezier curve with
the current point as first control point and the other control points
defined relative to the current point by the coordinates
(\var{dx1}, \var{dy1}), (\var{dx2}, \var{dy2}), and (\var{dx3}, \var{dy3}).
\end{classdesc}

Finally, an open sub path can be closed using:

\begin{classdesc}{closepath}{}
Path element which closes the current subpath.
\end{classdesc}

XXX \class{multicurveto} and \class{multilineto}

Some notes on the above:
\begin{itemize}
\item All coordinates can be given as number (in which case they are
interpreted as user units with the currently set default type or in
\PyX\ lengths.
\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 \class{normpath}}

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

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

XXX additional operations of normpaths

\subsection{Predefined paths}

For your convenience, some special PostScript paths are already defined.
All of them are sub classes of the \class{path} class.

\begin{classdesc}{line}{x1, y1, x2, y2, x3, y3}
A straight line from the point (\var{x1}, \var{y1}) to the point (\var{x2}, \var{y2}).
\end{classdesc}

\begin{classdesc}{curve}{x1, y1, x2, y2, x3, y3, x4, y4}
A B\'ezier curve with 
control points  (\var{x0}, \var{y0}), $\dots$, (\var{x3}, \var{y3}).\
\end{classdesc}

\begin{classdesc}{rect}{x, y, w, h}
A closed rectangle with lower left point (\var{x}, \var{y}), width \var{w}, and
  height \var{h}.
\end{classdesc}

\begin{classdesc}{circle}{x, y, r}
A closed circle with center (\var{x}, \var{y}) and radius \var{r}.
\end{classdesc}

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