GUI documentation

docs/crop_blank_margins.md

@@ -0,0 +1,97 @@
+# Scanned PDF margin cropping
+
+Copienator has one automatic crop detector. It finds strongly coloured or dark
+ink, recovers nearby weaker strokes, and removes substantial blank areas above
+and below the detected content. It is designed for scanned student work on
+plain, lined, or gridded paper, including mildly skewed pages and recurring
+punched-hole artifacts.
+
+## Review utility
+
+Run from the repository root:
+
+```sh
+python -m copienator.crop_blank_margins Interro01/Copies tmp/cropped-copies
+```
+
+The input can be a directory or one PDF. Directory processing includes only
+PDFs directly inside that directory. The utility writes processed PDFs, an HTML
+comparison gallery, JPEG previews, and JSON/CSV reports into the output
+directory. Source PDFs are never modified.
+
+Available options:
+
+- `--dpi 200`: analysis resolution.
+- `--padding-mm 6`: space retained around detected content.
+- `--min-crop-mm 5`: minimum worthwhile removal at either edge.
+
+The output retains filenames, page order, page count, colour, rotation, and the
+embedded scan data. Cropping changes the PDF CropBox rather than rasterizing the
+page. Red shading in `index.html` shows the removed part of each original page.
+A `review-*` status records uncertainty; one edge can still be cropped while the
+other remains unchanged.
+
+## Detection
+
+The detector uses colour and darkness as strong ink seeds. It recovers connected
+weak strokes within a 2 mm neighbourhood using directional contrast, which
+limits growth along paper lines. Two seed thresholds are compared so unstable
+boundaries can be flagged for review.
+
+For dark neutral paper, it deskews the scan and confirms repeated horizontal or
+vertical ruling before suppressing paper-line pixels. It uses short directional
+openings to tolerate broken or bent grid lines. Very dark fraction bars and
+diagram axes remain protected. Repeated components with similar size and
+alignment in the outer 15 mm are treated as punched holes only when at least
+three span a substantial part of the page. Writing in the same side column still
+protects its margin.
+
+The large-blank refinement changes an edge only when it finds at least 30 mm of
+additional empty paper. A 2 mm recovery neighbourhood is applied before the
+normal padding. Apparently blank pages and pages without reliable ink seeds are
+kept at full height.
+
+This remains a heuristic. Extremely faint isolated pencil marks, unusually
+damaged ruling, and repeated handwriting shaped like hole artifacts can be
+ambiguous. Review crops before generating answer coordinates.
+
+## Optional GUI step
+
+After **Séparer et réordonner les pages**, the GUI offers **Rogner les zones
+vides**. It can process the whole evaluation or a selected PDF. It runs at 200
+dpi with 6 mm padding and uses five worker processes by default. The CLI form is:
+
+```sh
+python -m copienator crop-margins EVALUATION --workers 5
+```
+
+The batch is fully prepared before any source is replaced. Detection failures
+and interruptions leave the working PDFs intact; replacement errors roll back.
+Each successful run saves the untrimmed PDFs and its report under
+`.copienator/runs/crop-margins-*/`. The **Archivage** step removes these backups
+and reports while keeping the cropped copies and execution logs.
+
+Cropping must run before label detection. If a selected PDF already has a
+same-named JSON coordinate file, the command stops before changing any PDFs.
+When `ALWAYS_CROP` is true in `config.py`, this facultative step starts
+automatically when first reached; the default configuration keeps it manual.
+
+## Performance
+
+Separate worker processes isolate MuPDF and each worker uses one OpenCV thread.
+The detector uses native channel operations, vectorized component filtering,
+cached separable background filtering, and a coarser Hough voting step for skew
+candidates. Report rows remain ordered by copy and page regardless of worker
+completion order.
+
+On the Ryzen 7 PRO 7840U, an end-to-end benchmark took 56.48 seconds for 48 PDFs
+of 10 pages, including rendering, detection, PDF writing, backups, and
+replacement. The fixture uses Interro01 and DS08VA scans and cycles pages in
+shorter copies, so it does not contain 480 distinct scans. Runtime depends on the
+CPU, storage, and scan content.
+
+Run the focused checks with:
+
+```sh
+python -m unittest tests.test_crop_blank_margins tests.test_ink_detection tests.test_crop_margins_command -v
+```

docs/crop_exercise_bottoms.md

@@ -0,0 +1,42 @@
+# Bottom cropping after exercise splitting
+
+This review utility processes the exercise PDFs stored directly under
+`Copies/CopieXX/`. It never changes the source files. Modified PDFs are written
+to a matching tree under the chosen output directory; unchanged PDFs are not
+copied.
+
+```sh
+python -m copienator.crop_exercise_bottoms Interro01 tmp/exercise-bottom-crop
+```
+
+One line is 1/36 of the uncropped full-page height recorded by the matching
+`Copies/CopieXX.pdf`. Each exercise PDF page is considered independently:
+
+1. Pages shorter than 10 lines are skipped.
+2. The bottom 0.75 line is excluded from detection so a fragment of the next
+   label cannot keep a large blank area.
+3. The existing scan detector locates the last ink above that strip and keeps
+   6 mm of padding.
+4. The bottom CropBox changes only if the proposed removal is at least 4 lines.
+   The top CropBox is always retained.
+
+The ignored 0.75-line strip is therefore not removed on its own. It is included
+in the result only when the complete proposed crop passes the four-line
+threshold.
+
+The output contains `index.html`, previews with removed areas shaded red, a
+plain `cropped-files.txt` list, `report.json`, and `report.csv`. The command uses
+five worker processes by default; `--workers`, `--dpi`, and `--padding-mm` are
+configurable.
+
+## GUI integration
+
+After **Découper les réponses par question**, the GUI offers the facultative
+step **Rogner le bas des réponses**. It runs the same thresholds at 200 dpi and
+uses five worker processes by default. Only PDFs with an accepted crop are
+replaced. Their unmodified versions and the complete report are stored under
+`.copienator/runs/crop-exercise-bottoms-*/`; a failure or interruption before
+publication leaves every exercise PDF unchanged. The **Archivage** step removes
+these retained originals and reports. When `ALWAYS_CROP` is true in `config.py`,
+this facultative step starts automatically when first reached; the default
+configuration keeps it manual.