runic-reader

Runic Reader

A photograph of a runic object goes in; either the catalogued inscription it shows, with its published transliteration and translation, or a drafted English or Swedish translation comes out. This repository is the installation package of the demonstration described in the paper Runic Reader: Identifying and Translating Runic Inscriptions from Photographs (EACL 2027 System Demonstrations).

The pipeline runs on Qwen3.5-4B: zero-shot localization of the inscription, a LoRA recognizer on the crop (transliteration in the Rundata convention), a search of the reading against 10,125 corpus records from Rundata and RuneS, and a LoRA translator for inscriptions the search does not find. Words on which a second recognizer disagrees are flagged, and the reading is editable, so a user who can see the object corrects it and searches again.

Install and run

git lfs install
git clone https://huggingface.co/kesha-humonen/runic-reader
cd runic-reader
python -m venv venv && source venv/bin/activate      # Python 3.10 or newer
pip install -r requirements.txt
python app.py                                        # http://127.0.0.1:7860

To browse the gallery, correct readings and search the corpus without the models, pip install gradio pillow is enough and the app starts as RUNIC_LIVE_MODELS=0 python app.py; the full requirements are needed only for running the models on your own transliteration or photograph.

The pinned versions target Linux on CPU; on other platforms install any recent torch, transformers and peft instead of the pinned ones. A GPU is used automatically when present.

The first tab replays the pipeline on 312 held-out test photographs from cached model outputs, and its corpus search runs live, so it works immediately on any CPU. The second tab runs the models on your own transliteration or photograph; the first such request downloads Qwen/Qwen3.5-4B (revision 851bf6e, about 8 GB) and takes roughly a minute per request on a laptop CPU, seconds on a GPU. To browse without ever loading the models, start it as RUNIC_LIVE_MODELS=0 python app.py.

What is inside

Data and licences

Texts come from Rundata (Samnordisk runtextdatabas) and RuneS-DB. Every photograph is a RuneS-DB record under an open licence, and the app prints the photographer and the licence next to each image. The code is released under CC BY-SA 4.0 together with the rest of this repository.