How vasikumar/classai works
What this project is (type + purpose)
This is a single-node, Python computer-vision monitoring system for online classes/exams. It:
• Captures live video from a webcam
• Runs real-time detection pipelines: face detection/recognition, eye/gaze-based “focus” detection, and mobile phone detection
• Emits real-time alerts on the video feed
• Produces post-session reports (console + JSON)
• Includes an optional Streamlit dashboard/UI (streamlit_app.py) and helper scripts (*.bat, setup checkers)
Read the file tree as architecture clues (what to map)
Top-level files indicate the main subsystems:
Core runtime / orchestration
• student_monitor.py → likely the primary entrypoint and session orchestrator (loads config, opens camera, loops frames, calls detectors, aggregates stats, writes report)
• streamlit_app.py → dashboard / visualization / report viewer (possibly launches via launch_dashboard.bat)
• demo.py, examples.py → examples / alternative runners
Inputs / models / configuration
• config.json, monitor_config.json → static configuration inputs (thresholds, durations, camera index, etc.)
• yolov8l.pt → object detection model weights for mobile detection
• sample_student_photos/ + zip workflow described in README → face database source
Setup / environment / dependency helpers
• requirements.txt
• check_setup.py, setup_test.py, install.bat, check_setup.bat
Reporting tests
• test_report.py, test_end_session.py, plus report fix guides in docs
Operator / Environment (external actors)
• Teacher/Proctor (starts session, views alerts/reports)
• Student(s) (appear in webcam feed)
• Webcam (video input device)
• Filesystem (student photo zip, model weights, generated JSON reports)
Monitoring Runtime (Python process)
• Entry: student_monitor.py
Dashboard Runtime (Streamlit)
• Entry: streamlit_app.py (optional, may read report JSONs)
Inside Monitoring Runtime: key components (module-level)
Even if the code is in a single file, represent these as logical components:
• Frame Capture
• OpenCV VideoCapture (implied)
• Preprocessing
• Face Detection
• Detect faces per frame
• Face Recognition / Identity Resolver
• Loads student photos from ZIP → creates face database/encodings/templates
• Matches detected face → student name/ID
• Focus (Gaze/Eye) Detector
• Eye detection; if both eyes visible => “Focused”
• Mobile Phone Detector
• Uses YOLOv8 weights (yolov8l.pt) or a simpler heuristic (README hints basic detection; file suggests YOLO is present)
• Policy / Threshold Evaluator
• Focus threshold (default 50%)
• Mobile detection incident rules
• Aggregation + Session State
• Per-student counters: focused/unfocused/total checks
• Incident timeline (timestamps for alerts)
• Renderer / Overlay
• Report Generator
• Console summary
• JSON report writer: focus_report_YYYYMMDD_HHMMSS.json
Offline/setup components (important but non-runtime)
• Setup Validator (check_setup.py, setup_test.py)
• Dependency Fixers (fix_face_recognition.py, bundled dlib wheel)
Teacher starts monitoring
• Teacher → student_monitor.py (CLI run)
Initialization phase
• student_monitor.py → reads config.json / monitor_config.json (config)
• student_monitor.py → reads name.zip (student photos) → builds Face DB
• student_monitor.py → loads yolov8l.pt (mobile detection model)
Runtime loop (per frame)
• Webcam → Frame Capture → Preprocessing
• Preprocessing → Face Detection → (Face crops) → Face Recognition → Student ID
• Preprocessing/face region → Eye/Focus Detector → Focus signal
• Full frame → Mobile Detector → Mobile incident signal
• Signals → Policy/Threshold Evaluator + Aggregator
• Aggregator → Overlay Renderer → Display (real-time visual feedback)
• Aggregator → Incident log (in memory)
Session end
• Aggregator → Report Generator → JSON report file on filesystem
• Report Generator → console output
Optional dashboard
• Teacher → Streamlit (streamlit_app.py)
• Streamlit → reads JSON report files (and possibly config) → renders charts/tables
Key detail to include: face recognition depends on the student photo ZIP artifact, while mobile detection depends on the YOLO weights artifact.
Architectural patterns to highlight (keep it grounded in this repo)
• Pipeline / staged processing: capture → detect → classify → decide → render → report
• Session-based aggregation: statistics computed over a monitoring interval (CHECK_INTERVAL)
• Config-driven behavior: threshold + duration + camera index
• Local-first execution: no server, no DB; persistence is JSON files
“Don’t overthink it” guidance (but still detailed)
For this repo, “best and most accurate” means:
• Split into as many logical components as exist in the README features (face recognition, focus detection, mobile detection, reporting, alerts)
• key artifacts (name.zip, yolov8l.pt, focus_report_*.json, configs)
• optional dashboard path separately so it doesn’t clutter the monitoring loop
• Does it show how mobile detection is implemented? (YOLO weights artifact + detector component)
• Does it show real-time vs post-session outputs? (overlay alerts vs JSON report)
• Does it show configuration points (threshold, interval, camera index)?
• Does it show the optional Streamlit dashboard and that it likely reads saved reports?