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, [deco.barrow.normal, deco.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 attribute \verb|filled| of the deco 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           deco.earrow.LARge([color.rgb.red,
  99                              deco.stroked([style.linejoin.round]),
 100                              deco.filled([color.rgb.green])])])
 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, attrs)} &
 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{attrs}. \\
 140   \texttt{fill(path, attrs=[])} &
 141   Fills the given \texttt{path} on the canvas, \textit{i.e.}\
 142   \texttt{insert}s it together with the necessary \texttt{newpath},
 143   \texttt{fill} sequence, applying the given \texttt{attrs}. \\
 144   \texttt{insert(PSOp, *args)} &
 145   Inserts an instance of \texttt{base.PSOp} into the canvas.
 146   If \texttt{args} are present, create a new \texttt{canvas}instance passing
 147   \texttt{args} as arguments and insert it. Returns \texttt{PSOp}.\\
 148   \texttt{set(*styles)} &
 149   Sets the given \texttt{styles} (instances of \texttt{base.PathStyle} or
 150   subclasses) for the rest of the canvas.\\
 151   \texttt{stroke(path, attrs=[])} &
 152   Strokes the given \texttt{path} on the canvas, \textit{i.e.}\
 153   \texttt{insert}s it togeither with the necessary \texttt{newpath},
 154   \texttt{stroke} sequence, applying the given \texttt{attrs}. \\
 155   \texttt{text(x, y, text, *args)} &
 156   Inserts \texttt{text} into the
 157   canvas (shortcut for
 158   \texttt{insert(texrunner.text(x, y, text, *args))}).\\
 159   \texttt{texrunner(texrunner)} &
 160   Sets the \texttt{texrunner}; default is \texttt{defaulttexrunner}
 161   from the \texttt{text} module.\\
 162     \texttt{writetofile(filename,
 163       \newline\phantom{writetofile(}paperformat=None,
 164       \newline\phantom{writetofile(}rotated=0,
 165       \newline\phantom{writetofile(}fittosize=0,
 166       \newline\phantom{writetofile(}margin="1 t cm",
 167       \newline\phantom{writetofile(}bbox=None,
 168       \newline\phantom{writetofile(}bboxenlarge="1 t pt")} &
 169   Writes the canvas to \texttt{filename}. Optionally, a
 170   \texttt{paperformat} can be specified, in which case the output will
 171   be centered with respect to the corresponding size using the given
 172   \texttt{margin}. See \texttt{canvas.\_paperformats} for a list of
 173   known paper formats . Use \texttt{rotated}, if you want to center on
 174   a $90^\circ$ rotated version of the respective paper format. If
 175   \texttt{fittosize} is set, the output is additionally scaled to the
 176   maximal possible size. Normally, the bounding box of the canvas is
 177   calculated automatically from the bounding box of its elements.
 178   Alternatively, you may specify the \texttt{bbox} manually. In any
 179   case, the bounding box becomes enlarged on all side by
 180   \texttt{bboxenlarge}. This may be used to compensate for the
 181   inability of \PyX{} to take the linewidths into account for the
 182   calculation of the bounding box.
 183 \end{tabularx}
 184 \medskip
 185
 186 \section{Patterns}
 187
 188 The \texttt{pattern} class allows the definition of PostScript Tiling
 189 patterns (cf.\ Sect.~4.9 of the PostScript Language Reference Manual)
 190 which may then be used to fill paths. The classes \texttt{pattern} and
 191 \texttt{canvas} differ only in their constructor and in the absence of
 192 a \texttt{writetofile} method in the former. The \texttt{pattern}
 193 constructor accepts the following keyword arguments:
 194
 195 \medskip
 196 \begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
 197 keyword&description\\
 198 \hline
 199 \texttt{painttype}&\texttt{1} (default) for coloured patterns or
 200 \texttt{2} for uncoloured patterns\\
 201 \texttt{tilingtype}&\texttt{1} (default) for constant spacing tilings
 202 (patterns are spaced constantly by a multiple of a device pixel),
 203 \texttt{2} for undistored pattern cell, whereby the spacing may vary
 204 by as much as one device pixel, or \texttt{3} for constant spacing and
 205 faster tiling which behaves as tiling type \texttt{1} but with
 206 additional distortion allowed to permit a more efficient
 207 implementation.\\
 208 \texttt{xstep}&desired horizontal spacing between pattern cells, use
 209 \texttt{None} (default) for automatic calculation from pattern
 210 bounding box.\\
 211 \texttt{ystep}&desired vertical spacing between pattern cells, use
 212 \texttt{None} (default) for automatic calculation from pattern
 213 bounding box.\\
 214 \texttt{bbox}&bounding box of pattern. Use \texttt{None} for an
 215 automatical determination of the bounding box (including an
 216 enlargement by $5$ pts on each side.)\\
 217 \texttt{trafo}&additional transformation applied to pattern or
 218 \texttt{None} (default). This may be used to rotate the pattern or to
 219 shift its phase (by a translation).
 220 \end{tabularx}
 221 \medskip
 222
 223 After you have created a pattern instance, you define the pattern
 224 shape by drawing in it like in an ordinary canvas. To use the pattern,
 225 you simply pass the pattern instance to a \texttt{stroke},
 226 \texttt{fill}, \texttt{draw} or \texttt{set} method of the canvas,
 227 just like you would to with a colour, etc.
 228
 229
 230
 231 \section{Subclasses of base.PathStyle}
 232
 233 The \verb|canvas| module provides a number of subclasses of the class
 234 \verb|base.PathStyle|, which allow to change the look of the paths
 235 drawn on the canvas. They are summarized in Appendix~\ref{pathstyles}.
 236
 237 % \section{Examples}
 238
 239
 240
 241
 242 %%% Local Variables:
 243 %%% mode: latex
 244 %%% TeX-master: "manual.tex"
 245 %%% End: