plasTeX 3.0 — A Python Framework for Processing LaTeX Documents

5.2.3 Generating Images

Not all output types that you might render are going to support everything that LaTeX is capable of. For example, HTML has no way of representing TikZ pictures directly, and most output types won’t be capable of rendering LaTeX’s picture environment. In cases like these, you can let plasTeX generate images of the document node. Generating images is done with a subclass of plasTeX.Imagers.Imager. The imager is responsible for creating a LaTeX document from the requested document fragments, compiling the document and converting each page of the output document into individual images. See section 2.1.6 on how to select an imager. The next section will explain how to generate vector images such as SVG images, which are often a better solution because they scale much better.

To generate an image of a document node, simply access the image property during the rendering process. This property will return an plasTeX.Imagers.Image instance. In most cases, the image file will not be available until the rendering process is finished since most renderers will need the generated LaTeX document to be complete before compiling it and generating the final images.

The example below demonstrates how to generate an image for the tikzcd environment (this is for illustration purposes only, plasTeXactually comes with a better handling of this package).

# Import renderer from first renderer example
from MyRenderer import Renderer

from plasTeX.TeX import TeX

def handle_tikzcd(node):
    return '<div><img src="%s"/></div>' % node.image.url

# Instantiate a TeX processor and parse the input text
tex = TeX()
tex.input(r'''
\documentclass{book}
\begin{document}

Previous paragraph.

\begin{tikzcd}
A \dar \rar & B \dar \\
C \rar & D
\end{tikzcd}

Next paragraph.

\end{document}
''')
document = tex.parse()

# Instantiate the renderer
renderer = Renderer()

# Insert the rendering method into all of the environment that might need it
renderer['tikzcd'] = handle_tikzcd

# Render the document
renderer.render(document)

The rendered output looks like the following, and the image is generated is located in ‘images/img-0001.png’.

<document>
<par>
Previous paragraph.
</par><par>
<div><img src="images/img-0001.png"/></div>
</par><par>
Next paragraph.
</par>
</document>

The names of the image files are determined by the document’s configuration. The filename generator is very powerful, and is in fact, the same filename generator used to create the other output filenames. For more information on customizing the image filenames see section 2.1.6.

In addition, the image types are customizable as well. plasTeX uses the Python Imaging Library (PIL) to do the final cropping and saving of the image files, so any image format that PIL supports can be used. The format that PIL saves the images in is determined by the file extension in the generated filenames, so you must use a file extension that PIL recognizes.

It is possible to write your own Imager subclass if necessary. See the Imager API documentation for more information (see 6.7).