INTRODUCTION

Mathtex is a parser/rendering framework for LaTeX math expressions. It can be used either as a library or standalone through a command line utility. The code is based off of that developed by the matplotlib project.

To compile and install mathtex please follow the instructions in INSTALL.

USING MATHTEX

COMMAND LINE

The simplest way to use mathtex is via the command line utility in util/mathtext. It provides access to most of the functionality of mathtex.

Example

$ ./mathtext test.png "\$x + \frac{y}{2}\$"

this will produce a file called test.png in the current directory. There are several things worth noting: firstly the use of $...$ to denote math. Anything outside of $...$ will be treated as regular text. Secondly the need to escape $ when entering them on the command line.

An easier way of passing the expression is by using stdin.

Example

$ ./mathtext test.png
$x + \frac{y}{2}$

If no expression is provided through the command line arguments then mathtext will attempt to read one from stdin.

The file-format is auto detected based off of the provided filename. While the Image backend only supports PNG (.png) the Cairo backend supports SVG (.svg), PDF (.pdf) and PS (.ps). Should the Cairo backend have been compiled without support for a desired format, or not be available at all then an error will be raised.

PYTHON

Mathtex is also easy to use through Python.

Example

>>> from mathtex.mathtex_main import Mathtex
>>> Mathtex("$x+y=z$", 'stix', 14, 100).save('test.pdf')

This will render the expression x+y=z using the STIX fonts at 14pt with a resolution of 100dpi and then save it as test.pdf.

FONT SUPPORT

Mathtex comes with built-in support for the Bakoma (Computer modern) and STIX fonts. The required .ttf files are bundled with mathtex. There is also experimental support for using unicode fonts.

The use of unicode fonts is slightly more complicated than using either Bakoma or STIX. On the command line it is done as follows:

$ ./mathtext test.png -f unicode -u "rm=times new roman,sf=arial"

rm, sf, ..., map to the font used by the corresponding LaTeX command. rm = \rm, sf = \sf and so on. The font can be any TrueType (.ttf) font installed on the system.

Using the mathtex API unicode font support is provided by the UnicodeFonts class from the mathtex.fonts module.

In order to improve performance a font-cache is used. This is automatically generated the first time mathtex is run. By default it is stored in ~/.mathtex. It may take several seconds to generate.

If new fonts are installed on the system the cache will need to be updated. The easiest way to do this is to delete ~/.mathtex.

UNIT/REGRESSION TESTS

Mathtex ships with a regression testing utility. It is currently under heavy development and subject to change. Currently it works by hashing the raw RGBA data generated by the Image backend and comparing it to a hash-file that is distributed with mathtex.

Although mostly functional there are some known issues

1) Different FreeType versions generate different RGBA data for
   the same expression. This results in test failures even when
   the image is acceptable.
2) Not all tests render correctly using the STIX fonts. This is a
   known bug and will be fixed in future releases :)

Running python tests.py --help will provide information about some of the more advanced testing functionality.