PreFigure is a Python package for authoring mathematical diagrams. Following the PreTeXt paradigm, an author creates an XML description of a diagram that PreFigure converts into an image file suitable for including in a text document. By default, PreFigure will create an SVG image that can be included in, say, an HTML document. However, PreFigure prioritizes the creation of accessible diagrams so that annotations can be added that enable a screen reader to easily navigate the diagram. Tactile diagrams can also be created from the same XML source.
More information, including detailed documentation, is available from the PreFigure homepage.
You may author and compile PreFigure diagrams in either of two environments:
PreFigure may be installed locally as a Python package in the usual way using pip
. However, there are a few details that require your attention.
PreFigure assumes the Python version specified in pyproject.toml
, which is currently 3.10. You may check your local Python version with one of the two commands below
python -V
python3 -V
You are encouraged to install liblouis
, which enables the creation of non-mathematical braille labels in tactile diagrams. PreFigure can still create non-tactile diagrams without this package installed though you will see a non-fatal warning message when you compile diagrams.
On a linux machine, use your package manager to install
python3-louis
while on a Mac, you will want
brew install liblouis
Alternatively, you can install liblouis
following these instructions.
Within a Python interpreter, you should then be able to import louis
without an error.
You are encouraged to install an additional library to support the Pycairo package. This may not be essential for your local machine, but there is no harm in performing this step and it will guarantee that PreFigure has access to a reqiured package.
You are now ready to install PreFigure with
pip install prefig
You will need a local installation of node
and npm
to produce mathematical labels. (The node
installation includes npm
.) This is a simple process, but you should search to find the instructions for your operating system. On a Ubuntu machine, it's as easy as
apt install nodejs
Once PreFigure is installed, help is available with
prefig --help
or, say,
prefig build --help
PreFigure source files can be compiled into SVG images using one of the following two commands, with the first command creating a regular SVG file while the second produces a tactile version of the diagram.
prefig build foo.xml
prefig build -f tactile foo.xml
By default, the output appears in output/foo.svg
and output/foo.xml
, where the XML output contains the annotations used by a screen reader.
To view the resulting diagram, use either
prefig view foo
prefig view -i foo
The first command will open the diagram in a browser using the diagcess
library, which enables a reader to explore the annotations interactively. The second command ignores the annotations and simply opens the SVG diagram in a browser.
Once a diagram has been compiled, you may create a PDF using
prefig pdf foo
Adding the -b
switch adds a build
command before the PDF is formed.
You may wish to perform the following steps to set up your authoring environment (these are automatically performed in a codespace):
To initialize your local installation, use
prefig init
which will use npm
to install some MathJax modules. It will also install the Braille29 font needed for tactile diagrams. If the MathJax modules are not installed when you attempt to build a diagram, PreFigure will attempt to install them when you build your first diagram.
You may install a set of examples for exploration in the current directory using
prefig examples
You may initialize a new PreFigure project in the current directory using
prefig new
This copies the diagcess
tools and a default publication file into the current directory and creates a source
directory in which to author diagrams.
Volker Sorge has provided crucial support for this project as well as access to the diagcess library for navigating an image with a screen reader.
The MathJax module mj-sre-page.js
included with this distribution was created by Davide Cervone and Volker Sorge.
Thanks also to the PreTeXt community, and especially Rob Beezer, for support and inspiration. This project was developed with support from the UTMOST Project
PreFigure is distributed with a GPL license.