The Status of 0.2

Last Wednesday I pushed out the first release candidate of 0.2. The main motivation behind the release was to get the new caching code (needed by matplotlib) out into the wild as soon as possible.

However, soon after my mentor, Michael Droettboom, sent me a patch adding support for the MathML torture tests to mathtex. These tests resulted in several issues being filed against mathtex. Further, Michael was kind enough to provide patches for many of then — which I hastily added to mathtex.

The result? The mathtex of today has much better rendering than the mathtex of a week ago. However, it does also mean that the differences between 0.2 RC 1 and 0.2 will be substantial — enough to warrant a version-bump. It is for this reason that I am planning to skip the 0.2 release series and go straight to 0.3 RC 1.

I expect to tag the release in the next day or so, but there is at least one issue which I would like to squish before doing so.

Rendering Improvements

Over the past couple of days I have been working to improve the rendering quality of mathtex. Rather than describe the changes with several paragraphs of prose I thought it more apt to have a before-and-after picture instead.

Before:

After:As can be seen the result is much closer to that produced by LaTeX.

YAPP (Yet Another Progress Report)

It only just hit that it has been well over a week since my last blog post. This is unfortunate, as I like to blog at least once a week. Without further ado here is what has been happening in mathtex this week.

Firstly, the matplotlib integration was tidied up. Mathtex is currently an optional component of matplotlib and has completely replaced the internal TeX rendering engine. I am hopeful that with a few tweaks it can be merged in the near future into the mainline matplotlib repository.

Secondly, the first public version of mathtex was released — 0.1 RC 1. However, due to an (embarrassing) slip-up on my part it was quickly superseded by 0.1 RC 2. For those who are interested it can be downloaded from http://code.google.com/p/mathtex/downloads/list Assuming all is well I hope to have a final release out by the end of the week.

Finally, the mailing list has been more active than ever! Over the past few days there have been several interesting discussions on equation breaking, build errors and how to use mathtex from a C/C++ application. Although not broad enough to constitute a blog post the topics make interesting reads nether the less.

Branching Off

As the more astute (or stalker) readers may have noticed there have not been any commits to the mathtex subversion repository over the past couple of days. The reason for this is because over the past couple of days (and probably for a few more) I have been working on re-integrating mathtex back into matplotlib.

The work — for those that are interested — is being done in the mathtex branch of the matplotlib subversion repository. This reintegration is especially important as although the success rate for summer of code projects is high (around 80% I believe) a surprising number of the projects never 'go gold' and make it into actual releases. Instead they live their days out in branches and separate repositories.

To ensure that mathtex does not succumb to this fate I have started integrating it back into matplotlib as soon as possible. This has several advantages: firstly it gives the API a good work-out to ensure that there are no glaring issues — reducing the chances that the API will change in the future; secondly it allows for mathtex to have a much wider userbase than it would have otherwise.

While it should not take long to port all of the existing backends over to mathtex the precise manner in which mathtex will be bundled with matplotlib is still up for debate. (But, it is almost certain that it will be bundled, resulting in no extra dependencies for matplotlib.) Once this is done — and tested — mathtex should be on much firmer ground.

Enhancements to the Command Line Utility

Today I implemented a challenge-response style persistence mode to the command line utility. Usually, the command line utility — which ships as part of mathtex — exits as soon as it has finished rendering the equation.

However, in persistence mode, which is invoked by providing no output file it works as follows:

./mathtext

$x+y=2$

/tmp/tmpg0gkiX.mathtex.png

$xy=4$

/tmp/tmpCqTVBH.mathtex.png

Upon entering persistence mode mathtext waits for an equation on stdin; after an equation has been typed in it is rendered and the filename — generated automatically — is written to stdout. This not only makes batch processing of equations easier but also makes it a lot more convenient to use mathtex in another application.

Rather than having to spawn a new instance of ./mathtext every time you need to render an equation you instead can just launch a single instance and pipe equations to it. This is significantly faster than spawning a new instance.

The resulting equations remain in the systems temporary directory until the caller deletes them. Alternative file formats are available by using the -j flag.

Testing, Testing...

Sadly this week I do not have any pretty pictures to show you.

However, for those of you still reading I would like to tell you about the unit/regression tests that are being added in Mathtex. Anyone who has been watching the commit log will know just how easy it is to break something in Mathtex. I have done this several times without even touching the rendering code.

Therefore last week I started work on a regression testing suite to ensure that layout and rendering errors can be caught before committing. There are currently around forty tests which cover most of the functionality in Mathtex. The suite runs each test several times — at different resolutions with different fonts.

Currently passes and failures are determined by hashing the generated bit-maps and seeing if they match to the reference hashes (kept in subversion). However, this is currently dependant on the version of FreeType used. (Different versions produce slightly different bit-maps for the same input.) Hence I am currently looking into fuzzy comparisons in order to account for these slight variations.

Rendering: Now Bug-for-Bug Compatible

Over the last week or so I have been doing a couple of things. Firstly, integrating FT2Font and the font-manager from matplotlib into mathtex to remove the dependency on matplotlib and secondly fixing various rendering issues.

As of r21 mathtex is now on a par with matplotlib. What follows are some sample renderings, showcasing what is currently possible and also highlighting areas where work is needed.


This showcases a simple square root. Although the left- and top-padding it is big excessive it is perfectly acceptable.


This is Euler's formula. Notice the un-even spacing around the = sign and the less-than-usual spacing around operators.


Here we have an integral. Although the fraction looks nice there is far too little spacing between the slanted integral symbol and the fraction.


And finally we have the quadratic formula. Instead of Computer Modern (Bakoma fonts) which are usually used with TeX this equation is typeset using the STIX fonts. Apart from a minor spacing issue (the -4ac) it renders quite nicely.

While my current focus is on getting a clean library API ready once that is done I should have time to correct some of these (minor) rendering issues.