Face Recognition Attendance

Relevant source files

The following files were used as context for generating this wiki page:

• app.py
• face_recognition_insightface.py
• static/js/capture.js
• templates/web_attendance.html
• templates/capture_wajah.html
• static/js/capture-simple.js
• static/openapi.yaml
• templates/add_employee_form.html

The Face Recognition Attendance system is a core feature of the Smart Absen project, providing a modern, high-accuracy method for employees to record their attendance. It leverages the InsightFace/ArcFace machine learning model, which boasts over 99% accuracy, to identify individuals via a webcam feed. The system is implemented as a web-based application using Flask for the backend and vanilla JavaScript for the frontend.

The feature is divided into two primary workflows: an admin-only process for employee registration and face model training, and a user-facing process for daily attendance (check-in and check-out). This design ensures that the face recognition model is populated with accurate data before being used for verification. The system is designed to be accessible from both desktop webcams and mobile device cameras, facilitated by a QR Code Authentication system.

Sources: README.md, app.py:40-48, app.py:328-360

System Architecture

The face recognition module operates on a client-server architecture. The frontend captures video frames, while the backend processes these frames to perform face detection, identification, and database updates.

This diagram shows the high-level data flow for the attendance process, from image capture on the client to processing and storage on the server.

Sources: app.py:1757-1845, templates/web_attendance.html:362-421

Part 1: Employee Onboarding & Face Training

Before an employee can use the face recognition feature, an administrator must register them and train the system with their facial data. This is a two-step process involving data entry and face capture.

Sources: templates/add_employee_form.html, templates/capture_wajah.html

Onboarding Flow

The following diagram illustrates the sequence of actions for adding a new employee and training their facial data.

Face Capture UI

The face capture interface is provided by capture_wajah.html and managed by static/js/capture-simple.js. It offers three modes for gathering training photos:

1. Manual Mode: The admin clicks a button to capture each photo, allowing for precise control over angles and expressions.
2. Auto Mode: The system automatically captures 10 photos in a short interval (3 seconds).
3. Upload Mode: The admin can upload existing photos from the device's storage.

The UI includes a live progress bar and a preview grid of the captured photos. A minimum of 5 photos is required to enable the save button, though 10 are targeted for optimal results.

Sources: templates/capture_wajah.html:298-384, static/js/capture-simple.js:12-65

Key JavaScript Configuration

The capture process is governed by constants defined in the JavaScript files.

Constant	Value	File	Description
MIN_PHOTOS	5	capture-simple.js:12	Minimum photos required to save.
TARGET_PHOTOS	10	capture-simple.js:13	Target number of photos for auto-capture.
AUTO_CAPTURE_INTERVAL	500	capture-simple.js:14	Milliseconds between each shot in auto-capture mode.
FACE_CONFIDENCE_THRESHOLD	0.5	capture.js:20	Minimum confidence score for face detection in the advanced capture.js.

Sources: static/js/capture-simple.js:11-14, static/js/capture.js:20

Backend Training Logic

When photos are saved via the /api/save_training_photos endpoint, the backend performs two key actions:

1. Saves Photos: Decodes the Base64 images and saves them as JPG files in a directory named after the employee's NIK (e.g., static/faces/3273051234567890/).
2. Triggers Model Training: Calls the train_model() function, which in turn invokes train_insightface_model() from the face_recognition_insightface.py module. This function scans the static/faces directory, extracts facial embeddings from all images, and saves them into static/face_embeddings.pkl.

Sources: app.py:1335-1375, app.py:421-449

Part 2: Real-time Attendance

The real-time attendance process is the primary interaction for employees. It uses the device's camera to capture an image, which is then sent to the server for identification.

Attendance Flow

This sequence diagram details the interaction between the user, browser, and server during an attendance attempt.

Frontend Logic (web_attendance.html)

The attendance page contains JavaScript to manage the camera feed and handle the submission process.

1. Camera Activation: On page load or button click, navigator.mediaDevices.getUserMedia() is called to start the video stream.
2. Mode Switching: Users can toggle between "Absen Masuk" and "Absen Pulang". This changes the currentMode variable, which is sent to the backend.
3. Image Capture & Submission: When the user clicks the attendance button, the markAttendance function is triggered. It:
   • Draws the current video frame onto a hidden <canvas> element.
   • Converts the canvas content to a Base64-encoded JPEG string using canvas.toDataURL('image/jpeg', 0.8).
   • Creates a FormData object and appends the image data and attendance mode.
   • Sends the data to the /mark_attendance_mobile endpoint via a fetch POST request.
4. Result Handling: Based on the JSON response from the server, it either shows a success popup (with a countdown redirect) or an error message. A "ding" sound is played on success.

Sources: templates/web_attendance.html:432-463, templates/web_attendance.html:492-540, templates/web_attendance.html:585-637

Backend Identification Logic (app.py)

The /mark_attendance_mobile endpoint in app.py orchestrates the identification process:

1. Image Decoding: It receives the Base64 image data, decodes it, and converts it into an OpenCV-compatible image format (BGR color).
2. Face Identification: The full, resized frame (640x480) is passed to identify_face_insightface_wrapper. This function calls the core identify_face_insightface function from the ML module.
   • The ML function detects faces in the image.
   • For each detected face, it extracts a 512-dimensional feature vector (embedding).
   • It compares this embedding against the pre-computed embeddings stored in face_embeddings.pkl.
   • If a match is found above a certain threshold (0.45), it returns the corresponding employee's NIK and a confidence score.
3. Database Update: If a known employee is identified, the update_attendance function is called to record the check-in or check-out time in the attendance table.
4. Device Registration: On a successful first attendance with a new device, the system automatically registers the device ID to the employee, enabling a "Device Terdaftar" status on subsequent visits.

Sources: app.py:1757-1845, app.py:328-386, app.py:2009-2077, face_recognition_insightface.py

Key API Endpoints

The following API endpoints are central to the face recognition functionality.

Method	Endpoint	Description
POST	/mark_attendance_mobile	Submits a captured face image for attendance verification. Expects image_data (Base64) and mode ('masuk'/'pulang').
POST	/api/save_training_photos	Admin-only. Saves an array of Base64-encoded photos for a new employee. Triggers model training.
POST	/api/train_model	Admin-only. Manually triggers the face recognition model training process.
POST	/admin/add_employee_complete	Admin-only. Saves a new employee's textual data to the database before proceeding to face capture.

Sources: app.py:1757, app.py:1289, app.py:1255, static/openapi.yaml:141-163

Conclusion

The Face Recognition Attendance system is a robust and accurate module built on the InsightFace model. It follows a logical two-part workflow, separating the administrative task of model training from the employee's daily task of attendance. The backend, powered by Flask, efficiently handles image processing and database interactions, while the frontend provides a simple, responsive interface for camera interaction on both desktop and mobile devices. This separation of concerns results in a secure and maintainable attendance solution.

Sources: README.md, app.py