Sumatra provides tools to include figures and other results generated by
Sumatra-tracked computations in documents, with links to full provenance
information: i.e. the full details of the code, input data and computational
environment used to generate the figure/result.
To include figures from a Sumatra project in a LaTeX document, copy the
file sumatra.sty from the sumatra/publishing/latex directory in the
Sumatra source distribution into your working directory, then add
in the preamble of your LaTeX document. If your LaTeX working directory is not
the same as your Sumatra project directory, you can specify the location of
the record store and the project name as package options:
You can then use the \smtincludegraphics command in place of the usual
Here the argument is the label of a Sumatra record. This command will look up
the record in your Sumatra project, find the location of the image file (whether
a local file path or a URL) and include the figure in the document. If you are
using the HttpRecordStore, the figure will also be a hyperlink to the
corresponding Sumatra record, so you can easily check the full provenance of the
If my_figure.png is the only image file produced by that Sumatra run,
then you can use just:
without the path part.
You can also use just a fragment of the image file name as a query term,
replacing the ”:” separator with ”?”:
All the usual \includegraphics options are supported, e.g.:
You can also include as an option the SHA1 hash of the image file contents, as
captured by Sumatra, to ensure that the image you include is the correct one,
and that it hasn’t been accidentally overwritten or replaced by another:
you will have to run latex/pdflatex with the -shell-escape option.
To include figures from a Sumatra project, or links to Sumatra records of
simulations or analyses, in a Sphinx document, you should first add
'sumatra.publishing.sphinxext' to the extensions list in your
conf.py and then set the following options:
sumatra_record_store = "/path/to/record/store"
sumatra_project = "MyProject"
sumatra_link_icon = "icon_info.png"
The sumatra.publishing.sphinxext extension provides a reStructuredText directive
smtimage and a reStructuredText role smtlink
The smtimage directive
smtimage includes an image file retrieved from a Sumatra project in your document.
If you are using the HttpRecordStore, the image will also be a hyperlink to the
corresponding Sumatra record.
.. smtimage:: 20120907-153528:my_figure.png
All the usual options to the normal image directive can be used (‘width’, ‘height, ‘align’, etc.),
as well as the Sumatra-specific options “digest” (which is used to check the
identity of the included image, as detailed in the section on LaTeX above) “record_store” and “project”,
which can be used to over-ride the global options specified in conf.py, and
so mix results from multiple projects in a single document. Here is a rather complete example.
.. smtimage:: 20120907-153528?my_fig
:width: 800 px
The smtlink role
If using a HttpRecordStore, the smtlink role inserts an
icon in the document, which is a hyperlink to a given record in the store.
To use this, you must set the sumatra_link_icon option, as discussed above.