Getting Started

Version 0.3.4
CPU


PyPotteryLayout arranges your pottery drawings on publication plates. You give it the images (and, if you like, a spreadsheet with the data of each piece); it sorts them, scales them, adds captions, numbers and a scale bar, and produces the plates as PDF, JPG or SVG. It needs no AI model and no GPU. This page gets you from zero to a running app; the full workflow is in the Usage guide.

What you can do

  1. Import the drawings, and optionally a spreadsheet (Excel or CSV) with their data.
  2. Choose the layout: a regular Grid, or a Puzzle that packs the drawings to waste as little space as possible.
  3. Sort and group the drawings by name, by a field of your spreadsheet, or at random, with a new page or a divider for each group.
  4. Annotate: captions built from the spreadsheet, a scale bar, plate numbers (“Tav. 1”, “Pl. 1”, …) and a number for each drawing.
  5. Export as PDF, JPG or SVG, with text you can still edit in a vector program.

Install

The PyPottery Suite Launcher installs and updates PyPotteryLayout for you, with no Python setup. Download it from the latest release, open it, and start PyPotteryLayout from its interface.

Requires Python 3.12.

git clone https://github.com/lrncrd/PyPotteryLayout.git
cd PyPotteryLayout
pip install -r requirements.txt
python app.py

Then open http://localhost:5005 in your browser. Installer scripts that also create a virtual environment are included: double-click PyPotteryLayout_WIN.bat on Windows, or run chmod +x PyPotteryLayout_UNIX.sh && ./PyPotteryLayout_UNIX.sh on Linux/macOS.

The standalone Windows executable

Until version 0.3.0 the releases on GitHub included a PyPotteryLayout.exe. Later releases do not, so an .exe you find there is an old version: use the Launcher, or run from source.

Requirements

PyPotteryLayout runs on any computer that runs Python 3.12 (Windows, macOS, Linux) and needs a modern browser. About 2 GB of RAM is enough; large sets of high-resolution drawings need more, because every image is loaded in memory. There is nothing to download at the first launch.

Where the files go

Next to the app, in two folders:

  • uploads/: the images and the spreadsheet you loaded, one subfolder for each browser session;
  • outputs/: the previews and the plates you generated, organized in the same way.

The Clear All button of the app empties both for the current session. To stop the app, close its browser tab: it shuts down a few seconds later. You can also press Ctrl+C in the terminal, or close it from the launcher.

Troubleshooting

Problem What to try
Python not found Install Python 3.12 from python.org (on Windows tick “Add Python to PATH”); on Linux sudo apt install python3 python3-venv; on macOS brew install python3
Dependency installation fails Check your connection, upgrade pip (python -m pip install --upgrade pip), or install the packages of requirements.txt one at a time to find the culprit
Port 5005 is already in use Close the other program, or start the app on another port by setting the PORT environment variable before python app.py
A drawing does not show a caption from the spreadsheet The first column of the spreadsheet must hold the name of the image: see Usage
A TIFF drawing is missing Update to version 0.3.4 or later: older versions accepted .tif files but did not load them

Updating

With the launcher, updates are handled for you. From source, pull the latest code and run pip install -r requirements.txt --upgrade.

Next step

Head to the Usage guide for a walkthrough of the app.

Contributors

Lorenzo Cardarelli
Lorenzo Cardarelli
Enzo Cocca
Enzo Cocca
Francesco Di Filippo
Francesco Di Filippo