# Module `canvas`

In addition it contains the class `canvas.clip` which allows clipping of the output.

## Class `canvas`

This is the basic class of the canvas module. Instances of this class collect visual elements like paths, other canvases, TeX or LaTeX elements. A canvas may also be embedded in another one using its `insert` method. This may be useful when you want to apply a transformation on a whole set of operations.

class `canvas.``canvas`(attrs=[], texrunner=None)

  Construct a new canvas, applying the given attrs, which can be instances of `trafo.trafo`, `canvas.clip`, `style.strokestyle` or `style.fillstyle`. The texrunner argument can be used to specify the texrunner instance used for the `text()` method of the canvas. If not specified, it defaults to text.defaulttexrunner.

Paths can be drawn on the canvas using one of the following methods:

`canvas.``draw`(path, attrs)

  Draws path on the canvas applying the given attrs. Depending on the attrs the path will be filled, stroked, ornamented, or a combination thereof. For the common first two cases the following two convenience functions are provided.

`canvas.``fill`(path, attrs=[])

  Fills the given path on the canvas applying the given attrs.

`canvas.``stroke`(path, attrs=[])

  Strokes the given path on the canvas applying the given attrs.

Arbitrary allowed elements like other `canvas` instances can be inserted in the canvas using

`canvas.``insert`(item, attrs=[])

  Inserts an instance of `base.canvasitem` into the canvas. If attrs are present, item is inserted into a new `canvas` instance with attrs as arguments passed to its constructor. Then this `canvas` instance is inserted itself into the canvas.

Text output on the canvas is possible using

`canvas.``text`(x, y, text, attrs=[])

  Inserts text at position (x, y) into the canvas applying attrs. This is a shortcut for `insert(texrunner.text(x, y, text, attrs))`.

To group drawing operations, layers can be used:

`canvas.``layer`(name, above=None, below=None)

  This method creates or gets a layer with name name.

  A layer is a canvas itself and can be used to combine drawing operations for ordering purposes, i.e., what is above and below each other. The layer name name is a dotted string, where dots are used to form a hierarchy of layer groups. When inserting a layer, it is put on top of its layer group except when another layer of this group is specified by means of the parameters above or below.

The `canvas` class provides access to the total geometrical size of its element:

`canvas.``bbox`()

  Returns the bounding box enclosing all elements of the canvas (see Sect. `bbox`).

A canvas also allows to set its TeX runner:

`canvas.``settexrunner`(texrunner)

  Sets a new texrunner for the canvas.

The contents of the canvas can be written to a file using the following convenience methods, which wrap the canvas into a single page document.

`canvas.``writeEPSfile`(file, *args, **kwargs)

  Writes the canvas to file using the EPS format. file either has to provide a write method or it is used as a string containing the filename (the extension `.eps` is appended automatically, if it is not present). This method constructs a single page document, passing args and kwargs to the `document.page` constructor and calls the `writeEPSfile()` method of this `document.document` instance passing the file.

`canvas.``writePSfile`(file, *args, **kwargs)

  Similar to `writeEPSfile()` but using the PS format.

`canvas.``writePDFfile`(file, *args, **kwargs)

  Similar to `writeEPSfile()` but using the PDF format.

`canvas.``writetofile`(filename, *args, **kwargs)

  Determine the file type (EPS, PS, or PDF) from the file extension of filename and call the corresponding write method with the given arguments arg and kwargs.

`canvas.``pipeGS`(device, seekable=False, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, ciecolor=False, input="eps", **kwargs)

  This method pipes the content of a canvas to the ghostscript interpreter to generate other output formats. The output is returned by means of a python file object. As this file object is generated from a pipe, it is not seekable by default. To make it seekable, enable the seekable flag. device specifies a ghostscript output device by a string. Depending on the ghostscript configuration `"png16"`, `"png16m"`, `"png256"`, `"png48"`, `"pngalpha"`, `"pnggray"`, `"pngmono"`, `"jpeg"`, and `"jpeggray"` might be available among others. See the output of `gs --help` and the ghostscript documentation for more information.

  resolution specifies the resolution in dpi (dots per inch). gscmd is the command to be used to invoke ghostscript. gsoptions is an option string passed to the ghostscript interpreter. textalphabits and graphicsalphabits are convenient parameters to set the `TextAlphaBits` and `GraphicsAlphaBits` options of ghostscript. The addition of these options can be skipped by setting their values to `None`. ciecolor adds the `-dUseCIEColor` flag to improve the CMYK to RGB color conversion. input can be either `"eps"` or `"pdf"` to select the input type to be passed to ghostscript (note slightly different features available in the different input types regarding e.g. `epsfile` inclusion and transparency).

  kwargs are passed to the `writeEPSfile()` method (not counting the file parameter), which is used to generate the input for ghostscript. By that you gain access to the `document.page` constructor arguments.

`canvas.``writeGSfile`(filename=None, device=None, **kwargs)

  This method is similar to pipeGS, but the content is written into the file filename. If filename is None it is auto-guessed from the script name. If filename is “-“, the output is written to stdout. In both cases, a device needs to be specified to define the format (and the file suffix in case the filename is created from the script name).

  If device is None, but a filename with suffix is given, PNG files will be written using the png16m device and JPG files using the jpeg device.

  All other arguments are identical to those of the `canvas.pipeGS()`.

For more information about the possible arguments of the `document.page` constructor, we refer to Sect. `document`.

## Class `clip`

In addition the canvas module contains the class `canvas.clip` which allows for clipping of the output by passing a clipping instance to the attrs parameter of the canvas constructor.