plasTeX 3.0 — A Python Framework for Processing LaTeX Documents: Imager Objects

6.7.1 Imager Objects

class Imager(document )

Instantiate the imager class.

document the document object that is being rendered.

The Imager class is responsible for creating a L^aT_eX document of requested images, compiling it, and generating images from each page in the document.

command

specifies the converter that translates the output from the L^aT_eX document compiler (e.g. PDF, DVI, PS) into images (e.g. PNG, JPEG, GIF). The only requirement is that the basename of each image is of the form ‘img%d’ where ‘%d’ is the number of the image.

Note: This is a class attribute.

Writing a renderer requires you to at least override the command that creates images. It can be as simple as the example below.

import plasTeX.Imagers
class DVIPNG(plasTeX.Imagers.Imager):
    """ Imager that uses dvipng """
    command = 'dvipng -o img%d.png -D 110'

compiler

specifies the L^aT_eX document compiler (i.e. latex, pdflatex) command.

Note: This is a class attribute.



config: contains the “images” section of the document configuration.



fileExtension: contains the file extension to use if no extension is supplied by the filename generator.

imageAttrs

contains a string template that will be used as a placeholder in the output document for the image height, width, and depth. These attributes cannot be determined in real-time because images are not generated until after the document has been fully rendered. This template generates a string that is put into the output document so that the image attributes can be post-processed in. For example, the default template (which is rather XML/HTML biased) is:

&${filename}-${attr};

The two variables available are filename , the filename of the image, and attr , the name of the attr (i.e. width, height, or depth).

imageUnits

contains a string template that will be used as a placeholder in the output document for the image units. This template generates a string that is put into the output document so that the image attribute units can be post-processed in. For example, the default template (which is rather XML/HTML biased) is:

&${units);

The only variable available is units and contains the CSS unit that was requested. The generate string will always occur immediately after the string generated by imageAttrs.



images: dictionary that contains the Image objects corresponding to the requested images. The keys are the image filenames.



newFilename: callable iterator that generates filenames according to the filename template in the configuration.



source: file object where the image L^aT_eX document is written to.



verifications: a list of commands that verifies the existence of the image converter on the current machine. If verifications is not specified, the executable specified in command is executed with the --help. If the return code of all commands are zero, the imager is considered valid. Otherwise, the imager is not considered valid.






close( ): closes the generated L^aT_eX document and starts the image generation routine.






compileLatex(source ): the method responsible for compiling the L^aT_eX source. The source file is ‘images.tex‘ in the current working directory (which is a temporary directory, not the directory from which the command is run). The result should be saved in the same directory, to be used by ‘executeConverter‘.






executeConverter(output ): executes the command that converts the output from the L^aT_eX compiler into image files. In the default implementation, it tries to convert from ‘./images.dvi‘, ‘./images.pdf‘ or ‘./images.ps‘, in that order.






getImage(node ): get an image for node in any way possible. The node is first checked to see if the imageoverride attribute is set. If it is, that image is copied to the image directory. If imageoverride is not set, or there was a problem in saving the image in the correct format, an image is generated using the source of node .

newImage(text, [context, filename] )

invokes the creation of an image using the L^aT_eX content in text .

context is the L^aT_eX code that sets up the context of the document. This generally includes the setting of counters so that counters used within the image code are correct.

filename is an optional filename for the output image. Generally, image filenames are generated automatically, but they can be overridden with this argument.






verify( ): verifies that the command in command is valid for the current machine. The verify method returns True if the command will work, or False if it will not.

writeImage(filename, code, context )

writes the L^aT_eX code to the generated document that creates the image content.

filename is the final filename of the image. This is not actually used in the document, but can be handy for debugging.

code is the L^aT_eX code that an image is needed of.

context is the L^aT_eX code that sets up the context of the document. This generally includes the setting of counters so that counters used within the image code are correct.






writePreamble(document ): this method is called when the imager is instantiated and is used to write any extra information to the preamble. If overridden, the subclass needs to make sure that document.preamble.source is the first thing written to the preamble.