Skip to main content

VisionFace

VisionFace

Python 3.8+ PyPI version License: MIT Downloads

Modern face detection, recognition & analysis in 3 lines of code

VisionFace is a state-of-the-art, open-source framework for comprehensive face analysis, built with PyTorch. It provides a unified interface for face detection, recognition, landmark detection, and visualization with support for multiple cutting-edge models.

Quick Start • Examples • Models • API Docs

Face Detection Face Recognition Face Landmarks
Face Analysis Face Verification Face Visualization

✨ What VisionFace Does

from VisionFace import FaceDetection, FaceRecognition

# Detect faces
detector = FaceDetection()
faces = detector.detect_faces("group_photo.jpg")

# Recognize faces  
recognizer = FaceRecognition()
matches = recognizer.search_faces("query.jpg", collection="my_team")
  • Detect faces in images with 12+ models (YOLO, MediaPipe, MTCNN...)
  • Recognize faces with vector search and embedding models
  • Extract landmarks (68-point, 468-point face mesh)
  • Batch process thousands of images efficiently
  • Production-ready with Docker support and REST API

🚀 Quick Start

pip install visionface

Face Detection

import cv2
from VisionFace import FaceDetection, FaceAnnotators

# 1. Initialize detector
detector = FaceDetection(detector_backbone="yolo-small")

# 2. Detect faces
image = cv2.imread("your_image.jpg")
faces = detector.detect_faces(image)

# 3. Visualize results
result = FaceAnnotators.box_annotator(image, faces)
cv2.imwrite("detected.jpg", result)

Face Recognition

from VisionFace import FaceRecognition

# 1. Setup recognition system
fr = FaceRecognition(detector_backbone="yolo-small", 
                     embedding_backbone="FaceNet-VGG")

# 2. Add known faces
fr.upsert_faces(
    images=["john.jpg", "jane.jpg", "bob.jpg"],
    labels=["John", "Jane", "Bob"],
    collection_name="employees"
)

# 3. Search for matches
matches = fr.search_faces("security_camera.jpg", 
                         collection_name="employees",
                         score_threshold=0.7)

for match in matches[0]:
    print(f"Found: {match['face_name']} (confidence: {match['score']:.2f})")

Face Embeddings

from VisionFace import FaceEmbedder

# 1. Initialize embedder
embedder = FaceEmbedder(embedding_backbone="FaceNet-VGG")

# 2. Generate embeddings for face images
embeddings = embedder.embed_faces(
    face_imgs=["face1.jpg", "face2.jpg"],
    normalize_embeddings=True  # L2 normalization
)

# 3. Use embeddings
for i, embedding in enumerate(embeddings):
    print(f"Face {i+1} embedding shape: {embedding.shape}")  # (512,)
    # Use for: face verification, clustering, custom databases

💡 Examples

🎯 Real-time Face Detection
import cv2
from VisionFace import FaceDetection, FaceAnnotators

detector = FaceDetection(detector_backbone="yolo-nano")  # Fastest model
cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    faces = detector.detect_faces(frame)
    annotated = FaceAnnotators.box_annotator(frame, faces)
    
    cv2.imshow('Face Detection', annotated)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()
📊 Batch Processing
from VisionFace import FaceDetection
import glob

detector = FaceDetection(detector_backbone="yolo-medium")

# Process entire folder
image_paths = glob.glob("photos/*.jpg")
images = [cv2.imread(path) for path in image_paths]

# Detect all faces at once
all_detections = detector.detect_faces(images)

# Save cropped faces
for i, detections in enumerate(all_detections):
    for j, face in enumerate(detections):
        if face.cropped_face is not None:
            cv2.imwrite(f"faces/image_{i}_face_{j}.jpg", face.cropped_face)
🔍 Face Landmarks
from VisionFace import LandmarkDetection, FaceAnnotators

landmark_detector = LandmarkDetection(detector_backbone="mediapipe")
image = cv2.imread("portrait.jpg")

# Get 468 facial landmarks
landmarks = landmark_detector.detect_landmarks(image)

# Visualize with connections
result = FaceAnnotators.landmark_annotator(
    image, landmarks[0], connections=True
)
cv2.imwrite("landmarks.jpg", result)
🏢 Employee Recognition System
from VisionFace import FaceRecognition
import os

# Initialize system
fr = FaceRecognition(db_backend="qdrant")

# Auto-enroll from employee photos folder
def enroll_employees(folder_path):
    for filename in os.listdir(folder_path):
        if filename.endswith(('.jpg', '.png')):
            name = filename.split('.')[0]  # Use filename as name
            image_path = os.path.join(folder_path, filename)
            
            fr.upsert_faces(
                images=[image_path],
                labels=[name],
                collection_name="company_employees"
            )
            print(f"Enrolled: {name}")

# Enroll all employees
enroll_employees("employee_photos/")

# Check security camera feed
def identify_person(camera_image):
    results = fr.search_faces(
        camera_image,
        collection_name="company_employees",
        score_threshold=0.8,
        top_k=1
    )
    
    if results[0]:  # If match found
        return results[0][0]['face_name']
    return "Unknown person"

🎯 Models

Choose the right model for your use case:

Use Case Speed Accuracy Recommended Model
🚀 Real-time apps ⚡⚡⚡ ⭐⭐ yolo-nano, mediapipe
🎯 General purpose ⚡⚡ ⭐⭐⭐ yolo-small (default)
🔍 High accuracy ⚡ ⭐⭐⭐⭐ yolo-large, mtcnn
📱 Mobile/Edge ⚡⚡⚡ ⭐⭐ mediapipe, yolo-nano
🎭 Landmarks needed ⚡⚡ ⭐⭐⭐ mediapipe, dlib
📋 Complete Model List

Detection Models:

  • yolo-nano, yolo-small, yolo-medium, yolo-large
  • yoloe-small, yoloe-medium, yoloe-large (prompt-based)
  • yolow-small, yolow-medium, yolow-large, yolow-xlarge (open-vocabulary)
  • mediapipe, mtcnn, opencv

Embedding Models:

  • FaceNet-VGG (512D) - Balanced accuracy/speed
  • FaceNet-CASIA (512D) - High precision
  • Dlib (128D) - Lightweight

Landmark Models:

  • mediapipe - 468 points + 3D mesh
  • dlib - 68 points, robust

📚 Documentation

🤝 Contributing

We welcome contributions! See our Contributing Guide.

Quick ways to help:

  • ⭐ Star the repo
  • 🐛 Report bugs
  • 💡 Request features
  • 📝 Improve docs
  • 🔧 Submit PRs

📄 License

MIT License - see LICENSE file.

🙏 Citation

@software{VisionFace2025,
  title = {VisionFace: Modern Face Detection & Recognition Framework},
  author = {VisionFace Team},
  year = {2025},
  url = {https://github.com/username/visionface}
}

⬆ Back to Top • Made with ❤️ by the VisionFace team

Metadata

Release files for visionface 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for visionface 1.0.0
File Size Uploaded
visionface-1.0.0.tar.gz 428.3 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for visionface 1.0.0
File Interpreter ABI Platform
visionface-1.0.0-py3-none-any.whl Python 3 none any Details

Total release size: 502.2 kB

Release files / visionface-1.0.0.tar.gz

Download URL visionface-1.0.0.tar.gz
Size 428.3 kB
Tags Source
SHA-256 checksum
How to use checksums
f7db88324fd553fe92cc9eacc5fb600a09008b3354c40243a329ab3debfc9368
BLAKE2b-256 checksum
How to use checksums
525809fa51cbb48ac72391371cacc507d7186309a6c5bd0a4182c3c4ab0eb67b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.3

Release files / visionface-1.0.0-py3-none-any.whl

Download URL visionface-1.0.0-py3-none-any.whl
Size 73.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
86ed8cc041fd7063ce9295ef9e601ecd7427699532aa82058d8bb1441ff1cc8e
BLAKE2b-256 checksum
How to use checksums
9a84ef3f5a03bf5f87062bfb7be27c88e21fb52aa27ee171e589b9f181d71df4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.12.3

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page