--- 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.