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
\usepackage{sumatra}
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:
\usepackage[recordstore=/path/to/db, project=MyProject]{sumatra}
You can then use the \smtincludegraphics command in place of the usual \includegraphics:
\smtincludegraphics{20120907-153528:my_figure.png}
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 figure.
If my_figure.png is the only image file produced by that Sumatra run, then you can use just:
\smtincludegraphics{20120907-153528}
without the path part.
You can also use just a fragment of the image file name as a query term, replacing the ”:” separator with ”?”:
\smtincludegraphics{20120907-153528?my_fig}
All the usual \includegraphics options are supported, e.g.:
\smtincludegraphics[width=\textwidth]{20120907-153528:my_figure.png}
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:
\smtincludegraphics[width=\textwidth, digest=e2d1054c2893f19f50c43ddd5a344b59383df648]{20120907-153528:my_figure.png}
Note
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
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
:record_store: http://sumatra.example.com/
:project: MyOtherProject
:digest: e2d1054c2893f19f50c43ddd5a344b59383df648
:width: 800 px
:align: center
:class: some-css-class
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.