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.