Spaces:
Runtime error
Runtime error
| 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: | |
| ```bash | |
| 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](https://sqlitebrowser.org/)). | |
| - **`employees`**: Stores basic profiles. | |
| - **`face_embeddings`**: Stores biometric arrays (binary BLOB). | |
| - **`attendance_logs`**: Stores historical timestamps, score confidence, and check-in/out event types. | |