Open Source & Community
PyPottery is an open-source project, and it works best as a collaborative one. It is written for archaeologists, and the people who can make it better are as often the archaeologists who use it every day as the programmers who can read its code.
Both are welcome, and you do not need to write code to help. Pottery documentation is a craft, and these tools are only as good as the workflows they have been tested on.
What open source means here
- Free to use
-
No fees, no accounts, no subscription
Install the whole suite and use it on your own material, in the field, in the lab or at home.
- Inspectable
-
Nothing hidden
The full source code is public, so you can check exactly what happens to your drawings. By default, everything runs on your own machine.
- Yours to keep
-
Your work is never locked in
Projects and exports are ordinary files in open formats (images, SVG, CSV, Excel, JSON). No proprietary format stands between you and your own data.
Who can take part
If you work with pottery
Archaeologists, ceramicists and illustrators know what a good result looks like. That is exactly what the models and the workflows are missing.
- Try the tools on your own material and tell us where they fail: a drawing style the inking model misreads, a monograph layout Lens cannot split, a label format Scan cannot read.
- Point out the steps of your workflow that are still done by hand.
- Share sample drawings you have the right to publish, to test and to train the models.
- Help write, correct and translate the guides.
If you write code
Each tool is a small Flask application with a plain HTML and JavaScript front end, and lives in its own repository, so you can work on just the one you use.
- Fix bugs, add tests, improve speed and memory use.
- Verify the suite on macOS and Linux and report what breaks.
- Work on the models: better training data, lighter weights, new hardware backends.
- Take on a feature from the issue tracker.
Teaching a course or running a field school? Use PyPottery with your students and tell us what worked and what confused them. If you got stuck on an unclear message or a missing explanation, others will too, and that is worth an issue.
Where help is needed most
| Help wanted | What it involves | Who is best placed |
|---|---|---|
| Testing on macOS and Linux | Install the suite, run each tool from start to finish, report what breaks. The launcher is developed mainly on Windows. | Anyone with a Mac or a Linux machine |
| Real-world material | Run the tools on unusual drawing conventions, periods and publication layouts, and share the results, good or bad. | Archaeologists, ceramicists, illustrators |
| Documentation and translations | Clearer guides, worked examples, versions in other languages. | Users of any tool, in any language |
| Datasets and models | Annotated examples, with the right to share them, so the models improve for everyone. | Projects with digitised, publishable drawings |
How to contribute
- Look around. Read the documentation and try the tools. Check the issue tracker to see whether your idea or problem is already there.
- Open an issue. Describe what you were doing, what you expected and what happened. A screenshot or a small example file helps a lot. For a bigger change, start a discussion first, so the effort goes in the right direction.
- Send your change. To fix or build something yourself, fork the repository of the tool concerned and open a pull request that explains what it does and why.
- Talk to us. Not sure where to begin, or interested in a research collaboration? Write to me.
The repositories
| Repository | What it is |
|---|---|
| PyPottery | The suite launcher, the installers and this documentation |
| PyPotteryLens | Extract pottery from PDF monographs |
| PyPotteryScan | Digitize field drawings and read their labels |
| PyPotteryInk | Turn pencil sketches into ink drawings |
| PyPotteryTrace | Vectorize vessel profiles with SAM 2 |
| PyPotteryLayout | Compose publication-ready plates |
Credit and citation
If PyPottery is useful for your research, please cite it: the publications list the right reference for each module. Contributors who would like to be mentioned are credited in the release notes.
Built by archaeologists, for archaeologists
PyPottery started from a real documentation backlog and grows with the people who use it. Your feedback, your samples and your code all move it forward.