manual/canvas.tex

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