2.6.1 Class canvas

2.6.1 Class `canvas`

This is the basic class of the canvas module, which serves to collect various graphical and text elements you want to write eventually to an (E)PS file.

class 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:

draw( path, attrs): Draws path on the canvas applying the given attrs.

fill( path, attrs=[]): Fills the given path on the canvas applying the given attrs.

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

insert( item, attrs=[]): Inserts an instance of base.canvasitem into the canvas. If attrs are present, item is inserted into a new canvasinstance with attrs as arguments passed to its constructor is created. Then this canvas instance is inserted itself into the canvas.

Text output on the canvas is possible using

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))).

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

bbox( ): Returns the bounding box enclosing all elements of the canvas.

A canvas also allows one to set its TeX runner:

settexrunner( texrunner): Sets a new texrunner for the canvas.

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

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 the calls the writeEPSfile method of this document.document instance passing the file.

writePSfile( file, *args, **kwargs): Similar to writeEPSfile but using the PS format.

writePDFfile( file, *args, **kwargs): Similar to writeEPSfile but using the PDF format.

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.

pipeGS( filename="-", device=None, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, **kwargs)

This method pipes the content of a canvas to the ghostscript interpreter directly to generate other output formats. At least filename or device must be set. filename specifies the name of the output file. No file extension will be added to that name in any case. When no filename is specified, the output is written to stdout. device specifies a ghostscript output device by a string. Depending on your 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. When filename is specified but the device is not set, "png16m" is used when the filename ends in .eps and "jpeg" is used when the filename ends in .jpg.

resolution specifies the resolution in dpi (dots per inch). gscmd is the command to be used to invoke ghostscript. gsoptions are an option string passed to the ghostscript interpreter. textalphabits are graphicsalphabits are conventient parameters to set the TextAlphaBits and GraphicsAlphaBits options of ghostscript. You can skip the addition of those option by set their value to None.

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.

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