Hugging Face's logo

Spaces:
Ma-Ri-Ba-Ku
/
Picarones
Running

App Files Community
Picarones / README.md
Claude
chore: remplacer toutes les références bnf/picarones par maribakulj/Picarones
cecde1f unverified
preview code
|
raw
history blame contribute delete
10.6 kB
metadata 
title: Picarones
emoji: 📜
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false

Picarones

Plateforme de comparaison de moteurs OCR/HTR pour documents patrimoniaux Apache 2.0

CI Python 3.11+ License: Apache 2.0

Picarones est un outil open-source conçu pour comparer des moteurs OCR et HTR (Tesseract, Pero OCR, Kraken, APIs cloud…) ainsi que des pipelines OCR+LLM sur des corpus de documents historiques (manuscrits, imprimés anciens, archives).

English version below

Sommaire

Fonctionnalités

Métriques adaptées aux documents patrimoniaux

  • CER (Character Error Rate) : brut, NFC, caseless, diplomatique (ſ=s, u=v, i=j…)
  • WER, MER, WIL avec tokenisation historique
  • Matrice de confusion unicode — fingerprint de chaque moteur
  • Scores ligatures : fi, fl, ff, œ, æ, ꝑ, ꝓ…
  • Scores diacritiques : accents, cédilles, trémas
  • Taxonomie des erreurs en 10 classes (confusion visuelle, abréviation, ligature, casse…)
  • Intervalles de confiance à 95% par bootstrap — tests de Wilcoxon pour la significativité
  • Score de difficulté intrinsèque par document (indépendant des moteurs)

Pipelines OCR+LLM

  • Chaînes composables : tesseract → gpt-4o, pero_ocr → claude-sonnet, LLM zero-shot…
  • Modes : texte seul, image+texte, zero-shot
  • Détection de sur-normalisation LLM : le LLM modernise-t-il à tort les graphies anciennes ?
  • Bibliothèque de prompts pour manuscrits médiévaux, imprimés anciens, latin…

Import de corpus

Source Commande
Dossier local picarones run --corpus ./corpus/
IIIF (Gallica, Bodleian, BL…) picarones import iiif <url>
Gallica (API SRU + OCR) GallicaClient / picarones import iiif
HuggingFace Datasets picarones import hf <dataset>
HTR-United picarones import htr-united
eScriptorium EScriptoriumClient

Rapport HTML interactif

  • Fichier HTML auto-contenu, lisible hors-ligne
  • Tableau de classement trié, graphiques radar, histogrammes
  • Vue galerie avec filtres dynamiques et badges CER colorés
  • Diff coloré façon GitHub, scroll synchronisé N-way
  • Vue spécifique OCR+LLM : diff triple GT / OCR brut / après correction
  • Vue Caractères : matrice de confusion unicode interactive
  • Export CSV, JSON, ALTO XML, PAGE XML, images annotées

Suivi longitudinal & robustesse

  • Base SQLite optionnelle pour historiser les runs
  • Courbes d'évolution CER dans le temps par moteur
  • Détection automatique des régressions entre deux runs
  • Analyse de robustesse : bruit, flou, rotation, réduction de résolution, binarisation
  • Commandes picarones history, picarones robustness

Installation rapide 

# Cloner et installer
git clone https://github.com/maribakulj/Picarones.git
cd picarones
pip install -e .

# Tesseract (binaire système, obligatoire pour le moteur Tesseract)
# Ubuntu/Debian
sudo apt install tesseract-ocr tesseract-ocr-fra tesseract-ocr-lat

# macOS
brew install tesseract

# Vérifier l'installation
picarones engines

Voir INSTALL.md pour un guide détaillé (Linux, macOS, Windows, Docker).

Usage rapide 

# Rapport de démonstration (sans moteur OCR installé)
picarones demo

# Benchmark sur un corpus local
picarones run --corpus ./mon_corpus/ --engines tesseract --output resultats.json

# Générer le rapport HTML interactif
picarones report --results resultats.json --output rapport.html

# Calculer CER/WER entre deux fichiers
picarones metrics --reference gt.txt --hypothesis ocr.txt

# Importer depuis Gallica (IIIF)
picarones import iiif https://gallica.bnf.fr/ark:/12148/xxx/manifest.json --pages 1-10

# Suivi longitudinal (historique des runs)
picarones history --demo
picarones history --engine tesseract --regression

# Analyse de robustesse
picarones robustness --corpus ./gt/ --engine tesseract --demo

# Interface web locale
picarones serve

Moteurs supportés

Moteur Type Installation
Tesseract 5 Local CLI pip install pytesseract + binaire système
Pero OCR Local Python pip install pero-ocr
Kraken Local Python pip install kraken
Mistral OCR API REST Clé MISTRAL_API_KEY
GPT-4o (LLM) API REST Clé OPENAI_API_KEY
Claude Sonnet (LLM) API REST Clé ANTHROPIC_API_KEY
Mistral Large (LLM) API REST Clé MISTRAL_API_KEY
Google Vision API REST Credentials JSON Google
AWS Textract API REST Credentials AWS
Azure Doc. Intel. API REST Endpoint + clé Azure
Ollama (LLM local) Local ollama serve
Moteur custom CLI/API YAML Déclaration YAML, sans code

Structure du projet 

picarones/
├── cli.py                      # CLI Click (run, demo, report, history, robustness…)
├── fixtures.py                 # Données de test fictives réalistes
├── core/
│   ├── corpus.py               # Chargement corpus (dossier, ALTO, PAGE XML…)
│   ├── metrics.py              # CER, WER, MER, WIL (jiwer)
│   ├── normalization.py        # Normalisation unicode, profils diplomatiques
│   ├── statistics.py           # Bootstrap CI, Wilcoxon, corrélations
│   ├── confusion.py            # Matrice de confusion unicode
│   ├── char_scores.py          # Scores ligatures et diacritiques
│   ├── taxonomy.py             # Taxonomie des erreurs (10 classes)
│   ├── structure.py            # Analyse structurelle
│   ├── image_quality.py        # Métriques qualité image
│   ├── difficulty.py           # Score de difficulté intrinsèque
│   ├── history.py              # Suivi longitudinal SQLite
│   ├── robustness.py           # Analyse de robustesse
│   ├── results.py              # Modèles de données + export JSON
│   └── runner.py               # Orchestrateur benchmark
├── engines/                    # Adaptateurs moteurs OCR
├── llm/                        # Adaptateurs LLM (OpenAI, Anthropic, Mistral, Ollama)
├── importers/                  # Sources d'import (IIIF, Gallica, eScriptorium, HF…)
├── pipelines/                  # Orchestrateur OCR+LLM
├── report/                     # Générateur rapport HTML
└── web/                        # Interface web FastAPI
tests/                          # Tests unitaires et d'intégration (743 tests)

Variables d'environnement 

# APIs LLM (selon les moteurs utilisés)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export MISTRAL_API_KEY="..."

# APIs OCR cloud (optionnel)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="eu-west-1"
export AZURE_DOC_INTEL_ENDPOINT="https://..."
export AZURE_DOC_INTEL_KEY="..."

Roadmap

Sprint Statut Livrables
Sprint 1 ✅ Structure, Tesseract, Pero OCR, CER/WER, CLI
Sprint 2 ✅ Rapport HTML v1, diff coloré, galerie
Sprint 3 ✅ Pipelines OCR+LLM, GPT-4o, Claude
Sprint 4 ✅ APIs cloud, import IIIF, normalisation diplomatique
Sprint 5 ✅ Métriques avancées : confusion unicode, ligatures, taxonomie
Sprint 6 ✅ Interface web FastAPI, HTR-United, HuggingFace, Ollama
Sprint 7 ✅ Rapport HTML v2 : Wilcoxon, clustering, scatter plots
Sprint 8 ✅ eScriptorium, Gallica API, historique longitudinal, robustesse
Sprint 9 ✅ Documentation, packaging, Docker, CI/CD

Contribuer

Voir CONTRIBUTING.md pour ajouter un moteur OCR, un adaptateur LLM, ou soumettre une pull request.

Licence

Apache License 2.0

English

Picarones — OCR/HTR Benchmark Platform for Heritage Documents

Picarones is an open-source platform for rigorously comparing OCR and HTR engines (Tesseract, Pero OCR, Kraken, cloud APIs…) and OCR+LLM pipelines on historical document corpora — manuscripts, early printed books, archives.

Key Features

  • Metrics tailored to historical documents: CER (raw, NFC, caseless, diplomatic), WER, MER, WIL; unicode confusion matrix; ligature and diacritic scores; 10-class error taxonomy; bootstrap confidence intervals; Wilcoxon significance tests
  • OCR+LLM pipelines: composable chains (tesseract → gpt-4o), three modes (text-only, image+text, zero-shot), LLM over-normalisation detection
  • Corpus import: local folder, IIIF (Gallica, Bodleian, BL…), Gallica API + OCR, HuggingFace Datasets, HTR-United, eScriptorium
  • Interactive HTML report: self-contained file, sortable ranking, gallery, coloured diff, unicode character view, CSV/JSON/ALTO/PAGE XML export
  • Longitudinal tracking: SQLite benchmark history, CER evolution curves, automatic regression detection
  • Robustness analysis: degraded image versions (noise, blur, rotation, resolution, binarisation), critical threshold detection

Quick Start 

pip install -e .
sudo apt install tesseract-ocr tesseract-ocr-fra   # Ubuntu/Debian
picarones demo          # demo report without any engine installed
picarones engines       # list available engines
picarones run --corpus ./corpus/ --engines tesseract --output results.json
picarones report --results results.json

See INSTALL.md for detailed installation on Linux, macOS, Windows, and Docker.

Supported Engines

Tesseract 5 · Pero OCR · Kraken · Mistral OCR · GPT-4o · Claude Sonnet · Mistral Large · Google Vision · AWS Textract · Azure Document Intelligence · Ollama (local LLMs) · Custom YAML engine

License

Apache License 2.0