AUTO-MULTIPLE-CHOI(1)

📦
version 1.7.0 · 3 versions
, in arch rolling, debian trixie, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 AUTO-MULTIPLE-CHOI(1) 💖

okay bestie, welcome to auto-multiple-choice-annotate — the glow-up era of your graded answer sheets ✨ (and yeah, she lives in the Auto Multiple Choice family, manual section 1, so now you know 🫶).

🌸 NAME 🌸

auto-multiple-choice-annotate — annotating completed answer sheets after marking, for AMC multiple choice exams. it's giving "your paper but make it ✨corrected✨".

🎀 SYNOPSIS 🎀

auto-multiple-choice annotate --project project-dir
                     --names-file students.csv [annotation options...]

💅 DESCRIPTION 💅

The auto-multiple-choice annotate command annotates your paper scans with scores for all questions, plus the global score and the mark, and spits out PDF files (either one for each student, or one single file — your call, diva).

✨ General options ✨

  • --project project-dir — sets the project name or directory. the main character of options ngl.
  • --data project-data-dir — tells her where the data files live (default value is project-dir/data).
  • --pdf-dir pdf-dir — sets the project pdf directory, i.e. where to output the annotated scans (default value is project-dir/cr/corrections/pdf).
  • --names-file students-list.csv — sets the students list file name.
  • --names-encoding encoding — picks an encoding for the file students-list.csv (default is utf-8).
  • --association-key key — sets the key (that's a column name in the students list file) used for association. the default value is stored in the database from the value actually used for association, so lowkey this option should not be used 🙈.
  • --subject subject.pdf — sets the path to the PDF question file (default is project-dir/DOC-sujet.pdf).
  • --compose mode — use this one if you want to take pages from the subject when there's no boxes to be filled on them (like, question pages before the annotated answer sheet, iykyk). When mode equals 1, the pages are taken from the subject, are filled or not according to the student's answers (the same as on the answer sheet), and the same correction marks are drawn as on the answer sheet. When mode equals 2, the pages are taken from the corrected answer sheet (so the ticked answers are the correct ones), and no correction marks are drawn.
  • --corrected corrected.pdf — sets the path to the PDF corrected subject (default is project-dir/DOC-corrected.pdf). If not present, this file will be built using values from options --n-copies, --with, --filter and --filtered-source.
  • --darkness-threshold t — sets the darkness threshold. Default value is stored in the database from the value actually used for scoring, so this option should not be used 💀.
  • --darkness-threshold-up upper_t — sets the upper darkness threshold. Default value is stored in the database from the value actually used for scoring, so again this option should not be used.
  • --csv-build-name name-model — sets the model for building students names from the students list file. Default value is '(nom|surname) (prenom|name)', so the name gets built using the nom column content (or the surname column if nom doesn't exist), followed by the content of the prenom column (or the name column) — so the result should be OK for French or English simple CSV files 👑.
  • --id-file ids.txt — gives a filename where to find the ids of copies to annotate (one per line, either the student number if photocopy mode is off, or student:copy if the photocopy mode is on). If no file is given, then all copies will be annotated.
  • --debug file.log — gives a file to fill with debugging information.

🌈 PDF output options 🌈

  • --single-output — use this if you need all annotated copies in a single PDF file. Default behavior is to build one PDF file per student.
  • --sort s — sets the sort key (only useful when using --single-output). use:
    • l — to keep students in the same order as in the students list file.
    • m — to sort students according to their marks.
    • i — to sort students according to the copy id.
    • n — to sort students according to their names.
  • --filename-model model — sets a file name model for annotated PDFs. In this model, some sequences get substituted:
    • (ID) — is replaced by the student's name (see --csv-build-name).
    • (N) — is replaced by the student number.
    • (COL) — is replaced by the value of column COL in the students list for the current student.

The default value is '(N)-(ID).pdf'.

🦋 Source file options 🦋

These options are used when the --corrected path points to a non-existing file, so that this file can be rebuilt. slay.

🧚 Options for embedded scans 🧚

When present, scans are embedded in the annotated PDF file. The following options control the quality of the embedded scans, to reduce the annotated file size (bestie we love a small file).

  • --embedded-max-size maxsize — sets the maximal size for scans (in the format widthxheight, in pixels). Default value is the empty string, which means there is no maximum size. Scans that are larger will be reduced before being included in the annotated file.
  • --embedded-format format — sets the format for scans inclusion: jpeg or png.
  • --embedded-jpeg-quality quality — sets the JPEG quality (from 1 to 100) for jpeg embedded scans.

💖 Annotation options 💖

These options control what kind of annotations are being drawn ✏️.

  • --font-size fs — sets the font size, in points, for annotations.
  • --text-color color — text color for annotations. Default value is red.
  • --verdict header — sets the text header to be printed on each first page of the students copies. This text may contain CR characters for multi-line headers. Some sequences get substituted in it:
    • %S — is replaced by the student total score.
    • %M — is replaced by the maximum total score.
    • %s — is replaced by the student mark.
    • %m — is replaced by the maximum mark.
    • %(ID) — is replaced by the student's name.
    • %(COL) — is replaced by the value of column COL in the students list for the current student.
  • --position pos — sets the position where question scores are to be written:
    • marge — the scores will be written in the left margin.
    • marges — the scores will be written in the closest margin (left or right).
    • case — the scores will be written near the boxes.
    • none — the scores won't be written.
  • --verdict-question perl-expression — sets the text to be printed next to all questions, through a perl expression to be evaluated (if you need a simple text, simply quote it with "). Some sequences get substituted in it before evaluation:
    • %S — is replaced by the student score for this question.
    • %M — is replaced by the maximum score for this question.
    • %s — is the same as %S, but rounded to nc significant digits (see option --ch-sign).
    • %m — is the same as %M, but rounded to nc significant digits (see option --ch-sign).

A standard value for this option is "\"%s/%m\"". You can also use tests (with the perl syntax ( TEST ? IF-YES : IF-NO )) to write Valid if the score is the maximal score, or Failed if not, using

--verdict-question "(%S==%M ? \"Valid\" : \"Failed\")"
  • --verdict-question-cancelled perl-expression — same as --verdict-question, but applies for cancelled questions (see allowempty scoring strategy). The default value is "X".
  • --indicatives — use this option to request boxes annotation for indicative questions (these questions' scores won't be taken into account while computing the global score. The correct/wrong status is often irrelevant for these questions, so there is no point correcting the corresponding boxes).
  • --line-width width — sets the line width (in points) when drawing symbols to correct answers.
  • --symbols symbols-definition — defines how boxes will be annotated. symbols-definition is a comma separated list of H-A:shape:color constructs, where H is 0 or 1 depending on whether the box has to be checked or not, A is 0 or 1 depending on whether the box is actually checked or not, shape is one of none, circle, mark, box, and color is a color (name or #RGB, see ImageMagick or GraphicsMagick documentation for details).

Default value is

"0-0:none,0-1:circle:red,1-0:mark:red,1-1:mark:blue"

🍓 Lengths 🍓

The following lengths can be given with a unit (in, ft, pt, cm or mm).

  • --dist-to-box d — sets the distance from the boxes (going left) where to write question scores when using --position case. Defaults to 1cm.
  • --dist-margin d — sets the margin size. Defaults to 5mm.
  • --dist-margin-global d — sets the margin size for the header. Defaults to 3mm.

⭐ AUTHORS ⭐

  • Alexis Bienvenüe <paamc@passoire.fr> — Main author 👑
  • Anirvan Sarkar — Author and Editor
  • Hiroto Kagotani — Editor
  • Frédéric Bréal — Author and Editor
  • Jean Bérard — Translation from French
  • Georges Khaznadar — Translation from French

Copyright © 2008-2025 Alexis Bienvenüe

This document can be used according to the terms of the GNU General Public License, version 2 or later.

okay that's the whole thing bestie, no notes 💅 this was Auto Multiple Choice 1.7.0, dated 2025-04-17, and yes she ate. go annotate something 🎀✨

📦 where this page comes from