Robust Face Verification under Image Variations

Custom CNN + Contrastive Embedding and SVM‐based pipeline to verify identity between filtered selfies and clean profile photos, with optional DeepFace batch verification comparison.

---

📋 Description

This repository provides an end-to-end face verification pipeline:

1. Preprocess: Detect and crop faces from raw images (preprocess_faces.py)
2. Encode: Compute 128-D face embeddings (generate_encodings.py)
3. Train: Train a multi-class SVM on embeddings (train_model.py)
4. Test: Evaluate the trained model and save cropped predictions (test_model.py)
5. DeepFace Batch Verify: Optionally compare all image pairs using DeepFace (deepface_batch_verify_exp.py)

---

📂 Repository Structure

robust-face-verification/
├── .gitignore
├── LICENSE
├── README.md
├── requirements.txt
├── Data/
│   ├── Raw/
│   │   ├── Sample/
│   │   │   ├── img1.jpg
│   │   │   └── img2.jpg
│   │   └── to_check/                        # Images to run inference on
│   └── processed/
│       ├── cropped/                         # Cropped faces (auto-created)
│       ├── encodings.pkl                    # Serialized embeddings (auto-generated)
├── results/
│   ├── model.pkl                            # Trained SVM model
│   ├── found/                               # Cropped detected faces
│   └── deepface_verification_results.csv    # DeepFace brute-force pairwise verification result 
├── src/
│   ├── preprocess_faces.py                  # Detect & crop faces
│   ├── generate_encodings.py                # Compute & save embeddings
│   ├── train_model.py                       # Train SVM on embeddings
│   ├── test_model.py                        # Load model, predict on images
│   └── deepface_batch_verify_exp.py         # DeepFace brute-force pairwise verification

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/Siddharthsinghkumar/robust-face-verification.git
cd robust-face-verification

2. Create & Activate a Virtual Environment

Use a virtual environment to avoid system conflicts:

python3 -m venv .venv
source .venv/bin/activate

3. Install All Dependencies

pip install --upgrade pip
pip install -r requirements.txt

This installs:

• opencv-python (for cv2)
• numpy, scikit-learn, matplotlib, torch, torchvision
• setuptools & wheel (required by face_recognition_models)
• dlib, face_recognition, face_recognition_models (for embedding & verification)
• deepface (for optional DeepFace verification)
• tf-keras (required by RetinaFace when using DeepFace with TensorFlow ≥2.19)

Troubleshooting:

• cv2 ModuleNotFoundError: Ensure opencv-python is listed and run pip install opencv-python.
• pkg_resources ModuleNotFoundError: Install setuptools and wheel via pip install setuptools wheel.
• face_recognition_models not found: Ensure it is listed as:

  face_recognition_models @ git+https://github.com/ageitgey/face_recognition_models
  

  in requirements.txt and reinstall:

  pip install -r requirements.txt

---

▶️ Running the Pipeline

1. Preprocess & Crop Faces

Detect and crop faces from each identity folder under Data/Raw/:

python3 src/preprocess_faces.py   --input Data/Raw/<IdentityName>   --output Data/processed/cropped/<IdentityName>

• Defaults: --input Data/Raw/Sample and --output Data/processed/cropped.

2. Generate Face Embeddings

Compute embeddings for all cropped faces (organizing labels by folder name):

python3 src/generate_encodings.py   --input Data/processed/cropped   --output Data/processed/encodings.pkl

• Each subfolder under Data/processed/cropped/ is treated as a separate identity label.

3. Train the SVM Model

Train a multi-class SVM using embeddings and labels:

python3 src/train_model.py   --encodings Data/processed/encodings.pkl   --output results/model.pkl

• Error “number of classes > 1”: Ensure you have at least two identity folders in Data/processed/cropped/.

4. Test & Predict on New Images

Load the trained model and predict on images in Data/Raw/to_check/:

python3 src/test_model.py   --model results/model.pkl   --test_dir Data/Raw/to_check   --detected_dir results/found   --not_detected_dir Data/processed/not_found

• Saves cropped faces labeled with predicted identity in results/found/.
• If no face detected in an image, it is copied to Data/processed/not_found/.

5. (Optional) DeepFace Batch Verification

By default, you can now just run:

python3 src/deepface_batch_verify_exp.py

• It will look in results/found/ and write to results/deepface_verification_results.csv.

To override defaults:

python3 src/deepface_batch_verify_exp.py   --dataset path/to/another/folder   --output path/to/results.csv

---

📝 Detailed Troubleshooting & Notes

1. Missing Dependencies

   • If ModuleNotFoundError: No module named 'cv2', run pip install opencv-python.
   • If ModuleNotFoundError: No module named 'sklearn', run pip install scikit-learn.
   • If ModuleNotFoundError: No module named 'pkg_resources', run pip install setuptools wheel.
   • If face_recognition_models still fails, ensure it is listed as

     face_recognition_models @ git+https://github.com/ageitgey/face_recognition_models
     

     in requirements.txt and reinstall:

     pip install -r requirements.txt

2. SVM Training Error

   ValueError: The number of classes has to be greater than one; got 1 class
   

   • Occurs when you only have one identity in Data/processed/cropped. Add at least two identity folders (e.g., AngelinaJolie, BradPitt) before generating embeddings.

3. False Positives During Testing

   • If SVM was trained on only one class, it labels every face as that class.
   • Solution: Include multiple classes, or switch to a distance-threshold verification approach (see face_recognition_util.py for helper functions).

4. DeepFace Verification Errors

   • If you see an error like:

     ValueError: You have tensorflow 2.19.0 and this requires tf-keras package. Please run `pip install tf-keras` or downgrade your tensorflow.
     

     simply install tf-keras (already added to requirements.txt) or downgrade TensorFlow.
   • DeepFace can be slow if you have many images. For large datasets, consider cropping & verifying in smaller batches.

---

📦 Requirements (requirements.txt)

opencv-python>=4.5.0
numpy>=1.19.0
scikit-learn>=1.0.0
matplotlib>=3.3.0
torch>=1.8.0
torchvision>=0.9.0
setuptools>=40.0.0
wheel>=0.30.0
dlib>=19.7.0
face_recognition>=1.3.0
face_recognition_models @ git+https://github.com/ageitgey/face_recognition_models
deepface>=0.0.75
tf-keras>=2.19.0

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.