
# Face Recognition Library

A comprehensive Python library for face detection and recognition with multiple example implementations.

**Built by KCEE Tech**

## Features

- Face detection and recognition using deep learning
- Multiple example implementations (webcam, image files, batch processing)
- Easy-to-use Python API
- Support for multiple face encodings and comparisons
- Real-time face recognition capabilities

## Prerequisites

- Python 3.8 or newer
- pip package manager
- C/C++ compiler (for dlib compilation)
- CMake (for building dependencies)

## Installation

### Method 1: Quick Setup (Recommended)

1. Create a virtual environment:
```bash
python -m venv face_recognition_env
```

2. Activate the virtual environment:
```bash
# Windows
face_recognition_env\Scripts\activate

# Linux/Mac
source face_recognition_env/bin/activate
```

3. Install dependencies:
```bash
pip install --upgrade pip setuptools wheel
pip install opencv-python numpy pillow
```

4. Install face recognition (if dlib installation fails, use OpenCV alternative):
```bash
pip install face_recognition
```

### Method 2: OpenCV Alternative (If dlib fails)

If you encounter dlib compilation issues, use the OpenCV-based demo:

```bash
pip install opencv-python numpy pillow
python examples/opencv_face_recognition_demo.py
```

## Usage

### Running Examples

1. **Webcam Face Recognition:**
```bash
python examples/facerec_from_webcam_fast.py
```

2. **Image File Recognition:**
```bash
python examples/recognize_faces_in_pictures.py
```

3. **Face Detection Only:**
```bash
python examples/find_faces_in_picture.py
```

4. **Digital Makeup Example:**
```bash
python examples/digital_makeup.py
```

5. **OpenCV Demo (Alternative):**
```bash
python examples/opencv_face_recognition_demo.py
```

### Basic Usage in Code

```python
import face_recognition
import cv2

# Load and encode a known face
known_image = face_recognition.load_image_file("known_person.jpg")
known_encoding = face_recognition.face_encodings(known_image)[0]

# Load an unknown image
unknown_image = face_recognition.load_image_file("unknown_person.jpg")
unknown_encodings = face_recognition.face_encodings(unknown_image)

# Compare faces
for encoding in unknown_encodings:
    results = face_recognition.compare_faces([known_encoding], encoding)
    if results[0]:
        print("Match found!")
```

## Troubleshooting

### dlib Installation Issues

If you encounter dlib compilation errors:

1. **Install Visual Studio Build Tools** (Windows):
   - Download from Microsoft Visual Studio website
   - Install C++ build tools

2. **Install CMake**:
   - Download from cmake.org
   - Add to system PATH

3. **Alternative: Use OpenCV**:
   - Use the provided OpenCV demo instead
   - Run: `python examples/opencv_face_recognition_demo.py`

### Common Issues

- **"No module named 'face_recognition'"**: Install using pip or use OpenCV alternative
- **Camera not found**: Check camera permissions and connections
- **Memory errors**: Reduce image size or use smaller face detection models

## Project Structure

```
face_recognition-master/
├── examples/                 # Example scripts and demos
├── face_recognition/         # Main library code
├── tests/                   # Unit tests
├── docs/                    # Documentation
├── requirements.txt         # Python dependencies
└── README.md               # This file
```

## Performance Tips

- Use `face_recognition.face_encodings()` with `num_jitters=1` for faster processing
- Resize large images before processing
- Use `face_recognition.face_locations()` with `model="cnn"` for better accuracy (slower)
- Use `model="hog"` for faster processing (less accurate)

## License

This project maintains its original license. Enhanced and documented by KCEE Tech.

## Support

For issues related to the KCEE Tech enhancements, please check the troubleshooting section above or refer to the example implementations provided.

