Test Manager Application - Setup & User Manual

This repository contains a cross-platform desktop GUI application (Tkinter) for managing OMR test forms, converting scanned PDFs into images, executing OMR evaluations, and syncing results with Google Firestore.

This guide is structured into two parts:

1. Developer & Admin Setup: For the technical team preparing, configuring, and maintaining the software.
2. School Setup & End-User Guide: For school administrators and teachers running the software daily to process OMR sheets.

---

PART 1: Developer & Admin Setup (Technical Team)

This section explains the code architecture, how to configure Firestore, prepare OMR templates, and package settings.

1. Local Database & Config Architecture

• SQLite Database (tests.db): Holds exam metadata (ID, test name, date, template folder name) in a flat table named tests.
• Config File (app_config.json): Stores file paths, execution commands, and the default PIN.
  • The configuration supports platform-specific keys (e.g. python_command_win32 vs python_command_darwin) to allow seamless usage across both Windows and macOS machines.

2. Google Cloud Firestore Setup

To enable cloud synchronization of OMR results, configure Google Firestore:

1. Create a Firebase/Google Cloud Project.
2. Enable Firestore Database in Native mode.
3. Go to IAM & Admin → Service Accounts in the GCP Console.
4. Create a service account and assign the role Cloud Datastore User or Firestore Data Owner.
5. Generate and download a new private key in JSON format.
6. Provide this JSON file to the school administrators to load into their preferences.

3. Creating & Packaging OMR Templates

OMR Checker templates must be placed inside the samples (or templates_dir) folder. Each template must be a subdirectory containing:

• template.json: Configures bubble layout coordinate maps.
• evaluation.json: Configures the grading weights. Make sure it uses "marking_schemes" (plural) to comply with OMRChecker specifications.
• answer_key.csv: A CSV map containing correct answers for all questions.
• omr_marker.jpg: Alignment marker asset.

4. Administrative Security (PIN Hashing)

The login screen is protected by a 6-digit PIN.

• PIN salt is set via PIN_SALT inside index.py.
• The hash is computed using SHA-256 and stored as pin_hash inside app_config.json.
• Default PIN is 123456. You can update it using the GUI's Settings → Change PIN option.

5. Building Standalone Installers

You can package this application into a standalone executable that runs without requiring Python or other libraries installed on the target machine.

• macOS Installer (.dmg): Run the build script on a Mac computer:

  python3 build_installer.py

  This creates dist/OMRTestManager.app and packages it into dist/OMRTestManager.dmg.
• Windows Executable (.exe): Run the batch script on a Windows computer:

  build_installer_win.bat

  This installs packages and compiles the app into a single executable dist/OMRTestManager.exe.
• Automated Cloud Builds (GitHub Actions): Every push to the main or mac-compatibility-and-fixes branches triggers a GitHub Actions workflow. You can download the pre-compiled OMRTestManager.exe directly from the Actions tab of your repository.

---

PART 2: School Setup & End-User Guide (School Staff)

Welcome! This guide will help you install and run the Test Manager software on your school computers.

Tip

Recommended: Use Standalone Installers If your technical team has provided you with the standalone installer, you do not need to install Python or run terminal commands:

• Windows: Simply download OMRTestManager.exe and double-click to run it.
• macOS: Download OMRTestManager.dmg, open it, and drag OMRTestManager into your Applications folder. Right-click the app and choose Open the first time to bypass the Apple security prompt.

---

1. Prerequisites (Alternative: Developer/Source Installation)

If you are running the software directly from the source code instead of the standalone installer, follow these steps:

Python Installation

• Make sure Python 3.7 or higher is installed on your computer.

Package Installation

Open your terminal (macOS) or Command Prompt (Windows) and install the required modules:

pip install Pillow pymupdf google-cloud-firestore opencv-python deepmerge dotmap jsonschema matplotlib numpy pandas rich screeninfo

---

2. Configuration & Preferences

1. Run the application:

   python3 index.py

2. Log in using your 6-digit PIN (Default: 123456).
3. In the menu bar, go to Settings → Preferences.
4. Configure the folders:
   • Input Directory: Create a folder on your computer (e.g., inputs) and select it. This is where scanned pages will be prepared.
   • Output Directory: Create a folder on your computer (e.g., outputs) and select it. This is where graded CSV results will be saved.
   • Templates Folder: Choose the folder where your OMR templates are stored (e.g., samples).
   • Python Command: Enter the path to your OMR evaluation script. Use {input} and {output} as placeholders:
     • Windows Example: py C:\OMRChecker-master\main.py --inputDir {input} --outputDir {output}
     • macOS Example: python3 /Users/yourusername/OMRChecker-master/main.py --inputDir {input} --outputDir {output}
   • Firestore Auth Key: Browse and load the Google Cloud credentials JSON file provided by your technical team.
5. Click Save.

---

3. Standard Workflow (How to process exams)

Follow these steps for every OMR test you need to grade:

Step A: Add a Test Exam

1. Click Add Test on the dashboard.
2. Enter the Test Name and Date (YYYY-MM-DD).
3. Select the appropriate layout template from the Template Folder dropdown list.
4. Click Save.

Step B: Load and Convert the Scan PDF

1. Select your test from the left-hand menu.
2. Click Input PDF.
3. Choose the scanned PDF containing all student answer sheets.
4. Confirm the page count on the pop-up window. The app will automatically split the PDF into page images and copy the layout template.

Step C: Run OMR Grading

1. Click Run Command.
2. Click Yes to confirm.
3. The OMR engine will grade the sheets. Once finished, a table preview of the results containing student scores, Roll Numbers, and marked answers will load automatically on the right panel.

Step D: Sync Results with Cloud

1. Click Push to Firestore.
2. Confirm the prompt to upload.
3. The results will be pushed directly to your school cloud database!

---

4. Troubleshooting Guide for Staff

• Error: "Template folder '...' not found."
  • Check that your Templates Folder in Preferences contains the folder name selected for this test.
• The CSV Preview shows old values or doesn't update.
  • Click on another test name on the left sidebar and click back to force the preview window to reload.
• Error: "Firestore Auth Key not found."
  • Go to Settings → Preferences and check that you have selected a valid credentials JSON key file.

---

PART 3: AI Pair Programming History & Prompt Log

This section details the historical developer steps, prompts, commits, and debugging processes that took place during development.

Step 1: macOS Compatibility & Firestore Bug Fixes

• What We Did: Added platform-specific configuration keys (_darwin, _win32) in SettingsManager to support multi-platform user environments, fixed Poppler paths, and cleared Firestore variable NameErrors.
• Commit: 82dd9bd

Step 2: CSV Preview Formatting & Indentation Error

• What We Did: Filtered path columns from CSV preview, formatted file labels (e.g. page_1.jpg -> Page 1), and resolved a start-up indent block issue.

Step 3: Documentation Separation

• What We Did: Restructured the documentation into developer setup (Part 1) and end-user setup (Part 2) guides.

Step 4: Standalone Packaging & Eliminating Poppler

• What We Did: Replaced pdf2image (Poppler dependent) with pymupdf (pure python PDF library) to completely eliminate Poppler dependencies. Bundled OMRChecker directly inside the app folder to run programmatically.
• Commit: 758897a

Step 5: Windows Executable & CI Build Errors

• What We Did: Added build_installer_win.bat for local Windows compiling and created a GitHub Actions workflow (build.yml) to build the Windows .exe automatically on push.
• Commit: 860c3c9

Step 6: OMR Refinements, Directory Isolation, and Crash Fixes

• What We Did: Isolated test folders by test ID, fixed relative path alignment issues, disabled OpenCV thread debug popups causing Cocoa GUI crashes on macOS, recursive template scanning, and resolved a page_count NameError crash.
• Commits: 7f76f8f to 8f2a2ca

Step 7: Packaging and Distributing Installers

• What We Did: Successfully compiled the macOS standalone .dmg installer locally and verified automated compilation of the Windows .exe installer.

Step 8: Project Completion & Installer Distribution

• What We Did: Generated and validated the final installers on macOS (.dmg) and Windows (.exe via GitHub Actions), updated all manuals with installer guides, and submitted the upstream Pull Request #4.

Step 9: Option Analysis, 60Q Template, and Robust Answer Key Validation

• What We Did: Created a pixel-perfect 60-question Standard_Template layout that precisely targets the school's OMR sheet (Mathematics 20Q, Physics 15Q, Chemistry 15Q, and MAT 10Q). Added a post-processing Option Analysis report generator that outputs selection statistics and success rates for each question in Option_Analysis.csv. Modified the OMR engine's verification step to automatically filter and align the answer key questions list to match the template's output columns (allowing 120-question keys to run seamlessly on 60-question templates).
• Commit: 2fa619b

Step 10: PyInstaller Frozen Dynamic Loader Fix

• What We Did: Explicitly registered and imported built-in OMR Checker processor classes (CropOnMarkers, CropPage, FeatureBasedAlignment, Levels, MedianBlur, GaussianBlur) to prevent standalone compiled binaries from crashing during dynamic directory walks.
• Commit: 93b6345

Step 11: Auto-Extract Answer Key, Option Analysis Filtering, & GUI/Firestore Exclusions

• What We Did: Implemented automatic answer key extraction from the first page of the scanned PDF (setting File ID to "Answer Key" and Roll Number to "KEY"), filtered metadata columns from Option Analysis stats, and hid Option_Analysis.csv from both the GUI table preview and Google Firestore sync list.
• Commit: 8ee0a0a