| | --- |
| | 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** |
| | ```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 |
| | |
