Skip to main content
\(\require{cancel}\newcommand{\definiteintegral}[4]{\int_{#1}^{#2}\,#3\,d#4} \newcommand{\myequation}[2]{#1\amp =#2} \newcommand{\indefiniteintegral}[2]{\int#1\,d#2} \newcommand{\testingescapedpercent}{ \% } \newcommand{\lt}{<} \newcommand{\gt}{>} \newcommand{\amp}{&} \)


Mathbook XML supports several languages for describing diagrams and pictures with human-readable source code (i.e. plain text), rather than using a “paint” program. Any macros used in the rest of your document may be employed in the -standalone or Asymptote diagrams (with Sage graphics coming next?).

Subsection9.1 images

There are several graphics engine packages that a document can employ. Code from these packages renders diagrams automatically as part of normal processing of files. For HTML output the mbx script produces SVG versions of the pictures. The script can also produce standalone TEX source files, PDFs, PNGs, and EPSs. The packages should be loaded in docinfo/latex-image-preamble, which is also where global package settings should be made. As mentioned in Subsection 8.1, if any ampersands occur in your code you should use the \amp macro. These first examples are from the site.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.1TikZ Electronics Diagram

The next example began life in Sketch, which will output TikZ code (though the code has been edited by hand for readability).

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.2TikZ Cone Drawing

The pgfplots package was included in docinfo/latex-image-preamble. Here, it is used. Also, here we demonstrate using \amp where you would normally use an ampersand in . There are known issues with xelatex processing any gradient shading in tikz. To (successfully) create the gradient shading in the 3D image here, you may need to use pdflatex until developers resolve this issue.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.3Sample pgfplots plot

A plot might use a graphics language to draw the axes and grid, but the data might be from an experiment and live in an external file that you do not wish to place in your source. Place such a file in a subdirectory directly below the directory where your master source file resides. In the example below data is the directory and hodgkin-huxley-data.dat is the file with the data points. You must place the file in a subdirectory (it cannot reside next to your source file), but that directory may have subdirectories if you have many such files and want to organize them that way. Then the --include command-line argument to the mbx script will manage the external files properly as it creates individual image files.

It is still your responsibility to be sure this directory of external data files follows your output to whatever directory you use to convert to a PDF and is in the right location for the relative path given in the XML source. The discussion above only applies to generating individual image files, such as you would need for the HTML output.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.4External data in a pgfplots plot

Subsection9.2Placing Images without a Caption

To place an image without a caption, use the <sidebyside> layout element, containing just a single <image>. There is no way to add a caption, and the item will not be numbered. You cannot cross-reference it, nor will it appear in a knowl in HTML output. You will get a bit of vertical separation for the transitions to/from horizontal layout. Use margins=auto on the <sidebyside> to center the image—this should become the default behavior. A variety of other elements may be placed in a similar manner. See Section 22 to learn more about the <sidebyside> layout element.


The Asymptote graphics language may be placed in your source to draw graphs, diagrams or pictures. Rules for formatting code are identical to those for Sage code. For more on Asymptote see

This is a simple physics diagram about levers, taken from the Asymptote documentation. In the HTML version of this article, the images are SVG's and so should scale nicely when you zoom in on the page.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.5Asymptote Lever Demonstration

And a colorful contour plot with logarithmic scale. Again, from the Asymptote documentation.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.6Asymptote Contour Plot

Here is the lever diagram again, but now we have added an integral to one of the legends, using a macro of our own, which is idential to one we used in the early part of this article. The point is, we only needed to define the macro once for the entire document, and it is available as we make Asymptote diagrams. This device can be used to maintain flexibility and consistency in your choice of notation.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.7Aymptote Lever, plus Integral

And finally, an example of a 3-D graph (from the documentation again).

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.8Asymptote 3-D Surface

Subsection9.4Sage Plots

Any of the numerous capabilities of Sage may be used to produce any graphics object, be it the simple graph of a single-variable function or some realization of a more complicated object. All of the usual rules about formatting Sage code (esp. indentation) apply, along with one more caveat. The last line of your Sage code must return a Sage Graphics object (or 3D plot). The mbx script will isolate this last line, use it as the RHS of an assignment statement, and the Sage .save() method will be called to generate the image, which is either a Portable Document Format (PDF) file amenable to output, or a Scalable Vector Graphics (SVG) file amenable to HTML output. For visualizations of 3D plots, Sage will only produce Portable Network Graphics (PNG) files, which can be included in HTML pages or output.

A standard parabola on the interval [-2,4]
Figure9.9A Sage standard parabola, on \([-2,4]\)

Pay careful attention to the requirement that the last line of your code be a graphics object. In particular, while show() might appear to do the right thing, it evaluates to Python's None object and that is just what you will get. The code for Figure 9.10 illustrates creating two graphics objects and combining them into an expression on the last line that evaluates to a graphics object.

Figure9.10Two Sage plots on one set of axes

The following examples are from the Sage Tour. We package them into a sidebyside layout element, see Section 22.

Figure9.11A Sage multigraph of a sentence
Figure9.12Sage polynomial approximations of \(f(x)=1/(1+25x^2)\)

From the Sage documentation, with slight modifications, credited to Douglas Summers-Stay. A plot of the implicity defined surface

\begin{equation*} 2 = \cos(x + ty) + \cos(x - ty) + \cos(y + tz) + \cos(y - tz) + \cos(z - tx) + \cos(z + tx) \end{equation*}

in rectangular \(xyz\) coordinates, with \(t\) equal to the golden ratio.

Figure9.13A Sage implicitly defined 3D surface

Subsection9.5Images from External Sources

If you have raster images (photographs, etc) then they are specified with complete filenames, as above in Figure 5.2. If you have existing images that are vector graphics, then PDF format works best for output and SVG format works best for HTML. The utility pdf2svg works well for converting PDF to SVG. In this case, specify your source as a filenmae, but leave off the file extension, and the appropriate version will be used for the current output format.

The image below is provided from a PDF file for the output, and was converted to an SVG for use with th HTML output.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.14Complete graph on \(16\) vertices, from

Subsection9.6Copies of Images

So you do not have to duplicate the source of an image (and risk them later diverging), or for other reasons of efficiency, you can place an image as a copy of another one. The copy is an exact copy, such as having the identical width. Though, if placed within a figure element, the caption and so on, can be changed.

To use this feature, simply be certain to give the original an xml:id and then place an image tag where you want the copy. Then use a @copy attribute to point to the original. Two test examples, one from TikZ source, the other from a raster image.

<<SVG image is unavailable, or your browser cannot render it>>

Figure9.15TikZ Cone Drawing (Copy)
Figure9.16Copy of raster image, now numbered, captioned

Subsection9.7Technical Details

The table below is a summary of how graphics and images are specified, constructed and manipulated. Additional processing is indicated by reference to the Python script mbx. Images need to be placed relative to the file that includes them during compilation, and placed relative to the HTML files which reference/include them. Author-provided image files may be placed in any subdirectory, and the @source attribute should include the complete relative path with the subdirectory. Files generated by the mbx script will be specified in the output using the relative directory images, which can be changed using the directory.images stringparam. There is no reason author-provided files cannot also be placed in this same directory (presuming no duplicate names). [This table is presently more readable in HTML, the PDF version will improve.]

MBX Element Specification /Print HTML Notes
image/@source full relative path, w/ extension directly included directly included author-provided PNG, JPEG
image/@source full relative path, w/o extension presumes PDF presumes SVG author-provided
image/latex-image-code -compatible source directly included SVG via mbx e.g. tikz, pgfplots, xypic
image/sageplot Sage code PDF via mbx SVG via mbx PNG for 3-D
image/asymptote Asymptote code PDF via mbx SVG via mbx

In the early stages of a writing project, it may be best not to track provisional image files built with mbx under version control, and just regenerate them periodically (see the -r option for mbx). As a project matures, then it makes sense to put stable files under version control for collaborators and others. In every case, managing graphics files (and other aspects of production), is much more pleasurable with a script (shell, Makefile, etc.)

Subsection9.8Caption Testing

A caption could be as substantial as a paragraph, here we test out one such example.

Figure9.17A caption can be a whole paragraph with lots of technical details, and maybe a hyperlink to something external, such as There could be some inline mathematics, such as \(x^2 + y^2 = c^2\text{.}\) Would a knowl open here? Recursively? Let's see: 9.17. Display mathematics, side-by-sides, theorems, and lots of other things should be banned. Footnotes sound like a bad idea. Strange characters should be fine: §.