PyPottery: an AI-powered end-to-end suite for pottery processing and publication
Organizations: Seminars für Ur- und Frühgeschichte Georg-August-Universität Göttingen Göttingen, 37073 · ISMed-CNR – Istituto di Studi sul Mediterraneo Naples, 80134 · Sapienza Università di Roma, Department of Antiquities, and Parco Archeologico del Colosseo, Via in Miranda 5, 00186 Rome, Italy
Abstract
The study of ceramic materials constitutes a cornerstone of archaeological research, yet the post-production workflow for pottery documentation remains labor-intensive and creates significant publication bottlenecks. This paper presents PyPottery, an open-source, AI-powered suite designed to semi-automate the complete ceramic documentation pipeline. The suite comprises four integrated modules: PyPotteryScan for automated image extraction and handwriting recognition; PyPotteryInk for automatic inking of pencil drawings; PyPotteryTrace for semantically-aware vectorization; and PyPotteryLayout for automated layout generation. Evaluated on 50 hand-drawn sheets containing 240 pottery drawings from the Terramara di Montale (Italy), the framework achieved substantial time savings confirmed by usability study participants, who reported a median perceived speedup of 40 over traditional workflows (range: 17.5--120). These results highlight the potential of AI-assisted tools in archaeological documentation, while the paper addresses the strategic redistribution of cognitive labor toward augmentation rather than automation.
Figures & tables
| Module | Function | Corresponding Traditional Phase | Key AI Technologies |
|---|---|---|---|
| PyPotteryScan | Automated scanning, image cropping, and metadata extraction from sheets. | 1. Scanning and Cataloging | LLMs (olmOCR, Qwen3) for handwriting recognition and structured parsing. |
| PyPotteryInk | Automatic inking of raster drawings. | 2. Inking/Vectorization | Deep learning models for image-to-image translation. |
| PyPotteryTrace | Semantically-aware vectorization of inked drawings. | 2. Inking/Vectorization | Segmentation models (SAM 2) and custom vectorization algorithms. |
| PyPotteryLayout | Automated generation of publication layouts. | 3. Layout and Publication | Spatial optimization algorithms. |
| Num examples | Accuracy | Precision | Recall | F1 | EMA | PMS |
|---|---|---|---|---|---|---|
| 1 | 77.82 3.72 | 38.50 3.46 | 37.74 3.42 | 37.86 3.47 | 13.56 7.80 | 66.59 5.96 |
| 3 | 88.99 3.26 | 51.01 6.27 | 50.99 6.25 | 50.94 6.25 | 52.63 10.79 | 83.48 5.19 |
| 5 | 91.45 1.64 | 53.58 4.65 | 55.59 5.87 | 54.15 4.75 | 60.36 8.52 | 87.55 2.89 |
| 7 | 91.53 2.38 | 56.85 7.65 | 57.14 6.70 | 56.42 6.92 | 61.70 8.89 | 87.58 3.82 |
| 10 | 93.13 0.73 | 60.22 6.68 | 59.27 5.45 | 59.07 5.22 | 67.60 2.65 | 90.30 1.08 |
| Library | Task | Time | Hardware impact | Task type |
| PyPotteryScan | Manual filing | 13’ | Irrelevant | Manual |
| Image extraction | 1’ 13” | Low | Automated | |
| OCR | 5’ 42” | High | Automated | |
| Cleaning | 10’ 14” | Irrelevant | Manual | |
| OCR correction | 10’ 40” | Irrelevant | Manual | |
| Parsing | 4’ 3” | High | Automated |
| File | Hausdorff |
|---|---|
| 0352.svg | 0.0266 |
| 3205.svg | 0.0197 |
| 3213.svg | 0.0211 |
| ceramic_001.svg | 0.0123 |
| ceramic_046.svg | 0.0086 |
| ceramic_066.svg | 0.0254 |
Appendix figures & tables25 assets
Supplementary material from the paper’s appendix.
Appendix
| ID | Age | Role | Institution | Arch. exp. (yrs) | Ceramic exp. (yrs) | Drawings processed | Software used |
|---|---|---|---|---|---|---|---|
| 0 | 26–35 | MA/MSc | Sapienza University of Rome | 5 | 4 | 200–500 | Illustrator, Photoshop |
| 1 | 26–35 | MA/MSc | University of Bologna | 6 | 5 | 500–1000 | Illustrator |
| 2 | 46–55 | Post-doc | University of Bologna | 25 | 25 | 1000 | Illustrator |
| 3 | 36–45 | Post-doc | University of Naples “Federico II” | 18 | 16 | 1000 | Illustrator, AutoCAD |
| 4 | 26–35 | Post-doc | University of Naples “Federico II” | 13 | 9 | 1000 | Illustrator, CorelDRAW, AutoCAD |
| Part. | Q1 | Q2 | Q3 | Q4 | Q5 | Q6 | Q7 | Q8 | Q9 | Q10 SUS |
|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 5 | 1 | 5 | 2 | 5 | 1 | 5 | 2 | 4 | 1 92.5 |
| 1 | 5 | 1 | 5 | 2 | 5 | 1 | 5 | 2 | 5 | 2 92.5 |
| 2 | 5 | 3 | 3 | 4 | 4 | 1 | 5 | 2 | 2 | 3 65.0 |
| 3 | 5 | 1 | 5 | 4 | 5 | 1 | 5 | 4 | 5 | 2 82.5 |
| 4 | 5 | 1 | 5 | 3 | 5 | 1 | 4 | 2 | 4 | 2 85.0 |
| Metric | Value | Interpretation |
|---|---|---|
| Mean SUS Score | 83.5 | Grade: A (Excellent) |
| Standard Deviation | 11.26 | |
| Median | 85.0 | |
| Range | 65.0 – 92.5 |
| ID | Role | Arch. exp. (yrs) | Ceramic exp. (yrs) | Drawings processed | SUS | Est. speedup |
|---|---|---|---|---|---|---|
| 0 | MA/MSc | 5 | 4 | 200–500 | 92.5 | 120 |
| 1 | MA/MSc | 6 | 5 | 500–1000 | 92.5 | 40 |
| 2 | Post-doc | 25 | 25 | 1000 | 65.0 | 100 |
| 3 | Post-doc | 18 | 16 | 1000 | 82.5 | 32 |
| 4 | Post-doc | 13 | 9 | 1000 | 85.0 | 17.5 |
| Career stage | n | Ceramic exp. | SUS (mean) | SUS (range) | Speedup (mean) | Speedup (range) |
|---|---|---|---|---|---|---|
| MA/MSc | 2 | 4–5 | 92.5 | 92.5–92.5 | 80.0 | 40 –120 |
| Post-doc | 3 | 9–25 | 77.5 | 65.0–85.0 | 49.8 | 17.5 –100 |
| All | 5 | 4–25 | 83.5 | 65.0–92.5 | 61.9 | 17.5 –120 |
| Module | “Faster than traditional” | Time Savings Estimate |
|---|---|---|
| PyPotteryScan (T1–T3) | 4.8/5 (all Agree/Strongly Agree) | 4/5 = 75% faster; 1/5 = 50–75% faster |
| PyPotteryInk (T4) | 4.8/5 | 4/5 = 75% faster; 1/5 = 25–50% faster |
| PyPotteryTrace (T5) | 4.6/5 | 3/5 = 75% faster; 1/5 = 50–75% faster; 1/5 = 25–50% faster |
| PyPotteryLayout (T6) | 5.0/5 (all Strongly Agree) | 5/5 = 75% faster |
| Participant | Minutes per Drawing |
|---|---|
| 0 | 40 |
| 1 | 10–15 |
| 2 | 30–180 |
| 3 | 15 |
| 4 | 13 |
| Participant | PyPottery (hours) | Traditional (hours) | Speedup Factor |
| 0 | 1 | 120 | 120 |
| 1 | 2 | 80 | 40 |
| 2 | 1.5 | 150 | 100 |
| 3 | 1.5 | 48 | 32 |
| 4 | 4 | 70 | 17.5 |
| Phase | Votes |
|---|---|
| Inking/Vectorization | 4 |
| Scanning/OCR | 1 |
| Layout | 1 |
| Phase | Votes |
|---|---|
| Inking/Vectorization | 4 |
| Scanning/OCR | 1 |
| Task | Complete | Partial | Failed | Success Rate |
|---|---|---|---|---|
| T1 (Sheet Processing) | 5 | 0 | 0 | 100% |
| T2 (OCR Extraction) | 4 | 1 | 0 | 80% |
| T3 (Parsing) | 5 | 0 | 0 | 100% |
| T4 (Inking) | 5 | 0 | 0 | 100% |
| T5 (Vectorization) | 1 | 4 | 0 | 20% |
| T6 (Layout) | 5 | 0 | 0 | 100% |
| Task | Total Help Requests |
|---|---|
| T1 | 1 |
| T2 | 0 |
| T3 | 0 |
| T4 | 0 |
| T5 | 6 |
| T6 | 0 |
| Score | Reason |
|---|---|
| 10 | “Speed” |
| 10 | “Time saving to do other stuff” |
| 9 | “Great job” |
| 9 | “A lot of time saved” |
| 9 | “Unimaginable potential time savings” |
| Context | Researcher / Institution | Chronology | Material | Doc. language | Modules used | Status |
|---|---|---|---|---|---|---|
| Pyrgi, “public-ceremonial” quarter (Santa Severa, Santa Marinella, Rome) | S. Servoli, Dipartimento di Scienze dell’Antichità, Sapienza University of Rome | Late 7th – late 5th c. BCE | “rosso-bruno” impasto ware | Italian | Scan, Ink, Trace, Layout | Ongoing preparation of doctoral monograph |
| Biriai (Oliena, Nuoro, Sardegna), Monte Claro culture settlement | F.I. Debandi, PhD, Post-doc fellow, Dept. of History and Cultures (DISCI), University of Bologna | Copper Age (2700–2500 BCE) | Impasto ceramic | Italian | Scan, Ink | Material study |
| Hüde I, distr. Diepholz | A. Philippi, LWL-Archäologie für Westfalen / Außenstelle Bielefeld | Late Mesolithic – Early Neolithic (Bischheim, Swifterbant, Michelsberg, Trichterbecher; c. 1,500-year span) | Impasto ceramic | German | Ink, Layout | Material study |
| Torre dell’Alto, Nardò (LE) | L. Schiavone, Università di Bologna | Mid–Late Bronze Age | Impasto ware | Italian | Ink, Layout | Ongoing paper publication |
| Arslantepe, “Edificio XLVI” | V. Parisi, PhD Program in Heritage Science, Dept. of Sciences of Antiquity, Sapienza University of Rome | Iron Age II/Middle (1000–850 BCE) | — | English/Italian | Ink, Trace, Layout | Material study |
| Shamiram-Aruch (Aragatsotn, Republic of Armenia) | E. Fausti, Dipartimento di Scienze dell’Antichità, Sapienza University of Rome | Middle Iron Age – Early Medieval (6th c. BCE–7th c. CE) | Impasto, depurated ware | Italian | Trace, Ink, Layout | Ongoing preparation of several scientific papers |