# OMRChecker Headless Server Package

Pinned installation for the **Written 50ABCDE v03** production bundle.

This matches the clean OMRChecker install that ChatGPT verified: same commit, same
v3 `template.json`, same `omr_marker.jpg`, same default processing settings, plus
only the headless display patch and a locked dependency list including OpenCV.

## 1. Pin the commit

```text
de3f698  Feat: add PDF input support with PyMuPDF (#282)
```

```bash
git clone https://github.com/udayraj123/OMRChecker.git
cd OMRChecker
git checkout de3f698
```

## 2. Apply the headless patch

Ensure `src/utils/interaction.py` includes the headless fallback (see
`deploy/patches/HEADLESS.md`). This repository already has that patch applied.

## 3. Create a virtual environment

```bash
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
```

## 4. Install pinned dependencies

```bash
pip install -r deploy/requirements-pinned.txt
```

Important: upstream `requirements.txt` does **not** list `opencv-python`. Without
it, `import cv2` fails. The pinned file includes `opencv-python==5.0.0.93`.

## 5. Place the v03 bundle

Copy into `samples/sample7/`:

| File | Purpose |
|------|---------|
| `template.json` | v03 layout (already in repo) |
| `omr_marker.jpg` | marker reference |
| `config.json` | `show_image_level: 0` |
| `2026-08-03-0002.jpg` | verified desktop scan |
| `PXL_20260803_185005794.jpg` | verified phone photo |

Do **not** resize, rotate, crop, or re-encode these images in your upload pipeline.
Pass the original file bytes to OMRChecker.

## 6. Verification command

```bash
export OMR_HEADLESS=1          # Linux/macOS
# set OMR_HEADLESS=1           # Windows PowerShell

python deploy/verify.py
```

Expected pass output for each scan:

- `DriverID: 159`
- `q1–q10: A B C D E A B C D E`
- `q11–q25: blank`
- `q26–q35: A B C D E A B C D E`
- `q36: AC`
- `q37–q40: B C D E`
- `q41–q48: A B C D E A B C`
- `q49: blank`
- `q50: DE`
- `global_thr` around **70–90** (not ~200)

## 7. Manual run

```bash
python main.py -i samples/sample7
```

Results CSV: `outputs/Results/`
Checked overlays: `outputs/CheckedOMRs/`

## 8. Connect to your website only after verify passes

If `deploy/verify.py` fails from the command line, fix the installation first.
Do not debug through the website upload path until CLI verification passes.

Common causes of mismatch vs the verified ChatGPT run:

| Problem | Symptom |
|---------|---------|
| Missing `OMR_HEADLESS=1` | Server crash on import or `cv2.imshow` |
| `show_image_level > 0` | GUI wait / headless failure |
| Missing `opencv-python` | `ModuleNotFoundError: cv2` |
| Image pre-processing in upload code | Wrong `global_thr` (~200), all `ABCDE` |
| Wrong template / old v02 PDF | Driver ID position wrong |
| `CropPage` added to template | README says use `CropOnMarkers` only |

## 9. Default processing settings

Leave OMRChecker defaults unless you have a verified reason to change them:

- `processing_width`: 666
- `processing_height`: 820
- `show_image_level`: 0
- Preprocessor: `CropOnMarkers` only (`sheetToMarkerWidthRatio: 24`)

Reference: `src/defaults/config.py`