---
title: Face Recognition Attendance System
emoji: 📈
colorFrom: pink
colorTo: yellow
sdk: gradio
sdk_version: 6.0.2
app_file: app.py
pinned: false
---


# 🎯 Face Recognition Attendance System

A modern, AI-powered attendance management system using facial recognition technology. Built with **UniFace** (RetinaFace + ArcFace) for accurate face detection and recognition, and **Gradio** for an intuitive web interface.

![Python](https://img.shields.io/badge/Python-3.8%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Status](https://img.shields.io/badge/Status-Active-success)

## ✨ Features

### Core Features
- 🔍 **Real-time Face Detection** - Powered by RetinaFace for accurate face detection
- 🧠 **Face Recognition** - Uses ArcFace for high-precision face recognition
- 📸 **Webcam Integration** - Live camera feed for registration and attendance
- 👤 **User Registration** - Easy registration with name and roll number
- ✅ **Automatic Attendance** - One-click attendance marking with face recognition
- 💾 **Persistent Storage** - All data saved locally in CSV and pickle files

### 🆕 New Features

#### 🚫 Duplicate Prevention
- **Duplicate Face Detection** - Prevents the same face from registering twice
- **Duplicate Attendance Prevention** - Same person can only mark attendance once per day
- Shows friendly messages: *"⚠️ Already registered!"* or *"😊 Welcome back! You're already marked PRESENT today"*

#### 📊 Advanced Reports
- **Date Filtering** - Filter by Today, This Week, This Month, Custom Range, or All Time
- **Summary Statistics** - View total records, unique users, and present count
- **CSV Download** - Export filtered attendance reports as CSV files
- **Proper Table Display** - Reports shown in clean, sortable tables

#### 📱 Fully Responsive Design
- **Mobile-First Design** - Works perfectly on phones (320px+)
- **Tablet Support** - Optimized layout for tablets (768px+)
- **Desktop Layout** - Full multi-column layout on desktop (1024px+)
- **Touch-Friendly** - Large buttons with 50px height for easy tapping
- **Dark Mode Support** - Automatically adapts to system preference

#### 😄 Fun Messages
Unregistered users see random funny quotes:
- *"🤔 Who dis? Register first, ghostie! 👻"*
- *"🕵️ Face not found... Are you a spy? 🔍"*
- *"👽 Alien detected! Please register on Earth first! 🌍"*

## 🚀 Quick Start

### Prerequisites

- Python 3.8 or higher
- Webcam/Camera
- Windows/Linux/MacOS

### Installation

1. **Clone the repository**
   ```bash
   git clone <your-repo-url>
   cd Face_Recognition_Attendance_System_uniface
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the application**
   ```bash
   python app.py
   ```

4. **Open your browser**
   Navigate to `http://localhost:7860`

## 📖 How to Use

### 1️⃣ Camera (Auto-Started)
- Camera starts **automatically** when the app launches
- Go to the **📷 Camera** tab to manage camera
- Click **🔄 Refresh Preview** to see the camera feed
- Use **⏹️ Stop Camera** if needed

### 2️⃣ Register Users
- Navigate to the **📝 Register** tab
- Enter the user's **Full Name**
- Enter their **Roll Number / ID**
- Click **📸 Capture & Register**
- The system will:
  - Detect the face
  - Check if face already exists (duplicate prevention)
  - Save new users to the database
  - Show registration status with emojis

### 3️⃣ Mark Attendance
- Go to the **✅ Attendance** tab
- Click **🔍 Detect & Mark Attendance**
- The system will:
  - Detect faces in the camera view
  - Recognize registered users
  - Check if already marked today (duplicate prevention)
  - Show appropriate messages:
    - ✅ "Attendance marked! Have a great day!"
    - 😊 "Welcome back! You're already marked PRESENT today"
    - 🤔 Funny quotes for unknown faces

### 4️⃣ View Reports
- Open the **📊 Reports** tab
- **Filter by Date Range:**
  - Today - Current day's records
  - This Week - Monday to today
  - This Month - 1st to today
  - Custom Range - Enter start and end dates (YYYY-MM-DD)
  - All Time - All attendance records ever
- Click **🔍 Apply Filter** to view filtered records
- Click **👥 All Users** to view all registered users
- Click **📥 Download CSV** to export the report

## 🏗️ Project Structure

```
Face_Recognition_Attendance_System_uniface/
├── app.py                      # Main application file
├── requirements.txt            # Python dependencies
├── README.md                   # This file
├── .gitignore                  # Git ignore rules
├── face_data/                  # Face embeddings database
│   ├── face_database.pkl       # Stored face embeddings
│   └── user_database.pkl       # User information
└── attendance_records/         # Attendance CSV files
    └── attendance_YYYY_MM_DD.csv
```

## 🔧 Technical Details

### Face Detection
- **Model**: RetinaFace
- **Features**: 
  - Detects faces in real-time
  - Extracts 5-point facial landmarks
  - Returns bounding boxes with confidence scores

### Face Recognition
- **Model**: ArcFace
- **Features**:
  - Generates 512-dimensional face embeddings
  - Normalized embeddings for consistent comparison
  - Cosine similarity for face matching
  - Threshold: 0.4 (adjustable in code)

### Duplicate Prevention
- **Registration**: Compares new face against all existing face embeddings
- **Attendance**: Checks both User_ID and Roll_No for same-day duplicates

### Data Storage
- **Face Embeddings**: Stored as pickle files (`face_database.pkl`)
- **User Info**: Stored as pickle files (`user_database.pkl`)
- **Attendance**: Daily CSV files with timestamps

### Technologies Used
- **UniFace**: Face detection and recognition
- **Gradio**: Web interface with responsive design
- **OpenCV**: Image processing
- **Pandas**: Data management and filtering
- **NumPy**: Numerical operations

## 📊 Database Schema

### User Database
```python
{
    "USER_001": {
        "name": "John Doe",
        "roll_no": "12345",
        "registration_date": "2025-12-03 00:15:30",
        "last_attendance": "2025-12-03 09:30:00"
    }
}
```

### Attendance Records (CSV)
| Timestamp | User_ID | Name | Roll_No | Status |
|-----------|---------|------|---------|--------|
| 2025-12-03 09:30:00 | USER_001 | John Doe | 12345 | Present |

## ⚙️ Configuration

### Adjust Recognition Threshold
Edit `app.py`:
```python
self.recognition_threshold = 0.4  # Lower = stricter, Higher = more lenient
```

### Change Server Port
Edit `app.py` last line:
```python
demo.launch(share=False, server_name="0.0.0.0", server_port=7860)
```

### Enable Public Sharing
```python
demo.launch(share=True)  # Creates a public Gradio link
```

## 🛠️ Troubleshooting

### Camera Not Working
- Ensure no other application is using the camera
- Check camera permissions in your OS settings
- Click "🔄 Refresh Preview" in the Camera tab
- Try restarting the application

### Face Not Detected
- Ensure good lighting conditions
- Face the camera directly
- Remove glasses or face coverings if possible
- Move closer to the camera

### "Already Registered" Error
- This means your face is already in the database
- Check the Reports → All Users to see your existing registration
- This is a feature to prevent duplicate registrations

### Recognition Accuracy Issues
- Register with clear, well-lit photos
- Ensure consistent lighting during recognition
- Adjust the `recognition_threshold` if needed
- Re-register users with poor recognition rates

### DLL Load Errors (Windows)
- Install Visual C++ Redistributable
- Update to latest Python version
- Reinstall onnxruntime: `pip install --upgrade onnxruntime`

## 📝 Requirements

```
gradio>=4.0.0
opencv-python>=4.8.0
numpy>=1.24.0
pandas>=2.0.0
uniface>=1.1.0
```

## 🔒 Privacy & Security

- All data is stored **locally** on your machine
- No data is sent to external servers (unless `share=True`)
- Face embeddings are encrypted in pickle format
- Attendance records are in plain CSV for easy access

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- **UniFace** - For the excellent face recognition library
- **Gradio** - For the amazing web interface framework
- **RetinaFace** - For robust face detection
- **ArcFace** - For state-of-the-art face recognition

## 📧 Contact

For questions or support, please open an issue on GitHub.

---

**Made with ❤️ using Python and AI**


Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference