license: apache-2.0
PyPotteryInk
Transform archaeological pottery drawings into publication-ready illustrations with AI
🚀 Try the demo on Google Colab 🚀
🎯 Overview
As part of the PyPottery toolkit, PyPotteryInk is a deep learning application for automating the digital inking process of archaeological pottery drawings. It transforms pencil drawings into publication-ready illustrations while preserving the original characteristics and enhancing their analytical power.
Example of PyPotteryInk transformation: from pencil sketch to publication-ready illustration
✨ Features
- 🚀 Single-Step Translation: Convert pencil drawings to inked versions using state-of-the-art diffusion models
- 🖼️ High-Resolution Processing: Advanced patch-based system for handling large drawings
- 🎨 Stippling Control: Fine-grained control over dot patterns and shading
- 📂 Batch Processing: Efficient handling of multiple drawings
📚 Documentation
🤖 Available Models
| Model | Description | Checkpoint Size | Link |
|---|---|---|---|
| 10k Model | General-purpose model for pottery drawings | 38.3MB | Download |
| 6h-MCG Model | High-quality model for Bronze Age drawings | 38.3MB | Download |
| 6h-MC Model | High-quality model for Protohistoric and Historic drawings | 38.3MB | Download |
| 4h-PAINT Model | Tailored model for Historic and painted pottery | 38.3MB | Download |
All models support custom fine-tuning for specific archaeological contexts or styles.
⚡ Benchmarks
| GPU | Processing time for test_image.jpg (s) |
|---|---|
| 3070Ti (Windows 11) | 51.48 |
| T4 (Google Colab) | 57.56 |
The benchmarks were performed using the process_single_image function.
📢 AI Disclosure and Citation
PyPotteryInk uses Generative AI to translate archaeological pottery drawings into publication-ready illustrations. To promote transparency about the use of Generative AI and proper attribution in scientific research, is required all users to include the following disclosure statement in any publication, presentation, or report that utilizes PyPotteryInk:
This research utilized PyPotteryInk (version X.X.X) for the AI-assisted translation of [number] pottery drawings. PyPotteryInk is a generative AI tool developed by Lorenzo Cardarelli (https://github.com/lrncrd/PyPotteryInk).
Where you need to specify the software version and the number of processed pottery drawings.
Usage Reporting
By using PyPotteryInk, you agree to:
- Clearly indicate in your methods section which model was used (e.g., "10k Model", "6h-MCG Model" or a custom model)
- Specify the number of images processed with PyPotteryInk
- Include the version number of PyPotteryInk used in your research
Citation
If you use PyPotteryInk in your research, please cite:
@software{cardarelli2025pypotteryink,
author = {Cardarelli, Lorenzo},
title = {PyPotteryInk: Transform archaeological pottery drawings into publication-ready illustrations with AI},
year = {2025},
url = {https://github.com/lrncrd/PyPotteryInk},
version = {0.0.3}
}
or
@article{cardarelli_pypotteryink_2025,
title = {{PyPotteryInk}: One-step diffusion model for sketch to publication-ready archaeological drawings},
volume = {74},
issn = {1296-2074},
url = {https://www.sciencedirect.com/science/article/pii/S1296207425001268},
doi = {10.1016/j.culher.2025.06.016},
shorttitle = {{PyPotteryInk}},
pages = {300--310},
journaltitle = {Journal of Cultural Heritage},
author = {Cardarelli, Lorenzo},
date = {2025-07-01},
keywords = {Archaeological drawing, Diffusion models, Generative {AI}, Image-to-image translation, Pottery},
}
👥 Contributors
Developed with ❤️ by Lorenzo Cardarelli
Based on img2img-turbo by GaParmar
The original code was released under the MIT Licence. The changes made in this fork are released under the Apache License 2.0.