PyPottery: an AI-powered end-to-end suite for pottery processing and publication

Lorenzo Cardarelli

cs.AIOct 1, 2026

PyPottery: an AI-powered end-to-end suite for pottery processing and publication

Authors: Lorenzo Cardarelli

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 $\times$ over traditional workflows (range: 17.5 $\times$ --120 $\times$ ). 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

Figure 1: The diagram shows the complete PyPottery workflow. Each block identifies a specific module and its function within the overall process. Orange boxes indicate outputs and green boxes indicate manual processing checks.

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.

Table 1: The main PyPottery modules, functions and IT technologies.

Figure 2: Examples of the PyPotteryScan GUI v.2.0.0. a) Annotated hand-drawn sheet. b) Manual OCR correction interface.

Figure 3: Examples of the PyPotteryTrace GUI v.2.0.0. a) Semantic segmentation. b) Built-in editing.

Figure 4: Vectorization pipeline applied to a ceramic profile. Each step is described in the text.

Figure 5: Few-shot learning efficiency across multiple metrics. Left: Precision, Recall, F1 for non-empty field values. Center: EMA (stringent all-fields-correct metric) vs. PMS (partial credit metric). Right: Accuracy (including empty-empty matches) vs. F1 (non-empty only), with 90% threshold marked. Error bars represent $\pm 1$ SD across 10 random example selections.

Num examples	Accuracy	Precision	Recall	F1	EMA	PMS
1	77.82 $\pm$ 3.72	38.50 $\pm$ 3.46	37.74 $\pm$ 3.42	37.86 $\pm$ 3.47	13.56 $\pm$ 7.80	66.59 $\pm$ 5.96
3	88.99 $\pm$ 3.26	51.01 $\pm$ 6.27	50.99 $\pm$ 6.25	50.94 $\pm$ 6.25	52.63 $\pm$ 10.79	83.48 $\pm$ 5.19
5	91.45 $\pm$ 1.64	53.58 $\pm$ 4.65	55.59 $\pm$ 5.87	54.15 $\pm$ 4.75	60.36 $\pm$ 8.52	87.55 $\pm$ 2.89
7	91.53 $\pm$ 2.38	56.85 $\pm$ 7.65	57.14 $\pm$ 6.70	56.42 $\pm$ 6.92	61.70 $\pm$ 8.89	87.58 $\pm$ 3.82
10	93.13 $\pm$ 0.73	60.22 $\pm$ 6.68	59.27 $\pm$ 5.45	59.07 $\pm$ 5.22	67.60 $\pm$ 2.65	90.30 $\pm$ 1.08

Table 2: Few-shot learning performance summary. Metrics reported as mean

\pm

standard deviation across 10 random samplings of training examples for each configuration.

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

Table 3: Task-level time breakdown for complete PyPottery pipeline processing 50 sheets (240 drawings). “Hardware impact” indicates GPU dependency: High = GPU-accelerated (significant speedup), Medium = optional GPU acceleration, Low/Irrelevant = CPU-only operations (see Section 3, Implementation).

Figure 6: Representative outputs from PyPotteryTrace showing automated vectorization of pottery profiles. a) annotated image; b) vectorized profile (each point is connected with a Bézier curve); c) post-processed vectors modified in vector-graphics software; d) Bézier curves-styled profile and semantic vector representation in Inkscape; the object tree (right) shows the semantic layer structure of the exported SVG file, with independently editable components (e.g., layer_Profile, layer_Handle, layer_SymmetryLine, layer_Profile_Mirrored).

Figure 7: Representative outputs from PyPotteryLayout showing automated publication layout generation. Materials are organized using hierarchical sorting (primary: stratigraphic unit; secondary: inventory number), with automatically calibrated metric scale, metadata-derived captions, and optimized spatial packing.

Figure S1: An example of a hand-drawn sheet from Montale. The sheet contains pottery drawings and textual data including stratigraphic information, inventory numbers and comments.

Figure S2: Example of the PyPotteryInk GUI v.2.1.0.

Figure S3: Example of the PyPotteryLayout GUI v.0.3.1. 1) Basic settings 2) Advanced settings.

Figure S4: Handwriting recognition performance across different metadata fields. Error bars represent $\pm 1$ standard deviation across 50 random iterations of 15-record samples.

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

Table S1: Hausdorff distance between manual and automatic vectorization outputs.

Figure S5: Comparison between manual and automatic vectorization outputs.

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

Appendix

Table S2: Participant demographics.

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

Appendix

Table S3: Individual SUS item scores and totals.

Metric	Value	Interpretation
Mean SUS Score	83.5	Grade: A (Excellent)
Standard Deviation	11.26
Median	85.0
Range	65.0 – 92.5

Appendix

Table S4: SUS summary statistics.

ID	Role	Arch. exp. (yrs)	Ceramic exp. (yrs)	Drawings processed	SUS	Est. speedup
0	MA/MSc	5	4	200–500	92.5	120 $\times$
1	MA/MSc	6	5	500–1000	92.5	40 $\times$
2	Post-doc	25	25	$>$ 1000	65.0	100 $\times$
3	Post-doc	18	16	$>$ 1000	82.5	32 $\times$
4	Post-doc	13	9	$>$ 1000	85.0	17.5 $\times$

Appendix

Table S5: Individual profile, SUS score and estimated speedup.

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 $\times$	40 $\times$ –120 $\times$
Post-doc	3	9–25	77.5	65.0–85.0	49.8 $\times$	17.5 $\times$ –100 $\times$
All	5	4–25	83.5	65.0–92.5	61.9 $\times$	17.5 $\times$ –120 $\times$

Appendix

Table S6: Aggregates by career stage.

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

Appendix

Table S7: Perceived time savings by module.

Participant	Minutes per Drawing
0	40
1	10–15
2	30–180
3	15
4	13

Appendix

Table S8: Self-reported manual inking time per drawing.

Participant	PyPottery (hours)	Traditional (hours)	Speedup Factor
0	1	120	120 $\times$
1	2	80	40 $\times$
2	1.5	150	100 $\times$
3	1.5	48	32 $\times$
4	4	70	17.5 $\times$

Appendix

Table S9: Estimated time for processing 100 drawings: PyPottery vs. traditional workflow.

Phase	Votes
Inking/Vectorization	4
Scanning/OCR	1
Layout	1

Appendix

Table S10: Phase identified as providing the greatest time savings.

Phase	Votes
Inking/Vectorization	4
Scanning/OCR	1

Appendix

Table S11: Phase identified as needing the most improvement.

Task	Complete	Partial	Success Rate
T1 (Sheet Processing)	5	0	100%
T2 (OCR Extraction)	4	1	80%
T3 (Parsing)	5	0	100%
T4 (Inking)	5	0	100%
T5 (Vectorization)	1	4	20%
T6 (Layout)	5	0	100%

Appendix

Table S12: Task completion status across the six standardized tasks.

Task	Total Help Requests
T1	1
T2	0
T3	0
T4	0
T5	6
T6	0

Appendix

Table S13: Help requests recorded per task.

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”

Appendix

Table S14: Net Promoter Score responses.

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

Appendix

Table S15: Early adoption contexts.

Figure S6: Pyrgi (Santa Severa, Rome). PyPotteryTrace GUI applied to “rosso-bruno” impasto ware.

Figure S7: Arslantepe, “Edificio XLVI” — PyPotteryScan GUI.

Figure S8: Arslantepe, “Edificio XLVI” — PyPotteryTrace.

Figure S9: Biriai (Oliena, Sardegna) — PyPotteryScan GUI.

Figure S10: Biriai (Oliena, Sardegna) — PyPotteryInk output inked plate.

Figure S11: Hüde I (Diepholz) — PyPotteryLayout GUI.

Figure S12: Hüde I (Diepholz) — PyPotteryLayout output.

Figure S13: Torre dell’Alto, Nardò — comparison plate between original and PyPotteryInk-processed drawings.

Figure S14: Shamiram-Aruch (Armenia) — PyPotteryTrace GUI.

Figure S15: Shamiram-Aruch (Armenia) — comparison plates between original and Ink-processed drawings.

Figure S16: Shamiram-Aruch (Armenia) — comparison plates between original and Ink-processed drawings.

Explore similar work

OCR-Based Field Extraction for Archaeological Pottery Metadata: The CENTURIA Dataset
Aug 31, 2026Gissu Valentina Naghavi, Dominik Hagmann, Martin Kampel +1Historical Manuscripts Archive
Computer Vision Lab, TU Wien, Vienna, Austria · Austrian Archaeological Institute, Austrian Academy of Sciences, Vienna, Austria
VaseMuseum: Digital Intelligent Museum for Ancient Greek Pottery
Jul 7, 2026Jiazi Wang, Nonghai Zhang, Qiushi Xie +5Archive Reference-Guided Multimodal In-Context Verification
School of Computer Science and Technology, Beijing Jiaotong University, Beijing 100044, China · School of Computer Science, Peking University, Beijing 100871, China · Department of Computer Science and Information Technology, La Trobe University, Melbourne VIC 3000, Australia +1
Vidya: An AI-Driven Modular Pipeline for Archival Automation and Semantic Metadata Enrichment
May 7, 2026Cloter Migliorini Filho, Julia Graciela Machado, Edson Armando Silva +1Metadata Large Language Model Pipelines
1Museu Campos Gerais - Universidade Estadual de Ponta Grossa - UEPG · 2Universidade Tecnol´ogica Federal do Paran´a - UTFPR

Aug 31, 2026, cs.CVJ/K move · Enter open · S save

OCR-Based Field Extraction for Archaeological Pottery Metadata: The CENTURIA Dataset

Gissu Valentina Naghavi, Dominik Hagmann, Martin Kampel, Irene Ballester

Computer Vision Lab, TU Wien, Vienna, Austria · Austrian Archaeological Institute, Austrian Academy of Sciences, Vienna, Austria

Historical Manuscripts Archive Metadata Maestro Dataset

Open paper AskPDF arXiv

Pottery is a primary source for reconstructing the chronological and economic dimensions of past societies. Archaeologists often document ceramic finds through technical drawings and handwritten metadata. This metadata is critical for dating, provenance attribution, and cross-site comparison, but remains inaccessible to computational analysis, requiring manual transcription of every record. We investigate whether state-of-the-art document analysis models can address this task, and introduce CENTURIA, a dataset of 507 pottery records from the Roman site of Carnuntum, providing transcriptions, bounding boxes, and structured field-level labels across seven metadata categories. Benchmarking five OCR models reveals a substantial domain gap: zero-shot transcription error reaches 15-32% SpACER-M, far exceeding rates on printed archival documents, with domain-specific fields recovered in fewer than 3% of cases. LoRA fine-tuning on just 57 samples, reflecting a realistic archival annotation budget, closes this gap, reducing transcription error to below 1.5% and recovering overall field-level accuracy above 87%. Our results show that a small expert-validated fine-tuning set suffices to convert handwritten pottery documentation into structured, searchable metadata ready for archaeological databases.

Abstract

Explore similar work

OCR-Based Field Extraction for Archaeological Pottery Metadata: The CENTURIA Dataset

VaseMuseum: Digital Intelligent Museum for Ancient Greek Pottery

Vidya: An AI-Driven Modular Pipeline for Archival Automation and Semantic Metadata Enrichment