Copies/docs/guide_utilisateur_gui.md

# Copienator — guide de l’interface graphique

Ce guide suit les intitulés et l’ordre des étapes de l’interface. Un **label** est l’identifiant d’une question ; une **copie** correspond au travail d’un élève.

## Prendre en main l’interface

- Choisissez le dossier **Évaluation** avec **Parcourir…**, puis **Charger**.
- Suivez la liste de gauche. Avant **Exécuter**, vérifiez le **Mode**, la **Cible** et les prérequis signalés. La cible est normalement toute l’évaluation ; choisir un fichier permet, lorsque proposé, de ne traiter qu’une copie. Les aides **ⓘ** précisent les options.
- N’activez une option d’écrasement que pour remplacer volontairement les résultats précédents.

## Préparation et énoncé

### Vérifier les fichiers d’entrée

**Effet :** vérifie la présence des documents nécessaires à l’évaluation.

Placez les scans des copies, `enonce.pdf`, `enonce.tex`, `correction.tex` et la liste d’élèves `names` dans le dossier d’évaluation (`names` peut aussi être à la racine du projet).

Pour un dossier nommé `A`, les noms `A.pdf`, `A.tex`, `Ac.tex` sont également acceptés. Vérifiez que qu’aucun PDF étranger ne sera pris pour une copie.

Après un ajout, cliquez sur **Recharger — vérifier à nouveau**.

### Analyser l’énoncé

**Effet :** extrait les labels des questions, les contenus des questions, contextes et solutions de vos fichiers, puis prépare des regroupement initiaux de questions, ainsi que des barèmes.

Choisissez **Analyse avec Gemini**.

Éventuellement traitez les alertes **Problèmes LaTeX…** avant de poursuivre.

**Ignorer le cache** recommence l’analyse Gemini : à réserver à une
analyse devenue incorrecte ou obsolète.

### Relire les barèmes — facultatif

**Effet :** permet de vérifier et d’ajuster les instructions qui guideront la correction.

Ouvrez les barèmes dans `Persp`. Vérifiez les réponses acceptables, les raisonnements alternatifs et les exigences de justification ; corrigez les consignes trop sévères, ambiguës ou erronées. Enregistrez vos modifications avant de marquer l’étape terminée.

## Prétraitement des copies

### Retourner toutes les copies — facultatif

**Effet :** applique une rotation de 180° à tous les scans de copies du dossier.

Exécutez seulement si toutes les copies sont à l’envers.

### Renommer les PDF en CopieXX.pdf

**Effet :** attribue un numéro aux copies selon l’ordre de leurs noms de fichiers.

Vérifiez qu’un PDF correspond à une copie et que le dossier ne contient pas de documents parasites. Exécutez puis contrôlez le nombre de copies.

### Séparer et réordonner les pages

**Effet :** Découpe les scans A3 en pages A4 correctement ordonnées.

Examinez chaque page :
 - déplacer la coupure si jamais l'élève a dépassé d'une moitié de sa
   copie A3 sur l'autre.
 - Utiliser les raccourcis donnés pour retirer les pages vides.

Suivez les raccourcis affichés dans la fenêtre, qui peuvent varier
selon votre profil. Par défaut :

| Action                                                              | Touche          |
|---------------------------------------------------------------------|-----------------|
| Déplacer la séparation                                              | ← / →           |
| Garder les deux moitiés et avancer                                  | `s`             |
| Garder seulement la gauche / la droite                              | `q` / `d`       |
| Garder la page entière, pour une page déjà A4                       | `f`             |
| Écarter une page réellement vide                                    | `z`             |
| Retourner la page / toutes les pages du fichier / tous les fichiers | `r` / `R` / `,` |
| Envoyer la page en fin / inverser l’ordre des pages                 | `a` / `i`       |
| Recommencer le fichier / revenir au fichier précédent               | `T` / `P`       |
| Ouvrir l’outil de réorganisation, s’il est disponible               | `A`             |

**Copies signalées uniquement** limite le traitement aux copies
précédemment signalées (par une étape suivante).

### Rogner les zones vides — facultatif

**Effet :** retire les marges vides en haut et en bas des pages, avec
sauvegarde des versions précédentes.

Ce n'est pas particulièrement utile, et il pourrait y avoir des faux positifs.

### Découper une partie à gauche pour détection des labels

**Effet :** Prépare des images qui seront utilisées pour repérés les numéros de questions.

Éventuellement, cocher `Toujours utiliser la page entière`. Pour rendre
cette étape non interactive, cocher aussi `et ne pas vérifier visuellement`.
Ce mode est plus cher : sans avoir vérifié, Astra estime que le coût
passerait de 0,50€ à 2€.

Sans quoi, pour chaque copie, il faut cadrer la bande pour qu'elle
contienne bien tous les labels :

**←/→** la déplacent, **↑/↓** l’élargissent ou la réduisent ; **Entrée** valide.

Si les labels sont dispersés, utilisez **1** pour utiliser les pages entières pour cette copie.

Cette vérification visuelle permet toutefois de repérer des copies à
l'envers, ou dont les pages sont dans le mauvais ordre. Utiliser **!**
pour signaler une copie problématique.

Vous pourrez alors relancer l'étape de réordonnement des copies avec
les copies signalées.

## Labels et regroupement

### Détecter les labels avec Gemini

**Effet :** reconnaît les identifiants de questions et leur position dans les copies.

### Vérifier visuellement les labels

**Effet :** valide ou corrige les repères qui serviront à découper les réponses.

Vérifiez visuellement les labels.
 - Quand un label est manquant, le suivant est affiché en jaune.
 - Quand un label n'est pas dans le bon ordre, il est affiché en rouge.

Pour faire des modifications : **e** ouvre le fichier .json à modifier à la main
 - Vous pouvez retirer un label, ou le modifier.
 - Pour ajouter un label manqué :
   - cliquer sur l'image là où est le label, ce qui va copie les coordonnées correspondantes
   - puis les coller dans le fichier .json, et renseignez le label.

**Entrée** pour valider, **i** pour ouvrir l'énoncer, **o** pour
ouvrir la copie d'origine, **p** pour revenir en arrière.

### Découper les réponses par question

**Effet :** crée un document de réponse pour chaque question repérée
dans chaque copie.

### Rogner le bas des réponses — facultatif

**Effet :** enlève les grands espaces vides sous les réponses découpées, avec sauvegarde des originaux.

### Regrouper les réponses

**Effet :** regroupe les réponses par label pour préparer la correction.

## Correction

### Lancer ou intégrer la correction

**Effet :** obtient les corrections automatiques ou intègre des résultats préparés en différé.

Il faut choisir un des modes suivants.

Initialement, vous voulez
 - soit le mode **Correction immédiate**, qui
   va faire les requêtes de corrections en live, ce qui peut prendre de
   l'ordre de 30min ou 1h. (Si elle est interrompue, il suffit de la
   relancer pour qu'elle reprenne d'où elle en était).
 - soit le mode **Préparer toutes les requêtes batch** : au lieu de
   faire des requêtes en live, les requêtes sont batchées et toutes
   envoyée à Gemini, qui les traitera en théorie au pire sous 24h, en
   pratique dans l'heure. L'avantage est que le coût est divisé par
   deux.

Le mode **Batch à partir d'un label** est un mode hybride inutile, où
certaines requêtes sont faites en live, et d'autres sont batch.

| Mode                                   | À faire et à vérifier                                                                                                     |
|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| **Correction immédiate**               | Lancez et surveillez le nombre de groupes traités.                                                                        |
| **Préparer toutes les requêtes batch** | Préparez les demandes, puis passez à **Envoyer les batchs** : la préparation seule ne les envoie pas.                     |
| **Batch à partir d’un label**          | Indiquez le premier label différé ; les précédents sont corrigés immédiatement. Suivez ensuite le circuit batch.          |
| **Recorrection depuis refaire.json**   | Relancez les questions sélectionnées, notamment après résolution des conflits. Vérifiez la sélection avant de lancer.     |
| **Intégrer les résultats batch**       | Utilisez après leur récupération ; attendez la fin de l’intégration avant de générer les annotations.                     |
| **Réinitialiser les corrections**      | Réservez ce mode à un recommencement volontaire ; lisez la confirmation et sauvegardez les corrections utiles auparavant. |

Laissez **Écraser les corrections existantes** décoché pour reprendre
sans tout recalculer. Une **Limite d’appels Pro** peut limiter le
travail de cette exécution : vérifiez ce qui reste à traiter.
**Interrompre** bloque les nouveaux appels, attend ceux en cours et
sauvegarde leurs résultats ; relancez pour terminer les validations
restantes. Examinez les erreurs et les conflits proposés, puis relisez
les résultats sur les copies annotées.

### Envoyer les batchs — si correction différée

**Effet :** transmet à Gemini les demandes de correction préparées.

Exécutez après la préparation batch et vérifiez que les envois
aboutissent. En cas d’envoi partiel, reprenez cette étape et consultez
l’état des jobs avant de poursuivre.

### Consulter l’état des batchs — si correction différée

**Effet :** vérifie si tous les traitements différés ont réussi et sont récupérables.

Cliquez sur **Exécuter**, ou sur **Vérifier toutes les 5 minutes** en
gardant Copienator ouvert. Attendez que tous les résultats soient
prêts ; une notification l’indique. Un job en attente ou en échec ne
vaut pas une correction terminée : lisez son état au lieu de forcer le
passage à la suite.

### Récupérer les résultats batch — si correction différée

**Effet :** télécharge et rassemble les réponses des traitements terminés.

Exécutez lorsque tous les résultats sont disponibles. Vérifiez
l’absence de récupération manquante ; l’interface revient ensuite à
**Lancer ou intégrer la correction**, en mode **Intégrer les résultats
batch**. Exécutez cette intégration.

### Résoudre les conflits manuels — si des conflits sont signalés

**Effet :** corrige les attributions ambiguës de réponses avant leur recorrection.

Lors de la correction, certains labels seront inévitablement érronés
(l'étudiant a mis le mauvais label, ou n'a pas mis de label, ou à
traiter une question à droite d'une autre).

L'étape de correction détecte ces problèmes (enfin, certains…), et
essaie de les corriger automatiquement. Les cas non automatiques
(«conflits») sont ceux où elle détecte un contenu correspondant à un
label `B`, alors qu'il y a déjà une image pour le label `B`

Cette étape permet de résoudre manuellement les conflits : on vous
donne une image initiale, avec un label d'origine `A` dont le contenu
est bizarre et correspond, éventuellement partiellement, à un label
`B` cible, qui a déjà une image.

On vous demande de choisir ce qu'il doit advenir de l'image d'origine.

Ouvrez les PDF source et cible proposés et comparez-les à l’énoncé.

Cliquez sur **Ouvrir dans un éditeur de texte** pour ajuster les
instructions. Leur forme est `Copie01 Label source OP Label cible|`.
Choisissez l’action d’après le contenu réel :

| Opérateur   | Résultat                                                                        |
|-------------|---------------------------------------------------------------------------------|
| `->` / `x>` | Ajouter la source à la cible ; conserver / archiver la source pour le label `A` |
| `-x` / `xx` | Remplacer la cible par la source ; conserver / archiver la source.              |
| `ss`        | Garder les deux réponses séparées (= ne rien faire)                             |
| `sx` / `xs` | Garder la source / la cible et archiver l’autre.                                |

Pour une fusion, `Cible|` met la cible avant la source, `|Cible` fait l’inverse.

Une autre opération est **Cut** : dans les cas où vous voulez découper
l'image d'origine en deux. Utiliser le bouton **Cut** pour choisir la
coupure, et quelle moitié doit être gardée. L'interface graphique vous
fournira alors une instruction texte à copier et à mettre dans le
fichier texte.

Enregistrez le fichier texte, éventuellement le **Recharger**, puis
**Exécuter**.

Retirer une instruction signifie accepter les PDF sans changement ;
exécutez même si vous avez retiré toutes les lignes.

Après succès, l’interface revient à l'étape de correction (avec le
mode **recorrection à partir de refaire.json** ) : lancez-la.

### Nettoyer la correction

**Effet :** Essaye de réparer des problèmes d'encodages courant dans les réponses de Gemini.

## Annotations et tablette

### Générer les copies annotées

**Effet :** Génère des versions des copies, annotées avec la correction Gemini.

Choisir le mode :
 - **Annotations simples (Anot)** Annote chaque copie en des documents qu
 - **Annotations avec cases (Bnot)** Annote chaque copie, avec des
   cases qui vous permettrons, en les cochant, de supprimer certains
   commentaires, ou de modifier la note
 - **Annotations groupées (BGnot)** Génère des documents pdf, où les
   réponses annotées sont regroupées par label (ou plutôt par groupes
   de label).

   Les groupes de label sont ceux qui ont été générés dans l'analyse
   de l'énoncé. Il est possible de les modifier à la main ici.

**Écraser les sorties** remplace les documents existants. **Mode
refaire** ne concerne qu’une reprise sélectionnée ; utilisez de
préférence le parcours dédié décrit plus bas.

### Exporter — facultatif

**Effet :** place les documents générés dans le dossier de transfert configuré.

Choisissez le même **Dossier d’annotations** qu’à la génération.

### Annoter les PDF sur la tablette

**Effet :** recueille votre validation pédagogique, vos changements de scores et vos annotations manuscrites.

Relisez chaque réponse avec sa correction. Dans les modes avec cases, cochez une seule note par question pour la remplacer ; laissez les notes correctes inchangées.

Une case près d’un commentaire le supprime, celle sur un rectangle
supprime ce rectangle ; **clr** supprime tous les commentaires et
rectangles de la question. Ajoutez vos propres remarques sans écrire
accidentellement dans les cases. Gardez les dimensions et l’ordre des
pages pour permettre la lecture du retour.

Avec le circuit d’export/import, renvoyez les fichiers sous **leur nom
exporté** (groupe ou `CopieXX.pdf`), dans le dossier d’import prévu.

### Importer les annotations manuscrites

**Effet :** rattache les fichiers modifiés manuellement aux documents de l’évaluation.

Vérifiez l’évaluation, le dossier d’import et le **Dossier
d’annotations**, puis exécutez. Écartez les anciens retours et ceux
d’autres évaluations pour éviter une mauvaise association.

## Finalisation

### Lire les annotations manuscrites

**Effet :** applique les cases cochées et les ajouts manuscrits pour reconstruire les copies et leurs scores.

Choisissez **Lecture Bnot** ou **Lecture BGnot** conformément à la
génération. Pour le parcours `Anot`, passez directement à
l’attribution des noms. Après lecture, ouvrez les résultats et
vérifiez notes modifiées, suppressions de commentaires et remarques
manuscrites.

Si les options `answers` sont présentes, choisissez les compléments
souhaités dans les réponses individuelles : contexte, énoncé,
correction.

En mode groupé, le PDF final peut omettre une réponse parfaite sans
commentaire conservé ni annotation manuscrite significative ; son
score reste enregistré. Le PDF peut même être absent si aucune réponse
ne reste à y inclure. Contrôlez donc aussi les scores et l’image
complète, sans assimiler automatiquement une omission à une perte de
réponse.

Le mode **Régénérer avec les nouveaux énoncés/corrigés et les
score.json** sert à mettre à jour les scores sur les images finales à
partir d'une modification manuelle des fichiers `score.json`.


### Attribuer les noms et préparer A Rendre

**Effet :** rassemble les résultats de chaque élève dans le dossier `A Rendre`.

Choisissez le dossier d’annotations utilisé et exécutez. Dans
**Vérification des noms**, traitez tous les noms `Unknown` et les
doublons : **Ouvrir l’originale**, saisir le nom, puis **Renommer**.

**Mettre à jour uniquement les images de answers** ne rafraîchit que
les réponses individuelles des élèves existants.

## Refaire une partie de l’évaluation

Utilisez ce parcours après avoir terminé le passage principal. Conservez ses annotations : elles servent à préserver les questions non sélectionnées. Ne démarrez **Nouvelle reprise** qu’après avoir importé et fusionné la reprise courante ; **Refaire la même sélection** permet de repartir avec les mêmes copies et questions.

### Choisir les copies et les questions

**Effet :** enregistre les réponses à reprendre et leur mode de présentation.

Choisissez une copie et une question, puis **+ Ajouter** ; répétez selon les besoins. **Toute la copie** sélectionne toutes ses questions ; **Toutes les copies** applique le choix à la classe. Vérifiez le tableau, retirez les erreurs, choisissez le **Passage principal** correct et la présentation **PDF à vérifier**, puis **Enregistrer la sélection**.

### Reprendre le découpage — facultatif

**Effet :** permet de corriger les repères des copies sélectionnées.

Reprenez les contrôles de la vérification visuelle des labels. Validez les images modifiées ; chaque copie sélectionnée s’ouvre à son tour, et fermer sa fenêtre passe à la suivante. Ignorez si les découpages sont déjà corrects.

### Redécouper les réponses — facultatif

**Effet :** reconstruit les réponses des copies sélectionnées à partir des repères corrigés.

Exécutez après toute modification du découpage. Ouvrez les réponses concernées et vérifiez leurs limites ; en présence de résolutions manuelles, contrôlez particulièrement les versions `_new` et `_old`. Ignorez si le découpage n’a pas changé.

### Refaire la correction — facultatif

**Effet :** relance la correction automatique des seules questions sélectionnées.

Vérifiez la sélection puis exécutez. Contrôlez les erreurs et les résultats proposés. Ignorez si vous souhaitez uniquement modifier les notes ou commentaires à la main lors de la relecture.

### Préparer les copies à vérifier

**Effet :** génère dans `BRnot` les documents avec cases du passage de reprise.

Exécutez puis vérifiez que seules les réponses voulues sont présentes, avec la présentation choisie. Cette génération remplace les documents de reprise concernés : ne la relancez pas sur une relecture manuscrite à conserver.

### Exporter vers la tablette — facultatif

**Effet :** transfère les documents du passage de reprise vers le dossier d’export.

Écartez les anciens exports, exécutez et contrôlez les documents transférés. Conservez leur nom complet, y compris le préfixe de reprise s’il est présent : il permet d’associer les retours au bon passage. Ignorez si vous relisez directement les fichiers locaux.

### Vérifier sur la tablette

**Effet :** recueille la validation et les modifications des réponses reprises.

Appliquez les mêmes règles de cases et d’écriture que pour le premier passage. Retournez tous les documents, même sans changement, sous leur nom exporté dans le dossier d’import ; retirez les anciens retours. En travail local, placez les `Concat_annotated.pdf` dans les sous-dossiers de cette reprise.

### Importer les copies vérifiées — facultatif

**Effet :** récupère les annotations du passage de reprise courant.

Exécutez et vérifiez que tous les retours attendus sont acceptés. Les fichiers portant le préfixe d’une autre reprise sont ignorés. Ignorez cette étape seulement si les `Concat_annotated.pdf` sont déjà au bon endroit.

### Mettre à jour les copies finales

**Effet :** fusionne les réponses refaites avec les autres réponses conservées du passage principal.

Vérifiez le **Passage principal**, puis exécutez. Contrôlez une question refaite et une question conservée pour chaque copie concernée ; résolvez tout retour manquant avant de poursuivre. Relancez ensuite **Attribuer les noms et préparer A Rendre** et vérifiez les livrables mis à jour avant de les remettre aux élèves.

## Archivage

### Nettoyer les fichiers intermédiaires — facultatif

**Effet :** supprime définitivement les fichiers de travail et la progression de l’interface en conservant les livrables prévus.

Attendez la fin des relectures et reprises. Vérifiez les résultats de tous les élèves dans `A Rendre` et sauvegardez l’évaluation si vous voulez pouvoir reprendre le travail. Choisissez d’abord **Prévisualiser sans supprimer**, puis examinez la liste. Ne lancez **Nettoyage définitif** qu’une fois certain de ne plus avoir besoin des intermédiaires : les PDF traités, textes de l’énoncé, corrections, journaux et livrables de `A Rendre` sont conservés, mais une reprise exigera de régénérer les données supprimées.