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, the purpose of which is
  17 the collection of various graphical and text elements you want to
  18 write eventually to an (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 import pyx
  28
  29 c = canvas.canvas()
  30 \end{verbatim}
  31 \end{quote}
  32 Basic drawing proceeds then via the construction of a \verb|path|, which
  33 can subsequently be drawn on the canvas using the method \verb|stoke()|:
  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, as well:
  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 sophisicated 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 After you are finished with the composition of your canvas, you can
 107 write it to a file using the method \verb|writetofile()|. It expects the
 108 obligatory argument \verb|filename|, the name of the output
 109 file. To write your results to the file "test.eps" just call it as follows:
 110 \begin{quote}
 111 \begin{verbatim}
 112 c.writetofile("test")
 113 \end{verbatim}
 114 \end{quote}
 115
 116
 117 \subsection{Methods of the class canvas}
 118
 119 The \verb|canvas| class provides the following methods:
 120
 121 \medskip
 122 \begin{tabularx}
 123   {\linewidth}
 124   {>{\hsize=.85\hsize}X>{\raggedright\arraybackslash\hsize=1.15\hsize}X}
 125   \texttt{canvas} method & function \\
 126   \hline
 127   \texttt{\_\_init\_\_(*args)} & Construct new canvas. \texttt{args}
 128   can be instances of \texttt{trafo.trafo}, \texttt{canvas.clip}
 129   and/or \texttt{canvas.PathStyle}.\\
 130   \texttt{bbox()} &
 131   Returns the bounding box enclosing all elements of the canvas.\\
 132   \texttt{draw(path, *styles)} &
 133   Generic drawing routine for given \texttt{path} on the canvas (\textit{i.e.}\
 134   \texttt{insert}s it together with the necessary \texttt{newpath}
 135   command, applying the given \texttt{styles}. Styles can either be instances of
 136   \texttt{base.PathStyle} or \texttt{canvas.PathDeco} (or subclasses thereof).\\
 137   \texttt{fill(path, *styles)} &
 138   Fills the given \texttt{path} on the canvas, \textit{i.e.}\
 139   \texttt{insert}s it together with the necessary \texttt{newpath},
 140   \texttt{fill} sequence, applying the given \texttt{styles}. Styles can
 141   either be instances of \texttt{base.PathStyle} or
 142   \texttt{canvas.PathDeco} (or subclasses
 143   therof).\\
 144   \texttt{insert(*PSOps)} &
 145   Inserts one ore more instances of the class \texttt{base.PSOp} in the
 146   canvas and returns the last one. Thereby, instances of \texttt{canvas.canvas} are
 147   bracketed by \texttt{gsave}/\texttt{grestore} pair. \\
 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, *styles)} &
 152   Strokes the given \texttt{path} on the canvas, \textit{i.e.}\
 153   \texttt{insert}s it together with the necessary \texttt{newpath},
 154   \texttt{stroke} sequence, applying the given \texttt{styles}. Styles
 155   can either be instances of \texttt{base.PathStyle} or
 156   \texttt{canvas.PathDeco}
 157   (or subclasses thereof).\\
 158     \texttt{writetofile(filename,
 159       \newline\phantom{writetofile(}paperformat=None,
 160       \newline\phantom{writetofile(}rotated=0,
 161       \newline\phantom{writetofile(}fittosize=0,
 162       \newline\phantom{writetofile(}margins="1 t cm")} &
 163   Writes the canvas to \texttt{filename}. Optionally a
 164   \texttt{paperformat} can be specified, in which case the output will
 165   be centered with respect to the corresponding size using the given
 166   \texttt{margin}. See \texttt{canvas.\_paperformats} for a list of
 167   known paper formats . Use \texttt{rotated}, if you want to center on
 168   a $90^\circ$ rotated version of the respective paper format. If
 169   \texttt{fittosize} is set, the output is additionally scaled to the
 170   maximal possible size.
 171 \end{tabularx}
 172 \medskip
 173
 174
 175
 176
 177 \section{Subclasses of base.PathStyle}
 178
 179 The \verb|canvas| module provides a number of subclasses of the class
 180 \verb|base.PathStyle|, which allow to change the look of the paths
 181 drawn on the canvas.
 182
 183
 184
 185
 186
 187 %%% Local Variables:
 188 %%% mode: latex
 189 %%% TeX-master: "manual.tex"
 190 %%% End: