How atsurak/automated-proctoring works
Project Type and Purpose
• This is a Python‑based, open‑source proctoring application that processes live webcam feeds to detect cheating behaviors in online exams.
• Key features (from README): face detection/recognition, landmark detection, head‑pose estimation, spoof detection, lip tracking, and cheating aggregation.
File Structure
• Top‑level files:
• main.py – orchestrator, launches the proctoring loop
• cheating_detector.py – core logic to decide if cheating occurred
• utils.py, testing.py, plot_graphs.py – helpers, testing, reporting
• Top‑level modules (face_detector.py, face_recognition.py, face_landmarks.py, head_pose.py, face_spoofing.py, mouth_detector.py): each implements a specific detection/estimation step.
• assets/ holds environment configuration (proctorenv.yml) and sample images.
• results/ is the output directory for per‑session reports.
Extract Architecture Insights from the README
• Runtime: Python 3.x inside a Conda environment (proctorenv).
• Dependencies: OpenCV, TensorFlow/Keras (FaceNet, anti‑spoofing), dlib, BlazeFace (lightweight detector).
• Workflow: from registration (image capture) → continuous proctoring → detection modules → report generation.
Main Components to Capture
a. Input Layer
• Webcam (live video frames)
• User registration subflow (captures 5 images via main.py)
1. Face Detector (blazeface)
2. Face Recognizer (FaceNet512)
3. Face Landmarks (shape_predictor_68)
4. Head Pose Estimation
5. Lip/Mouth Detector
6. Face Spoofing Detector (anti‑spoofing h5/json model)
7. Cheating Detector (aggregator logic in cheating_detector.py)
c. Data / Model Storage
• models/ directory (weights and model definitions)
• assets/proctorenv.yml (environment spec)
d. Output Layer
• Real‑time display / GUI overlays (via OpenCV windows)
• Report files in results/ (CSV or JSON logs)
• plot_graphs.py – post‑hoc visualization
e. External Dependencies
• OEP dataset (for offline testing)
• Conda (environment manager)
Relationships & Data Flow
• Face Detector → branches to Face Recognizer & Face Landmarks
• Face Landmarks → Head Pose + Mouth Detector
• Face Recognizer + Spoof Detector + Head Pose + Mouth Detector → Cheating Detector
• Cheating Detector → Report Writer (results/) + GUI
• Testing pipeline (testing.py) reads from OEP dataset → modules → plot_graphs.py
Architectural Patterns & Design Principles
• Modular pipeline: each detection step is its own module/file.
• Single‑process orchestrator (main.py) coordinating modules in sequence.
• Separation of concerns: model loading (models/) vs. detection logic.
• Extensibility: add new detectors by dropping in new .py modules and updating cheating_detector.py.