update readme

README.md

@@ -16,19 +16,20 @@ are done within the browser and no sensitive files will be transmitted anywhere.
 
 We have previously used
 [FormScanner](https://sites.google.com/site/examgrader/formscanner), but
-encountered issues in our use case: Java tends to be a pain to set up, using
+encountered issues in our use cases: Java tends to be a pain to set up, using
 Excel to grade the exams wasn't convenient for us and it was very difficult to
 check for mistakes in the individual grading.
 
-We are supporting the forms generated by FormScanner.
+As this is work in progress, we chose to be compatible with bubble sheets as
+used by form scanner.
 
-## Idea
+## High level idea
 
 You have a bubble sheet like this:
 
 ![filledoutform](assets/filled_out_example.png)
 
-You want it automatically graded. `autograder` had a command line interface,
+You want it automatically graded. `autograder` has a command line interface,
 which is self-documented. The following is for the wasm web application.
 
 ## Preparation
@@ -43,7 +44,7 @@ skewed by a scanner. You need to enter the following information:
 
 - how many questions there are
 - how long the student ID is
-- how many versions the form has
+- how many versions the exam has
 - how many answers each question has
 - how wide an answer bubble is (in px)
 - how high an answer bubble is (in px)
@@ -56,32 +57,45 @@ skewed by a scanner. You need to enter the following information:
 
 You should use an image editor like gimp to find out those coordinates.
 
-After entering this data and uploading an image file, you can hit "Preview" so
+After entering this data and uploading an image file, you can hit "Preview" to
 see if everything goes well. You can then download the configuration to
 `template.json`
 
 ### The exam key
 
-Go to *Create Key*. Enter how many versions you have and enter the answers. You
-can then download the key as `key.json`
+Go to *Create Key*. Enter how many versions you have and enter the correct
+answers. You can then download the key as `key.json`
+
+At this point every question is graded as one point and only one choice can be
+correct.
 
 ## Grading Exams
 
 The most reliable way to scan exams is to use *Multipage Grayscale Tiffs*. PDFs
-are also supported, but we have encountered issues with some scanners who
-produce invalid JPGs, which we cannot handle. A resolution of 200dpi is sufficient.
+are also supported, but we have encountered issues with Toshiba scanners which
+produced invalid JPGs, which we cannot handle. A resolution of 200dpi is sufficient.
 
 Scan to grayscale (and not to "black and white" or binary), because many
-scanners use bad algorithms for this.
+scanners use bad algorithms for the conversion to pure black and white.
+`autograder` also uses pure black and white internally by converting grayscale
+to binary using Otesu's method.
 
 In the *Generate Report* view you can upload a `template.json`, a `key.json` and
 an image container (like a multi-page tiff, a PDF, or a single image).
 
 Once you have uploaded them, you see a button to *Do the thing*. This might take
-a moment -- especially unpacking and recoding all images in memory might take a
-while. You might also run out of RAM depending on how many images you are trying
-to deal with. In that case, split your scans into multiple files and batch
-process them.
+a moment -- and because the browser has only access to a single thread, updates
+in the UI might take a while. Scans are processed in batches of 20, occasionally
+triggering an update in the view. You can always look into the developer
+console, which has a rather verbose output to what is happening in the background.
 
 Afterwards you can download a zip file containing a CSV file with all the
 results and conveniently named reports like this ![example report](assets/sample_report.png).
+
+These image reports were the main motivation to develop this software: using OMR
+will always be a bit error-prone, especially when students use the bubble sheet
+in ways that is not intended.
+
+A green circle means that autograder thinks that the selected bubble is the
+circled one, which according to the key is correct. A red circle shows the
+correct answer, meaning that the selected bubble is elsewhere.