VisionFace
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
✨ 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-largeyoloe-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/speedFaceNet-CASIA(512D) - High precisionDlib(128D) - Lightweight
Landmark Models:
mediapipe- 468 points + 3D meshdlib- 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)
| File | Size | Uploaded | |
|---|---|---|---|
| visionface-1.0.0.tar.gz | 428.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| 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
|