manual/canvas.tex

   1 \chapter{Module canvas: PostScript interface}
   2
   3 \label{canvas}
   4
   5 The central module for the PostScript access in \PyX{} is named
   6 \verb|canvas|. Besides providing the class \verb|canvas|, which
   7 presents a collection of visual elements like paths, other canvases,
   8 \TeX{} or \LaTeX{} elements, it contains also various path styles (as
   9 subclasses of \texttt{base.PathStyle}), path decorations like arrows
  10 (with the class \texttt{canvas.PathDeco} and subclasses thereof), and
  11 the class \texttt{canvas.clip} which allows clipping of the output.
  12
  13
  14 \section{Class canvas}
  15
  16 This is the basic class of the canvas module, which serves to collect
  17 various graphical and text elements you want to write eventually to an
  18 (E)PS file.
  19
  20 \subsection{Basic usage}
  21
  22 Let us first demonstrate the basic usage of the \texttt{canvas} class.
  23 We start by constructing the main \verb|canvas| instance, which we
  24 shall by convention always name \verb|c|.
  25 \begin{quote}
  26 \begin{verbatim}
  27 from pyx import *
  28
  29 c = canvas.canvas()
  30 \end{verbatim}
  31 \end{quote}
  32 Basic drawing then proceeds via the construction of a \verb|path|, which
  33 can subsequently be drawn on the canvas using the method \verb|stroke()|:
  34 \begin{quote}
  35 \begin{verbatim}
  36 p = path.line(0, 0, 10, 10)
  37 c.stroke(p)
  38 \end{verbatim}
  39 \end{quote}
  40 or more concisely:
  41 \begin{quote}
  42 \begin{verbatim}
  43 c.stroke(path.line(0, 0, 10, 10))
  44 \end{verbatim}
  45 \end{quote}
  46 You can modify the appearance of a path by additionally passing
  47 instances of the class \verb|PathStyle|. For instance, you can draw the
  48 the above path \verb|p| in blue:
  49 \begin{quote}
  50 \begin{verbatim}
  51 c.stroke(p, color.rgb.blue)
  52 \end{verbatim}
  53 \end{quote}
  54 Similarly, it is possible to draw a dashed version of \verb|p|:
  55 \begin{quote}
  56 \begin{verbatim}
  57 c.stroke(p, canvas.linestyle.dashed)
  58 \end{verbatim}
  59 \end{quote}
  60 Combining of several \verb|PathStyle|s is of course also possible:
  61 \begin{quote}
  62 \begin{verbatim}
  63 c.stroke(p, color.rgb.blue, canvas.linestyle.dashed)
  64 \end{verbatim}
  65 \end{quote}
  66 Furthermore, drawing an arrow at the begin or end of the path is done
  67 in a similar way. You just have to use the provided \verb|barrow| and
  68 \verb|earrow| instances:
  69 \begin{quote}
  70 \begin{verbatim}
  71 c.stroke(p, canvas.barrow.normal, canvas.earrow.large)
  72 \end{verbatim}
  73 \end{quote}
  74
  75 Filling of a path is possible via the \verb|fill| method of the canvas.
  76 Let us for example draw a filled rectangle
  77 \begin{quote}
  78 \begin{verbatim}
  79 r = path.rect(0, 0, 10, 5)
  80 c.fill(r)
  81 \end{verbatim}
  82 \end{quote}
  83 Alternatively, you can use the class \verb|filled| of the canvas module
  84 in combination with the \verb|stroke| method:
  85 \begin{quote}
  86 \begin{verbatim}
  87 c.stroke(r, canvas.filled())
  88 \end{verbatim}
  89 \end{quote}
  90
  91 To conclude the section on the drawing of paths, we consider a pretty
  92 sophisticated combination of the above presented \verb|PathStyle|s:
  93 \begin{quote}
  94 \begin{verbatim}
  95 c.stroke(p,
  96          color.rgb.blue,
  97          canvas.earrow.LARge(color.rgb.red,
  98                              canvas.stroked(canvas.linejoin.round),
  99                              canvas.filled(color.rgb.green)))
 100
 101 \end{verbatim}
 102 \end{quote}
 103 This draws the path in blue with a pretty large green arrow at the
 104 end, the outline of which is red and rounded.
 105
 106 A canvas may also be embedded in another one using the \texttt{insert}
 107 method. This may be useful when you want to apply a transformation on
 108 a whole set of operations. XXX: Example
 109
 110 After you have finished the composition of the canvas, you can
 111 write it to a file using the method \verb|writetofile()|. It expects the
 112 required argument \verb|filename|, the name of the output
 113 file. To write your results to the file "test.eps" just call it as follows:
 114 \begin{quote}
 115 \begin{verbatim}
 116 c.writetofile("test")
 117 \end{verbatim}
 118 \end{quote}
 119
 120
 121 \subsection{Methods of the class canvas}
 122
 123 The \verb|canvas| class provides the following methods:
 124
 125 \medskip
 126 \begin{tabularx}
 127   {\linewidth}
 128   {>{\hsize=.85\hsize}X>{\raggedright\arraybackslash\hsize=1.15\hsize}X}
 129   \texttt{canvas} method & function \\
 130   \hline
 131   \texttt{\_\_init\_\_(*args)} & Construct new canvas. \texttt{args}
 132   can be instances of \texttt{trafo.trafo}, \texttt{canvas.clip}
 133   and/or \texttt{canvas.PathStyle}.\\
 134   \texttt{bbox()} &
 135   Returns the bounding box enclosing all elements of the canvas.\\
 136   \texttt{draw(path, *styles)} &
 137   Generic drawing routine for given \texttt{path} on the canvas (\textit{i.e.}\
 138   \texttt{insert}s it together with the necessary \texttt{newpath}
 139   command, applying the given \texttt{styles}. Styles can either be instances of
 140   \texttt{base.PathStyle} or \texttt{canvas.PathDeco} (or subclasses thereof).\\
 141   \texttt{fill(path, *styles)} &
 142   Fills the given \texttt{path} on the canvas, \textit{i.e.}\
 143   \texttt{insert}s it together with the necessary \texttt{newpath},
 144   \texttt{fill} sequence, applying the given \texttt{styles}. Styles can
 145   either be instances of \texttt{base.PathStyle} or
 146   \texttt{canvas.PathDeco} (or subclasses
 147   therof).\\
 148   \texttt{insert(PSOp, *args)} &
 149   Inserts an instance of \texttt{base.PSOp} into the canvas.
 150   If \texttt{args} are present, create a new \texttt{canvas}instance passing
 151   \texttt{args} as arguments and insert it. Returns \texttt{PSOp}.\\
 152   \texttt{set(*styles)} &
 153   Sets the given \texttt{styles} (instances of \texttt{base.PathStyle} or
 154   subclasses) for the rest of the canvas.\\
 155   \texttt{stroke(path, *styles)} &
 156   Strokes the given \texttt{path} on the canvas, \textit{i.e.}\
 157   \texttt{insert}s it togeither with the necessary \texttt{newpath},
 158   \texttt{stroke} sequence, applying the given \texttt{styles}. Styles
 159   can either be instances of \texttt{base.PathStyle} or
 160   \texttt{canvas.PathDeco}
 161   (or subclasses thereof).\\
 162   \texttt{text(x, y, text, *args)} &
 163   Inserts \texttt{text} into the
 164   canvas (shortcut for
 165   \texttt{insert(texrunner.text(x, y, text, *args))}).\\
 166   \texttt{texrunner(texrunner)} &
 167   Sets the \texttt{texrunner}; default is \texttt{defaulttexrunner}
 168   from the \texttt{text} module.\\
 169     \texttt{writetofile(filename,
 170       \newline\phantom{writetofile(}paperformat=None,
 171       \newline\phantom{writetofile(}rotated=0,
 172       \newline\phantom{writetofile(}fittosize=0,
 173       \newline\phantom{writetofile(}margin="1 t cm",
 174       \newline\phantom{writetofile(}bbox=None,
 175       \newline\phantom{writetofile(}bboxenlarge="1 t pt")} &
 176   Writes the canvas to \texttt{filename}. Optionally, a
 177   \texttt{paperformat} can be specified, in which case the output will
 178   be centered with respect to the corresponding size using the given
 179   \texttt{margin}. See \texttt{canvas.\_paperformats} for a list of
 180   known paper formats . Use \texttt{rotated}, if you want to center on
 181   a $90^\circ$ rotated version of the respective paper format. If
 182   \texttt{fittosize} is set, the output is additionally scaled to the
 183   maximal possible size. Normally, the bounding box of the canvas is
 184   calculated automatically from the bounding box of its elements.
 185   Alternatively, you may specify the \texttt{bbox} manually. In any
 186   case, the bounding box becomes enlarged on all side by
 187   \texttt{bboxenlarge}. This may be used to compensate for the
 188   inability of \PyX{} to take the linewidths into account for the
 189   calculation of the bounding box.
 190 \end{tabularx}
 191 \medskip
 192
 193 \section{Patterns}
 194
 195 The \texttt{pattern} class allows the definition of PostScript Tiling
 196 patterns (cf.\ Sect.~4.9 of the PostScript Language Reference Manual)
 197 which may then be used to fill paths. The classes \texttt{pattern} and
 198 \texttt{canvas} differ only in their constructor and in the absence of
 199 a \texttt{writetofile} method in the former. The \texttt{pattern}
 200 constructor accepts the following keyword arguments:
 201
 202 \medskip
 203 \begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
 204 keyword&description\\
 205 \hline
 206 \texttt{painttype}&\texttt{1} (default) for coloured patterns or
 207 \texttt{2} for uncoloured patterns\\
 208 \texttt{tilingtype}&\texttt{1} (default) for constant spacing tilings
 209 (patterns are spaced constantly by a multiple of a device pixel),
 210 \texttt{2} for undistored pattern cell, whereby the spacing may vary
 211 by as much as one device pixel, or \texttt{3} for constant spacing and
 212 faster tiling which behaves as tiling type \texttt{1} but with
 213 additional distortion allowed to permit a more efficient
 214 implementation.\\
 215 \texttt{xstep}&desired horizontal spacing between pattern cells, use
 216 \texttt{None} (default) for automatic calculation from pattern
 217 bounding box.\\
 218 \texttt{ystep}&desired vertical spacing between pattern cells, use
 219 \texttt{None} (default) for automatic calculation from pattern
 220 bounding box.\\
 221 \texttt{bbox}&bounding box of pattern. Use \texttt{None} for an
 222 automatical determination of the bounding box (including an
 223 enlargement by $5$ pts on each side.)\\
 224 \texttt{trafo}&additional transformation applied to pattern or
 225 \texttt{None} (default). This may be used to rotate the pattern or to
 226 shift its phase (by a translation).
 227 \end{tabularx}
 228 \medskip
 229
 230 After you have created a pattern instance, you define the pattern
 231 shape by drawing in it like in an ordinary canvas. To use the pattern,
 232 you simply pass the pattern instance to a \texttt{stroke},
 233 \texttt{fill}, \texttt{draw} or \texttt{set} method of the canvas,
 234 just like you would to with a colour, etc.
 235
 236
 237
 238 \section{Subclasses of base.PathStyle}
 239
 240 The \verb|canvas| module provides a number of subclasses of the class
 241 \verb|base.PathStyle|, which allow to change the look of the paths
 242 drawn on the canvas. They are summarized in Appendix~\ref{pathstyles}.
 243
 244 % \section{Examples}
 245
 246
 247
 248
 249 %%% Local Variables:
 250 %%% mode: latex
 251 %%% TeX-master: "manual.tex"
 252 %%% End: