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
| path | contents |
|---|---|
app.py, runic_demo/ |
the interface, the corpus search, the word alignment and the model wrappers |
adapters/ocr4b_crop, adapters/mt4b |
the LoRA adapters for recognition and translation, for Qwen/Qwen3.5-4B |
data/corpus.jsonl |
10,125 catalogued records (Rundata, RuneS) used by the search |
data/examples.jsonl |
the 312 gallery photographs with cached pipeline outputs and their references |
data/calib.json |
the confidence calibration of the search, measured on held-out photographs |
media/full, media/crop |
the photographs and their located crops |
ABOUT.md |
the method and the evaluation, as shown in the third tab |
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.