This repository demonstrates practical usage of the degirum-face Python package for face detection, recognition, and tracking. Here you'll find ready-to-run scripts and a web app that show how to:
- Detect and recognize faces in images and video
- Build and search a face database
- Track faces in real time
- Easily enroll new faces
degirum-face is a high-performance, easy-to-use Python library for face recognition and tracking. It offers:
- Fast and efficient face detection, alignment, embedding extraction, and recognition for images, video files, and live streams
- Multi-hardware support: Works on CPU, GPU, and a wide range of edge AI accelerators:
- Hailo (HAILORT/HAILO8, HAILORT/HAILO8L)
- Axelera (AXELERA/METIS)
- DEEPX (DEEPX/M1A)
- Intel (OPENVINO/CPU, OPENVINO/GPU, OPENVINO/NPU)
- NVIDIA (TENSORRT/GPU)
- Rockchip (RKNN/RK3588)
- Google (TFLITE/EDGETPU)
- DeGirum (N2X/ORCA1)
- Simple APIs: Minimal code to detect, enroll, and recognize faces, with easy batch processing
- Flexible configuration: YAML or Python config for models, thresholds, and database paths
- Robust database and real-time tracking: Face re-identification, database search, event notification, and easy batch enrollment
- Production-ready: Used in real-world applications
DeGirum hosts its own PyPI server for DeGirum packages.
pip install -i https://pkg.degirum.com degirum-facePrerequisites:
- AI Hub Account: Create an account at DeGirum AI Hub and set up a workspace. See Workspace Plans for details.
- Authentication Token: Set up your AI Hub token following the token management guide.
- Python & OS: See DeGirum PySDK Documentation for requirements.
- Hardware Drivers (optional): See Runtimes & Drivers for hardware acceleration setup.
Quick Start: Use @cloud inference to try without installing drivers locally. The Quickstart example below uses local CPU models for immediate testing.
Try it now — this example uses built-in demo images and runs on CPU (TFLITE/CPU) locally, so it works on any system:
import degirum_face
from degirum_tools import remote_assets
# Demo parameters – change these to try your own images / names
ENROLL_IMAGE = remote_assets.face1
TEST_IMAGE = remote_assets.face2
PERSON_NAME = "Alice"
# 1. Create a face recognizer with default configuration
# By default: uses TFLITE/CPU models running locally (@local inference host)
face_recognizer = degirum_face.FaceRecognizer()
# 2. Enroll a person from a reference image
face_recognizer.enroll_image(ENROLL_IMAGE, PERSON_NAME)
# 3. Recognize faces in a test image
print("After enrollment:")
result = face_recognizer.predict(TEST_IMAGE)
for face in result.faces:
print(face)| Example | Description |
|---|---|
| face_recognition_simple.py | Recognize faces in images |
| face_recognition_enroll.py | Add faces to database |
| face_tracking_simple.py | Real-time face tracking |
| find_similar_faces.py | Find similar faces in a collection |
| group_similar_faces.py | Group photos by person |
| Tutorials.ipynb | Interactive Jupyter notebook tutorials |
| Web App | Full-featured web UI for tracking + NVR |
See examples/ for all available examples.
📚 Complete Documentation - Professional documentation site in the docs/ folder
Getting Started
- Installation & Setup - Get up and running
- Basic Concepts - Core concepts and terminology
Face Recognizer (Images & Batches)
- Overview - When to use and key concepts
- Configuration - Models, hardware, and filters
- Methods & API - Complete API reference
Face Tracker (Video & Streams)
- Overview - Real-time video tracking
- Configuration - Video sources, alerts, clips
- Methods - All methods with workflows
Reference
- Face Data Classes - FaceAttributes and FaceRecognitionResult
- Face Filters - Quality filtering options
- Object Storage - S3 and local clip storage
This repository (examples, documentation, and tutorials) is licensed under the MIT License. See LICENSE for details.
Note: The degirum-face library itself requires a license from DeGirum. This MIT license applies only to the example code and documentation in this repository, not to the degirum-face package. See the documentation for more information about degirum-face licensing.