AttendAI 🎓

AI-powered face recognition attendance system built for the NIST University Smart Campus initiative.

---

📌 Overview

AttendAI automates student attendance using real-time face recognition. Faculty start a class session, the system auto-scans faces continuously via browser webcam, and attendance is marked instantly — no manual effort, no proxy attendance possible.

Built as part of the NIST University AI-Enabled Smart Campus Project under the Department of Computer Science & Engineering.

---

✨ Features

• 🎥 Browser-based webcam capture — no server camera required, works on any deployment
• 👁️ Liveness detection — MediaPipe blink detection prevents photo/screen spoofing
• 🔄 Auto-continuous scanning — scans every 3 seconds, marks entire class without manual clicks
• 👤 20-frame face registration — captures multiple angles for better recognition accuracy
• 🔐 bcrypt password hashing — secure auth for Admin, Faculty, and Student roles
• ⚡ Optimized model loading — LBPH model loads once at startup, not on every scan
• 🔁 Auto-retrain — model retrains automatically after every new student registration
• 📊 Analytics dashboard — attendance stats by department and subject
• 📥 CSV export — download attendance reports as Excel-compatible CSV
• 🗂️ Role-based access — Admin, Faculty, Student with separate dashboards
• ☁️ Supabase cloud database — no local DB setup, works from anywhere
• 🌐 Environment-based config — no hardcoded credentials, uses .env
• 📧 Low attendance email alerts — automatic email notifications for students below attendance threshold (requires SMTP credentials)

---

🛠️ Tech Stack

Layer	Technology
Backend	Python, Flask 3.x
Face Detection	OpenCV (Haar Cascade)
Face Recognition	LBPH (Local Binary Patterns Histograms)
Liveness Detection	MediaPipe Face Mesh (Eye Aspect Ratio)
Frontend	HTML, CSS, JavaScript (getUserMedia API)
Database	Supabase (PostgreSQL)
Auth	bcrypt, Flask Session
Config	python-dotenv

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• Webcam
• Supabase account (free at supabase.com)

Installation

# Clone the repo
git clone https://github.com/Subham503/AttendAI.git
cd AttendAI

# Install dependencies
pip install flask opencv-contrib-python bcrypt numpy python-dotenv 
pip install flask opencv-contrib-python bcrypt numpy python-dotenv supabase

---

Contributor Notes

Contributors do not require production credentials.

For local development:

• Create your own .env
• Use personal SMTP credentials for testing email alerts
• If mail credentials are absent, email functionality remains disabled

Production credentials are intentionally not committed to the repository.

---

Environment Variables

Create a .env file in the root directory:

SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_service_role_key
SECRET_KEY=your_flask_secret_key
SESSION_TIMEOUT_MINUTES=30

# Email alerts (required for attendance warning emails)
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_gmail_app_password

• FLASK_DEBUG=true → runs in debug mode (local development only)
• FLASK_DEBUG=false → runs in production mode (safe default)

Notes:

• MAIL_USERNAME should be a Gmail account used for sending alerts.
• MAIL_PASSWORD must be a Gmail App Password, not your normal Gmail password.
• Email alert functionality remains disabled if mail credentials are not configured.
• Contributors without SMTP credentials can still run the project normally.

Database Setup

Go to Supabase Dashboard → SQL Editor → Run:

CREATE TABLE students (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100),
  reg_no VARCHAR(50) UNIQUE,
  department VARCHAR(50),
  class VARCHAR(50),
  password VARCHAR(255),
  email VARCHAR(255)
);

CREATE TABLE attendance (
  id SERIAL PRIMARY KEY,
  student_id INT REFERENCES students(id),
  name VARCHAR(100),
  department VARCHAR(50),
  class VARCHAR(50),
  subject VARCHAR(100),
  date DATE,
  time TIME,
  status VARCHAR(20)
);

CREATE TABLE admins (
  id SERIAL PRIMARY KEY,
  username VARCHAR(50),
  password VARCHAR(255)
);

CREATE TABLE faculty (
  id SERIAL PRIMARY KEY,
  faculty_id VARCHAR(50),
  name VARCHAR(100),
  password VARCHAR(255)
);

Run

python app.py

Visit http://localhost:5000

---

🛠️ Troubleshooting

If you encounter issues while setting up or running AttendAI, try the following solutions.

1. ModuleNotFoundError

Problem

ModuleNotFoundError: No module named 'flask'

Solution

• Activate your virtual environment.
• Install all required dependencies:

pip install -r requirements.txt

If requirements.txt is unavailable, install the required packages manually.

---

2. Missing or Incorrect .env Variables

Problem

The application fails to start or cannot connect to Supabase.

Solution

• Create a .env file in the project root.
• Copy the required variables from the README.
• Ensure there are no spelling mistakes or empty values.

---

3. Supabase Connection Errors

Problem

Database operations fail or authentication errors occur.

Solution

• Verify SUPABASE_URL and SUPABASE_KEY.
• Confirm your Supabase project is active.
• Restart the Flask application after updating the .env file.

---

4. Webcam Permission Issues

Problem

The browser cannot access the webcam.

Solution

• Allow camera permission in your browser.
• Close any other application currently using the webcam.
• Refresh the page and try again.

---

5. MediaPipe or OpenCV Installation Problems

Problem

Import errors occur for MediaPipe or OpenCV.

Solution

pip install --upgrade mediapipe opencv-contrib-python

If the issue persists, recreate your virtual environment and reinstall dependencies.

---

6. Port 5000 Already in Use

Problem

Address already in use
Port 5000 is already occupied.

Solution

Run the application on another port:

flask run --port=5001

or stop the process currently using port 5000.

---

7. Flask-Mail Configuration Errors

Problem

Attendance warning emails are not being sent.

Solution

• Verify MAIL_USERNAME and MAIL_PASSWORD.
• Use a Gmail App Password instead of your Gmail account password.
• Restart the application after updating mail credentials.

---

📁 Project Structure

AttendAI/
├── app.py                              
# Attendance email alert utilities
├── alerts.py
# Main Flask application        
├── face_utils.py                       # DeepFace utility (future upgrade)
├── train.py                            # Standalone training script
├── haarcascade_frontalface_default.xml # Face detection model
├── images/                             # Registered face images (local)
├── trainer.yml                         # Trained LBPH model (auto-generated)
├── labels.pickle                       # Label map (auto-generated)
├── .env                                # Environment variables (not committed)
└── templates/
    ├── index.html                      # Home dashboard
    ├── login.html                      # Multi-role login
    ├── register.html                   # Browser webcam 20-frame registration
    ├── camera.html                     # Auto-continuous attendance scanner
    ├── attendance.html                 # Records + CSV export
    ├── dashboard.html                  # Analytics charts
    └── class_session.html             # Session setup

---

🔄 How It Works

Register Student
      │
      ▼
Browser opens webcam → captures 20 frames
      │
      ▼
Flask detects faces → saves images → auto-retrains LBPH model
      │
      ▼
Faculty starts class session (subject + department)
      │
      ▼
Camera page → MediaPipe blink check (liveness verified)
      │
      ▼
Auto-scans every 3 seconds → face detected → LBPH predicts identity
      │
      ▼
Attendance marked in Supabase → live log shown on screen
      │
      ▼
Export CSV → downloadable attendance report

---

---

📸 Screenshots

🔐 Login Page

Secure login interface for Admin, Faculty, and Student users.

📝 Registration Page

Student registration page with webcam-based face capture.

🎥 Camera Interface

Captures student faces for registration and attendance.

📚 Class Session

Faculty can create and manage attendance sessions.

📷 Attendance Scanner

Real-time face recognition used for marking attendance.

🖥️ Dashboard

Displays attendance information and system overview.

---

🗺️ Project Workflow

---

👁️ Liveness Detection

AttendAI uses MediaPipe Face Mesh to compute the Eye Aspect Ratio (EAR) in real time. When EAR drops below threshold for 2+ consecutive frames, a blink is detected — confirming the face is real and not a photo or screen.

EAR = (vertical distances) / (horizontal distance)
Open eye → EAR ≈ 0.25–0.30
Blink    → EAR < 0.20 → LIVENESS CONFIRMED ✅
Photo    → EAR never drops → REJECTED ❌

---

🔐 Roles

Role	Access
Admin	All records, retrain model, manage sessions, export CSV
Faculty	Start sessions, mark attendance, view records
Student	View own attendance history

---

📧 Attendance Alert System

AttendAI supports automated attendance warning emails.

Admins can trigger attendance checks and automatically notify students whose attendance falls below a configurable threshold.

Workflow

Admin triggers attendance check
          │
          ▼
Fetch all students from Supabase
          │
          ▼
Calculate attendance percentage
          │
          ▼
Below threshold?
     YES / NO
       │
       ▼
Send email warning via Flask-Mail

Requirements

• Gmail SMTP credentials configured in .env
• Student email addresses stored in database
• Flask-Mail installed

Default threshold: 75%

---

📍 Roadmap

• Browser-based webcam capture
• Liveness detection (anti-spoofing)
• Auto-continuous scanning
• Supabase cloud database
• CSV export
• bcrypt auth
• Low attendance email alerts
• QR-based student self-checkin
• DeepFace / FaceNet upgrade
• React Native mobile app

---

👨‍💻 Author

Subham Sahu

• GitHub: @Subham503
• Email: sahusubham38632@gmail.com

---

📄 License

MIT License — see LICENSE for details.

---

Built with ❤️ for NIST University Smart Campus Initiative