Documentation

Installation Guide

AI-Powered Exam Integrity Guardian: Real-Time Classroom Cheating Detection System Using YOLOv8 and Pose Estimation

Step-by-step Setup Verified Instructions Chat Support
Back to Project
Complete Guide

Complete Installation and Setup Guide

Follow this comprehensive step-by-step guide to install and configure the AI-Powered Classroom Cheating Detection System on your local machine. The setup process takes approximately 15-20 minutes.

System Requirements

Hardware Requirements

  • RAM: Minimum 4GB (8GB recommended for HD video processing)
  • Processor: Intel i5 or equivalent with at least 4 cores
  • Storage: 2GB free disk space for project and models
  • GPU: Optional but improves processing speed significantly
  • Webcam: 720p or higher resolution for live detection
  • Internet: Stable connection for downloading models and dependencies

Software Requirements

  • Operating System: Windows 10/11, macOS 11+, or Ubuntu 20.04 LTS+
  • Python: Version 3.8, 3.9, 3.10, or 3.11
  • pip: Latest version of Python package manager
  • Git: For cloning the repository
  • Web Browser: Chrome, Firefox, Safari, or Edge (latest version)

Step 1: Verify Python Installation

Before starting, ensure Python is properly installed on your system. Open your terminal or command prompt and run:

python --version

You should see output like Python 3.8.x or higher. If Python is not installed, download it from python.org and install with the "Add to PATH" option enabled.

Verify pip installation:

pip --version

Step 2: Clone the Project Repository

Open your terminal or command prompt and navigate to the directory where you want to install the project:

cd Desktop

Clone the project repository (or extract the ZIP file if downloaded):

git clone [repository-url]

Navigate into the project directory:

cd "cheating detection"

Step 3: Create Virtual Environment (Recommended)

Creating a virtual environment isolates project dependencies from your system Python installation, preventing conflicts with other projects.

Create the virtual environment:

python -m venv venv

Activate the virtual environment:

On Windows:
venv\Scripts\activate

On macOS/Linux:
source venv/bin/activate

Once activated, you'll see (venv) prefix in your terminal prompt.

Step 4: Install Project Dependencies

Install all required Python packages using the provided requirements file:

pip install -r requirements.txt

This command installs the following core packages:

  • Django 5.0 - Web framework for backend development
  • ultralytics 8.0.0+ - YOLOv8 models for object detection and pose estimation
  • opencv-python 4.8.0+ - Computer vision and video processing library
  • numpy 1.24.0+ - Numerical computing and array operations
  • Pillow 10.0.0+ - Image processing and manipulation

The installation process may take 5-10 minutes depending on your internet speed. If you encounter any errors, try upgrading pip first:

pip install --upgrade pip

Step 5: Download YOLOv8 Models

The system uses pre-trained YOLOv8 models for detection. These models will be automatically downloaded on first run, but you can pre-download them to save time:

python -c "from ultralytics import YOLO; YOLO('yolov8n.pt'); YOLO('yolov8n-pose.pt')"

This downloads two models:

  • yolov8n.pt - Standard YOLOv8 for phone and object detection (6MB)
  • yolov8n-pose.pt - YOLOv8 Pose model for posture analysis (6MB)

Models are cached in ~/.ultralytics/ directory and reused across sessions.

Step 6: Configure Database

Initialize the SQLite database and create necessary tables by running Django migrations:

python manage.py migrate

You should see output confirming the creation of tables for:

  • User authentication and sessions
  • Detection logs and incident records
  • Email notification configurations
  • System settings and preferences

Step 7: Create Administrator Account (Optional)

Create a superuser account to access the Django admin panel for advanced configuration:

python manage.py createsuperuser

You'll be prompted to enter:

  • Username: Choose an admin username
  • Email: Your email address
  • Password: Secure password (entered twice for confirmation)

After creating the superuser, you can access the admin panel at http://127.0.0.1:8000/admin/

Step 8: Configure Email Notifications

To enable email alerts for detected cheating incidents, configure SMTP settings in the Django settings file.

Open cheating_detector/settings.py in a text editor and locate the email configuration section:

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.gmail.com' # Change to your SMTP server
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'your-email@gmail.com' # Your email
EMAIL_HOST_PASSWORD = 'your-app-password' # Your password or app password
DEFAULT_FROM_EMAIL = 'your-email@gmail.com'

Gmail Users: For Gmail accounts, you need to generate an App Password:

  1. Go to Google Account Settings → Security
  2. Enable 2-Step Verification
  3. Generate an App Password for "Mail"
  4. Use the 16-character app password in EMAIL_HOST_PASSWORD

Other Email Providers: Update EMAIL_HOST and EMAIL_PORT according to your provider's SMTP settings.

Step 9: Adjust Detection Parameters (Optional)

Customize detection sensitivity and thresholds based on your specific requirements. In cheating_detector/settings.py, find the DETECTION_SETTINGS dictionary:

DETECTION_SETTINGS = {
    'CONFIDENCE_THRESHOLD': 0.5, # Min confidence for object detection (0.0-1.0)
    'POSE_CONFIDENCE': 0.6, # Min confidence for pose estimation (0.0-1.0)
    'POSITION_THRESHOLD': 100, # Max pixels from seat position
    'HAND_PROXIMITY_THRESHOLD': 80, # Pixels for document passing detection
    'POSTURE_ANGLE_THRESHOLD': 30, # Degrees for abnormal posture
}

Recommended settings for different scenarios:

  • High Security Exams: Lower thresholds (0.4 confidence, 60 pixel proximity)
  • Standard Monitoring: Default values (0.5 confidence, 80 pixel proximity)
  • Relaxed Environment: Higher thresholds (0.6 confidence, 100 pixel proximity)

Step 10: Create Media Directories

Create directories for storing uploaded videos and processed outputs:

python manage.py collectstatic --noinput

The system automatically creates the following directories:

  • media/uploads/ - Stores uploaded video files
  • media/processed/ - Stores processed videos with detection overlays
  • media/screenshots/ - Stores incident screenshots

Step 11: Start the Development Server

Launch the Django development server:

python manage.py runserver 8000

You should see output similar to:

Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.

The server is now running and ready to accept requests.

Step 12: Access the Application

Open your web browser and navigate to:

http://127.0.0.1:8000/

You'll see the beautiful glassmorphism dashboard with animated Three.js background. The application includes these main sections:

  • Dashboard (/): Overview with statistics, charts, and recent detections
  • Video Upload (/upload/): Upload recorded videos for batch analysis
  • Live Detection (/live/): Real-time webcam monitoring
  • Settings (/settings/): Configure email notifications and detection parameters
  • Admin Panel (/admin/): Advanced database management (requires superuser)

Step 13: Test the System

Verify that all features are working correctly:

Testing Video Upload:

  1. Navigate to the Video Upload page
  2. Drag and drop a sample video or use the file picker
  3. Click "Start Analysis" and wait for processing to complete
  4. View the processed video with detection overlays
  5. Check the dashboard for updated statistics

Testing Live Detection:

  1. Navigate to the Live Detection page
  2. Click "Start Camera" to access your webcam
  3. Grant browser permission to use the camera
  4. Test detection by holding a phone in view
  5. Observe real-time bounding boxes and alerts

Testing Email Notifications:

  1. Go to Settings page and add your email address
  2. Enable notifications for specific detection types
  3. Trigger a detection event (upload video or use live mode)
  4. Check your inbox for alert emails with incident details

Step 14: Troubleshooting Common Issues

Webcam Not Detected

  • Check browser camera permissions in Settings → Privacy
  • Ensure no other application is using the webcam
  • Try a different browser if issues persist
  • Update webcam drivers on Windows

YOLOv8 Models Not Loading

  • Check internet connection for automatic downloads
  • Manually download models from Ultralytics GitHub
  • Place model files in project root directory
  • Verify ultralytics package is properly installed

Email Notifications Not Sending

  • Verify SMTP credentials in settings.py are correct
  • Check if firewall is blocking port 587 or 465
  • For Gmail, ensure App Password is used instead of regular password
  • Test SMTP connection using Django shell

Slow Video Processing

  • Reduce video resolution before uploading
  • Increase frame skip rate in detection engine
  • Close other resource-intensive applications
  • Consider using GPU acceleration if available

Port 8000 Already in Use

  • Use a different port: python manage.py runserver 8080
  • Or kill the process using port 8000
  • On Windows: netstat -ano | findstr :8000 then taskkill /PID [number] /F
  • On Linux/Mac: lsof -ti:8000 | xargs kill -9

Database Migration Errors

  • Delete db.sqlite3 file and run migrations again
  • Ensure no other process is accessing the database
  • Check file permissions in project directory

Step 15: Production Deployment (Advanced)

For deploying to a production environment, follow these additional steps:

Security Configuration

# In settings.py
DEBUG = False
ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']
SECRET_KEY = 'generate-new-secret-key' # Use environment variable

Database Setup

Replace SQLite with PostgreSQL or MySQL for better performance:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'cheating_detection',
        'USER': 'your_db_user',
        'PASSWORD': 'your_db_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

Web Server Configuration

Use Gunicorn as WSGI server:

pip install gunicorn
gunicorn cheating_detector.wsgi:application --bind 0.0.0.0:8000

Reverse Proxy with Nginx

Configure Nginx to handle static files and proxy requests to Gunicorn:

server {
    listen 80;
    server_name yourdomain.com;
    
    location /static/ {
        alias /path/to/project/staticfiles/;
    }
    
    location /media/ {
        alias /path/to/project/media/;
    }
    
    location / {
        proxy_pass http://127.0.0.1:8000;
    }
}

SSL Certificate

Install SSL certificate using Let's Encrypt:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

Additional Configuration Tips

Optimizing for Different Hardware

  • Low-end Systems: Use yolov8n (nano) model, process every 3rd frame, reduce video resolution to 640x480
  • Mid-range Systems: Use yolov8s (small) model, process every 2nd frame, use 1280x720 resolution
  • High-end Systems: Use yolov8m (medium) model, process all frames, support 1920x1080 resolution

Multiple Camera Setup

To monitor multiple examination rooms simultaneously:

  1. Run multiple Django instances on different ports
  2. Configure each instance for a specific camera/room
  3. Use Nginx to route requests based on room identifier
  4. Implement centralized dashboard for monitoring all rooms

Backup and Maintenance

  • Schedule regular database backups using cron jobs
  • Implement log rotation for detection logs
  • Clean up old media files periodically
  • Update packages monthly: pip install --upgrade -r requirements.txt
  • Monitor disk space usage for video storage

System Maintenance Commands

# Update all packages
pip install --upgrade ultralytics opencv-python Django

# Clear detection logs older than 30 days
python manage.py shell -c "from detection.models import Detection; Detection.objects.filter(timestamp__lt=datetime.now()-timedelta(days=30)).delete()"

# Backup database
python manage.py dumpdata > backup.json

# Restore database
python manage.py loaddata backup.json

# Check system health
python manage.py check

# View application logs
tail -f logs/django.log

Performance Benchmarks

Expected performance on different hardware configurations:

Hardware FPS (Live) Processing Speed
Intel i5, 8GB RAM, No GPU 10-15 FPS 2x video duration
Intel i7, 16GB RAM, No GPU 20-25 FPS 1.5x video duration
AMD Ryzen 7, 16GB RAM, GTX 1660 30-40 FPS Real-time processing
Intel i9, 32GB RAM, RTX 3070 50-60 FPS 0.5x video duration

Getting Help and Support

If you encounter issues not covered in this guide:

  • Check the project documentation in the README.md file
  • Review Django logs in the console output
  • Contact CodeAJ support through the marketplace
  • Join the community forum for troubleshooting assistance
  • Report bugs via the project issue tracker

Next Steps After Installation

  1. Customize the glassmorphism theme colors in static/css/style.css
  2. Add your institution logo and branding
  3. Configure detection parameters for your specific use case
  4. Set up automated backups for detection logs
  5. Train staff on using the dashboard and interpreting alerts
  6. Conduct pilot testing with sample exam videos
  7. Document your customizations for future reference

Congratulations! Your AI-Powered Classroom Cheating Detection System is now fully installed and ready to use. Start by uploading a test video or trying the live detection feature to see the system in action.

Need Help?

Our team is here to assist you with installation and setup.

Chat with Us
WhatsAppTelegramSignal
Chat with us