## 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 LaTeX 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 LaTeX 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 LaTeX 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 LaTeX document is written to.

`verification`

  command that verifies the existence of the image converter on the current machine. If `verification` is not specified, the executable specified in `command` is executed with the --help. If the return code is zero, the imager is considered valid. If the return code is anything else, the imager is not considered valid.

`close``(``)`

  closes the generated LaTeX document and starts the image generation routine.

`compileLatex``(`source`)`

  the method responsible for compiling the LaTeX source.

  source is a file object containing the LaTeX document.

`convert``(`output`)`

  sets up the temporary environment for the image converter, then executes `executeConverter`. It also moves the generated images into their final location specified in the configuration.

`executeConverter``(`output`)`

  executes the command that converts the output from the LaTeX compiler into image files.

  output is a file object containing the compiled output of the LaTeX document.

`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 LaTeX content in text.

  context is the LaTeX 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 LaTeX 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 LaTeX code that an image is needed of.

  context is the LaTeX 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.