manual/graphics.tex

   1 \chapter{Basic graphics}
   2
   3 \sectionauthor{J\"org Lehmann}{joergl@users.sourceforge.net}
   4
   5 \label{graphics}
   6
   7 \section{Introduction}
   8
   9 The path module allows one to construct PostScript-like
  10 \textit{paths}, which are one of the main building blocks for the
  11 generation of drawings. A PostScript path is an arbitrary shape
  12 consisting of straight lines, arc segments and cubic B\'ezier curves.
  13 Such a path does not have to be connected but may also comprise
  14 several disconnected segments, which will be called \textit{subpaths}
  15 in the following.
  16
  17 XXX example for paths and subpaths
  18
  19 Usually, a path is constructed by passing a list of the path
  20 primitives \class{moveto}, \class{lineto}, \class{curveto}, etc., to the
  21 constructor of the \class{path} class. The following code snippet, for
  22 instance, defines a path \var{p} that consists of a straight line
  23 from the point $(0, 0)$ to the point $(1, 1)$
  24 \begin{verbatim}
  25 from pyx import *
  26 p = path.path(path.moveto(0, 0), path.lineto(1, 1))
  27 \end{verbatim}
  28 Equivalently, one can also use the predefined \class{path} subclass
  29 \class{line} and write
  30 \begin{verbatim}
  31 p = path.line(0, 0, 1, 1)
  32 \end{verbatim}
  33
  34 While already some geometrical operations can be performed with this
  35 path (see next section), another \PyX{} object is needed in order to
  36 actually being able to draw the path, namely an instance of the
  37 \class{canvas} class. By convention, we use the name \var{c} for this
  38 instance:
  39 \begin{verbatim}
  40 c = canvas.canvas()
  41 \end{verbatim}
  42 In order to draw the path on the canvas, we use the \method{stroke()} method
  43 of the \class{canvas} class, i.e.,
  44 \begin{verbatim}
  45 c.stroke(p)
  46 c.writeEPSfile("line")
  47 \end{verbatim}
  48 To complete the example, we have added a \method{writeEPSfile()} call,
  49 which writes the contents of the canvas to the file \file{line.eps}.
  50 Note that an extension \file{.eps} is added automatically, if not
  51 already present in the given filename.
  52
  53 As a second example, let us define a path which consists of more than
  54 one subpath:
  55 \begin{verbatim}
  56 cross = path.path(path.moveto(0, 0), path.rlineto(1, 1),
  57                   path.moveto(1, 0), path.rlineto(-1, 1))
  58 \end{verbatim}
  59 The first subpath is again a straight line from $(0, 0)$ to $(1, 1)$,
  60 with the only difference that we now have used the \class{rlineto}
  61 class, whose arguments count relative from the last point in the path.
  62 The second \class{moveto} instance opens a new subpath starting at the
  63 point $(1, 0)$ and ending at $(0, 1)$. Note that although both lines
  64 intersect at the point $(1/2, 1/2)$, they count as disconnected
  65 subpaths.  The general rule is that each occurrence of a \class{moveto}
  66 instance opens a new subpath. This means that if one wants to draw a
  67 rectangle, one should not use
  68 \begin{verbatim}
  69 rect1 = path.path(path.moveto(0, 0), path.lineto(0, 1),
  70                   path.moveto(0, 1), path.lineto(1, 1),
  71                   path.moveto(1, 1), path.lineto(1, 0),
  72                   path.moveto(1, 0), path.lineto(0, 0))
  73 \end{verbatim}
  74 which would construct a rectangle out of four disconnected
  75 subpaths (see Fig.~\ref{fig:rects}a). In a better solution (see
  76 Fig.~\ref{fig:rects}b), the pen is not lifted between the first and
  77 the last point:
  78 %
  79 \begin{figure}
  80 \centerline{\includegraphics{rects}}
  81 \caption{Rectangle consisting of (a) four separate lines, (b) one open
  82   path, and (c) one closed path. (d) Filling a
  83   path always closes it automatically.}
  84 \label{fig:rects}
  85 \end{figure}
  86 %
  87 \begin{verbatim}
  88 rect2 = path.path(path.moveto(0, 0), path.lineto(0, 1),
  89                   path.lineto(1, 1), path.lineto(1, 0))
  90 \end{verbatim}
  91 However, as one can see in the lower left corner of
  92 Fig.~\ref{fig:rects}b, the rectangle is still incomplete.  It needs to
  93 be closed, which can  be done explicitly by using for the last straight
  94 line of the rectangle (from the point $(0, 1)$ back to the origin at $(0, 0)$)
  95 the \class{closepath} directive:
  96 \begin{verbatim}
  97 rect3 = path.path(path.moveto(0, 0), path.lineto(0, 1),
  98                   path.lineto(1, 1), path.lineto(1, 0),
  99                   path.closepath())
 100 \end{verbatim}
 101 The \class{closepath} directive adds a straight line from the current
 102 point to the first point of the current subpath and furthermore
 103 \textit{closes} the sub path, i.e., it joins the beginning and the end
 104 of the line segment. This results in the intended rectangle shown in
 105 Fig.~\ref{fig:rects}c. Note that filling the path implicitly closes
 106 every open subpath, as is shown for a single subpath in
 107 Fig.~\ref{fig:rects}d), which results from
 108 \begin{verbatim}
 109 c.stroke(rect2, [deco.filled([color.grey(0.95)])])
 110 \end{verbatim}
 111 More details on the available path elements can be found in
 112 Sect.~\ref{path:pathitem}.
 113
 114 XXX more on styles and attributes and reference to corresponding section
 115
 116 Of course, rectangles are also predefined in \PyX{}, so above we could
 117 have as well written
 118 \begin{verbatim}
 119 rect2 = path.rect(0, 0, 1, 1)
 120 \end{verbatim}
 121 Here, the first two arguments specify the origin of the rectangle
 122 while the second two arguments define its width and height,
 123 respectively. For more details on the predefined paths, we
 124 refer the reader to Sect.~\ref{path:predefined}.
 125
 126 \section{Path operations}
 127
 128 Often, one wants to perform geometrical operations with a path before
 129 placing it on a canvas by stroking or filling it.  For instance, one
 130 might want to intersect one path with another one, split the paths at
 131 the intersection points, and then join the segments together in a new
 132 way. \PyX{} supports such tasks by means of a number of path methods,
 133 which we will introduce in the following.
 134
 135 Suppose you want to draw the radii to the intersection points of a
 136 circle with a straight line. This task can be done using the following
 137 code which results in Fig.~\ref{fig:radii}
 138 \verbatiminput{radii.py}
 139 \begin{figure}
 140 \centerline{\includegraphics{radii}}
 141 \caption{Example: Intersection of circle with line yielding two radii.}
 142 \label{fig:radii}
 143 \end{figure}
 144 Here, the basic elements, a circle around the point $(0, 0)$ with
 145 radius $2$ and a straight line, are defined. Then, passing the \var{line}, to
 146 the \method{intersect()} method of \var{circle}, we obtain a tuple of
 147 parameter values of the intersection points. The first element of the
 148 tuple is a list of parameter values for the path whose
 149 \method{intersect()} method has been called, the second element is the
 150 corresponding list for the path passed as argument to this method. In
 151 the present example, we only need one list of parameter values, namely
 152 \var{isects_circle}.  Using the \method{at()} path method to obtain
 153 the point corresponding to the parameter value, we draw the radii for
 154 the different intersection points.
 155
 156 Another powerful feature of \PyX{} is its ability to split paths at a
 157 given set of parameters. For instance, in order to fill in the
 158 previous example the segment of the circle delimited by the straight
 159 line (cf.\ Fig.~\ref{fig:radii2}), one first has to construct a path
 160 corresponding to the outline of this segment. The following code
 161 snippet yields this \var{segment}
 162 \begin{verbatim}
 163 arc1, arc2 = circle.split(isects_circle)
 164 if arc1.arclen() < arc2.arclen():
 165     arc = arc1
 166 else:
 167     arc = arc2
 168
 169 isects_line.sort()
 170 line1, line2, line3 = line.split(isects_line)
 171
 172 segment = line2 << arc
 173 \end{verbatim}
 174 \begin{figure}
 175 \centerline{\includegraphics{radii2}}
 176 \caption{Example: Intersection of circle with line yielding radii and
 177   circle segment.}
 178 \label{fig:radii2}
 179 \end{figure}
 180 Here, we first split the circle using the \method{split()} method passing
 181 the list of parameters obtained above. Since the circle is closed,
 182 this yields two arc segments. We then use the \method{arclen()}, which
 183 returns the arc length of the path, to find the shorter of the two
 184 arcs. Before splitting the line, we have to take into account that
 185 the \method{split()} method only accepts a sorted list of parameters.
 186 Finally, we join the straight line and the arc segment. For
 187 this, we make use of the \verb|<<| operator, which not only adds
 188 the paths (which could be done using \samp{line2 + arc}), but also
 189 joins the last subpath of \var{line2} and the first one of
 190 \var{arc}. Thus, \var{segment} consists of only a single subpath
 191 and filling works as expected.
 192
 193 An important issue when operating on paths is the parametrisation
 194 used. Internally, \PyX{} uses a parametrisation which uses an interval
 195 of length $1$ for each path element of a path. For instance, for a
 196 simple straight line, the possible parameter values range from $0$ to
 197 $1$, corresponding to the first and last point, respectively, of the
 198 line. Appending another straight line, would extend this range to a
 199 maximal value of $2$. You can always query this maximal value using
 200 the \method{range()} method of the \class{path} class.
 201
 202 However, the situation becomes more complicated if more complex
 203 objects like a circle are involved. Then, one could be tempted to
 204 assume that again the parameter value range from $0$ to $1$, because
 205 the predefined circle consists just of one \class{arc} together with a
 206 \class{closepath} element. However, as a simple \samp{path.circle(0,
 207   0, 1).range()} will tell, this is not the case: the actual range is
 208 much larger. The reason for this behaviour lies in the internal path
 209 handling of \PyX: Before performing any non-trivial geometrical
 210 operation with a path, it will automatically be converted into an
 211 instance of the \class{normpath} class (see also
 212 Sect.~\ref{path:normpath}). These so generated paths are already
 213 separated in their subpaths and only contain straight lines and
 214 B\'ezier curve segments. Thus, as is easily imaginable, they are much
 215 simpler to deal with.
 216
 217 A unique way of accessing a point on the path is to use the arc length
 218 of the path segment from the first point of the path to the given
 219 point. Thus, all \PyX{} path methods that accept a parameter value
 220 also allow the user to pass an arc length. For instance,
 221 \begin{verbatim}
 222 from math import pi
 223
 224 pt1 = path.circle(0, 0, 1).at(arclen=pi)
 225 pt2 = path.circle(0, 0, 1).at(arclen=3*pi/2)
 226
 227 c.stroke(path.path(path.moveto(*pt1), path.lineto(*pt2)))
 228 \end{verbatim}
 229 will draw a straight line from a point at angle $180$ degrees (in
 230 radians $\pi$) to another point at angle $270$ degrees (in radians
 231 $3\pi/2$) on the unit circle.
 232
 233 More information on the available path methods can be found
 234 in Sect.~\ref{path:path}.
 235
 236 \section{Attributes: Styles and Decorations}
 237
 238 XXX to be done