manual/canvas.rst

   1
   2 .. module:: canvas
   3
   4 ====================
   5 Module :mod:`canvas`
   6 ====================
   7
   8 .. sectionauthor:: Jörg Lehmann <joergl@users.sourceforge.net>
   9
  10
  11 In addition it
  12 contains the class ``canvas.clip`` which allows clipping of the output.
  13
  14
  15 Class :class:`canvas`
  16 ---------------------
  17
  18 This is the basic class of the canvas module. Instances of this class collect
  19 visual elements like paths, other canvases, TeX or LaTeX elements. A canvas may
  20 also be embedded in another one using its ``insert`` method. This may be useful
  21 when you want to apply a transformation on a whole set of operations.
  22
  23 .. class:: canvas(attrs=[], texrunner=None)
  24
  25    Construct a new canvas, applying the given *attrs*, which can be instances of
  26    :class:`trafo.trafo`, :class:`canvas.clip`, :class:`style.strokestyle` or
  27    :class:`style.fillstyle`.  The *texrunner* argument can be used to specify the
  28    texrunner instance used for the :meth:`text` method of the canvas.  If not
  29    specified, it defaults to *text.defaulttexrunner*.
  30
  31 Paths can be drawn on the canvas using one of the following methods:
  32
  33
  34 .. method:: canvas.draw(path, attrs)
  35
  36    Draws *path* on the canvas applying the given *attrs*. Depending on the
  37    *attrs* the path will be filled, stroked, ornamented, or a combination
  38    thereof. For the common first two cases the following two convenience
  39    functions are provided.
  40
  41
  42 .. method:: canvas.fill(path, attrs=[])
  43
  44    Fills the given *path* on the canvas applying the given *attrs*.
  45
  46
  47 .. method:: canvas.stroke(path, attrs=[])
  48
  49    Strokes the given *path* on the canvas applying the given *attrs*.
  50
  51 Arbitrary allowed elements like other :class:`canvas` instances can be inserted
  52 in the canvas using
  53
  54
  55 .. method:: canvas.insert(item, attrs=[])
  56
  57    Inserts an instance of :class:`base.canvasitem` into the canvas.  If *attrs* are
  58    present, *item* is inserted into a new :class:`canvas` instance with *attrs*
  59    as arguments passed to its constructor. Then this :class:`canvas` instance
  60    is inserted itself into the canvas.
  61
  62 Text output on the canvas is possible using
  63
  64
  65 .. method:: canvas.text(x, y, text, attrs=[])
  66
  67    Inserts *text* at position (*x*, *y*) into the canvas applying *attrs*. This is
  68    a shortcut for ``insert(texrunner.text(x, y, text, attrs))``.
  69
  70 To group drawing operations, layers can be used:
  71
  72
  73 .. method:: canvas.layer( name, above=None, below=None)
  74
  75    This method creates or gets a layer with name *name*.
  76
  77    A layer is a canvas itself and can be used to combine drawing operations for
  78    ordering purposes, i.e., what is above and below each other. The layer name
  79    *name* is a dotted string, where dots are used to form a hierarchy of layer
  80    groups. When inserting a layer, it is put on top of its layer group except
  81    when another layer instance of this group is specified by means of the
  82    parameters *above* or *below*.
  83
  84
  85 The :class:`canvas` class provides access to the total geometrical size of its
  86 element:
  87
  88
  89 .. method:: canvas.bbox()
  90
  91    Returns the bounding box enclosing all elements of the canvas (see Sect. :mod:`bbox`).
  92
  93 A canvas also allows to set its TeX runner:
  94
  95
  96 .. method:: canvas.settexrunner(texrunner)
  97
  98    Sets a new *texrunner* for the canvas.
  99
 100 The contents of the canvas can be written to a file using the following
 101 convenience methods, which wrap the canvas into a single page document.
 102
 103
 104 .. method:: canvas.writeEPSfile(file, *args, **kwargs)
 105
 106    Writes the canvas to *file* using the EPS format. *file* either has to provide a
 107    write method or it is used as a string containing the filename (the extension
 108    ``.eps`` is appended automatically, if it is not present). This method
 109    constructs a single page document, passing *args* and *kwargs* to the
 110    :class:`document.page` constructor and calls the :meth:`writeEPSfile` method
 111    of this :class:`document.document` instance passing the *file*.
 112
 113
 114 .. method:: canvas.writePSfile(file, *args, **kwargs)
 115
 116    Similar to :meth:`writeEPSfile` but using the PS format.
 117
 118
 119 .. method:: canvas.writePDFfile(file, *args, **kwargs)
 120
 121    Similar to :meth:`writeEPSfile` but using the PDF format.
 122
 123
 124 .. method:: canvas.writetofile(filename, *args, **kwargs)
 125
 126    Determine the file type (EPS, PS, or PDF) from the file extension of *filename*
 127    and call the corresponding write method with the given arguments *arg* and
 128    *kwargs*.
 129
 130
 131 .. method:: canvas.pipeGS(device, seekable=False, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, ciecolor=False, input="eps", **kwargs)
 132
 133    This method pipes the content of a canvas to the ghostscript interpreter
 134    to generate other output formats. The output is returned by means of a
 135    python file object. As this file object is generated from a pipe, it is
 136    not seekable by default. To make it seekable, enable the *seekable* flag.
 137    *device* specifies a ghostscript output device by a string. Depending on the
 138    ghostscript configuration ``"png16"``, ``"png16m"``, ``"png256"``,
 139    ``"png48"``, ``"pngalpha"``, ``"pnggray"``, ``"pngmono"``, ``"jpeg"``, and
 140    ``"jpeggray"`` might be available among others. See the output of ``gs
 141    --help`` and the ghostscript documentation for more information.
 142
 143    *resolution* specifies the resolution in dpi (dots per inch). *gscmd* is the
 144    command to be used to invoke ghostscript. *gsoptions* is an option string
 145    passed to the ghostscript interpreter. *textalphabits* and *graphicsalphabits*
 146    are convenient parameters to set the ``TextAlphaBits`` and
 147    ``GraphicsAlphaBits`` options of ghostscript. The addition of these options
 148    can be skipped by setting their values to ``None``. *ciecolor* adds the
 149    ``-dUseCIEColor`` flag to improve the CMYK to RGB color conversion. *input*
 150    can be either ``"eps"`` or ``"pdf"`` to select the input type to be passed
 151    to ghostscript (note slightly different features available in the different
 152    input types regarding e.g. :mod:`epsfile` inclusion and transparency).
 153
 154    *kwargs* are passed to the :meth:`writeEPSfile` method (not counting the *file*
 155    parameter), which is used to generate the input for ghostscript. By that you
 156    gain access to the :class:`document.page` constructor arguments.
 157
 158 .. method:: canvas.writeGSfile(filename=None, device=None, **kwargs)
 159
 160    This method is similar to pipeGS, but the content is written into the file
 161    *filename*. If filename is None it is auto-guessed from the script name. If
 162    filename is "-", the output is written to stdout. In both cases, a device
 163    needs to be specified to define the format (and the file suffix in case the
 164    filename is created from the script name).
 165
 166    If device is None, but a filename with suffix is given, PNG files will
 167    be written using the png16m device and JPG files using the jpeg device.
 168
 169    All other arguments are identical to those of the :meth:`canvas.pipeGS`.
 170
 171 For more information about the possible arguments of the :class:`document.page`
 172 constructor, we refer to Sect. :mod:`document`.
 173
 174
 175 Class :class:`clip`
 176 ---------------------
 177
 178 In addition the canvas module contains the class ``canvas.clip`` which allows for
 179 clipping of the output by passing a clipping instance to the attrs parameter of
 180 the canvas constructor.