Latex Text Rendering

CLUScript defines a number of functions that allow you to render latex text as bitmaps, which may then be used as descriptive text or to annotate visualizations. Note that for these functions to work you need to have the following software installed,

  1. LaTeX,
  2. dvips,
  3. Ghostscript.

Under a Linux standard distribution all this software should already be installed. However, CLUCalc only works properly with either GNU Ghostscript v7.07 or AFPL Ghostscript v8.13, or a later version of either. For example, under SuSE 8.2 only GNU Ghostscript v7.05 is installed, which causes problems, since it does not seem to support eps-cropping. To obtain the latest version of Ghostscript go to www.ghostscript.com. It is also preferable to install AFPL Ghostscript, since it supports anti-aliasing of text. That makes your annotations look much nicer.

Under Windows you will need to install MikTex from www.miktex.org (or something comparable) and AFPL Ghostscript v8.13 or later from www.ghostscript.com. They both come with an installer for Windows and are easy to install.

Rendering Latex

The function that actually renders the Latex text is DrawLatex(x, y, z, [Text]). The text passed in the parameter Text is wrapped with the following LaTeX code before it is processed by latex.
\documentclass{article}

\usepackage{latexsym}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}

\begin{document}
\pagestyle{empty}

[The text from the Text parameter]

\end{document}

Attention:
If an error occurs during the parsing of the LaTeX code, the error messages generated by latex are shown in the output window of CLUCalc.
If you want to use a different wrapper, you need to start the text passed to the DrawLatex() function with "\\plain:". However, in this case you will have to set the documentclass, load the necessary packages and begin and end the document, just as in a proper latex file.

If you want to parse an external file you can do this as well, by passing the following text to the function: "\\file:[the filename]". The path to the file will be taken relative to the path the currently executed script is in.

Each time DrawLatex() is executed, it checks whether the text passed has changed since the last call, or whether a latex file given via "\\file:[the filename]" has been modified. If something has changed the LaTeX code is rendered again and then displayed.

Since not everybody has LaTeX installed but may want to look at a script that uses LaTeX annotations, you can also store the rendered LaTeX bitmaps in a file. These are then simply loaded instead of rendering the latex code every time the script is started. The rendered LaTeX is only stored in a file if the Name parameter is given. The filename used to store the bitmaps is then constructed as follows: "[filename of script]_[\a Name].rlb". The extension "rlb" stands for rendered latex bitmap. It is in fact a simple bitmap file and you can view with any other program simply by renaming the extension of these files to "bmp".

Attention:
Using uncompressed bitmap files to store the rendered latex bitmaps is quite a waste of disk space. I'm working on improving this.
Wether a LaTeX bitmap is rendered from the given text or simply loaded from the disk if available, also depends on a global variable which either enables or disables latex rendering. This variable is set with the function EnableRenderLatex(). By default the rendering of LaTeX code is switched off in CLUCalc. If LaTeX rendering is switched off, the function DrawLatex() always tries to load a previously rendered LaTeX bitmap. If you want to force the rendering of LaTeX nonetheless, you can choose the appropriate menu option from the menu "Code" in the CLUCalc editor window. That LaTeX is not always rendered when a script is loaded is also important for presentations, since you do not want to wait for a couple of seconds before the next slide appears.

Here is a simple example.

// Set the background color to white
_BGColor = White;

// Set Latex Magnification
SetLatexMagStep(10);

// Set the active color
:Blue;
// Draw a formula starting at 
// the front bottom left corner
// of the frame box.
DrawLatex(1.5,-1.5,1.5, 
"\[\int_{-\infty}^\infty\,a_1\wedge b^\|\]",
"formula");

// Set the current color to red.
:Red;

// Start an overlay block.
// Elements drawn within this block 
// are not rotated and translated
// together with the standard 
// visualization frame.
StartOverlay();

// Increase the Latex size
SetLatexMagStep(12);

// Align the drawing of bitmaps to
// the left top corner of the bitmap.
SetLatexAlign(0,1);

// Draw the latex bitmap 10% into the 
// visualization window from the left
// and 10% down from the top.
DrawLatex(10,10,0, 
"Hello,\par This is a little bit of \LaTeX.\par  
\begin{itemize}
\item Start
\item the game.
\end{itemize}",
"text");

// End the overlay block
EndOverlay();

This generates the following visualization.

LatexTest1_img1.jpg