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