👤 Face Recognition System (Python / OpenCV)

This project implements a real-time face recognition system using Python, the face_recognition library (built on dlib), and OpenCV for video capture and display. The system requires a one-time encoding step to "train" the known faces and then runs a continuous loop to detect and identify people via a webcam.

🛠️ Requirements and Environment Setup

This project uses dependencies that include C++ binaries, making environment setup on Windows the most critical step.

Python Compatibility

Version	Status	Recommendation
Python 3.10.x to 3.12.x	Supported	✅
Python 3.13+	Incompatible	❌ Will lead to persistent dlib installation failures

We highly recommend using Python 3.11.x for maximum stability.

🔑 Windows Prerequisites (Critical!)

The installation requires two external C++ build tools to successfully compile the dlib dependency:

1. CMake: The cross-platform build system.

   • Action: Download the installer from cmake.org. Crucially, select "Add CMake to the system PATH" during installation.

2. Visual C++ Build Tools: The necessary compiler.

   • Action: Install Visual Studio Community (free) and select the "Desktop development with C++" workload during installation.

📦 Installation

Step 1: Create and Activate Virtual Environment

This prevents system-wide conflicts.

# Use the compatible python executable (e.g., py -3.11)
py -3.11 -m venv venv_311
.\venv_311\Scripts\activate

Step 2: Install Dependencies

pip install face_recognition opencv-python numpy

Step 3: Generate requirements.txt

For sharing your project:

pip freeze > requirements.txt

🗺️ Project Roadmap (The 3 Sequences)

The program was built in three logical sequences:

Sequence	File(s)	Goal
1. The Foundation	requirements.txt	Set up the compatible environment and install all necessary dependencies (dlib, CMake, VCC++).
2. The Core Logic	encode_faces.py	Convert images of known people into a numerical database (face_encodings.pkl).
3. The Program Loop	recognize_face.py	Load the database, capture video (OpenCV), perform real-time comparison, and display results.

📂 Project Structure

face_recognition_project/
├── known_faces/              # Input: Place images of people to be recognized here
│   ├── elon.jpg
│   └── mark.jpg
├── face_encodings.pkl        # Output: Generated by encode_faces.py (DO NOT EDIT)
├── encode_faces.py           # Script to run FIRST (Sequence 2)
├── recognize_face.py         # Script to run SECOND (Sequence 3)
└── requirements.txt          # File listing all dependencies

⚙️ Usage

Step 1: Prepare Data

1. Create the known_faces/ folder.
2. Place clear, forward-facing images inside it.
3. Name the file after the person (e.g., elon.jpg).

Step 2: Encode Faces

Run the encoding script once. This creates the recognition database:

python encode_faces.py

Expected Output: ✅ All known faces encoded and saved to face_encodings.pkl

Step 3: Run Recognition

Start the main program loop to activate your webcam and perform real-time recognition:

python recognize_face.py

To Exit: Press the q key when the webcam window is active.

⚠️ Troubleshooting Guide (Windows Errors)

This project often fails due to environment issues. If your initial installation fails, refer to these solutions:

Error	Cause	Solution
error: CMake is not installed on your system!	Missing required build tool.	Install CMake and ensure you check "Add CMake to the system PATH" during installation.
You must use Visual Studio to build a python extension...	Missing C++ compiler.	Install Visual Studio Community and select the "Desktop development with C++" workload.
PSSecurityException when activating venv	PowerShell security policy blocks local script execution.	Temporarily bypass the policy: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass then run .\venv_311\Scripts\activate
Please install face_recognition_models...	Python version is too new/incompatible (e.g., Python 3.13).	Downgrade to a stable version (e.g., Python 3.11.x) and create a new virtual environment using that executable.

✨ Future Improvements

For developers looking to extend this project:

• Batch Recognition: Implement a mode to process a folder full of static images (e.g., album photos) instead of a live webcam feed.

• Performance Tuning: Replace the simple cv2.resize() with a more advanced detection method (e.g., using face_locations with a higher model parameter) or integrate a GPU accelerated method if available.

• Confidence Threshold: Implement a system to display a recognition match only if the distance metric (returned by face_distance) is below a certain threshold (e.g., $0.6$).

• Logging: Integrate the logging module to save timestamps and names of recognized individuals to a CSV file.