Ressources numériques en sciences humaines et sociales OpenEdition Nos plateformes OpenEdition Books OpenEdition Journals Hypothèses Calenda Bibliothèques OpenEdition Freemium Suivez-nous

Publication d’un modèle de transcription et de la vérité de terrain !

Afin de rendre visible le travail colossale d’annotation réalisé par les équipes des Archives nationales, les transcriptions susceptibles de servir de données d’entraînement sont désormais publiées au sein du projet HTR-United, dans 3 répertoires Github distincts. Leur publication permet désormais à d’autres utilisateurs et utilisatrices de l’HTR de les réemployer pour leur propres expérimentations.

Il s’agit des répertoires suivants :

LECTAUREP Repertoires : qui contient les pages de répertoires, transcrites et validées (de nombreuses nouvelles pages sont en cours de relecture).

LECTAUREP Bronod : qui contient les minutes rédigées par Maître Bronod, dont le format diffère du corpus de répertoires car elles datent de 1742.

LECTAUREP Mariages et Divorces : qui contient les registres des Mariages et Divorces, pour le début du XXe siècle principalement.

Illustration des 3 types de documents issus de chaque corpus
Illustration des 3 types de documents issus de chaque corpus (de gauche à droite : Bronod, Repertoires, Mariage et Divorce)

Un modèle générique v1

Un nouveau modèle générique intitulé lectaurep_base a été entraîné à partir de ces données. Il est publié sur deux plateformes :

– sur Zenodo, ce qui le rend interrogeable depuis Kraken et permet de lui attribuer un DOI : https://zenodo.org/record/6542744

– sur Github afin de correctement documenter ses conditions de création : https://github.com/lectaurep/lectaurep_base_model

Les deux espaces de publication sont synchronisés et ont l’avantage de permettre de versionner les dépôts. Cela signifie que lorsque de nouvelles données seront publiées, nous pourrons entraîner un nouveau modèle et le publier dans les mêmes répertoires comme des v2, 3, etc.

Il est toujours possible d’accéder aux autres modèles entraînés au cours du projet LECTAUREP, notamment Generic_lectaurep_26, en se rendant ici : https://gitlab.inria.fr/dh-projects/kraken-models.

9,8% de CER

Le modèle générique produit encore beaucoup d’erreurs car son CER (Character Error Rate) reste au-dessus de 5%. Ce taux d’erreur augmente sur des données hors-domaine, c’est-à-dire des variations d’écritures inconnues pour le modèle.

Si on l’applique à un poème autographe d’Apollinaire par exemple, il fait 5 erreurs sur le titre :

Lettres à lire Lettres lue
L l
ont ais
b l
Aperçu de la transcription produite par lectaurep_base, comparé à la transcription attendue (manual) et à celle produite par generic_lectaurep_26
Aperçu de la transcription produite par lectaurep_base sur une écriture inconnue, comparée à la transcription attendue (manual) et à celle produite par generic_lectaurep_26

Le modèle lit donc “le Pais Miraleau” au lieu de “Le Pont Mirabeau”. Il est toutefois intéressant de noter deux choses :

– sur ce même segment, le modèle lectaurep_base fait moins d’erreurs que le modèle generic_lectaurep_26 (même si une partie d’entre elles sont identiques)

– les erreurs propres à lectaurep_base ont plus de sens que celles de generic_lectaurep_26 : si on regarde le tracé des lettres, on comprend l’origine de ces inversions.

L’ajout de nouvelles données d’entraînement pourra peut-être permettre d’abaisser le taux d’erreur théorique, mais cela permettra surtout d’augmenter la robustesse face à des écritures inconnues. Par ailleurs, le but d’un tel modèle n’est pas forcément d’être utilisé comme tel, mais plus de servir de base (comme son nom l’indique) pour affiner de nouveaux modèles de transcription, spécialisés sur une période ou une famille d’écritures.

Publication avec Kraken

Le dépôt Zenodo à été généré à partir de l’utilitaire de publication proposé par Kraken. Il me paraît intéressant d’expliquer ici la marche suivie.

Après avoir installé Kraken (dans un environnement virtuel), la commande “ketos publish” permet de lancer l’utilitaire de publication. La commande complète la plus basique ressemble à ceci :

ketos publish -a $ACCESS_TOKEN chemin/vers/le/model.mlmodel

Cette commande déclenche l’utilitaire en mode interactif. L’utilisateur ou l’utilisatrice est alors amené(e) à renseigner, entre autres, le nom des auteurs et autrices du modèle, leur affiliation, la licence associée au modèle, ainsi qu’une description plus ou moins longue.

La valeur ACCESS_TOKEN doit être obtenue prélablement à partir de Zenodo. Pour cela, il faut créer un compte Zenodo et s’y connecter, puis aller sur Paramètres, puis Applications (ou cliquer ici). C’est depuis cette page que l’on peut créer un jeton d’authentification (access token) qu’il faut prendre soin de copier avant qu’il ne devienne invisible. Le jeton est une (longue) liste de caractères, par exemple “xTjfTjffMh3Ch0CSfwT1tpC”. Avec une telle valeur, la commande ressemble donc à ceci :

ketos publish -a xTjfTjffMh3Ch0CSfwT1tpC chemin/vers/le/model.mlmodel

Comme il peut sembler risqué d’utiliser la ligne de commande pour fournir les métadonnées qui seront ensuite publiées avec le modèle, il est possible d’utiliser un fichier JSON reprenant la structure suivante :

{"authors": [{"name": "", "affiliation": ""}], "summary": "", "description": "", "accuracy": 00.00, "license": "", "script": [], "name": "", "graphemes": []}

C’est l’option “-i” qui permet de passer le fichier de métadonnées à Ketos. Le mode interactif ne se déclenche pas si on utilise cette option. Admettons que le fichier soit nommé “metadata.json”, la commande ressemblerait à ceci :

ketos publish -i chemin/vers/metadata.json -a xTjfTjffMh3Ch0CSfwT1tpC chemin/vers/le/model.mlmodel

Lorsque la publication vers Zenodo est terminée, Kraken affiche l’identifiant du nouveau dépôt. Il est alors possible d’éditer les métadonnées depuis Zenodo de manière à corriger des erreurs, mieux structurer la description longue, ou encore ajouter d’autres contributeurs et contributrices.

En publiant à l’aide de Kraken, le modèle est automatiquement associé à la communauté “OCR/HTR model repository“. Cela lui donne plus de visibilité, ce qui n’est pas un luxe dans l’océan de dépôts qu’est Zenodo !

Résolution de bug : Something went wrong during the segmentation

Lorsque l’on suit la procédure pour transférer des données de Transkribus vers eScriptorium, il arrive que durant l’exécution de l’étape 3 (le re-calcul des maques) le message “Something went wrong during the segmentation” s’affiche plusieurs fois, tandis que sur autant de cartes-images, l’icône “segmentation” s’affiche désormais en rouge.

Ce qui suit est une proposition de résolution pour ce problème.

Comment rendre mes pages compatibles avec le calcul des masques ?

Si vous cliquez sur l’une des cartes-images problématiques et affichez le volet de segmentation, en activant le mode “line mask”, vous vous rendez rapidement compte quand dans les pages où la segmentation n’a pas marché, il existe des lignes pour lesquels un masque existe sans baseline.

Affichage des baselines et des masques dans eScriptorium: la dernière ligne n'a pas de baseline
La dernière ligne n’a pas de baseline !

Un procédé relativement simple consiste à :

  • copier la transcription de la ligne fautive et l’enregistrer temporairement ailleurs ;
  • en gardant le mode “line mask” activé,  sélectionner le masque sans baseline puis le supprimer ;
  • dessiner une nouvelle baseline (automatiquement associée à un masque) puis lui assigner à la transcription initiale.

Une fois qu’il ne reste plus de masques sans baseline sur l’image, il est alors possible de relancer la segmentation de tous les masques pour cette page.

La segmentation s'effectue maintenant sans problème
La segmentation s’effectue désormais sans problème !

Comment faire si toutes les lignes de la page sont concernées ?

Il n'y a que des masques sans baseline correspondantes
Il n’y a aucune baseline, que des masques !

Afin de traiter l’ensemble de la page en une seule fois, il est possible d’utiliser le volet “Text” pour copier/coller la totalité de la transcription au lieu de procéder ligne par ligne :

  • activer le volet “Text” et copier la transcription ;
  • sélectionner la totalité des masques et les supprimer ;
  • tracer une par une les baselines en suivant l’ordre de lecture ;
  • vérifier l’ordre des lignes puis coller la transcription initiale.

Pourquoi ne pas ignorer ces messages ?

Lorsque vous transférer vos données de Transkribus vers eScriptorium, il est possible que vous souhaitiez comparer les performances des deux logiciels. Si vous ne faites rien pour résoudre ce problème, vous risquez de fragiliser les bases de votre expérimentation. En effet, ces pages non segmentées contiennent des données qui ne seront pas utilisables par Kraken lors de l’entrainement d’un modèle.

Cela signifie aussi que l’intégrité de vos donnée n’est pas garantie pour la suite de vos expérimentations sur eScriptorium.

D’où vient le problème ?

Il est possible de prévenir ces problèmes de segmentation en inspectant les fichiers XML PAGE générés par Transkribus. En effet, on se rend alors compte que les lignes qui posent problèmes correspondent à des noeuds TextLine où l’élément Baseline est absent. Dans l’image ci-dessous, on peut voir :

  • de la ligne 40 à 45, un noeud TextLine incorrect, sans élément Baseline ;
  • de la ligne 46 à 52 un noeud TextLine correct.
Extrait d'un fichier XML PAGE ayant généré une mauvaise segmentation
L’élément TextLine de la lingne 40 à 45 n’a pas d’élément Baseline.

 

Switching from Transkribus to eScriptorium with Aspyre

Warning: the pipeline described below is no longer necessary to transfer data from Transkribus to eScriptorium. It is indeed preferrable to use PAGE XML, which is immediately compatible with eScriptorium. See our tutorial.

 

 

eScriptorium is a transcription platform currently being developed by SCRIPTA PSL. It provides Kraken with a GUI and an API, increasing the accessibility of this OCR software and broadening its functionalities1. Both eScriptorium and Kraken are free and open source, and so are the models created with them. This is important because it means that when using eScriptorium and/or Kraken you can save your model as a file and share it with whoever you want, however you want. This makes the effort put into creating the ground-truth all the more worthwhile2!

Additionally, Kraken produces two types of models:

  1. Segmenters which detect lines of text on an image; and
  2. Recognizers which transcribe these lines. 

Both types of models can be trained with your own data on the eScriptorium platform. Therefore, if your documents’ layout is too specific to be properly handled by a generic model, you can create one from scratch or finetune the default generic model in order for it to fit your own needs and objectives. In other words, compared to a platform like Transkribus, eScriptorium gives you more flexibility and more freedom to build your own models for the detection of the layout and the transcription of your documents. 

If you have started your project using Transkribus and wish to transfer your data to eScriptorium, it is possible. To address the complexities encountered and bridge the gap between these two platforms, we developed Aspyre, an easy-to-use solution leveraging ALTO XML as a hub.

This article is not a tutorial on how to use eScriptorium or Transkribus: rather, it is intended to be extended documentation on what to expect from and how to use Aspyre.

LectAuRep, a case example

Back in 2018, during an exploratory phase of the LectAuRep project which aimed at determining whether it was possible to automatically transcribe our documents3, we evaluated the performance of several transcription tools, including Transkribus and Kraken. 

A major issue we encountered was that of detecting the text on the documents and reproducing the table-like layout. We soon realized that the quality of segmentation weighs a lot in the quality of transcription. We were successful at training an acceptable transcription model in Transkribus4, but would spend too much time manually rendering the layout on this platform. 

It became necessary to find another solution to automatically detect the segments and Kraken and eScriptorium offered promising perspectives. 

As a result, we switched to Kraken while in the meantime leaving the data produced during phase 1 on Transkribus. Recently, we decided to retrieve the transcriptions created with Transkribus and transfer them to eScriptorium. Our intentions were to compare, given an identical dataset, the transcription performances of Kraken and Transkribus. Ideally, we also wanted to add the ground truth created during phase 1 to the rest of the data generated with eScriptorium.

Transferring the data from Transkribus to eScriptorium turned out to be more complicated than just exporting data from Transkribus and importing them to eScriptorium. A few changes needed to be made in the documents exported from Transkribus: we developed Aspyre to execute these modifications.

Okay, so what about Aspyre?

Aspyre is a Python library that will help import into eScriptorium data you exported from Transkribus. Because you may want to use Aspyre quickly without having to worry about a local installation, we also provide Aspyre as a service online (GUI) on a demo server5. We even created a ready-to-use script to run Aspyre as a CLI.

Aspyre uses ALTO XML because this standard is processed by both Transkribus and eScriptorium. However, by default the files produced by the former slightly differ from the files expected by the latter6. The three main issues are:

  1. Transkribus’ exports follow the ALTO 2 schema specifications, while eScriptorium is based on ALTO 4;
  2. Transkribus does not refer to the image associated with a transcription whereas eScriptorium relies on it to dynamically pair a transcription and the corresponding image;
  3. Transkribus exports only refer to a baseline coordinate from the y axis (“At which height on the image do we find the baseline?”) whereas eScriptorium will produce a baseline based on at least two x-y coordinates. 

To summarize Aspyre’s actions: it takes an archive exported from Transkribus and re-composes the information needed by eScriptorium. It injects the reference to the source image matched by the transcription and transforms the ALTO XML tree to conform to the correct schema specifications on top of fixing how baselines are specified. 

Using Aspyre: a walkthrough

The steps to run your data through Aspyre are fairly simple.

  1. Export your data in the “Transkribus Document” format, checking the “Export ALTO” and “Export Image” options (see screenshot below). You will now have a ZIP file.
  2. If you use Aspyre as a GUI, you need to keep your ZIP file under 500 MB. Conveniently, Aspyre does not need the images to run7 so you can eliminate them from the archive following your preferred method8
  3. Run Aspyre on your data from the CLI or upload the archive on Aspyre GUI following the documentation provided with each tool. You will obtain a new ZIP file containing modified ALTO XML files.
  4. After uploading your images on eScriptorium, import the transcriptions using the “Import Transcription” option and select the new ZIP file.
Minimal configuration of the exports on Transkribus: check "Transkribus Document" and then "Export ALTO" and "Export Image".
Minimal configuration of the exports on Transkribus.

Dissecting Aspyre

Aspyre was developed as a library (aspyrelib), so you can add it to your own pipeline and call its main function (aspyrelib.main()). 

To run properly, Aspyre will take a directory with an architecture similar to the ones you can extract from Transkribus: at minimum, it shall contain a file named “mets.xml” and a directory named “alto/” containing ALTO XML files. The file “mets.xml” must contain a node such as “<ns3:fileGrp ID=”IMG”>” referring to image files, and a node such as “<ns3:fileGrp ID=”ALTO”>” referring to the ALTO XML files.

The ALTO XML file has a new schema declaration and includes a reference to the corresponding image after being processed by Aspyre.
The ALTO XML file has a new schema declaration and includes a reference to the corresponding image after being processed by Aspyre.

After Aspyre has listed the image files referred to in “mets.xml” and the XML files in the alto directory, each ALTO XML file is mapped with its corresponding source image. This is rendered by the creation of a “sourceImageInformation” node in the “Description” section of the ALTO XML file. 

The schema specifications are updated to ALTO 4 (currently an eScriptorium-flavored version9 ) and non-ALTO 4 elements are modified. Mainly, this results in “composedBlock” elements being removed, although their content is kept in the tree.

Additional modifications are made on the segment level. First, since complete baseline coordinates are key information for eScriptorium, Aspyre makes sure that they are properly expressed: it takes the unique value stored in the @BASELINE attributes  and extrapolates the correct coordinates based on the values associated with the corresponding @HPOS, @VPOS and @WIDTH attributes. @BASELINE attributes are then populated with the right coordinates. At the end of the process baseline coordinates are expressed as “xA yA xB yB” instead of “yA”. Unfortunately, for images where the text is crooked or tilted, this extrapolation may result in unsatisfying segments, forcing the user to later manually correct the imported segments. This aspect of the transformation will be improved in future developments.

After Aspyre is ran, BASELINE attributes refer to 4 x and y coordinates, calculated from the values in the original BASELINE, HPOS, VPOS and WIDTH.
After Aspyre is ran, BASELINE attributes refer to 4 x and y coordinates, calculated from the values in the original BASELINE, HPOS, VPOS and WIDTH.

Finally, since the ALTO 4 specifications used by eScriptorium currently differ slightly from the official schema, we want to point out that coordinates associated with the @BASELINE and @POINTS attributes must be expressed without any comma. The coordinates “xA,yA xB,yB” will thus become “xA yA xB yB”. This modification is handled by Aspyre as well and is easily reversed.

Commas are removed from the values of POINTS attributes, following eScriptorium's ALTO schema specifications.
Commas are removed from the values of POINTS attributes, following eScriptorium’s ALTO schema specifications.

Contribute!

The transformation scenario followed by Aspyre was tested against data produced in various contexts. However, your data and your practices may differ from ours. This can cause Aspyre to not exactly fit your needs or to somehow not be compatible with your data. Please, let us know if Aspyre has failed you! 

Aspyre is a work in progress and we would be happy to make updates so it is compatible with your data. Even if you have no idea why it didn’t work, we ask that you report the error by creating an issue on our development platform

Of course, you can also dig into the code yourself and find out what is causing the issue. In such cases, please, shoot us a pull request!

  1. For more information on eScriptorium and its functionalities, see https://escripta.hypotheses.org/ []
  2. For example, you can share your ground-truth via the HTR-United initiative:  https://htr-united.github.io/ []
  3. Digitized notary registers from Minutier Central’s collection at the Archives nationales. For more information on this collection, see http://www.archives-nationales.culture.gouv.fr/fr/web/guest/archives-des-notaires-de-paris  []
  4.  For more information on this phase, see Marie-Laurence Bonhomme. Répertoire des Notaires parisiens Segmentation automatique et reconnaissance d’écriture : Rapport exploratoire. Inria. 2018, pp.1-10. ⟨hal-01949198v2⟩. []
  5. Since this is a demo server, there is a limitation on the size of the files you can upload: 500 MB max! []
  6. Compare documents exported from each platform : https://github.com/alix-tz/aspyre-gt/tree/master/data/altos  []
  7. It only needs the mets.xml file to refer to them, this is the reason why you have to check “Export Image” in Transkribus. []
  8. You can use a software like 7-Zip or run this step from the command line. In any case, to remove the image from the archive, unzip it and rezip it keeping only the “alto” directory and the “mets.xml” file. []
  9. We believe this divergence from the official schema is only temporary and closely linked to future improvements in the ALTO 4 specifications.  []