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 StartExamplesModelsAPI 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 TopMade with ❤️ by the VisionFace team

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

visionface-1.0.0.tar.gz (428.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

visionface-1.0.0-py3-none-any.whl (73.9 kB view details)

Uploaded Python 3

File details

Details for the file visionface-1.0.0.tar.gz.

File metadata

  • Download URL: visionface-1.0.0.tar.gz
  • Upload date:
  • Size: 428.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for visionface-1.0.0.tar.gz
Algorithm Hash digest
SHA256 f7db88324fd553fe92cc9eacc5fb600a09008b3354c40243a329ab3debfc9368
MD5 48357776a49de87f885d8eb729219929
BLAKE2b-256 525809fa51cbb48ac72391371cacc507d7186309a6c5bd0a4182c3c4ab0eb67b

See more details on using hashes here.

File details

Details for the file visionface-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: visionface-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 73.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for visionface-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 86ed8cc041fd7063ce9295ef9e601ecd7427699532aa82058d8bb1441ff1cc8e
MD5 48e8bb90358a82256e8c1c7a3fd09a95
BLAKE2b-256 9a84ef3f5a03bf5f87062bfb7be27c88e21fb52aa27ee171e589b9f181d71df4

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page