# VisionFace
<div align="center">
<img src="banners/VisionFace2.png" alt="VisionFace"/></td>
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/visionface)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/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](#-quick-start) • [Examples](#-examples) • [Models](#-models) • [API Docs](https://visionface.readthedocs.io)
</div>
<div align="center">
<table>
<tr>
<td><img src="banners/face_detection.jpg" alt="Face Detection" width="500"/></td>
<td><img src="banners/face_recognition.jpg" alt="Face Recognition" width="500"/></td>
<td><img src="banners/face_landmarks.jpg" alt="Face Landmarks" width="500"/></td>
</tr>
<tr>
<td><img src="banners/face_analysis.jpg" alt="Face Analysis" width="500"/></td>
<td><img src="banners/face_verification.jpg" alt="Face Verification" width="500"/></td>
<td><img src="banners/face_visualization.jpg" alt="Face Visualization" width="500"/></td>
</tr>
</table>
</div>
## ✨ What VisionFace Does
```python
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
```bash
pip install visionface
```
### Face Detection
```python
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
```python
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
```python
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
<details>
<summary><b>🎯 Real-time Face Detection</b></summary>
```python
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()
```
</details>
<details>
<summary><b>📊 Batch Processing</b></summary>
```python
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)
```
</details>
<details>
<summary><b>🔍 Face Landmarks</b></summary>
```python
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)
```
</details>
<details>
<summary><b>🏢 Employee Recognition System</b></summary>
```python
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"
```
</details>
## 🎯 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` |
<details>
<summary><b>📋 Complete Model List</b></summary>
**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
</details>
## 📚 Documentation
- 📖 [Full Documentation](https://visionface.readthedocs.io)
- 🎓 [Tutorials & Guides](https://visionface.readthedocs.io/tutorials)
- 🔌 [REST API Reference](https://visionface.readthedocs.io/api)
- 💡 [Use Case Examples](https://github.com/username/visionface/tree/main/examples)
## 🤝 Contributing
We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md).
**Quick ways to help:**
- ⭐ Star the repo
- 🐛 Report bugs
- 💡 Request features
- 📝 Improve docs
- 🔧 Submit PRs
## 📄 License
MIT License - see [LICENSE](LICENSE) file.
## 🙏 Citation
```bibtex
@software{VisionFace2025,
title = {VisionFace: Modern Face Detection & Recognition Framework},
author = {VisionFace Team},
year = {2025},
url = {https://github.com/username/visionface}
}
```
---
<div align="center">
**[⬆ Back to Top](#visionface)** • **Made with ❤️ by the VisionFace team**
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/miladfa7/visionface",
"name": "visionface",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "computer-vision, face-detection, face-recognition, facial-landmarks, deep-learning, pytorch, yolo, mediapipe, artificial-intelligence, biometrics, image-processing, real-time, production-ready",
"author": "VisionFace Team",
"author_email": "visio.face2025@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/52/58/09fa51cbb48ac72391371cacc507d7186309a6c5bd0a4182c3c4ab0eb67b/visionface-1.0.0.tar.gz",
"platform": "any",
"description": "# VisionFace\n\n<div align=\"center\">\n\n<img src=\"banners/VisionFace2.png\" alt=\"VisionFace\"/></td>\n\n[](https://www.python.org/downloads/)\n[](https://badge.fury.io/py/visionface)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/visionface)\n\n\n**Modern face detection, recognition & analysis in 3 lines of code**\n\nVisionFace 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.\n\n[Quick Start](#-quick-start) \u2022 [Examples](#-examples) \u2022 [Models](#-models) \u2022 [API Docs](https://visionface.readthedocs.io)\n\n</div>\n\n<div align=\"center\">\n<table>\n <tr>\n <td><img src=\"banners/face_detection.jpg\" alt=\"Face Detection\" width=\"500\"/></td>\n <td><img src=\"banners/face_recognition.jpg\" alt=\"Face Recognition\" width=\"500\"/></td>\n <td><img src=\"banners/face_landmarks.jpg\" alt=\"Face Landmarks\" width=\"500\"/></td>\n\n </tr>\n <tr>\n <td><img src=\"banners/face_analysis.jpg\" alt=\"Face Analysis\" width=\"500\"/></td>\n <td><img src=\"banners/face_verification.jpg\" alt=\"Face Verification\" width=\"500\"/></td>\n <td><img src=\"banners/face_visualization.jpg\" alt=\"Face Visualization\" width=\"500\"/></td>\n </tr>\n</table>\n</div>\n\n## \u2728 What VisionFace Does\n\n\n```python\nfrom VisionFace import FaceDetection, FaceRecognition\n\n# Detect faces\ndetector = FaceDetection()\nfaces = detector.detect_faces(\"group_photo.jpg\")\n\n# Recognize faces \nrecognizer = FaceRecognition()\nmatches = recognizer.search_faces(\"query.jpg\", collection=\"my_team\")\n```\n\n- **Detect faces** in images with 12+ models (YOLO, MediaPipe, MTCNN...)\n- **Recognize faces** with vector search and embedding models\n- **Extract landmarks** (68-point, 468-point face mesh)\n- **Batch process** thousands of images efficiently\n- **Production-ready** with Docker support and REST API\n\n## \ud83d\ude80 Quick Start\n\n```bash\npip install visionface\n```\n\n### Face Detection \n\n```python\nimport cv2\nfrom VisionFace import FaceDetection, FaceAnnotators\n\n# 1. Initialize detector\ndetector = FaceDetection(detector_backbone=\"yolo-small\")\n\n# 2. Detect faces\nimage = cv2.imread(\"your_image.jpg\")\nfaces = detector.detect_faces(image)\n\n# 3. Visualize results\nresult = FaceAnnotators.box_annotator(image, faces)\ncv2.imwrite(\"detected.jpg\", result)\n```\n\n### Face Recognition\n\n```python\nfrom VisionFace import FaceRecognition\n\n# 1. Setup recognition system\nfr = FaceRecognition(detector_backbone=\"yolo-small\", \n embedding_backbone=\"FaceNet-VGG\")\n\n# 2. Add known faces\nfr.upsert_faces(\n images=[\"john.jpg\", \"jane.jpg\", \"bob.jpg\"],\n labels=[\"John\", \"Jane\", \"Bob\"],\n collection_name=\"employees\"\n)\n\n# 3. Search for matches\nmatches = fr.search_faces(\"security_camera.jpg\", \n collection_name=\"employees\",\n score_threshold=0.7)\n\nfor match in matches[0]:\n print(f\"Found: {match['face_name']} (confidence: {match['score']:.2f})\")\n```\n\n### Face Embeddings \n\n```python\nfrom VisionFace import FaceEmbedder\n\n# 1. Initialize embedder\nembedder = FaceEmbedder(embedding_backbone=\"FaceNet-VGG\")\n\n# 2. Generate embeddings for face images\nembeddings = embedder.embed_faces(\n face_imgs=[\"face1.jpg\", \"face2.jpg\"],\n normalize_embeddings=True # L2 normalization\n)\n\n# 3. Use embeddings\nfor i, embedding in enumerate(embeddings):\n print(f\"Face {i+1} embedding shape: {embedding.shape}\") # (512,)\n # Use for: face verification, clustering, custom databases\n```\n## \ud83d\udca1 Examples\n\n<details>\n<summary><b>\ud83c\udfaf Real-time Face Detection</b></summary>\n\n```python\nimport cv2\nfrom VisionFace import FaceDetection, FaceAnnotators\n\ndetector = FaceDetection(detector_backbone=\"yolo-nano\") # Fastest model\ncap = cv2.VideoCapture(0)\n\nwhile True:\n ret, frame = cap.read()\n faces = detector.detect_faces(frame)\n annotated = FaceAnnotators.box_annotator(frame, faces)\n \n cv2.imshow('Face Detection', annotated)\n if cv2.waitKey(1) & 0xFF == ord('q'):\n break\n\ncap.release()\ncv2.destroyAllWindows()\n```\n</details>\n\n<details>\n<summary><b>\ud83d\udcca Batch Processing</b></summary>\n\n```python\nfrom VisionFace import FaceDetection\nimport glob\n\ndetector = FaceDetection(detector_backbone=\"yolo-medium\")\n\n# Process entire folder\nimage_paths = glob.glob(\"photos/*.jpg\")\nimages = [cv2.imread(path) for path in image_paths]\n\n# Detect all faces at once\nall_detections = detector.detect_faces(images)\n\n# Save cropped faces\nfor i, detections in enumerate(all_detections):\n for j, face in enumerate(detections):\n if face.cropped_face is not None:\n cv2.imwrite(f\"faces/image_{i}_face_{j}.jpg\", face.cropped_face)\n```\n</details>\n\n<details>\n<summary><b>\ud83d\udd0d Face Landmarks</b></summary>\n\n```python\nfrom VisionFace import LandmarkDetection, FaceAnnotators\n\nlandmark_detector = LandmarkDetection(detector_backbone=\"mediapipe\")\nimage = cv2.imread(\"portrait.jpg\")\n\n# Get 468 facial landmarks\nlandmarks = landmark_detector.detect_landmarks(image)\n\n# Visualize with connections\nresult = FaceAnnotators.landmark_annotator(\n image, landmarks[0], connections=True\n)\ncv2.imwrite(\"landmarks.jpg\", result)\n```\n</details>\n\n<details>\n<summary><b>\ud83c\udfe2 Employee Recognition System</b></summary>\n\n```python\nfrom VisionFace import FaceRecognition\nimport os\n\n# Initialize system\nfr = FaceRecognition(db_backend=\"qdrant\")\n\n# Auto-enroll from employee photos folder\ndef enroll_employees(folder_path):\n for filename in os.listdir(folder_path):\n if filename.endswith(('.jpg', '.png')):\n name = filename.split('.')[0] # Use filename as name\n image_path = os.path.join(folder_path, filename)\n \n fr.upsert_faces(\n images=[image_path],\n labels=[name],\n collection_name=\"company_employees\"\n )\n print(f\"Enrolled: {name}\")\n\n# Enroll all employees\nenroll_employees(\"employee_photos/\")\n\n# Check security camera feed\ndef identify_person(camera_image):\n results = fr.search_faces(\n camera_image,\n collection_name=\"company_employees\",\n score_threshold=0.8,\n top_k=1\n )\n \n if results[0]: # If match found\n return results[0][0]['face_name']\n return \"Unknown person\"\n```\n</details>\n\n## \ud83c\udfaf Models\n\n**Choose the right model for your use case:**\n\n| Use Case | Speed | Accuracy | Recommended Model |\n|----------|-------|----------|------------------|\n| \ud83d\ude80 **Real-time apps** | \u26a1\u26a1\u26a1 | \u2b50\u2b50 | `yolo-nano`, `mediapipe` |\n| \ud83c\udfaf **General purpose** | \u26a1\u26a1 | \u2b50\u2b50\u2b50 | `yolo-small` (default) |\n| \ud83d\udd0d **High accuracy** | \u26a1 | \u2b50\u2b50\u2b50\u2b50 | `yolo-large`, `mtcnn` |\n| \ud83d\udcf1 **Mobile/Edge** | \u26a1\u26a1\u26a1 | \u2b50\u2b50 | `mediapipe`, `yolo-nano` |\n| \ud83c\udfad **Landmarks needed** | \u26a1\u26a1 | \u2b50\u2b50\u2b50 | `mediapipe`, `dlib` |\n\n<details>\n<summary><b>\ud83d\udccb Complete Model List</b></summary>\n\n**Detection Models:**\n- `yolo-nano`, `yolo-small`, `yolo-medium`, `yolo-large`\n- `yoloe-small`, `yoloe-medium`, `yoloe-large` (prompt-based) \n- `yolow-small`, `yolow-medium`, `yolow-large`, `yolow-xlarge` (open-vocabulary)\n- `mediapipe`, `mtcnn`, `opencv`\n\n**Embedding Models:**\n- `FaceNet-VGG` (512D) - Balanced accuracy/speed\n- `FaceNet-CASIA` (512D) - High precision\n- `Dlib` (128D) - Lightweight\n\n**Landmark Models:**\n- `mediapipe` - 468 points + 3D mesh\n- `dlib` - 68 points, robust\n</details>\n\n\n## \ud83d\udcda Documentation\n\n- \ud83d\udcd6 [Full Documentation](https://visionface.readthedocs.io)\n- \ud83c\udf93 [Tutorials & Guides](https://visionface.readthedocs.io/tutorials)\n- \ud83d\udd0c [REST API Reference](https://visionface.readthedocs.io/api)\n- \ud83d\udca1 [Use Case Examples](https://github.com/username/visionface/tree/main/examples)\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See our [Contributing Guide](CONTRIBUTING.md).\n\n**Quick ways to help:**\n- \u2b50 Star the repo\n- \ud83d\udc1b Report bugs\n- \ud83d\udca1 Request features \n- \ud83d\udcdd Improve docs\n- \ud83d\udd27 Submit PRs\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## \ud83d\ude4f Citation\n\n```bibtex\n@software{VisionFace2025,\n title = {VisionFace: Modern Face Detection & Recognition Framework},\n author = {VisionFace Team},\n year = {2025},\n url = {https://github.com/username/visionface}\n}\n```\n\n---\n\n<div align=\"center\">\n\n**[\u2b06 Back to Top](#visionface)** \u2022 **Made with \u2764\ufe0f by the VisionFace team**\n\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Modern face detection, recognition & analysis framework with 12+ models",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/miladfa7/visionface/issues",
"Changelog": "https://github.com/miladfa7/visionface/blob/main/CHANGELOG.md",
"Documentation": "https://visionface.readthedocs.io",
"Homepage": "https://github.com/miladfa7/visionface",
"Source Code": "https://github.com/miladfa7/visionface"
},
"split_keywords": [
"computer-vision",
" face-detection",
" face-recognition",
" facial-landmarks",
" deep-learning",
" pytorch",
" yolo",
" mediapipe",
" artificial-intelligence",
" biometrics",
" image-processing",
" real-time",
" production-ready"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9a84ef3f5a03bf5f87062bfb7be27c88e21fb52aa27ee171e589b9f181d71df4",
"md5": "48e8bb90358a82256e8c1c7a3fd09a95",
"sha256": "86ed8cc041fd7063ce9295ef9e601ecd7427699532aa82058d8bb1441ff1cc8e"
},
"downloads": -1,
"filename": "visionface-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "48e8bb90358a82256e8c1c7a3fd09a95",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 73945,
"upload_time": "2025-08-04T19:32:25",
"upload_time_iso_8601": "2025-08-04T19:32:25.131209Z",
"url": "https://files.pythonhosted.org/packages/9a/84/ef3f5a03bf5f87062bfb7be27c88e21fb52aa27ee171e589b9f181d71df4/visionface-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "525809fa51cbb48ac72391371cacc507d7186309a6c5bd0a4182c3c4ab0eb67b",
"md5": "48357776a49de87f885d8eb729219929",
"sha256": "f7db88324fd553fe92cc9eacc5fb600a09008b3354c40243a329ab3debfc9368"
},
"downloads": -1,
"filename": "visionface-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "48357776a49de87f885d8eb729219929",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 428264,
"upload_time": "2025-08-04T19:32:31",
"upload_time_iso_8601": "2025-08-04T19:32:31.750924Z",
"url": "https://files.pythonhosted.org/packages/52/58/09fa51cbb48ac72391371cacc507d7186309a6c5bd0a4182c3c4ab0eb67b/visionface-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 19:32:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miladfa7",
"github_project": "visionface",
"github_not_found": true,
"lcname": "visionface"
}
JSON
