# PreFigure
PreFigure is a Python package for authoring mathematical diagrams. Following the [PreTeXt](https://pretextbook.org/) paradigm, an author writes 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.
PreFigure diagrams can now be authored inside a PreTeXt document. More information, including detailed documentation, is available from the [PreFigure homepage](https://prefigure.org).
## Using PreFigure
You may author and compile PreFigure diagrams in either of two environments:
1. You may use the [Prefigure Playground](https://davidaustinm.github.io/prefigure/) and download SVG files directly from the playground.
2. PreFigure is available in a [GitHub Codespace](https://github.com/davidaustinm/prefigure-codespace). This is a free, cloud-based platform that takes care of all the installation details and creates a fully configured working environment. Follow the instructions on that page to create your codespace and then get started authoring diagrams.
3. PreFigure may be installed locally as a Python package following the instructions in the **Local Installation** section below.
## Local Installation
PreFigure may be installed locally as a Python package in the usual way using `pip`. However, there are a few additional details that require your attention.
1. PreFigure assumes Python version 3.8.5 or higher. You may check your local Python version with one of the two commands below
```
python -V
```
```
python3 -V
```
2. You are encouraged to install `liblouis`, which enables the creation of non-mathematical braille labels in tactile diagrams. PreFigure can still create diagrams without this package installed though you will see a non-fatal warning message when you compile a tactile diagram and any requested labels will not appear in the diagram.
On a linux machine, use your package manager to install `python3-louis`. Ubuntu users can use
```
apt get python3-louis
```
while on a Mac, you will want
```
brew install liblouis
```
Alternatively, you can install `liblouis` following [these instructions](https://liblouis.io/downloads/).
Within a Python interpreter, you should then be able to `import louis` without an error.
3. You are encouraged to install an [additional library](https://pycairo.readthedocs.io/en/latest/getting_started.html) to support the `pycairo` package. This may not be essential for your local machine, but there is no harm in performing this step. The `pycairo` package is needed to produce labels having plain text (rather than mathematics). If you are not able to install `pycairo`, you will still be able to build PreFigure diagrams, but any labels with plain text will not appear.
4. You are now ready to install PreFigure with
```
pip install prefig[pycairo]
```
If this fails, it is due to the `pycairo` dependency so you can instead install PreFigure without `pycairo` using
```
pip install prefig
```
5. 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
```
6. For creating tactile graphics to be embossed, you are encouraged to install `rsvg-convert`, which PreFigure uses to convert SVGs into PDFs. On Ubuntu, you can say
```
apt install librsvg2-bin
```
while Mac users can use
```
brew install librsvg
```
7. Once installed, the command `prefig init` will install MathJax and the Braille29 font needed to tactile diagrams. If you do not perform this step, MathJax will be automatically installed when you first build a diagram with mathematical labels.
## Usage
Once PreFigure is installed, help is available with
```
prefig --help
```
or, say,
```
prefig build --help
```
Details of a requested operation may be obtained using the `-v` and `-vv` flags. For instance,
```
prefig -vv build foo.xml
```
will print debugging information to the terminal.
Here is a summary of PreFigure commands.
1. 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. If PreFigure is called from within a PreTeXt document, then the annotations will appear in `foo-annotations.xml`.
2. 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.
3. Once a diagram has been compiled, you may create a PDF using
```
prefig pdf foo
```
Adding the `-b` switch will build the diagram from PreFigure source before the PDF is formed.
4. Similarly,
```
prefig png foo
```
creates a PNG. Add the `-b` switch to `build` the diagram first.
5. To validate PreFigure source against the PreFigure XML schema, use
```
prefig validate foo.xml
```
You may wish to perform the following steps to set up your authoring environment (these are automatically performed in a codespace):
1. 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.
2. You may install a set of examples for exploration in the current directory using
```
prefig examples
```
3. 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.
## Acknowledgements
[Volker Sorge](https://www.birmingham.ac.uk/staff/profiles/computer-science/academic-staff/sorge-volker) 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](https://www.math.union.edu/~dpvc/) and Volker Sorge.
Thanks also to the PreTeXt community, and especially [Rob Beezer](http://buzzard.ups.edu/), for support and inspiration. This project was developed with support from the [UTMOST Project](https://utmost.aimath.org/)
## License
PreFigure is distributed with a GPL license.
Raw data
{
"_id": null,
"home_page": "https://prefigure.org",
"name": "prefig",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "David Austin",
"author_email": "david.austin.m@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6a/31/fbd9c1749bf7123c4d3c46e11937506e77e7743e7423edf1a7611d9fa1ce/prefig-0.3.8.tar.gz",
"platform": null,
"description": "# PreFigure\n\nPreFigure is a Python package for authoring mathematical diagrams. Following the [PreTeXt](https://pretextbook.org/) paradigm, an author writes 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.\n\nPreFigure diagrams can now be authored inside a PreTeXt document. More information, including detailed documentation, is available from the [PreFigure homepage](https://prefigure.org).\n\n## Using PreFigure\n\nYou may author and compile PreFigure diagrams in either of two environments:\n\n1. You may use the [Prefigure Playground](https://davidaustinm.github.io/prefigure/) and download SVG files directly from the playground.\n2. PreFigure is available in a [GitHub Codespace](https://github.com/davidaustinm/prefigure-codespace). This is a free, cloud-based platform that takes care of all the installation details and creates a fully configured working environment. Follow the instructions on that page to create your codespace and then get started authoring diagrams.\n3. PreFigure may be installed locally as a Python package following the instructions in the **Local Installation** section below.\n\n## Local Installation\n\nPreFigure may be installed locally as a Python package in the usual way using `pip`. However, there are a few additional details that require your attention.\n\n1. PreFigure assumes Python version 3.8.5 or higher. You may check your local Python version with one of the two commands below\n\n ```\n python -V\n ```\n\n ```\n python3 -V\n ```\n\n2. You are encouraged to install `liblouis`, which enables the creation of non-mathematical braille labels in tactile diagrams. PreFigure can still create diagrams without this package installed though you will see a non-fatal warning message when you compile a tactile diagram and any requested labels will not appear in the diagram.\n\n On a linux machine, use your package manager to install `python3-louis`. Ubuntu users can use\n\n ```\n apt get python3-louis\n ```\n\n while on a Mac, you will want\n\n ```\n brew install liblouis\n ```\n\n Alternatively, you can install `liblouis` following [these instructions](https://liblouis.io/downloads/). \n\n Within a Python interpreter, you should then be able to `import louis` without an error.\n\n3. You are encouraged to install an [additional library](https://pycairo.readthedocs.io/en/latest/getting_started.html) to support the `pycairo` package. This may not be essential for your local machine, but there is no harm in performing this step. The `pycairo` package is needed to produce labels having plain text (rather than mathematics). If you are not able to install `pycairo`, you will still be able to build PreFigure diagrams, but any labels with plain text will not appear.\n\n4. You are now ready to install PreFigure with\n\n ```\n pip install prefig[pycairo]\n ```\n\n If this fails, it is due to the `pycairo` dependency so you can instead install PreFigure without `pycairo` using\n\n ```\n pip install prefig\n ```\n\n5. 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 \n\n ```\n apt install nodejs\n ```\n\n6. For creating tactile graphics to be embossed, you are encouraged to install `rsvg-convert`, which PreFigure uses to convert SVGs into PDFs. On Ubuntu, you can say\n\n ```\n apt install librsvg2-bin\n ```\n\n while Mac users can use\n\n ```\n brew install librsvg\n ```\n\n7. Once installed, the command `prefig init` will install MathJax and the Braille29 font needed to tactile diagrams. If you do not perform this step, MathJax will be automatically installed when you first build a diagram with mathematical labels.\n\n## Usage\n\nOnce PreFigure is installed, help is available with\n\n```\nprefig --help\n```\n\nor, say,\n\n```\nprefig build --help\n```\n\nDetails of a requested operation may be obtained using the `-v` and `-vv` flags. For instance,\n```\nprefig -vv build foo.xml\n```\nwill print debugging information to the terminal.\n\nHere is a summary of PreFigure commands.\n\n1. 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.\n\n ```\n prefig build foo.xml\n ```\n\n ```\n prefig build -f tactile foo.xml\n ```\n\n 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. If PreFigure is called from within a PreTeXt document, then the annotations will appear in `foo-annotations.xml`.\n\n2. To view the resulting diagram, use either\n\n ```\n prefig view foo\n ```\n\n ```\n prefig view -i foo\n ```\n\n 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.\n\n3. Once a diagram has been compiled, you may create a PDF using\n\n ```\n prefig pdf foo\n ```\n\n Adding the `-b` switch will build the diagram from PreFigure source before the PDF is formed.\n\n4. Similarly,\n\n ```\n prefig png foo\n ```\n\n creates a PNG. Add the `-b` switch to `build` the diagram first.\n\n5. To validate PreFigure source against the PreFigure XML schema, use\n\n ```\n prefig validate foo.xml\n ```\n\n\n\nYou may wish to perform the following steps to set up your authoring environment (these are automatically performed in a codespace):\n\n1. To initialize your local installation, use\n\n ```\n prefig init\n ```\n\n 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.\n\n2. You may install a set of examples for exploration in the current directory using\n\n ```\n prefig examples\n ```\n\n3. You may initialize a new PreFigure project in the current directory using\n\n\n ```\n prefig new\n ```\n \n This copies the `diagcess` tools and a default publication file into the current directory and creates a `source` directory in which to author diagrams.\n\n## Acknowledgements\n\n[Volker Sorge](https://www.birmingham.ac.uk/staff/profiles/computer-science/academic-staff/sorge-volker) has provided crucial support for this project as well as access to the diagcess library for navigating an image with a screen reader.\n\nThe MathJax module `mj-sre-page.js` included with this distribution was created by [Davide Cervone](https://www.math.union.edu/~dpvc/) and Volker Sorge.\n\nThanks also to the PreTeXt community, and especially [Rob Beezer](http://buzzard.ups.edu/), for support and inspiration. This project was developed with support from the [UTMOST Project](https://utmost.aimath.org/)\n\n## License\n\nPreFigure is distributed with a GPL license.\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "An authoring system for mathematical diagrams",
"version": "0.3.8",
"project_urls": {
"Homepage": "https://prefigure.org",
"Repository": "https://github.com/davidaustinm/prefigure"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9b2cec41bb8c218f1a4ab9dda3a3aeacd1989d61a44f6878a9dbe804b5dce0bb",
"md5": "ffe0f2c8705af80672f889255a2fc04f",
"sha256": "a45e379ba0bf41003fec9ef67a6baf28b7244c41dd8a41f4c060639001e186be"
},
"downloads": -1,
"filename": "prefig-0.3.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ffe0f2c8705af80672f889255a2fc04f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 149551,
"upload_time": "2025-07-25T19:30:39",
"upload_time_iso_8601": "2025-07-25T19:30:39.623622Z",
"url": "https://files.pythonhosted.org/packages/9b/2c/ec41bb8c218f1a4ab9dda3a3aeacd1989d61a44f6878a9dbe804b5dce0bb/prefig-0.3.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a31fbd9c1749bf7123c4d3c46e11937506e77e7743e7423edf1a7611d9fa1ce",
"md5": "91fa026b1221f055e9572dca95754d9a",
"sha256": "f84646b0e71259d8df253ca6fdcbe91e3f80cef4d8a7c923edea2c9536752c26"
},
"downloads": -1,
"filename": "prefig-0.3.8.tar.gz",
"has_sig": false,
"md5_digest": "91fa026b1221f055e9572dca95754d9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 126342,
"upload_time": "2025-07-25T19:30:41",
"upload_time_iso_8601": "2025-07-25T19:30:41.068088Z",
"url": "https://files.pythonhosted.org/packages/6a/31/fbd9c1749bf7123c4d3c46e11937506e77e7743e7423edf1a7611d9fa1ce/prefig-0.3.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 19:30:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davidaustinm",
"github_project": "prefigure",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "lxml",
"specs": [
[
"==",
"5.2.2"
]
]
},
{
"name": "networkx",
"specs": [
[
"==",
"3.1"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.24.4"
]
]
},
{
"name": "pycairo",
"specs": [
[
"==",
"1.26.0"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.10.1"
]
]
}
],
"lcname": "prefig"
}
JSON
