13. Using LaTeX Expressions in GMT
GMT supports the use of LaTeX equations embedded in text strings that are used with -B in titles, subtitles and axis labels, as well as for single lines of text placed via text. These expressions must be enclosed by the marker @[ (e.g., “Plotting @[\Delta \sigma_{xx}^2@[“), or alternatively enclose the expressions with <math> and </math> (e.g., “Plotting <math>\Delta \sigma_{xx}^2</math>”). If these markers are found, the entire line will be converted to an Encapsulated PostScript file (EPS) via system commands to latex and dvips, which must be available on your system. The EPS file is then placed in the location instead of the regular text.
Here is the source script for the figure above:
gmt begin GMT_latex
gmt basemap -R-200/200/0/2 -JX15c -Bxaf+l"@[\nabla^4 \psi - \Delta \sigma_{xx}^2@[ (MPa)" -BS
gmt end show
13.1. GMT fonts and LaTeX
LaTeX is a large and complicated type-setting system with many optional packages, and we simply must assume that your LaTeX installation has all the needed features; see our wiki for typical installs via package managers. Your installation must have support for the packages fontenc and inputenc, as well as the required fonts helvet, mathptmx, courier, symbol, avantgar, bookman, newcent, mathpazo, zapfchan and zapfding. If the conversion from LaTeX to EPS fails, please follow instructions to run the conversion script manually in the terminal so you may determine what packages or fonts you may be missing. The list of fonts above were selected to match the standard fonts used by GMT. Hence, if you change the default font for a title (i.e., FONT_TITLE), then we also set that font as the default font in the LaTeX script we generate under the hood. This is done so the regular text in a title will follow the current GMT default settings.
13.2. Technical Details
To help anyone debug their LaTeX installation, consider the case where you make a basemap that contains the title request -B+t”Use @[\Delta g = 2\pi\rho Gh@[”. This request ends up creating a temporary directory containing a small LaTeX file called gmt_eq.tex:
\documentclass{article}
\usepackage[T1]{fontenc} \usepackage[utf8]{inputenc}
\usepackage{helvet}
\begin{document}
\thispagestyle{empty}
\fontfamily{phv}\selectfont
Use $\Delta g = 2\pi\rho Gh$
\end{document}
Because FONT_TITLE was set to Helvetica, the LaTeX file changes the default font to Helvetica as well (package helvet, code phv). This file is then converted to a DVI file by the command:
latex -interaction=nonstopmode gmt_eq.tex > /dev/null
followed by the conversion to EPS via:
dvips -q -E gmt_eq.dvi -o equation.eps
These two commands are executed via the script gmt_eq.sh (or gmt_eq.bat under Windows).
If the system command returns a successful status then we read the EPS file equation.eps
into memory and place it instead of the title. However, should the script fail, for
whatever reason, we print an error message and direct you to do forensic work in the
temporary directory. You should run the latex
command (but remove the redirection
to > /dev/null) so you can see the error messages. Usually, the messages will indicate what
the problem is, say, which font is missing, or similar. If you cannot solve the riddle
then please open an issue on GitHub
and share the LaTeX script and the error messages.