faceverify-sdk 1.0.0rc1

A modular, open-source face verification SDK for Python

FaceVerify

A modular, open-source face verification SDK for Python.

FaceVerify provides a complete pipeline for face detection, embedding generation, similarity comparison, and identity verification with a clean, extensible architecture.

Face Detection --> Embedding Generator --> Similarity Engine --> Decision Engine --> Verified / Not Verified

---

Table of Contents

• Features
• How It Works
• Models Used
• Installation
• Quick Start
• CLI Usage
• Configuration
• API Reference
• Testing
• Docker
• Project Structure
• Contributing
• License
• Contact

---

Features

• Multi-backend Detection - OpenCV, MTCNN, RetinaFace, MediaPipe support
• State-of-the-art Embeddings - DeepFace with Facenet512 model (512-dimensional vectors)
• Multiple Similarity Metrics - Cosine, Euclidean, Manhattan distance calculations
• Adaptive Decision Making - Threshold-based and adaptive verification
• GPU Acceleration - Optional CUDA support for faster processing
• Comprehensive CLI - Command-line interface for quick verification
• Batch Processing - Process multiple image pairs efficiently
• Well Tested - Unit tests and integration tests included
• Configurable - YAML/JSON configuration, environment variables

---

How It Works

FaceVerify uses a multi-stage pipeline to verify if two face images belong to the same person:

Stage 1: Face Detection

The detector locates faces in the input images and extracts the face regions. Multiple backends are supported:

Backend	Description	Speed	Accuracy
OpenCV	Haar Cascade / DNN based	Fast	Good
MTCNN	Multi-task CNN	Medium	Very Good
RetinaFace	Deep learning based	Slow	Excellent
MediaPipe	Google MediaPipe	Fast	Good

Stage 2: Embedding Generation

The detected face is converted into a 512-dimensional numerical vector (embedding) that represents the unique facial features. This uses the Facenet512 model via DeepFace.

Stage 3: Similarity Calculation

The embeddings from both images are compared using distance metrics:

• Cosine Similarity - Measures angle between vectors (default)
• Euclidean Distance - Measures straight-line distance
• Manhattan Distance - Measures grid-based distance

Stage 4: Decision Engine

The similarity score is compared against a threshold (default: 0.65) to determine if the faces match:

• Similarity >= Threshold --> VERIFIED (Same Person)
• Similarity < Threshold --> NOT VERIFIED (Different People)

---

Models Used

Component	Model	Details
Face Embedding	Facenet512	512-dimensional embeddings, trained on MS-Celeb-1M and VGGFace2
Face Detection	OpenCV DNN	Pre-trained Caffe model for face detection
Similarity	Cosine Similarity	Normalized dot product of embedding vectors

[!NOTE] The Facenet512 model weights are automatically downloaded on first use (~90MB). Subsequent runs use the cached model.

---

Installation

Requirements

• Python 3.8 or higher
• pip package manager

Install from PyPI

pip install faceverify-sdk

Install Pre-release Version

pip install faceverify-sdk --pre

Install from Source

git clone https://github.com/nayandas69/faceverify.git
cd faceverify
pip install -e .

Install with Development Dependencies

git clone https://github.com/nayandas69/faceverify.git
cd faceverify
pip install -e ".[dev]"

Dependencies

The main dependencies are automatically installed:

deepface>=0.0.79
tf-keras>=2.15.0
opencv-python>=4.8.0
numpy>=1.24.0
Pillow>=10.0.0
pyyaml>=6.0

[!IMPORTANT] On first run, DeepFace will download the Facenet512 model weights. Ensure you have an internet connection.

---

Quick Start

Basic Verification

from faceverify import FaceVerifier

# Initialize the verifier
verifier = FaceVerifier()

# Verify two faces
result = verifier.verify("person1.jpg", "person2.jpg")

print(f"Verified: {result.verified}")
print(f"Confidence: {result.confidence:.2%}")
print(f"Similarity: {result.similarity:.4f}")

Output Example

Verified: True
Confidence: 92.31%
Similarity: 0.9231

Advanced Configuration

from faceverify import FaceVerifier
from faceverify.config import VerifierConfig

# Custom configuration
config = VerifierConfig(
    detector_backend="opencv",
    embedding_model="facenet512",
    similarity_metric="cosine",
    threshold=0.65,
    enable_gpu=False
)

verifier = FaceVerifier(config)
result = verifier.verify("image1.jpg", "image2.jpg")

---

CLI Usage

FaceVerify includes a command-line interface for quick operations.

Check Version

python -m faceverify --version

Verify Two Images

python -m faceverify verify path/to/image1.jpg path/to/image2.jpg

Verify with Custom Threshold

python -m faceverify verify image1.jpg image2.jpg -t 0.70

Detect Faces in Image

python -m faceverify detect image.jpg

Show System Info

python -m faceverify info

Batch Verification from CSV

python -m faceverify batch pairs.csv -o results.json

CSV format:

image1,image2
path/to/face1.jpg,path/to/face2.jpg
path/to/face3.jpg,path/to/face4.jpg

[!TIP] Use python -m faceverify --help to see all available commands and options.

---

Configuration

YAML Configuration

Create a config.yaml file:

detector:
  backend: "opencv"
  confidence_threshold: 0.9
  
embedding:
  model: "facenet512"
  normalize: true
  
similarity:
  metric: "cosine"
  
decision:
  threshold: 0.65
  adaptive: false
  
performance:
  enable_gpu: false
  batch_size: 32

Load configuration:

from faceverify import FaceVerifier
from faceverify.config import VerifierConfig

config = VerifierConfig.from_yaml("config.yaml")
verifier = FaceVerifier(config)

Environment Variables

export FACEVERIFY_DETECTOR=opencv
export FACEVERIFY_EMBEDDING_MODEL=facenet512
export FACEVERIFY_THRESHOLD=0.65
export FACEVERIFY_ENABLE_GPU=false

---

API Reference

FaceVerifier Class

class FaceVerifier:
    def __init__(self, config: Optional[VerifierConfig] = None)
    def verify(self, image1, image2) -> VerificationResult
    def verify_batch(self, pairs: List[Tuple]) -> List[VerificationResult]
    def identify(self, query, database) -> List[IdentificationResult]
    def extract_embedding(self, image) -> np.ndarray
    def detect_faces(self, image) -> List[Face]

VerificationResult Dataclass

@dataclass
class VerificationResult:
    verified: bool          # True if faces match
    confidence: float       # Confidence score (0-1)
    similarity: float       # Raw similarity score
    distance: float         # Distance between embeddings
    threshold: float        # Threshold used for decision
    detector_backend: str   # Detection backend used
    embedding_model: str    # Embedding model used
    processing_time: float  # Time taken in seconds

Configuration Options

Parameter	Type	Default	Description
detector_backend	str	"opencv"	Face detection backend
embedding_model	str	"facenet512"	Embedding model to use
similarity_metric	str	"cosine"	Similarity calculation method
threshold	float	0.65	Verification threshold
enable_gpu	bool	False	Enable GPU acceleration
min_face_size	int	20	Minimum face size in pixels

---

Testing

Run All Tests

pytest tests/ -v

Run with Coverage Report

pytest tests/ --cov=src/faceverify --cov-report=html

Run Specific Test File

pytest tests/unit/test_similarity.py -v

Run Integration Tests

pytest tests/integration/ -v

[!CAUTION] Always run tests locally before pushing changes to ensure nothing is broken.

---

Docker

Build Image

docker build -t faceverify .

Run Container

docker run -p 8000:8000 faceverify

Docker Compose

docker-compose up

Run Verification in Container

docker run -v $(pwd)/images:/images faceverify python -m faceverify verify /images/face1.jpg /images/face2.jpg

---

Project Structure

faceverify/
├── src/
│   └── faceverify/
│       ├── __init__.py          # Package initialization
│       ├── __main__.py          # CLI entry point
│       ├── core/
│       │   ├── verifier.py      # Main FaceVerifier class
│       │   ├── pipeline.py      # Verification pipeline
│       │   └── result.py        # Result dataclasses
│       ├── detection/
│       │   ├── base.py          # Abstract detector
│       │   ├── opencv.py        # OpenCV implementation
│       │   └── factory.py       # Detector factory
│       ├── embedding/
│       │   ├── base.py          # Abstract embedder
│       │   ├── facenet.py       # DeepFace/Facenet512 implementation
│       │   └── factory.py       # Embedder factory
│       ├── similarity/
│       │   ├── metrics.py       # Distance metrics
│       │   └── engine.py        # Similarity engine
│       ├── decision/
│       │   ├── threshold.py     # Threshold-based decision
│       │   └── adaptive.py      # Adaptive threshold
│       ├── config/
│       │   ├── settings.py      # Configuration classes
│       │   └── defaults.py      # Default values
│       ├── cli/
│       │   └── __init__.py      # CLI implementation
│       ├── utils/
│       │   ├── image.py         # Image utilities
│       │   └── validators.py    # Input validation
│       └── exceptions/
│           └── errors.py        # Custom exceptions
├── tests/
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── examples/                    # Usage examples
├── configs/                     # Configuration files
├── pyproject.toml               # Project metadata
├── requirements.txt             # Dependencies
├── Dockerfile                   # Docker configuration
├── LICENSE                      # MIT License
├── CONTRIBUTING.md              # Contribution guidelines
├── CHANGELOG.md                 # Version history
└── README.md                    # This file

---

Contributing

Contributions are welcome! Please follow these steps:

Before You Start

1. Fork the repository
2. Clone your fork locally
3. Create a virtual environment and install dev dependencies

git clone https://github.com/YOUR_USERNAME/faceverify.git
cd faceverify
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Making Changes

1. Create a new branch for your feature/fix
2. Make your changes
3. Format code with Black
4. Run tests locally

git checkout -b feature/your-feature-name
# Make your changes
black src/ tests/
pytest tests/ -v

[!WARNING] Do not push without running formatters and tests. PRs with failing tests will not be merged.

Submitting

1. Commit with clear messages
2. Push to your fork
3. Create a Pull Request

git add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name

Commit Message Format

Use Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• test: - Adding or updating tests
• refactor: - Code refactoring
• chore: - Maintenance tasks

[!IMPORTANT] Always test your changes locally before submitting a PR. Run pytest tests/ -v to ensure all tests pass.

---

Uninstallation

To remove FaceVerify from your system:

pip uninstall faceverify-sdk

To remove all dependencies:

pip uninstall faceverify-sdk deepface tf-keras opencv-python numpy Pillow pyyaml

---

Troubleshooting

Common Issues

Issue: Model download fails

[!TIP] Ensure you have a stable internet connection. The Facenet512 model is downloaded from GitHub on first run.

Issue: No face detected

[!NOTE] Ensure the image contains a clearly visible face. The minimum face size is 20x20 pixels by default.

Issue: Low accuracy

[!TIP] Try adjusting the threshold value. Lower threshold = more strict matching. Default is 0.65.

Issue: GPU not detected

[!NOTE] Ensure CUDA and cuDNN are properly installed. Set enable_gpu=True in config.

---

License

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

---

Contact

Nayan Das - @nayandas69

Project Link: https://github.com/nayandas69/faceverify

---

Made with dedication in Bangladesh by Nayan Das