Face Attendance System

A modern, local-first face recognition system for automatic attendance marking

Features • Quick Start • Web UI • Installation • Usage

Features

Core Features ✅ Real-time Face Recognition — ~5 fps live detection ✅ Auto Attendance Marking — One entry per person per day ✅ Face Enrollment — Add new people with simple UI ✅ Attendance Reports — View daily records and history ✅ Local-Only Runtime — Uses the listed Python packages locally; no cloud service is required

Advanced Features 🌐 Modern Web UI — Local Flask dashboard with live webcam 📊 Statistics — Track enrolled people & daily attendance 🎨 Real-time Annotation — Green/red boxes for faces 📁 CSV Export — Automatic daily attendance records ⚡ Fast Processing — Optimized for low-end systems

Quick Start

Two Modes of Operation

Mode 1: Web UI (Recommended) 🌐

Perfect for modern browsers, real-time visual feedback, and team use.

# 1. Install dependencies
pip install flask

# 2. Run the web server
python web_app.py

# 3. Open browser
# Navigate to http://localhost:5000

Mode 2: Server Launcher

Start the Flask server from the src directory for server-oriented use. This entrypoint starts the web server; it does not provide an interactive menu.

# Start the Flask server
cd src
python main.py

---

Web UI

Features

• Live Video Preview — Real-time webcam feed in browser
• Live Recognition — 5 fps frame sampling and annotation
• Enroll People — Add faces directly from webcam
• View Attendance — See today's records in real-time
• Statistics Dashboard — Count of enrolled people and attendance

Access

• URL: http://localhost:5000
• Protocol: HTTP only (localhost)
• Browser Support: Chrome, Firefox, Edge, Safari
• Cost: $0 (runs entirely on your machine)

Screenshots

Screen	Description
Dashboard	Start/Stop recognition, enroll new people, view live attendance stats
Live Feed	Side-by-side: raw webcam video + annotated recognition results
Detection	Green bounding boxes for recognised faces, red for unknown visitors
Enrollment	Step-by-step: capture → enter name → submit → encoding saved automatically

💡 Run the app locally and capture your own screenshots to add here!

---

Project Structure

face-attendance-opencv-python/
│
├── web_app.py                      # Flask server (entry point)
├── templates/
│   └── index.html                  # Web UI (vanilla JS)
│
├── src/
│   ├── face_attendance_app.py       # Core recognition engine
│   ├── attendance.py               # Attendance tracking
│   ├── mock_face_recognition.py    # Dependency-free fallback for face encoding
│   ├── utils.py                    # Utility functions
│   └── main.py                     # Alternate Flask server entry point
│
├── ImagesAttendance/               # Enrollment images
├── data/
│   └── Attendance/                 # Daily CSV records
│
├── requirements.txt                # Dependencies
└── README.md                       # This file

Installation

Prerequisites

• Python: 3.10 or higher
• Webcam: USB or built-in camera
• OS: Windows, macOS, Linux

Step 1: Clone Repository

git clone https://github.com/icecold009/face-attendance-opencv-python.git
cd face-attendance-opencv-python

Step 2: Create Virtual Environment (Recommended)

# Windows
python -m venv .venv
.venv\Scripts\activate

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Note: First install of dlib may take 5-10 minutes. This is normal.

Usage Guide

Web UI Workflow

1️⃣ Start Recognition

Click "Start Recognition" → Live video appears
→ Face detection runs at 5 fps
→ Green boxes for matches, red for unknown
→ Attendance auto-marks for recognized faces
→ Click "Stop Recognition" to pause

2️⃣ Enroll New Person

Click "Enroll New Person" → Enter name
→ Click "Capture Face for Enrollment"
→ Position face in camera for 1-2 seconds
→ Click "Submit Enrollment"
→ Face encoding is saved automatically

3️⃣ View Attendance

Click "View Attendance" → See today's records
→ Shows Name, Time, Status
→ Automatically updates in real-time

Configuration

Adjust Recognition Tolerance

Edit src/face_attendance_app.py:

tolerance=0.6  # 0.4 (strict) to 0.7 (lenient)

Change Camera

Edit web_app.py or src/main.py:

cap = cv2.VideoCapture(0)  # 0=default, 1=USB, 2=external

Custom Frame Rate

Edit templates/index.html:

const FPS = 5;  // Frames per second (adjust for speed/accuracy)

How It Works

Face Recognition Pipeline

The /video_feed route opens the default camera, processes each frame, and annotates recognized and unknown faces:

Camera frame
    ↓
Resize to 25% and convert BGR to RGB
    ↓
Detect faces with `face_recognition.face_locations(model="hog")`
    ↓
Generate 128-D face encodings with `face_recognition.face_encodings`
    ↓
Compare encodings using Euclidean distance
    ↓
Distance ≤ 0.6 → recognized name, green box, and attendance mark
Distance > 0.6 → `Unknown` and red box

With the declared face-recognition dependency installed, the hog detector uses dlib's HOG detector and the encoder uses its 128-D ResNet model. If that dependency is unavailable, modules/detection.py and modules/encoding.py explicitly use src/mock_face_recognition.py as a dependency-free fallback.

Attendance Storage

Known names are passed to AttendanceSystem.mark_attendance(). The system creates one dated CSV per date and rejects repeated marks for a name after the first successful mark in the current app run.

data/Attendance/Attendance_<YYYY-MM-DD>.csv
Name,Time,Status
<PersonName>,<YYYY-MM-DD HH:MM:SS>,Present

System Requirements

Component	Minimum	Recommended
CPU	Intel i3 / Ryzen 3	Intel i7 / Ryzen 5+
RAM	2 GB	4 GB+
Storage	100 MB	500 MB+
Python	3.7	3.9+
OS	Win/Mac/Linux	Win/Mac/Linux

---

Tips for Best Results

For Enrollment

• Capture 5-10 images per person
• Use different angles and lighting
• Ensure face is clearly visible
• Good lighting (face 30cm-1m from camera)

For Recognition

• Consistent lighting is crucial
• Steady camera position
• No glasses or minimal appearance changes
• Frontal face angles work best

For Performance

• Lower tolerance (0.4) = Faster but stricter
• Reduce FPS if system is slow
• Use powerful GPU if available

Troubleshooting

"No module named 'face_recognition'"

pip install face-recognition
# Note: First install takes 5-10 minutes

Webcam not detected

# Try different camera index
# In code, change: cv2.VideoCapture(0) → cv2.VideoCapture(1)

Low recognition accuracy

• Enroll more images (10+)
• Check lighting conditions
• Reduce tolerance to 0.4-0.5

Slow performance

• Reduce FPS from 5 to 2
• Close other applications
• Use better processor

Dependencies

opencv-python==4.8.1.78       # Computer vision
numpy==1.24.3                 # Numerical computing
face-recognition-models       # Pre-trained models
face-recognition              # Face detection & encoding
dlib>=19.7                     # Face detection backend
flask>=2.0.0                  # Web server
pandas>=2.0.3                 # Data handling
Pillow>=10.0.0                # Image processing

Output Files

Enrollment Data

Add 5–10 consented, public-domain, or synthetic photos per person under ImagesAttendance/<Name>/; these files stay local and are intentionally ignored by Git.

ImagesAttendance/
├── <PersonName>/
│   ├── photo-1.jpg
│   └── photo-2.jpg
└── <AnotherPerson>/
    └── photo-1.jpg

When /video_feed starts, the loader scans each person directory, encodes the first detected face in each readable image, and uses the directory name as the person label.

Attendance Records

data/Attendance/
└── Attendance_<YYYY-MM-DD>.csv

Name,Time,Status
<PersonName>,<YYYY-MM-DD HH:MM:SS>,Present

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for setup instructions and guidelines.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Roadmap

• Liveness detection to prevent photo spoofing
• PostgreSQL backend to replace CSV attendance files
• Docker container for portable deployment

---

Made with ❤️ by icecold009

⭐ If you found this helpful, please consider starring the repository!