{"id":30239872,"url":"https://github.com/miladfa7/visionface","last_synced_at":"2025-08-15T04:05:45.542Z","repository":{"id":308214969,"uuid":"968740219","full_name":"miladfa7/visionface","owner":"miladfa7","description":"VisionFace: All-in-one face analysis framework: detection, recognition, embeddings, landmarks, anti-spoofing and support visualization","archived":false,"fork":false,"pushed_at":"2025-08-08T19:30:42.000Z","size":26148,"stargazers_count":25,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-13T06:08:16.089Z","etag":null,"topics":["deep-learning","face","face-analysis","face-detection","face-landmarks","face-recognition","face-search","machine-learning","visionface"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/visionface/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/miladfa7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-18T16:37:40.000Z","updated_at":"2025-08-12T20:47:40.000Z","dependencies_parsed_at":"2025-08-04T21:31:48.024Z","dependency_job_id":null,"html_url":"https://github.com/miladfa7/visionface","commit_stats":null,"previous_names":["miladfa7/visionface"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/miladfa7/visionface","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladfa7%2Fvisionface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladfa7%2Fvisionface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladfa7%2Fvisionface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladfa7%2Fvisionface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/miladfa7","download_url":"https://codeload.github.com/miladfa7/visionface/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miladfa7%2Fvisionface/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270519961,"owners_count":24599257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","face","face-analysis","face-detection","face-landmarks","face-recognition","face-search","machine-learning","visionface"],"created_at":"2025-08-15T04:02:42.596Z","updated_at":"2025-08-15T04:05:45.528Z","avatar_url":"https://github.com/miladfa7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VisionFace\n\n\u003cdiv align=\"center\"\u003e\n\n  ![VisionFace](https://github.com/user-attachments/assets/52ac9123-304c-4098-a1e5-f413d03bfec9)\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI version](https://badge.fury.io/py/visionface.svg)](https://badge.fury.io/py/visionface)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\n**Modern face detection, recognition \u0026 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) • [Examples](#-examples) • [Models](#-models) • [API Docs](https://visionface.readthedocs.io)\n\n\u003c/div\u003e\n\n## ✨ What VisionFace Does\n\n\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ca href=\"#face-detection\"\u003e\n        \u003cfigure\u003e\n          \u003cimg src=\"banners/face_detection.jpg\" alt=\"Face Detection\" width=\"500\"/\u003e\n          \u003cfigcaption style=\"text-align: center;\"\u003eFace Detection\u003c/figcaption\u003e\n        \u003c/figure\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"#face-recognition\"\u003e\n        \u003cfigure\u003e\n          \u003cimg src=\"banners/face_recognition.jpg\" alt=\"Face Recognition\" width=\"500\"/\u003e\n          \u003cfigcaption style=\"text-align: center;\"\u003eFace Recognition\u003c/figcaption\u003e\n        \u003c/figure\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"#face-landmarks\"\u003e\n        \u003cfigure\u003e\n          \u003cimg src=\"banners/face_landmarks.jpg\" alt=\"Face Landmarks\" width=\"500\"/\u003e\n          \u003cfigcaption style=\"text-align: center;\"\u003eFace Landmarks\u003c/figcaption\u003e\n        \u003c/figure\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ca href=\"#-examples\"\u003e\n        \u003cfigure\u003e\n          \u003cimg src=\"banners/face_analysis.jpg\" alt=\"Face Analysis\" width=\"500\"/\u003e\n          \u003cfigcaption style=\"text-align: center;\"\u003eFace Analysis\u003c/figcaption\u003e\n        \u003c/figure\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"#face-embeddings-1-minute\"\u003e\n        \u003cfigure\u003e\n          \u003cimg src=\"banners/face_verification.jpg\" alt=\"Face Verification\" width=\"500\"/\u003e\n          \u003cfigcaption style=\"text-align: center;\"\u003eFace Verification\u003c/figcaption\u003e\n        \u003c/figure\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ca href=\"#-examples\"\u003e\n        \u003cfigure\u003e\n          \u003cimg src=\"banners/face_visualization.jpg\" alt=\"Face Visualization\" width=\"500\"/\u003e\n          \u003cfigcaption style=\"text-align: center;\"\u003eFace Visualization\u003c/figcaption\u003e\n        \u003c/figure\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/div\u003e\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## 🚀 Quick Start\n\n```bash\npip install visionface\n```\n\n### Face Detection \nThe `Face Detection` module is your gateway to identifying faces in any image. Built for both beginners and experts, it provides a unified interface to 12+ cutting-edge detection models.\n\n✨ **Key Features:**\n   * **Multiple Input Sources**: Image Files, URLs, PIL images, NumPy arrays\n   * **Flexible Processing**: Single image or batch processing thousands of images efficiently\n   * **12+ State-of-the-Art Models**: From ultra-fast mobile models to high-precision detectors\n   * **One-Line Detection**: Get results with just ```detector.detect_faces(image)```\n   * **Rich Outputs**: Bounding boxes, confidence scores, cropped faces ready to use\n\n![face_detection_2](https://github.com/user-attachments/assets/6cb7e953-3448-486e-b6b4-32c654da1fce)\n\n📝 **Quick Example:**\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[0])\ncv2.imwrite(\"detected.jpg\", result)\n```\n\n### Face Recognition\nThe `Face Recognition` module identifies individuals by generating embeddings and comparing them in a vector database. The process includes three stages: detecting faces, creating embeddings with the chosen model, and searching the database to find the closest matches.\n\n✨ **Key Features**:\n\n* **Multi-model support**: Choose from high-accuracy embedding backbones such as FaceNet-VGG, FaceNet-CASIA, and Dlib.\n* **Vector DB Integration**: Store and query embeddings using Qdrant, Milvus, or local file-based storage.\n* **Scalable Search**: Efficiently match thousands or millions of faces with fast search.\n* **Flexible Enrollment**: Add faces one-by-one or in batches with associated labels.\n* **Threshold \u0026 Ranking**: Control similarity thresholds and retrieve top-k matches for robust recognition results.\n\n![face)recognition](https://github.com/user-attachments/assets/55f83bc1-93ec-479d-a86b-820c7cef0605)\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                     db_backend=\"qdrant\")\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(\"query_face_image.jpg\", \n                         collection_name=\"employees\",\n                         score_threshold=0.7,\n                         top_k=3)\n\nfor match in matches:\n    print(f\"Found: {match['face_name']} (confidence: {match['score']:.2f})\")\n```\n\n### Face Embeddings \nThe `Face Embeddings` module transforms each detected face into a high-dimensional numeric vector (embedding) that captures its unique features.\nThese embeddings can be used for:\n\n* **Face verification**: Check if two faces belong to the same perso\n* **Recognition**: Match against a database of known faces\n* **Clustering**: Group similar faces automatically\n* **Advanced analytics**: \n\n**✨ Supported Embedding Models:**\n`FaceNet-VGG`, `FaceNet-CASIA`, `Dlib`\n\n📝 **Quick Example:**\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\n### Face Landmarks\nThe `Landmarks` module identifies key facial features with pixel-perfect accuracy. From eye positions to lip contours, get detailed facial geometry for advanced applications.\n\n✨ **Key Features:**\n\n* **Multiple Input Sources**: Image Files, URLs, PIL images, NumPy arrays\n* **Flexible Processing**: Single image or batch processing thousands of images efficiently\n* **2D \u0026 3D Support**: Standard 2D points or full 3D face mesh\n* **Rich Annotations**: Built-in visualization with customizable styling\n* **Multiple Backends**: MediaPipe (468 points) or Dlib (68 points)\n\n![face_landmarks](https://github.com/user-attachments/assets/9b8264d1-2ea7-442c-ab08-7d11d35f1824)\n\n📝 **Quick Example:**\n\n```python\nfrom visionface import LandmarkDetection\nfrom visionface.annotators.landmark import MediaPipeFaceMeshAnnotator\n\nlandmark_detector = LandmarkDetection(detector_backbone=\"mediapipe\")\nimage = cv2.imread(\"your_image.jpg\")\n\n# Get 468 facial landmarks\nlandmarks = landmark_detector.detect_3d_landmarks(image)\n\n# Visualize with connections\nvizualizer = MediaPipeFaceMeshAnnotator(thickness=2, circle_radius=3)\nresult = vizualizer.annotate(\n    image, landmarks[0], connections=True\n)\ncv2.imwrite(\"detected_landmarks.jpg\", result)\n```\n\n## 💡 Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🎯 Real-time Face Detection\u003c/b\u003e\u003c/summary\u003e\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) \u0026 0xFF == ord('q'):\n        break\n\ncap.release()\ncv2.destroyAllWindows()\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📊 Batch Processing\u003c/b\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🏢 Employee Recognition System\u003c/b\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n## 🎯 Models\n\n**Choose the right model for your use case:**\n\n| Use Case | Speed | Accuracy | Recommended Model |\n|----------|-------|----------|------------------|\n| 🚀 **Real-time apps** | ⚡⚡⚡ | ⭐⭐ | `yolo-nano`, `mediapipe` |\n| 🎯 **General purpose** | ⚡⚡ | ⭐⭐⭐ | `yolo-small` (default) |\n| 🔍 **High accuracy** | ⚡ | ⭐⭐⭐⭐ | `yolo-large`, `mtcnn` |\n| 📱 **Mobile/Edge** | ⚡⚡⚡ | ⭐⭐ | `mediapipe`, `yolo-nano` |\n| 🎭 **Landmarks needed** | ⚡⚡ | ⭐⭐⭐ | `mediapipe`, `dlib` |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📋 Complete Model List\u003c/b\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\n## 📚 Documentation\n\n- 📖 [Full Documentation](https://visionface.readthedocs.io)\n- 🎓 [Tutorials \u0026 Guides](https://visionface.readthedocs.io/tutorials)\n- 🔌 [REST API Reference](https://visionface.readthedocs.io/api)\n- 💡 [Use Case Examples](https://github.com/username/visionface/tree/main/examples)\n\n## 🤝 Contributing\nWe welcome contributions! See our [Contributing Guide](CONTRIBUTING.md).\n\n\u003ca href=\"https://github.com/miladfa7/visionface/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=miladfa7/visionface\" /\u003e\n\u003c/a\u003e\n\u003cbr\u003e\n\n\n**Quick ways to help:**\n- ⭐ Star the repo\n- 🐛 Report bugs\n- 💡 Request features  \n- 📝 Improve docs\n- 🔧 Submit PRs\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## 🙏 Citation\n\n```bibtex\n@software{VisionFace2025,\n  title = {VisionFace: Modern Face Detection \u0026 Recognition Framework},\n  author = {VisionFace Team},\n  year = {2025},\n  url = {https://github.com/miladfa7/visionface}\n}\n```\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⬆ Back to Top](#visionface)** • **Made with ❤️ by the VisionFace team**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiladfa7%2Fvisionface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiladfa7%2Fvisionface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiladfa7%2Fvisionface/lists"}