Tags

, , , ,

Sometimes you will write a presentation in something that is not LaTeX or design a poster and you want to include equations. These equations you want to be nicely typeset with LaTeX, but they need to be standalone graphics.

This blog post describes a script which will take an input file of the LaTeX code for the equation and process it into either a bitmap (png) or vector (pdf) graphic.

I have previously blogged on this topic using a different method, here. However, I now prefer this method as it is easier to use and faster to do. It also uses much simpler files for the equations and makes it easier to get a coherent look across all the equations in your presentation or poster by using a common preamble.

This blog post is a guide to the script, and explains both how to use it and how it works.

Overview
There are a few stages to the process, first the script constructs a LaTeX file. Then the script processes this LaTeX file, producing the typeset equation as output. Then it crops the pdf and optionally converts to raster (png) graphics at high resolution. Finally it cleans up all the temporary files created.

Usage
The user must provide a LaTeX based input file containing the code to typeset the equation. This is standard LaTeX code when the packages amsmath,amssymb,bm,amsthm,bbold,latexsym,inputenc,fontenc, and mathrsfs are loaded. The user’s input file gets placed inside an equation environment so the user can get straight on to writing the equation.

When calling the script the user must provide an option flag to set the output to either -v (for vector, pdf, graphics) or -b (for bitmap, png, graphics).

The Input Files
The script then creates two temporary files to concatenate with the .texpart file to create the temporary .tex file. The contents of these files is as follows:

\documentclass{article}
\usepackage{amsmath,amssymb,bm,amsthm,bbold}
\usepackage{latexsym}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{mathrsfs}
\begin{document}
\pagestyle{empty}
\begin{equation*}

for part 1, and,

\end{equation*}
\end{document}

for part 3, with part 2 being provided by the .texpart file.

This is fairly standard for a stripped down document preamble. We use the empty pagestyle because it removes any page numbers and the starred equation environment to remove equation labels. We want the page to be completely empty apart from the equation. This will help the cropping program automatically determine the size to crop to. The part 1 file can be altered by adding or removing packages or providing any formatting specifications as the user desires.

The three files are put together using cat and >.

cat part1.temp $2 part3.temp > full.temp.tex

The user input file will always be at $2 because the option flags count as an input.

Processing the file
The script runs lualatex using this command,

lualatex -interaction=batchmode full.temp.tex

Note the option -interaction=batchmode silences the main LaTeX run, and prevents it from stopping on errors or warnings. I use lualatex here because it has been recognised as the successor to pdflatex but it is possible to swap it out for any latex engine that produces a pdf output directly. It is even possible to swap it out for a set of commands that produce a pdf output indirectly, but for the purposes of this script I will treat it as creating a pdf file.

Option testing
The option to specify bitmap or vector graphics is interpreted by the script using getopts. This method is explained in the bash hackers wiki. This is used by putting it inside a loop and implementing the valid options with a case switch.

The loop is a while loop,

while getopts "vb" OPTION
do
commands-go-here
done

this loops over all options picking out v and b as valid options and storing the current one in the variable OPTION.

The case test is,

case $OPTION in
v) commands-for-v-option
;;
b) commands-for-b-option
;;
\?) exit 1;; #This should never happen, as the getopts only selects valid options, but if something has gone wrong, it exits.
esac

The case tests the value of the variable OPTION and executes the appropriate set of commands. The test is inside a loop, so putting both options, -vb, will result in both sets of commands being executed in the order specified by the user. For this script, this is a desired effect, they are not mutually exclusive.

Cropping the resulting pdf
I use pdfcrop to crop the pdf to the exact size of the equation. It is available (with documentation) from ctan. The comand is,

pdfcrop --margins 5 full.temp.pdf ${2%\.*}.pdf

I use margins of 5 pixels because this gives an appropriately sized border to account for the fact that some character glyphs extend slightly beyond their bounding box.

The output file uses a parameter expansion on the input file the script is called on. This is to give the final output file the same name, but with the correct extension for the output. This particular parameter expansion removes everything after the final dot. After the parameter expansion, we then concatenate with .pdf to give the file name. If the user has chosen to output to png, I just crop to a standard filename of full.temp.cropped.pdf.

Converting to png
I use the bash command convert from the suite of software imagemagick, this command is described in full here. It is called with,

convert -density 500 full.temp.cropped.pdf ${2%\.*}.png

I have set a density of 500 to make sure there is a high enough quality (dpi) for the equation to look good enough as a rasterised image. I again use a parameter expansion for this command, same as the pdfcrop command.

Cleaning up temporary files
Finally we delete all of the extra files created by this script using,

rm part1.temp part3.temp full.temp.tex full.temp.aux full.temp.log full.temp.pdf

Be warned that it doesn’t check modification times or anything, it will just remove any file in the current directory with these names. Also don’t run this script as root, you may harm your system. In the case of converting to png, the script will have already deleted the pdf interim.

The full script

#!/bin/bash

#  This program is free software: you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation, either version 3 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program.  If not, see .

# This program was written by Dominic Hosler 
# There is a description of how it works on my blog https://dominichosler.wordpress.com
# Please ask on the blog if you have any questions, thank you.

# Script to take an input file containing LaTeX code for an equation.
# It takes one optional argument, -v, to output the equations as vector graphics
# (pdf) or -i, to output as raster (png).
# The script will then remove the files it created (apart from the output file).

#Create temporary files for latex file
echo "Constructing LaTeX file"

echo "\documentclass{article}
\usepackage{amsmath,amssymb,bm,amsthm,bbold}
\usepackage{latexsym}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{mathrsfs}
\begin{document}
\pagestyle{empty}
\begin{equation*}" > part1.temp

echo "\end{equation*}
\end{document}
" > part3.temp

cat part1.temp $2 part3.temp > full.temp.tex

echo "Process the LaTeX file"
lualatex -interaction=batchmode full.temp.tex


#Test if the user has input the -v option (for vector) or -b (for bitmap)
while getopts "vb" OPTION
do
case $OPTION in
v) #In the case of vector graphics, just crop the pdf with a small margin and output to correct filename.
  echo "Output set to vector graphics, pdf."
  pdfcrop --margins 5 full.temp.pdf ${2%\.*}.pdf
;;
b) #In the case of bitmap graphics, crop the pdf with margin
  echo "Output set to bitmap graphics, png."
  pdfcrop --margins 5 full.temp.pdf full.temp.cropped.pdf
  #Then convert to a png with a high resolution for rasterisation.
  convert -density 500 full.temp.cropped.pdf ${2%\.*}.png
  rm full.temp.cropped.pdf
;;
\?) exit 1;;
esac
done

#Cleanup temp files
echo "Cleanup temporary files"

rm part1.temp part3.temp full.temp.tex full.temp.aux full.temp.log full.temp.pdf

To use the above script you need to copy and paste it into a text file and make the file executable. Then to run, you need to have the file on your PATH variable or in the same directory.

Example usage file
We take the example of my favourite equation, which involves the five most important numbers, 0, 1, e, i and pi, and the four most important operations =, +, * and ^.
The example file, example.texpart is this:

e^{i \pi}+1=0

Yes, the usage file really is that simple.

Advertisements