README.md

metadata

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.

✨ 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

   git clone <your-repo-url>
   cd Face_Recognition_Attendance_System_uniface
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Run the application

   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

{
    "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:

self.recognition_threshold = 0.4  # Lower = stricter, Higher = more lenient

Change Server Port

Edit app.py last line:

demo.launch(share=False, server_name="0.0.0.0", server_port=7860)

Enable Public Sharing

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