Getting Started

Version 0.1.2
CPU CUDA


PyPotteryTrace turns scanned archaeological pottery drawings into editable vector graphics (SVG). You mark the vessel on the drawing with a few clicks, the Segment Anything Model 2 (SAM 2) finds its outline, and the app traces it, mirrors the profile around the vessel’s axis and gives you clean, layered SVG files that you can refine in the built-in editor and export for publication. This page gets you from zero to a running app; the full workflow is in the Usage guide, and the geometry behind it is in the Technical Reference.

What you can do

  1. Create a project and load the drawings you want to vectorize.
  2. Choose a SAM 2 model, from the fastest to the most precise.
  3. Segment every element of a drawing (profile, handle, decoration, …) with clicks, a box or a hand-drawn polygon, and set the vessel’s rotation center.
  4. Edit the SVG: move points, add or delete them, and draw the missing part of a fractured profile with a continuation line.
  5. Post-process and export all the drawings of the project in one go, as SVG, PNG or JPG, with the line weights of your publication.

Install

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

Requires Python 3.12.

git clone https://github.com/lrncrd/PyPotteryTrace.git
cd PyPotteryTrace
pip install -r requirements.txt   # includes PyTorch and SAM 2
python app.py

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

Hardware

SAM 2 runs on an NVIDIA GPU (CUDA) when one is found, and on the CPU otherwise. The CPU works, but each click takes noticeably longer, and the larger models are best kept for a GPU. On Apple Silicon the app runs on the CPU.

First launch

The SAM 2 weights are downloaded from Meta’s servers and stored in the models/ folder of the app (with the launcher, in a cache shared by the PyPottery apps). Four sizes are available:

Model Size Speed Accuracy
Tiny ~156 MB Very fast Good
Small (default) ~184 MB Fast High
Base+ ~323 MB Medium Excellent
Large ~898 MB Slower Highest

Small is the model loaded by default. On the very first start, the page opens and asks whether to download it; confirm and follow the progress bar. Any other model is downloaded the same way when you select it in the Setup tab, and models you already have are used at once.

After that, everything runs on your computer, without an internet connection. Your projects are stored in the projects/ folder next to the app. 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
“SAM2 not installed” Install it from the source with pip install git+https://github.com/facebookresearch/segment-anything-2.git, then start the app again
Port 5004 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
“No SAM 2 model is loaded” when you open an image You cancelled the first download: select a model in the Setup tab and confirm the download
A model download fails Check your connection and free disk space, then select the model again: the download restarts
Segmentation is slow Choose a smaller model in Setup; check in the Info window whether the app sees your GPU (it says CPU Only otherwise)
Your GPU is not used Reinstall PyTorch with the CUDA build that matches your drivers (see pytorch.org)

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 five tabs.

Contributors

Lorenzo Cardarelli
Lorenzo Cardarelli