README.md

metadata

title: SecureAttendAI
emoji: 🛡️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

SecureAttend AI — Local Face Recognition Attendance System

An end-to-end, production-ready localized attendance module utilizing cutting-edge deep learning biometric matching. The application opens your local PC camera, detects and tracks faces, matches them against a pre-enrolled employee database, and automatically logs check-in and check-out events dynamically.

---

🌟 Key Features

1. High-Performance Deep Learning Engine:
   • YuNet: Extremely fast and light neural face detector capable of sub-22ms frame processing on standard CPUs (operating at ~30+ FPS).
   • SFace: A state-of-the-art vectorizer that extracts a 128-dimensional floating-point embedding from facial geometry.
   • Match comparison executed via Cosine Similarity under a standard mathematical cutoff threshold of 0.363.
2. Multi-Angle 3D Pose Enrollment (5 POVs):
   • Guided wizard requests 5 distinct angles per employee: Center Face, Look Left, Look Right, Tilt Up, Tilt Down.
   • Capturing multiple perspective templates guarantees robust, near-perfect recognition matching regardless of head turn, tilt, or slight occlusion (e.g. wearing face masks, glasses, or shadows).
3. Double-Scan Cooldown Guard:
   • To prevent rapid-fire double scans (e.g., someone checking out instantly within 1 second of checking in), the camera pipeline features a 2-minute smart cooldown debounce.
   • Scanning a matched face registers a check_in. Scanning the same face again after the 2-minute cooldown seamlessly registers a check_out.
4. Real-Time Push Alerts (SSE):
   • Integrated Server-Sent Events (SSE) push channel. When a scan successfully logs in the background thread, a glowing glassmorphism alert card instantly slides in on the admin dashboard, and metrics counters increment in real time without refreshing the page!
5. Futuristic Glassmorphism Dashboard:
   • Stunning responsive UI themed in obsidian dark-mode gradients, neon-cyan visual trackers, glowing landmark points, and laser scanning overlays.

---

🛠️ Technology Stack

• Backend: FastAPI (Python Async web server) + Uvicorn
• AI Processing: OpenCV DNN Module (YuNet + SFace ONNX neural models)
• Database: SQLite (local transactional relational storage)
• Frontend: Vanilla HTML5 + ES6+ Javascript + Custom CSS3 (with zero-latency MJPEG frame streaming)

---

📂 Project Architecture

FaceDetection/
├── backend/
│   ├── models/          # Local store for YuNet and SFace ONNX binaries
│   ├── camera.py        # Background webcam thread, cybernetic overlays, debounce logic
│   ├── database.py      # SQLite tables schema and CRUD transactions
│   ├── face_engine.py   # ONNX model loader, 5-point alignment, embedding extraction
│   ├── schemas.py       # Pydantic input/output schemas
│   └── main.py          # FastAPI endpoint routers, MJPEG stream, SSE alert channels
├── frontend/
│   ├── css/
│   │   └── style.css    # Premium glassmorphism dark-theme design tokens
│   ├── js/
│   │   └── app.js       # Navigation controller, SSE listener, Multi-step wizard
│   └── index.html       # Dynamic Single-Page control dashboard
├── requirements.txt     # Python dependency lists
├── run.py               # 1-Click launcher script (auto-installs and runs app)
└── README.md            # Detailed user manual

---

🚀 1-Click Startup Guide

Prerequisites

• Python 3.9 to 3.13 installed on your system. Make sure Python is added to your environment PATH.
• A connected USB webcam or integrated laptop PC camera.
• Ensure other applications that lock the webcam (such as Zoom, Microsoft Teams, or Skype) are closed.

Launching the Application

Open a terminal (Command Prompt or PowerShell) inside the FaceDetection/ folder and run the launcher script:

python run.py

The script will automatically:

1. Check your Python environment and install all required pip packages.
2. Connect to the public Hugging Face OpenCV models vault and download the raw binary .onnx models (~36MB total) into the backend/models/ folder.
3. Start the FastAPI server on http://127.0.0.1:8000.
4. Automatically fire open your default web browser to launch the dashboard!

---

💡 User Walkthrough Guide

Step 1: Add a New Employee (Multi-Angle Enrollment Wizard)

1. Go to the Employee Directory tab in the sidebar and click Register Employee.
2. Step 1: Profile Details: Enter the Employee ID (e.g. EMP-01), Full Name, Email, and Designation. Click Next Step.
3. Step 2: Biometric Scans:
   • Position yourself comfortably in front of the camera.
   • Click SCAN on 1. Center Face. The camera captures your face, draws landmark dots, and the card flashes green with a checkmark upon success!
   • Slightly turn your head to the left and click SCAN on 2. Look Left.
   • Repeat for Look Right, Tilt Up, and Tilt Down.
   • Once all 5 checklist cards are green, the Save & Complete button lights up neon!
4. Step 3: Complete: Confirm the success card and click Return to Control Directory. The employee is now fully active!

Step 2: Running Live Attendance Scanning

1. Go to the Live Scanner tab in the sidebar.
2. The webcam stream starts instantly. You will see a glowing cyan visual grid, active scanlines, and neon cyan corner bounding boxes.
3. When a registered face steps into view:
   • The detector locates your eyes, nose, and mouth, highlighting them with glowing cyan dots.
   • The SFace vectorizer matches your face against database templates in <1 millisecond.
   • Bounding box turns Neon Emerald Green, displaying your Name, Match Confidence %, and the registered event (e.g., KUNAL K. (92%) | CHECK IN).
   • In the background, a new SQLite record is saved.
   • A glassmorphism alert card instantly slides into the top-right corner of your screen!
4. If an unregistered person steps into view:
   • The box turns Neon Crimson Red labeled UNKNOWN SECURE ID. No attendance is logged.

Step 3: Checking Out

• To check out, simply step in front of the camera scanner again!
• If the 2-minute cooldown has passed since your last check_in, the system automatically logs a check_out event and broadcasts a yellow/amber logout success toast!

---

🔧 Troubleshooting & Admin Control

1. Changing Active Camera Device

If the application loads a black screen or binds to the wrong camera (e.g. OBS Virtual Camera instead of your laptop webcam):

• Go to the Admin Settings tab in the sidebar.
• Choose your camera index (e.g. Camera Index 0 for default, Camera Index 1 for external USB).
• Click Switch Active Camera Source. The backend releases the old camera and hooks the new index seamlessly.

2. Manual SQLite Log Management

All data is stored in the local file attendance.db. You can inspect, query, or export logs using any standard SQLite manager (e.g. DB Browser for SQLite).

• employees: Stores basic profiles.
• face_embeddings: Stores biometric arrays (binary BLOB).
• attendance_logs: Stores historical timestamps, score confidence, and check-in/out event types.