# protograf
__protograf__ is a utility written in Python for designing and creating
simple, regular, graphical outputs in PDF (or PNG/GIF/SVG) format via a script.
__protograf__ has been primarily created to handle the prototyping of cards,
counters, tiles and boards for board games, including hexagonal grids, but can
also be used for creating any simple design that has regular or repetitive
elements; typically a mix of graphics and text.
> You do not need to know the Python language to be able to use __protograf__
> but you do need Python installed on your machine!
## :notebook: Documentation
The online documentation for __protograf__ is available at
[Read the Docs](https://protograf.readthedocs.io/);
its highly recommended to read the sections in the order presented in the
[Guide](https://protograf.readthedocs.io/en/latest/guide.html).
If you're not familiar with any kind of programming or scripting, you should
at least read some of the introductory sections, and especially the
[installation](https://protograf.readthedocs.io/en/latest/setting_up.html)
before proceeding...
## :hammer_and_wrench: Requirements
__protograf__ requires Python (version of 3.13 or higher) to be installed
and running on your machine.
If this is **not** your current Python version, or Python is not installed on
your machine, may want to [install uv](https://docs.astral.sh/uv/getting-started/installation/)
which is a cross-platform tool able to [install Python](https://docs.astral.sh/uv/guides/install-python).
If using [uv](https://docs.astral.sh/uv/), it is recommended to also create and use a
[virtual environment](https://docs.astral.sh/uv/pip/environments/#creating-a-virtual-environment).
## :toolbox: Quick Start (for the impatient)
Assuming that Python 3.13 or higher is installed on your machine, you can then
install __protograf__ via:
```
pip install protograf
```
or, if using [uv](https://docs.astral.sh/uv/):
```
uv pip install protograf
```
To check that __protograf__ is working, you can use one (or more) of
the files from any of the various
[examples](https://github.com/gamesbook/protograf/blob/master/examples/)
sub-directories.
As a quick test, make a copy of `example1.py` script from the `examples/manual`
directory. To do so, open the
[example1.py](https://github.com/gamesbook/protograf/blob/master/examples/manual/example1.py)
link in your browser, click on the `Raw` button (near the top right), and then
save the web page as a file into a local directory on your machine.
Open a command-line window (also known as a *terminal* or a *console*), change to the
directory where you saved the above file and type:
```
python example1.py
```
and press the `Enter` key.
This script is very simple - it just contains these lines:
```
# `example1` script for protograf
# Written by: Derek Hohls
# Created on: 29 February 2016
from protograf import *
Create()
Save()
```
and is designed to produce a single, blank, A4-sized page in a PDF file.
It should create an output file called `example1.pdf`, which will appear in the
same directory as the script. You should be able to open and view this file using
any PDF-capable program or application. (If you run the script in a Python shell,
the output file will be called `test.pdf`.)
If this works, then download and try out other scripts from any of the `examples`
sub-directories (**note** some examples may require additional files such as
images, CSV files, or spreadsheets). You can download all the examples in a single
[ZIP file](https://github.com/gamesbook/protograf/blob/master/examples.zip).
If it does not work, you may want to look at more detail provided in the
[installation](https://protograf.readthedocs.io/en/latest/setting_up.html)
guide.
## :handshake: Contributions
Please see the [list of contributors](CONTRIBUTORS.txt).
## :game_die: Potential Features
These features are **not** guaranteed to be implemented; they just represent
current / potential areas of work or idea development.
* [ ] New Shapes:
* [ ] Diamond shape
* [ ] Parallelogram shape
* [ ] Cross shape
* [ ] Pod shape
* [ ] Common objects:
* [ ] CompassRose (replace Compass Shape)
* [ ] Cube (Rhombus composite; "3D")
* [ ] Domino (DotGrid inside Rectangle outline)
* [ ] Die (Rectangle with DotGrid)
* [ ] Meeple (Polyshape with Arcs)
* [ ] Picture Frame (Trapezoid composite)
* [ ] Hexagons: 18xx tile example (requires `Arcs` below!)
* [ ] Hexagon Grid: better hexhex creation with notations
* [ ] Polyline: define arcs along the path
* [ ] Arcs (pathways) inside a hexagon (**in progress**)
* [ ] Shortcut notation for styling of a Shape
* [ ] Stripes: interior "areas" for a Rectangle
* [ ] Cards:
* [ ] support card-back designs
* [ ] grid lines for hexagonal cards
* [ ] multiple custom bleed areas
* [x] access to Google Sheets
* [x] extract rectangular cards as PNG files
* [ ] page annotations
* [ ] Color:
* [ ] add support for CYMK
## :jigsaw: Potential Examples
These are possible examples to show board creation based on existing games:
* [ ] Extra abstract game boards: Ludo, Wari, Mu Torere
* [ ] Wargame board: Squad Leader with full terrain features (vector and bitmap)
* [ ] Traveller board: show a fully-styled Star System
* [x] WarpWar board: show a fully-styled example
* [ ] 18xx board: show a basic map with tracks, towns, cities and off-map areas
## :mega: Acknowledgements
> *The world is full of power and energy and a person can go far by just
> skimming off a tiny bit of it.*
> "[Snow Crash](https://en.wikipedia.org/wiki/Snow_Crash)", Neal Stephenson, 1992.
As always, with Python, you are building "on the shoulders of giants".
In this case, the [pyMuPDF](https://pymupdf.io/) library provides all of the
core infrastructure used to do the underlying graphics processing, PDF file
creation and images exports; __protograf__ is effectively a highly customised
wrapper to simplify common uses around its existing and extensive capabilities.
Earlier versions of __protograf__ used the *ReportLab PDF Toolkit*, which is
also a very powerful library for supporting this type of application. Internal
terminology, such as `shapes`, was developed before the adoption of *pyMuPDF*
and it is coincidental that these are similar!
### :books: Additional Libraries
* `cairoSVG` https://pypi.org/project/cairosvg/ - support for drawing SVG images
* `bgg-api` https://pypi.org/project/bgg-api/ - support for access to the
[BoardGameGeek](https://boardgamegeek.com) API
* `xlrd` https://pypi.org/project/xlrd/ - support for access to Excel `.xls` files
* `openpyxl` https://pypi.org/project/openpyxl/ - support for access to Excel files
* `imageio` https://pypi.org/project/imageio/- support for compiling PNGs into a GIF
* `jinja` https://jinja.palletsprojects.com - template logic with variables
* `pillow` https://github.com/python-pillow/Pillow - support for image processing
* `segno` https://github.com/heuer/segno/ - support for QRCode creation
## :scroll: License
__protograf__ is licensed under the GNU General Public License.
Raw data
{
"_id": null,
"home_page": null,
"name": "protograf",
"maintainer": "Rory Meyer",
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": "rory@oceanmaps.xyz",
"keywords": "python, graphics, boardgames, cards, counters, tiles",
"author": "Derek Hohls",
"author_email": "gamesbook@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2e/4f/a827bc1e0d87667256604df182d6f93a385055e1272133b9c5a3f211dc90/protograf-0.2.7.tar.gz",
"platform": null,
"description": "# protograf\n\n![protograf](logo.png \"protograf logo\")\n\n__protograf__ is a utility written in Python for designing and creating\nsimple, regular, graphical outputs in PDF (or PNG/GIF/SVG) format via a script.\n\n__protograf__ has been primarily created to handle the prototyping of cards,\ncounters, tiles and boards for board games, including hexagonal grids, but can\nalso be used for creating any simple design that has regular or repetitive\nelements; typically a mix of graphics and text.\n\n> You do not need to know the Python language to be able to use __protograf__\n> but you do need Python installed on your machine!\n\n## :notebook: Documentation\n\nThe online documentation for __protograf__ is available at\n[Read the Docs](https://protograf.readthedocs.io/);\nits highly recommended to read the sections in the order presented in the\n[Guide](https://protograf.readthedocs.io/en/latest/guide.html).\n\nIf you're not familiar with any kind of programming or scripting, you should\nat least read some of the introductory sections, and especially the\n[installation](https://protograf.readthedocs.io/en/latest/setting_up.html)\nbefore proceeding...\n\n## :hammer_and_wrench: Requirements\n\n__protograf__ requires Python (version of 3.13 or higher) to be installed\nand running on your machine.\n\nIf this is **not** your current Python version, or Python is not installed on\nyour machine, may want to [install uv](https://docs.astral.sh/uv/getting-started/installation/)\nwhich is a cross-platform tool able to [install Python](https://docs.astral.sh/uv/guides/install-python).\n\nIf using [uv](https://docs.astral.sh/uv/), it is recommended to also create and use a\n[virtual environment](https://docs.astral.sh/uv/pip/environments/#creating-a-virtual-environment).\n\n## :toolbox: Quick Start (for the impatient)\n\nAssuming that Python 3.13 or higher is installed on your machine, you can then\ninstall __protograf__ via:\n```\npip install protograf\n```\nor, if using [uv](https://docs.astral.sh/uv/):\n```\nuv pip install protograf\n```\nTo check that __protograf__ is working, you can use one (or more) of\nthe files from any of the various\n[examples](https://github.com/gamesbook/protograf/blob/master/examples/)\nsub-directories.\n\nAs a quick test, make a copy of `example1.py` script from the `examples/manual`\ndirectory. To do so, open the\n[example1.py](https://github.com/gamesbook/protograf/blob/master/examples/manual/example1.py)\nlink in your browser, click on the `Raw` button (near the top right), and then\nsave the web page as a file into a local directory on your machine.\n\nOpen a command-line window (also known as a *terminal* or a *console*), change to the\ndirectory where you saved the above file and type:\n```\npython example1.py\n```\nand press the `Enter` key.\n\nThis script is very simple - it just contains these lines:\n```\n# `example1` script for protograf\n# Written by: Derek Hohls\n# Created on: 29 February 2016\nfrom protograf import *\nCreate()\nSave()\n```\nand is designed to produce a single, blank, A4-sized page in a PDF file.\n\nIt should create an output file called `example1.pdf`, which will appear in the\nsame directory as the script. You should be able to open and view this file using\nany PDF-capable program or application. (If you run the script in a Python shell,\nthe output file will be called `test.pdf`.)\n\nIf this works, then download and try out other scripts from any of the `examples`\nsub-directories (**note** some examples may require additional files such as\nimages, CSV files, or spreadsheets). You can download all the examples in a single\n[ZIP file](https://github.com/gamesbook/protograf/blob/master/examples.zip).\n\nIf it does not work, you may want to look at more detail provided in the\n[installation](https://protograf.readthedocs.io/en/latest/setting_up.html)\nguide.\n\n## :handshake: Contributions\n\nPlease see the [list of contributors](CONTRIBUTORS.txt).\n\n## :game_die: Potential Features\n\nThese features are **not** guaranteed to be implemented; they just represent\ncurrent / potential areas of work or idea development.\n\n* [ ] New Shapes:\n * [ ] Diamond shape\n * [ ] Parallelogram shape\n * [ ] Cross shape\n * [ ] Pod shape\n* [ ] Common objects:\n * [ ] CompassRose (replace Compass Shape)\n * [ ] Cube (Rhombus composite; \"3D\")\n * [ ] Domino (DotGrid inside Rectangle outline)\n * [ ] Die (Rectangle with DotGrid)\n * [ ] Meeple (Polyshape with Arcs)\n * [ ] Picture Frame (Trapezoid composite)\n* [ ] Hexagons: 18xx tile example (requires `Arcs` below!)\n* [ ] Hexagon Grid: better hexhex creation with notations\n* [ ] Polyline: define arcs along the path\n* [ ] Arcs (pathways) inside a hexagon (**in progress**)\n* [ ] Shortcut notation for styling of a Shape\n* [ ] Stripes: interior \"areas\" for a Rectangle\n* [ ] Cards:\n * [ ] support card-back designs\n * [ ] grid lines for hexagonal cards\n * [ ] multiple custom bleed areas\n * [x] access to Google Sheets\n * [x] extract rectangular cards as PNG files\n * [ ] page annotations\n* [ ] Color:\n * [ ] add support for CYMK\n\n## :jigsaw: Potential Examples\n\nThese are possible examples to show board creation based on existing games:\n\n* [ ] Extra abstract game boards: Ludo, Wari, Mu Torere\n* [ ] Wargame board: Squad Leader with full terrain features (vector and bitmap)\n* [ ] Traveller board: show a fully-styled Star System\n* [x] WarpWar board: show a fully-styled example\n* [ ] 18xx board: show a basic map with tracks, towns, cities and off-map areas\n\n## :mega: Acknowledgements\n\n> *The world is full of power and energy and a person can go far by just\n> skimming off a tiny bit of it.*\n> \"[Snow Crash](https://en.wikipedia.org/wiki/Snow_Crash)\", Neal Stephenson, 1992.\n\nAs always, with Python, you are building \"on the shoulders of giants\".\nIn this case, the [pyMuPDF](https://pymupdf.io/) library provides all of the\ncore infrastructure used to do the underlying graphics processing, PDF file\ncreation and images exports; __protograf__ is effectively a highly customised\nwrapper to simplify common uses around its existing and extensive capabilities.\n\nEarlier versions of __protograf__ used the *ReportLab PDF Toolkit*, which is\nalso a very powerful library for supporting this type of application. Internal\nterminology, such as `shapes`, was developed before the adoption of *pyMuPDF*\nand it is coincidental that these are similar!\n\n### :books: Additional Libraries\n\n* `cairoSVG` https://pypi.org/project/cairosvg/ - support for drawing SVG images\n* `bgg-api` https://pypi.org/project/bgg-api/ - support for access to the\n [BoardGameGeek](https://boardgamegeek.com) API\n* `xlrd` https://pypi.org/project/xlrd/ - support for access to Excel `.xls` files\n* `openpyxl` https://pypi.org/project/openpyxl/ - support for access to Excel files\n* `imageio` https://pypi.org/project/imageio/- support for compiling PNGs into a GIF\n* `jinja` https://jinja.palletsprojects.com - template logic with variables\n* `pillow` https://github.com/python-pillow/Pillow - support for image processing\n* `segno` https://github.com/heuer/segno/ - support for QRCode creation\n\n## :scroll: License\n\n__protograf__ is licensed under the GNU General Public License.\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Python utility for designing and creating simple, regular, graphic outputs as PDF/PNG files",
"version": "0.2.7",
"project_urls": {
"Bug Tracker": "https://github.com/gamesbook/protograf/issues",
"Documentation": "https://protograf.readthedocs.io/en/latest/",
"Repository": "https://github.com/gamesbook/protograf"
},
"split_keywords": [
"python",
" graphics",
" boardgames",
" cards",
" counters",
" tiles"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "04e8ef16fbd1342e4ca286a8375cb6b2fc76b645304021a9ba354226ffb2b339",
"md5": "35d6ca41685e5de858cce30c300704de",
"sha256": "cce4995fca203bf3885d87184c21fe5972db19108b0bc3de7e8918a78fb9903f"
},
"downloads": -1,
"filename": "protograf-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35d6ca41685e5de858cce30c300704de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 154957,
"upload_time": "2025-07-14T08:22:57",
"upload_time_iso_8601": "2025-07-14T08:22:57.005303Z",
"url": "https://files.pythonhosted.org/packages/04/e8/ef16fbd1342e4ca286a8375cb6b2fc76b645304021a9ba354226ffb2b339/protograf-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2e4fa827bc1e0d87667256604df182d6f93a385055e1272133b9c5a3f211dc90",
"md5": "d592c25458c895e5425421e27e41e241",
"sha256": "a11ef0ec8e2f7db173fc7dc9f2b2d700ee5c6e24852ce7aea52d8f2257922674"
},
"downloads": -1,
"filename": "protograf-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "d592c25458c895e5425421e27e41e241",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 148563,
"upload_time": "2025-07-14T08:22:58",
"upload_time_iso_8601": "2025-07-14T08:22:58.713389Z",
"url": "https://files.pythonhosted.org/packages/2e/4f/a827bc1e0d87667256604df182d6f93a385055e1272133b9c5a3f211dc90/protograf-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 08:22:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gamesbook",
"github_project": "protograf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "protograf"
}
JSON
