Pipeline HTR - Documentation

Pôle HTR des hackathons du master Humanités numériques de l'École nationale des chartes-PSL (janvier 2026). Travail collectif (dir. Chahan Vidal-Gorène et Alexandre Lionnet-Rollin).

Projets concernés :

• One prompt to rule them all? Compet. d’HTR de manuscrits médiévaux français - École nationale des chartes-PSL, ERC LostMa (dir. Jean-Baptiste Camps)
• Text Acquisition Pipeline for Early-Modern Latin Manuscripts - École nationale des chartes-PSL, ANR (dir. Katarzyna Kapitan)
• Abbreviations and algorithms - The Icelandic challenge - École nationale des chartes-PSL, ANR (dir. Paola Peratello)

Pipeline HTR (Local)

Installation

pip install -r requirements_htr.txt

Modèle YOLO requis: models/LINES-bbox_YOLOv11n.pt

Architecture

scripts/
├── modules/
│   ├── layout_detection.py
│   ├── model_wrappers.py
│   ├── data_processing.py
│   └── yolo_detection.py
├── app_gradio.py
├── htr_pipeline_modular.py
└── sort_lines-topological.py

Modules

Le pipeline est organisé en modules dans scripts/modules/:

layout_detection.py

Détection de la mise en page des documents.

Fonctions:

• detect_layout() - Détection des paragraphes et lignes
• unify_rows() - Regroupement des lignes
• unify_paragraphs() - Fusion des paragraphes
• get_horizontal_breakpoints() / get_vertical_breakpoints() - Analyse spatiale

Dépendances: numpy, pandas, scipy

model_wrappers.py

Wrappers pour les modèles HTR.

Classes:

• TrOCRMedievalWrapper - TrOCR médiéval
• QwenWrapper - Qwen3-VL (4B/8B) avec adapter Catmus
• MiniCPMWrapper - MiniCPM-Llama3-V-2.5 (modes ABBR/NOT_ABBR)

Support quantization 4-bit optionnelle via bitsandbytes.

Dépendances: torch, transformers, peft, PIL

data_processing.py

Chargement et traitement des données.

Fonctions:

• load_image() - Charge une image
• convert_yolo_to_bbox() - Conversion coordonnées YOLO
• process_detections() - Pipeline complet de traitement
• get_crop_coordinates() - Calcul coordonnées de crop

Dépendances: cv2, pandas

yolo_detection.py

Détection des lignes via YOLOv11.

Classes:

• YOLOLineDetector - Détecteur de lignes

Dépendances: ultralytics, torch

Utilisation

Interface Gradio

python scripts/app_gradio.py

Accessible sur http://127.0.0.1:7861

Pipeline CLI

python scripts/htr_pipeline_modular.py \
    --img data-test/image.jpg \
    --txt results/detection_lines/labels/image.txt \
    --model qwen4b \
    --out_txt output.txt \
    --no_4bit

Tri des lignes indépendant (si besoin, debug)

python scripts/sort_lines-topological.py \
    --img data-test/image.jpg \
    --txt results/detection_lines/labels/image.txt \
    --out result_sorted.jpg \
    --out_txt result_sorted.txt

Extension

Ajout d'un nouveau modèle HTR:

1. Créer une classe dans model_wrappers.py héritant de ModelWrapper
2. Implémenter transcribe(self, image: Image.Image) -> str
3. Ajouter dans load_model() de htr_pipeline_modular.py
4. Mettre à jour les choix dans app_gradio.py

Transcription via API externe (OpenRouter)

Script standalone pour utiliser des VLM via OpenRouter avec In-Context Learning.

Installation

pip install -r requirements_openrouter.txt

Architecture

scripts/
└── openrouter_transcribe.py
prompts/
├── system.txt
└── user.txt

Configuration

Prompts modifiables dans prompts/:

• system.txt - Instructions système
• user.txt - Prompt utilisateur

Utilisation

python scripts/openrouter_transcribe.py \
    --img image.jpg \
    --gt_dir exemples/GT \
    --api_key sk-or-v1-xxx

Paramètres

Requis:

• --img - Image à transcrire
• --gt_dir - Dossier avec exemples (images + .txt associés)
• --api_key - Clé API OpenRouter (ou variable OPENROUTER_API_KEY)

Optionnels:

• --prompts_dir - Dossier des prompts (défaut: prompts)
• --system_prompt - Fichier prompt système (défaut: system.txt)
• --user_prompt - Fichier prompt utilisateur (défaut: user.txt)
• --model - Modèle (défaut: google/gemini-3-flash-preview)
• --max_examples - Nombre d'exemples ICL (défaut: 3)
• --temperature - Température (défaut: 0.1)
• --output - Fichier de sortie

Exemple complet

export OPENROUTER_API_KEY=sk-or-v1-xxx
python scripts/openrouter_transcribe.py \
    --img page.jpg \
    --gt_dir GT/ \
    --prompts_dir prompts \
    --model "google/gemini-3-flash-preview" \
    --max_examples 5 \
    --output result.txt