Une documentation sur eScriptorium à jour et plus complète est désormais disponible ici : https://escriptorium.readthedocs.io/

Documents

• Démo vidéo d’une partie des fonctionnalités d’eScriptorium : https://escripta.hypotheses.org/escriptorium-video-gallery
• Code source d’eScriptorium : https://gitlab.inria.fr/scripta/escriptorium
• Version anglaise de ce tutoriel

Pré-requis

• Disposer d’un compte sur une instance eScriptorium ;
• Ou bien avoir fait une installation locale d’eScriptorium (avec Docker ou sans Docker).

Sommaire

• 1. Pas-à-pas
  
  • 1.1. Connexion à eScriptorium
  • 1.2. Créer un nouveau projet et un nouveau document
    
    • 1.2.1. Point terminologie
    • 1.2.2. Instructions
  • 1.3. Charger des images
    • 1.3.1. Accéder à l’interface
    • 1.3.2. Importer des fichiers locaux
    • 1.3.3. Importer des images depuis un fichier PDF
    • 1.3.4. Utiliser un manifeste IIIF
  • 1.4. Annoter manuellement les documents
    • 1.4.1. Accéder à l’interface
    • 1.4.2. Annoter les segments et les zones sur l’image
    • 1.4.3. Annoter la transcription
    • 1.4.4. Gestion des versions de transcription
    • 1.4.5. Comparer les transcriptions
    • 1.4.6. Aparté sur l’articulation des baselines, des polygones et des transcriptions
    • 1.4.7. Modifier l’ordre des segments
    • 1.4.8. Annotation sémantique
    • 1.4.9. Clavier virtuel
  • 1.5. Importer des annotations
    
    • 1.5.1. Importer des annotations structurées en XML
    • 1.5.2. Importer des annotations à partir d’un texte brut
  • 1.6. Annoter automatiquement les documents
    • 1.6.1. Instructions
    • 1.6.2. Paramétrage de la segmentation
  • 1.7. Importer ou entraîner des modèles
    • 1.7.1. Lancer un entraînement
    • 1.7.2. Importer un modèle
    • 1.7.3. Affiner un modèle ou partir de zéro ?
  • 1.8. Exporter les données
  • 1.9. Ajouter des étiquettes sur les documents
• 2. Gérer une campagne d’annotation collaborative
  • 2.1. Créer un groupe d’utilisateurs
  • 2.2. Partager un document avec un autre utilisateur ou avec un groupe
  • 2.3. Partager un modèle avec un autre utilisateur ou avec un groupe

---

1. Pas-à-pas

1.1. Connexion à eScriptorium

On se connecte à eScriptorium avec un compte individuel associant un login ou une adresse e-mail à un mot de passe. Ce compte a été créé par l’utilisateur après réception d’une invitation ou bien par l’administrateur du site.

Une fois connecté, on atterrit sur le tableau de bord qui permet de gérer l’ensemble des projets créés par ou partagés avec le compte. Lors de la première connexion, ce tableau de bord est vide.

---

1.2. Créer un nouveau projet et un nouveau document

1.2.1. Point terminologie

• Un “projet” est une collection de documents partageant des paramètres (utilisateurs, tags, etc) ;
• Un “document” est une collection d’images formant un ensemble ;
• Une “document-part” est une image, une page appartenant à un document.

1.2.2. Instructions

Pour créer un projet, aller sur “My Projects” et cliquer sur le bouton “Create new project” ; une nouvelle page s’affiche, dans lequel un unique champ permet de nommer le projet. Le projet est créé dès que le bouton “Create” est activé. Le projet, vide, est désormais affiché dans la liste des projets. 

Pour créer un document, cliquer sur un projet puis sur sur le bouton “Create new Document” ; une nouvelle page s’affiche ainsi qu’un formulaire de saisie.

Le champs “Name” est obligatoire. Les autres sont optionnels et peuvent être remplis plus tard. Nous reviendrons sur la section “Ontology” plus tard.

Une fois les informations saisies, cliquer sur “Create” pour créer le document, un message s’affiche alors : “Document created successfully!”.

Vous pouvez encore modifier les données saisies : le bouton “Create” a été remplacé par un bouton “Update”.

Pour revenir à ce formulaire depuis le tableau de bord, cliquer sur le document dans la liste puis, une fois l’onglet “Images” ouverte, cliquer sur l’onglet “Description” . Ou bien, si le document contient déjà des images, cliquer sur l’icône “Edit last updated image” puis sur l’onglet “Description”.

1.4. Annoter manuellement les documents

1.4.1. Accéder à l’interface

L’annotation manuelle est nécessaire pour générer des données de vérité de terrain (ground truth) utilisées pour entraîner des modèles, ou pour corriger le résultat de ces opérations. Elle peut également intervenir dans le cadre d’une campagne d’annotation ne faisant pas usage de modèles Kraken (eScriptorium sert alors seulement d’environnement de saisie).

L’onglet d’édition des document-parts permet de créer ou de modifier des éléments d’annotation manuellement. On y accède en cliquant sur l’onglet “Edit” en haut de page ou bien en cliquant sur le bouton “Edit” présent sur chaque “carte” représentant une document-part. Il existe dans cet onglet plusieurs volets de visualisation correspondant à chaque tâche d’édition possible.

• “Source image” permet d’afficher l’image source ;
• “Segmentation” permet d’afficher le volet d’édition de la segmentation ;
• “Transcription” permet d’afficher le volet d’édition de la transcription en vue diplomatique ;
• “Text-Annotation” permet d’afficher le volet d’édition de la transcription en mode texte et de modifier l’ordre des lignes ou encore (bientôt) d’annoter le texte.

---

1.4.2. Annoter les segments et les zones sur l’image

Le volet d’édition des segments permet de réaliser plusieurs opérations essentielles :

• Tracer des lignes de base (baselines) correspondant aux emplacement du texte sur l’image selon deux modes :
  • tracé libre (déconseillé) ;
  • tracé point par point.
• Ajouter des points sur une ligne (la sélectionner puis double-cliquer à l’emplacement du point) ;
• Déplacer un ou plusieurs point(s) par un simple sélectionner-glisser ;
• Supprimer un ou plusieurs point(s) sur une ligne ;
• Sectionner une ou plusieurs lignes à l’aide de l’outil ciseaux ;
• Joindre une ou plusieurs lignes ;
• Paramétrer le sens de lecture d’une ligne ;
• Activer le calcul des polygones associés à chaque ligne (cette tâche est automatique et gérée de manière asynchrone sans action de la part de l’utilisateur après la première utilisation) ;
• Associer une ou plusieurs lignes à une région.

Dans ce volet, il est également possible de créer des régions (ou zones) et d’y associer des segments. Un segment situé dans le périmètre d’une région n’est donc pas automatiquement associé à celle-ci.

L’ensemble des manipulations réalisables dans ce volet est détaillé dans une fenêtre d’aide (pour l’afficher, cliquer sur “?”). On notera ainsi qu’il existe de nombreux raccourcis permettant de simplifier toutes ces opérations.

---

1.4.3. Annoter la transcription

C’est uniquement lorsqu’il existe des segments et des masques sur l’image qu’il est possible de d’utiliser les fonctionnalités des onglets “Transcription” et “Text”.

Pour ajouter ou modifier une transcription associée à la un segment depuis le volet “Transcription”, cliquer sur la zone correspondante. Une fenêtre de saisie s’affiche. Pour enregistrer une transcription, taper sur “Entrée” : l’interface de transcription affiche automatique le champs de saisie pour le segment suivant.

Au fur et à mesure de la saisie dans le volet “Transcription”, les zones crénelées sont remplacées par du texte et le contenu du volet “Text” évolue. Il est donc également possible de modifier le texte depuis le volet “Text” et même de copier-coller plusieurs lignes d’un seul coup.

---

1.4.4. Gestion des versions de transcription

Un document peut être associé simultanément à plusieurs versions de transcription. Chaque version possède un nom. Il en existe toujours une par défaut, appelée “manual”. Une nouvelle version est créée dès qu’un modèle de transcription est appliqué aux documents. La version est alors nommée d’après le modèle utilisé.

L’affichage de la liste des versions de transcription disponibles se fait depuis l’onglet “Edit”. En haut, au centre de la fenêtre, un menu déroulant permet de changer la version du texte affiché. 

Attention, même lorsque un modèle de transcription n’est appliqué qu’à une partie des images contenues dans un document, l’ensemble des document-parts sera désormais associé à la nouvelle version de transcription. Cela signifie que, même si l’affichage se fait au niveau du document-part, la création ou la suppression d’une version de transcription impacte l’ensemble du document.

Pour supprimer une version de transcription, cliquer sur le bouton “Transcription Management” à côté du menu déroulant. Le bouton “Delete” supprimera la version concernée de manière irréversible pour l’ensemble des pages du document.

---

1.4.5. Comparer les transcriptions

Il est possible de comparer plusieurs versions de transcription. Pour cela, activer les versions souhaitées depuis l’onglet “Transcription Management”, puis cliquer sur n’importe quelle ligne du document dans le volet de transcription.

Les portions en rouge indiquent les caractères supprimés, celles en vert les caractères ajoutés.

 

---

1.4.6. Aparté sur l’articulation des baselines, des polygones et des transcriptions

La baseline constitue l’élément central du stockage des informations dans la base de données d’eScriptorium. Ainsi :

• Il est possible de modifier une baseline (supprimer/déplacer/ajouter des points) sans que cela n’impacte la transcription ;
• C’est toujours à partir de la baseline qu’est calculé le polygone, y compris lors de l’entraînement
• Il est possible de modifier le polygone manuellement (déconseillé) sans que cela n’impacte la transcription.

Durant l’entraînement des modèles Kraken, la réinitialisation du calcul des polygones peut être activée : l’utilisateur a donc intérêt à peu intervenir sur les polygones et à s’assurer au contraire que les baselines sont tracées de telles sorte que les polygones générés automatiquement sont corrects. Par ailleurs, lorsque l’on saisit manuellement des données de vérité de terrain, on veillera généralement à ne transcrire que ce qui se trouve à l’intérieur du polygone.

---

1.4.7. Modifier l’ordre des segments

L’ordre de lecture des segments est calculé automatiquement. On peut afficher le numéro d’ordre de chaque segment depuis le volet “Segmentation” en cliquant sur “Toggle ordering display (L)” ou depuis le volet “Text” où les lignes sont affichées en suivant l’ordre de lecture.

Il est possible de modifier cet ordre depuis le volet “Text” en cliquant que “Toggle sorting mode”. Un simple glisser-déposer des lignes suffit ensuite à réaliser la modification.

Attention, il est conseillé de s’assurer de la qualité de la segmentation avant de changer l’ordre des lignes car ajouter ou supprimer des lignes relance systématique le calcul de cet ordre, écrasant au passage les modifications manuelles.

---

1.4.8. Annotation sémantique

Il est possible d’associer des labels aux segments et aux régions en suivant une ontologie pré-définie par l’utilisateur depuis l’onglet “Description”. Il existe des labels par défaut, mais il est possible d’en ajouter à l’aide du champs de saisie (cliquer sur “+” puis “Update” pour ajouter le nouveau label à la liste) ou d’en supprimer (décocher la case devant le label puis cliquer sur “Update”).

Depuis le volet “Segmentation”, sélectionner une zone ou un segment, puis cliquer sur “Set the type on all selected lines/regions (T)” et choisissez le label approprié. La couleur de la zone ou de la ligne change.

Il est possible d’appliquer un label à plusieurs régions ou segments en une seule fois : il suffit d’en sélectionner plusieurs (Ctrl + cliquer-glisser ou maintenir Ctrl enfoncé et cliquer les segments/régions visées).

Il est possible d’adopter une terminologie standardisé en s’appuyant par exemple sur le cadre proposé par SegmOnto.

---

1.4.9. Clavier virtuel

Un clavier virtuel est accessible depuis l’interface de saisie des transcriptions. Pour l’activer, cliquer sur l’icône “Toggle Virtual Keyboard for the document” puis cliquer dans la zone de saisie.

Le clavier virtuel permet de pré-définir un ensemble de raccourcis claviers et de boutons virtuel pour faciliter la saisie de caractères spéciaux fréquents. Le bouton “Manage Keyboard” permet de gérer ce paramétrage, voire d’importer une configuration sous la forme d’un fichier JSON ou d’un lien vers un fichier JSON.

---

1.5. Importer des annotations

1.5.1. Importer des annotations structurées en XML

Il est possible d’importer des segments et/ou une transcription générés en dehors d’eScriptorium. Pour ce faire, dans l’onglet “Images”, cliquer sur l’option “Import/Transcription (XML)”.

Un formulaire apparaît vous permettant de spécifier un nom permettant d’identifier la version importer et de charger le fichier à importer. Celui-ci peut être un fichier XML ALTO, un fichier XML PAGE ou bien un ZIP contenant plusieurs fichiers XML ALTO ou PAGE.

Il n’est pas nécessaire de sélectionner au préalable quelles document-parts sont concernées par l’import : le lien se fait automatiquement en fonction des informations contenues dans les fichiers XML.

Attention, après l’import de segments générés sans Kraken/eScriptorium, il est indispensable de réinitialiser les polygones (masks) avant d’utiliser ces documents pour entraîner un modèle de transcription. Une autre solution consiste à utiliser Layout Segmentation Simplifier (LSS) avant d’importer les données dans eScriptorium.

---

1.5.2. Importer des annotations à partir d’un texte brut

Il est possible d’importer manuellement une transcription à partir d’une version en texte brut en utilisant le volet “Text” de l’onglet “Edit”. Chaque saut de ligne indique alors le passage à un nouveau segment. Il faut donc veiller à ce que l’ordre de lecture des lignes corresponde.

---

1.6. Annoter automatiquement les documents

1.6.1. Instructions

L’annotation automatique des documents est géré depuis l’onglet “Images”.

• Sélectionner les images à annoter ;
• Cliquer sur “Segment” (pour la détection des lignes de base, des polygones et/ou des zones) ou sur “Transcribe” (pour la transcription) ;
• Un formulaire s’affiche : il permet de charger un modèle Kraken ou d’utiliser un modèle déjà disponible dans eScriptorium et de, pour la segmentation, de paramétrer l’annotation.

---

1.6.2. Paramétrage de la segmentation

• “Segmentation steps” permet de gérer quel niveau de segmentation est réalisée :
  • “Line and Regions” conduit à la génération des zones (sous réserve que le modèle employé ait été entraîné pour cela), des lignes de bases et des polygones associés.
  • “Line Baselines and Masks” conduit à la génération des lignes de bases et des polygones associés.
  • “Only line Masks” ne nécessite pas de charger un modèle ; cette option permet de réinitialiser à la volée le calcul des polygones associés aux lignes de bases déjà présentes sur les images. 
  • “Regions” permet de conserver intactes les lignes de bases et les polygones déjà présents sur les images et de ne générer que les zones.

• “Text direction” permet d’indiquer le sens de lecture des lignes.

---

1.7. Entraîner des modèles

1.7.1. Lancer un entraînement

L’entraînement de modèles Kraken est lancé depuis un document dans l’onglet “Images”. Son statut d’exécution est suivi depuis l’onglet “Models” du document ou bien depuis la page “My Models”. L’onglet “Models” est inactif tant qu’aucun modèle autre que le modèle par défaut n’est associé au document.

L’accès aux fonctionnalités d’entraînement peut être soumis à autorisation. Il est géré depuis l’interface d’administration.

Pour entraîner un modèle, toutes les images/annotations mobilisées doivent se trouver dans le même document.

• Sélectionner les document-parts contenant la vérité de terrain ;
• Cliquer sur “Train” puis sélectionner le type de modèle à entraîner : “Segmenter” pour un modèle de segmentation, “Recognizer” pour un modèle de transcription ;
• Remplir le formulaire puis cliquer sur “Train” ;
• La tâche d’entraînement est lancée, il faut parfois attendre avant que cela ne s’affiche.

Lorsque l’entraînement est terminé, l’utilisateur reçoit une notification et peut accéder au modèle final depuis l’onglet “Models” ou depuis la page “My Models”. Il est alors possible de télécharger le modèle, de le partager avec d’autres utilisateurs ou bien de l’utiliser sur le document.

---

1.7.2. Importer un modèle

L’import de modèle se fait depuis la page “My Models”. Le format de fichier doit être compatible avec le moteur d’OCR/HTR utilisé en arrière-plan, Kraken dans la configuration par défaut. Un fichier compatible avec l’import est donc un fichier “.mlmodel”. Attention à la version de Kraken utilisée pour entraîner le modèle : par exemple, un modèle produit avec Kraken 2 ne fonctionnera pas avec Kraken 3.

Sur la page “My Models”, cliquer sur “Upload a model” pour afficher un formulaire à partir duquel charger le fichier depuis le système local et modifier si nécessaire le nom du fichier. Le reste des métadonnées est extrait automatiquement.

---

1.7.3. Affiner un modèle ou partir de zéro ?

Le formulaire de paramétrage des entraînements permet de choisir :

• S’il l’on souhaite partir de zéro (pour cela indiquer simplement le nom à donner au nouveau modèle qui sera créé) ;
• Ou si l’on souhaite affiner un modèle (celui-ci peut être chargé depuis le gestionnaire de fichiers, ou bien être déjà présent dans la liste des modèles associés au document courant).

---

1.8. Exporter les annotations

L’export des annotations est réalisé depuis l’onglet “Images”.

• Sélectionner les document-parts concernées ;
• Cliquer sur “Export” puis remplir le formulaire :
  • Spécifier la version de la transcription à exporter ;
  • Spécifier le format d’export (“Alto” pour du XML ALTO, “Pagexml” pour du XML PAGE, ou “Text” pour du plain texte) ;
  • Cocher “Include Images” si vous souhaitez également exporter les images ;
• Clicher sur Export et enregistrer le fichier ZIP généré.

1.9. Ajouter des étiquettes sur les documents

L’ajout d’étiquettes sur les documents permet d’activer la fonction de filtre et de faciliter l’exploration des documents rassemblés au sein d’un projet.

L’ajout d’étiquettes se fait depuis la liste des documents :

• pour un traitement simultané sur plusieurs documents, en cliquant sur le bouton “Manage tags” en haut à droite, après avoir sélectionné les documents concernés;
• pour le traitement d’un seul document en cliquant sur le bouton “Manage tags” directement dans la liste.

Pour créer une nouvelle étiquette, saisir son nom dans le champ de saisi, choisir la couleur désirée, puis cliquer sur “Save”.

Pour ajouter à un document ou retirer de celui-ci une étiquette existante, cliquer sur “Manage tags” puis sur le menu déroulant : les étiquettes actives pour le document doivent être cochées. Un document peut posséder plusieurs étiquettes en même temps.

Pour filtrer la liste des documents en fonction des étiquettes, il suffit d’activer l’étiquette dans la section “filters”. Il est possible de cocher plusieurs valeurs. Seuls les documents possédant l’ensemble des étiquettes choisies seront affichés.

 

---

2. Gérer une campagne d’annotation collaborative

2.1. Créer un groupe d’utilisateurs (admin)

Il est possible de créer des groupes d’utilisateurs depuis le tableau de bord de l’administrateur (à condition de posséder les droits associés). Ces groupes permettent de définir des équipes de travail ou d’attribuer certains droits à un ensemble d’utilisateurs.

Il sera bientôt possible pour un utilisateur disposant des droits suffisants, de créer une équipe et d’y inviter d’autres utilisateurs.

---

2.2. Partager un projet ou un document avec un autre utilisateur ou avec un groupe

Un utilisateur peut partager tout un projet ou bien un seul document avec plusieurs utilisateurs, y compris en dehors de/des groupe(s) au(x)quel(s) il appartient.

Pour partager un projet:

• Cliquer sur le projet dans la liste des projets puis sur le bouton “Share this Project”
• Entrer le nom des utilisateurs à avec qui partager le projet ou bien cocher son nom dans la liste qui s’affiche
• Pour confirmer, cliquer sur “Share”

Lorsqu’un projet est partagé avec des utilisateurs, l’ensemble des documents qu’il contient est accessible aux utilisateurs concernés.

Pour partager un document :

• Cliquer sur le projet et, depuis l’onglet “Description”, cliquer sur le bouton “Share”
• Entrer le nom de l’utilisateur avec qui partager le document, ou cocher son nom dans la liste qui s’affiche
• Pour confirmer, cliquer sur “Share”

Lorsqu’un document est partagé individuellement, l’utilisateur concerné par le partage voit le projet dans sa liste des projets, mais ne peux voir que le document partagé avec lui.

---

2.3. Partager un modèle avec un autre utilisateur ou avec un groupe

La gestion du partage des modèles se fait depuis la page “My Models”. Pour le modèle concerné, cliquer sur le bouton “share model” puis ajouter autant d’utilisateurs ou de groupe que souhaité. Pour enregistrer un nouveau partage, après avoir sélectionner le nom d’utilisateur ou le groupe, cliquer sur le bouton “Add right” (+ vert).

Pour partager un modèle avec un utilisateur qui n’est pas branché sur la même instance ou travaillant en local, il suffit de télécharger le fichier depuis la page “My Models” et de le partager via n’importe quel système d’échange.