Prendre en main eScriptorium

Documents

Pré-requis

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

Sommaire


1. Pas-à-pas

1.1. Connexion à eScriptorium

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

Aperçu de l'interface de connexion, où l'on entre son login et son mot de passe avant de cliquer sur "login".
Formulaire de connexion

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

Aperçu du tableau de bord, vide
Aperçu du tableau de bord, vide

1.2. Créer un nouveau document

1.2.1. Point terminologie

  • 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 document, cliquer sur le bouton “Create new” ; une nouvelle page s’affiche ainsi qu’un formulaire de saisie.

Onglet de description d'un document
Onglet de “description” d’un document – où l’on renseigne les métadonnées.

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”.

Accéder à l’interface d’édition des documents depuis le tableau de bord.

Pour revenir à ce formulaire depuis le tableau de bord, cliquer sur l’icône “Edit” en face du document.

 

1.3. Charger des images

1.3.1. Accéder à l’interface

L’interface “Images” permet de gérer la plupart des tâches liées au traitement automatique des images et aux imports/exports.

Pour accéder à l’interface de chargement des images, cliquer sur l’onglet “Images”.

Navigation entre les onglets “Description” et “Images”.

Il existe plusieurs moyens d’importer des images sur la plateforme.


1.3.2. Importer des fichiers locaux

Charger simplement les fichiers à l’aide d’un glisser-déposer ou cliquer dans la zone pour ouvrir l’explorateur de fichiers.

Attention, il faut attendre que toutes les images soient chargées avant de rafraîchir la page !

Démonstration de l’import d’images depuis le système de fichiers local.

1.3.3. Importer des images depuis un fichier PDF

Cliquer sur l’option Import/Images (PDF) puis charger un fichier PDF pour aspirer les images. Attention, seules les images sont importées, si le PDF contient une couche texte correspondant à la transcription, celle-ci n’est pas importée.

démonstration de l'import d'images issues d'un PDF
Démonstration de l’import d’images issues d’un PDF.

1.3.4. Utiliser un manifeste IIIF

Cliquer sur l’option Import/Images (IIIF) puis entrer l’url d’un manifeste IIIF. Toutes les images associées au manifeste sont alors copiées localement, de même que les métadonnées, qui sont visibles dans l’onglet “Description”.

Exemple : https://gallica.bnf.fr/iiif/ark:/12148/btv1b53026595r/manifest.json
démonstration de l'import d'images via IIIF
Démonstration de l’import d’images par le biais d’un manifeste IIIF.

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é 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.
Activation et désactivation des volets d'édition
Activation et désactivation des volets d’édition.

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).

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.

Éditer manuellement la transcription depuis le volet “Transcription”.

1.4.4. 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 à ne transcrire que ce qui se trouve à l’intérieur du polygone.


1.4.5. 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.

Éditer l’ordre des segments depuis le volet “Text”.

1.4.6. Annotation sémantique

Il est possible d’associer des étiquettes (ou tags) aux segments et aux régions en suivant une ontologie pré-définie par l’utilisateur depuis l’onglet “Description”. Il existe des tags par défaut, mais il est possible d’en ajouter à l’aide du champs de saisie (cliquer sur “+” puis “Update” pour ajouter le nouveau tag à la liste) ou d’en supprimer (décocher la case devant le tag 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 tag approprié. La couleur de la zone ou de la ligne change.

Il est possible d’appliquer un tag à 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).

 

Ajouter des éléments dans l'ontologie depuis le volet "Description" puis appliquer les tags aux segments/régions depuis le volet "Edit".
Ajouter des éléments dans l’ontologie depuis le volet “Description” puis appliquer les tags aux segments/régions depuis le volet “Edit”.

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.

Formulaire de paramétrage des imports de segmentation et/ou transcription
Formulaire de paramétrage des imports de segmentation et/ou transcription

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.


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.
Aperçu des options disponibles dans le formulaire de paramétrage de la segmentation automatique.

1.7. Entraîner des modèles

1.7.1. Lancer un entraînement

L’entraînement de modèles Kraken est lancé depuis l’onglet “Images” ; il est suivi depuis l’onglet “Models” (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”. Il est alors possible de télécharger le modèle ou de l’utiliser sur le document.


1.7.2. 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).

Attention : dans la version 0.6.9, la modification du nom du modèle à entraîner n’est prise en compte que dans le cas d’un modèle partant de zéro. Afin de ne pas écraser un modèle déjà existant, il faut veiller à télécharger le modèle localement, le renommer d’après le nom souhaite pour le nouveau modèle, puis le charger dans eScriptorium depuis le formulaire.


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é.

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 documents avec un autre utilisateur ou avec un groupe

Un utilisateur peut partager un document avec plusieurs utilisateurs, y compris en dehors de/des groupe(s) au(x)quel(s) il appartient. 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”
Partager un document avec un groupe ou un utilisateur.

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

Un modèle est associé à un document et non à un utilisateur. Pour partager un modèle avec un autre utilisateur, il existe deux possibilités :

  • Télécharger le modèle depuis l’onglet “Models” et envoyer le modèle par un autre système d’échange (e-mails, etc) ;
  • Partager avec l’utilisateur le document auquel le modèle est associé. C’est alors à l’autre utilisateur de télécharger le modèle puis de le charger dans le document où il souhaite l’appliquer.