Installation Guide

Setting up PyPotteryInk for Archaeological Drawing Processing

Installation Overview

PyPotteryInk requires specific hardware and software components to function properly. This guide will walk you through the installation process step by step, ensuring you have everything needed to start processing archaeological drawings.

System Requirements

Before installing PyPotteryInk, ensure your system meets these minimum requirements:

Hardware Requirements

For model inference (using the tool):

  • CPU: Modern multi-core processor (Intel i5/i7 or AMD Ryzen 5/7)
  • RAM: 16GB minimum, 32GB recommended
  • Storage: Minimum 10GB for the base installation and models
  • GPU: NVIDIA GPU with 8GB VRAM (for optimal performance)

For model training or fine-tuning:

  • GPU: NVIDIA GPU with at least 24GB VRAM
  • RAM: 32GB minimum
  • Storage: 100GB+ recommended for datasets and model checkpoints

Software Requirements

PyPotteryInk requires Python 3.10 or newer and depends on several deep learning frameworks:

  • CUDA Toolkit 11.8 or newer (for GPU support)
  • PyTorch 2.0 or newer
  • Other Python dependencies (automatically installed)

Installation Steps

1. Download the Project

First, download the latest release from our GitHub repository. You can find the release package at:

2a. Automatic installation

PyPotteryInk includes a unified installation script that works on all platforms:

git clone https://github.com/lrncrd/PyPotteryInk.git
cd PyPotteryInk
python install.py

The installation script will: - Create a virtual environment

- Install all dependencies

- Download required models

- Set up the application

Running the Application

After installation:

- Windows: Double-click run.bat or run it from terminal

- macOS/Linux: Run ./run.sh or python app.py

The web interface will open automatically in your browser at http://127.0.0.1:7860 (or the next available port).

2b. Manual installation

After downloading, extract the package to your desired location. The folder structure should look like this:

pypotteryink/
├── requirements.txt
├── models/ # This folder will be created by running test.py
├── ink.py
├── models.py
├── preprocessing.py
├── postprocessing.py
├── test.py
├── utils.py
└── Montale_stats.npy

Install Dependencies

Move to the downloaded folder and run this command

pip install -r requirements.txt

The installation might take several minutes depending on your internet connection.

Verify Installation

After installation, you can verify everything is working correctly. Move into the folder and run

python test.py

The test will detect CUDA installation and run some functions to a test image.

Common Installation Issues

CUDA Not Found

If you see an error about CUDA not being available:

  1. Ensure you have the NVIDIA drivers installed
  2. Verify CUDA installation by running:
nvidia-smi
  1. Make sure your GPU is CUDA-capable and properly recognised
Important

This guide is about inference. For training or fine-tuning, check out the Training guide section!