File Structure

project_root/
├── app/
│   ├── __init__.py
│   ├── attendance_app.py    # Main application class (GUI + logic)
│   └── about_app.py         # About tab content
│
├── face/
│   ├── __init__.py
│   └── face_manager.py      # DNN detection + LBPH recognition + training
│
├── data/
│   ├── __init__.py
│   └── database.py          # SQLite CRUD operations
│
├── models/                  # Pre-trained DNN files (must be downloaded)
│   └── dnn/
│       ├── deploy.prototxt
│       └── res10_300x300_ssd_iter_140000_fp16.caffemodel
│
├── images/                  # Stored face crops (auto-created)
├── exports/                 # CSV exports (auto-created)
├── main.py                  # Application entry point
├── wipe_db_script.py        # Utility to reset all data
└── requirements.txt

Core Design Patterns

FaceManager – Encapsulation of Computer Vision Logic

FaceManager centralises all face-related operations: loading the DNN network, detecting faces in a frame, extracting and resizing face ROIs, performing LBPH recognition, and training the model on newly registered persons. It manages the persistence of the LBPH model and loads it automatically at startup.

class FaceManager:
    def __init__(self):
        self.face_net = cv2.dnn.readNetFromCaffe(...)
        self.recognizer = cv2.face.LBPHFaceRecognizer_create()
        self.load_model()

Database Abstraction

All SQLite operations are wrapped in simple functions in database.py (e.g., add_person, log_attendance, get_all_sessions). The module handles connection management using context managers, ensuring transactions are properly committed or rolled back.

Threading for Responsive Registration

Registration involves capturing multiple face crops (~4 seconds) and then training the LBPH model. Training runs in a background thread while a timer updates the UI with elapsed time.

thread = threading.Thread(target=self._do_registration, daemon=True)
thread.start()
self._update_processing_timer()   # updates status label every 500ms

Polymorphism – Single Display Method

A single display_frame() method handles video feeds across both tabs, with configurable target dimensions.

Key Features

• Face Registration — Capture multiple face images while the user moves their head; train the LBPH model incrementally.
• Attendance Sessions — Start a named session; recognised persons are automatically logged once per session.
• Real-time Feedback — Displays detected faces with names/status on the video feed; a side panel logs every event.
• CSV Export — Export any past session to a CSV file with full timestamps.
• Offline Operation — No external network calls; all data stays on the local machine.
• Reset Functionality — Wipe all persons, sessions, images, and the trained model with a single click.

Workflow & Lifecycle

Registration Flow

1. User enters a name and clicks Register Person.
2. The camera starts a 4-second capture phase; the user slowly moves their head while the system collects face crops (every 0.25 s).
3. A progress bar and countdown are overlaid on the video feed.
4. If at least 10 faces are captured, training runs in a background thread.
5. On completion, the model is updated and the new person is stored in the database.

Attendance Session Flow

1. User enters a session name and clicks Start Attendance.
2. A session record is created in SQLite and an empty CSV is initialised.
3. For each frame, faces are detected and recognised.
4. If a recognised person is not yet logged in the session, their name and timestamp are appended to the CSV and the database.
5. The video feedback shows:
   • 🟢 Green — "Registered in session"
   • 🟡 Yellow — "Already registered"
   • 🔴 Red — Unknown face
6. Click Stop Attendance to end the session; the CSV is finalised with start/end times.

Code Highlights

Face Detection with DNN

The DNN expects a 300×300 blob; detections are filtered by a confidence threshold and bounding boxes are scaled back to the original frame dimensions.

blob = cv2.dnn.blobFromImage(cv2.resize(frame, (300, 300)), 1.0, (300, 300), (104.0, 177.0, 123.0))
self.face_net.setInput(blob)
detections = self.face_net.forward()

LBPH Recognition and Confidence

LBPH returns a label and confidence score (lower = better). If confidence is below the threshold (default 70), the person is considered recognised.

label, confidence = self.recognizer.predict(face_roi)
if confidence < CONFIDENCE_THRESHOLD:
    name = get_person_name_by_id(label)

Overlay Feedback During Registration

A semi-transparent overlay displays the app name, status message, countdown, captured face count, and a progress bar.

overlay = frame.copy()
cv2.rectangle(overlay, (10, 10), (w - 10, 190), (0, 0, 0), -1)
frame = cv2.addWeighted(overlay, 0.45, frame, 0.55, 0)

CSV Export with Metadata

Each export writes session metadata followed by a header row and all attendance records.

writer.writerow(["Session ID", session_id])
writer.writerow(["Session Name", session_name])
writer.writerow(["Start Time", start_time])
writer.writerow(["End Time", end_time])
writer.writerow([])
writer.writerow(["Name", "Timestamp"])
writer.writerows(records)

Thread-Safe Status Updates

UI updates from the registration background thread are scheduled via root.after() to keep Tkinter responsive.

def _update_processing_timer(self):
    if not self._reg_timer_running:
        return
    elapsed = time.time() - self._reg_start_time
    self.set_reg_status(f"Processing registration... {elapsed:.1f}s", fg="blue")
    self.root.after(500, self._update_processing_timer)

Setup & Installation

Prerequisites

• Python 3.8 or higher
• A working webcam

1. Clone the repository

git clone <repository-url>
cd facial-recognition-attendance

2. Install dependencies

pip install -r requirements.txt

requirements.txt:

opencv-python>=4.5
opencv-contrib-python>=4.5   # required for LBPH
Pillow>=9.0

3. Download the DNN model files

The application uses the res10_300x300_ssd_iter_140000_fp16 model. Download the following two files and place them in models/dnn/:

• deploy.prototxt
• res10_300x300_ssd_iter_140000_fp16.caffemodel

4. Run the application

python main.py

Troubleshooting

Data Management

To reset everything completely and start fresh:

python wipe_db_script.py

This deletes the database, the images/ and exports/ folders, and the model file.

Upcoming Improvements

I plan to replace the current face detection model with a more robust, modern architecture (e.g., YOLO‑face or RetinaFace) to improve accuracy in challenging lighting and pose conditions. This upgrade will also bring:

Better handling of partial occlusions and side profiles.

Faster inference with optional GPU support.

Improved confidence scoring for more reliable attendance logging.

Estimated timeline: Next major release within 2‑3 months.

License

This project is provided for educational and non-commercial use.