0
# Face Analysis Pipeline
1
2
High-level interface for complete face analysis that orchestrates multiple specialized models to provide unified face detection, recognition, landmark detection, and attribute prediction capabilities.
3
4
## Capabilities
5
6
### FaceAnalysis Class
7
8
The primary interface for face analysis tasks. Automatically loads and manages multiple models based on the specified model pack.
9
10
```python { .api }
11
class FaceAnalysis:
12
def __init__(self, name='buffalo_l', root='~/.insightface', allowed_modules=None, **kwargs):
13
"""
14
Initialize face analysis pipeline.
15
16
Parameters:
17
- name: str, model pack name (default: 'buffalo_l')
18
- root: str, model storage directory (default: '~/.insightface')
19
- allowed_modules: list, restrict to specific model types (e.g., ['detection', 'recognition'])
20
- **kwargs: additional arguments passed to model initialization
21
"""
22
23
def prepare(self, ctx_id, det_thresh=0.5, det_size=(640, 640)):
24
"""
25
Prepare models for inference.
26
27
Parameters:
28
- ctx_id: int, context ID for device selection (0 for CPU, 0+ for GPU)
29
- det_thresh: float, detection confidence threshold (0.0-1.0)
30
- det_size: tuple, detection input size (width, height)
31
"""
32
33
def get(self, img, max_num=0) -> List[Face]:
34
"""
35
Detect and analyze faces in image.
36
37
Parameters:
38
- img: np.ndarray, input image in BGR format
39
- max_num: int, maximum number of faces to detect (0 for unlimited)
40
41
Returns:
42
List of Face objects with analysis results
43
"""
44
45
def draw_on(self, img, faces) -> np.ndarray:
46
"""
47
Draw face detection results on image.
48
49
Parameters:
50
- img: np.ndarray, input image
51
- faces: list, Face objects to draw
52
53
Returns:
54
np.ndarray: image with drawn bounding boxes and landmarks
55
"""
56
```
57
58
### Face Result Object
59
60
Container for face analysis results that accumulates data from multiple models.
61
62
```python { .api }
63
class Face(dict):
64
def __init__(self, d=None, **kwargs):
65
"""
66
Initialize Face object.
67
68
Parameters:
69
- d: dict, initial data dictionary
70
- **kwargs: additional face attributes
71
"""
72
73
@property
74
def embedding_norm -> float:
75
"""L2 norm of the face embedding vector."""
76
77
@property
78
def normed_embedding -> np.ndarray:
79
"""Normalized face embedding (unit vector)."""
80
81
@property
82
def sex -> str:
83
"""Gender as string: 'M' for male, 'F' for female."""
84
```
85
86
### Dynamic Face Attributes
87
88
The Face object dynamically accumulates attributes from different analysis models:
89
90
```python { .api }
91
# Detection model attributes
92
bbox: np.ndarray # Bounding box coordinates [x1, y1, x2, y2]
93
det_score: float # Detection confidence score (0.0-1.0)
94
kps: np.ndarray # Facial keypoints, shape (5, 2) for 5-point landmarks
95
96
# Recognition model attributes
97
embedding: np.ndarray # Face embedding vector, typically shape (512,)
98
99
# Attribute prediction model attributes
100
gender: int # Gender prediction: 0=female, 1=male
101
age: int # Age prediction in years
102
103
# Landmark detection model attributes
104
landmark_2d_68: np.ndarray # 68 2D facial landmarks, shape (68, 2)
105
landmark_3d_68: np.ndarray # 68 3D facial landmarks, shape (68, 3)
106
landmark_2d_106: np.ndarray # 106 2D facial landmarks, shape (106, 2)
107
108
# Pose estimation attributes
109
pose: np.ndarray # Head pose angles [pitch, yaw, roll] in degrees
110
```
111
112
## Usage Examples
113
114
### Basic Face Analysis
115
116
```python
117
import cv2
118
from insightface.app import FaceAnalysis
119
120
# Initialize with default model pack
121
app = FaceAnalysis()
122
app.prepare(ctx_id=0, det_thresh=0.6, det_size=(640, 640))
123
124
# Load and analyze image
125
img = cv2.imread('family_photo.jpg')
126
faces = app.get(img)
127
128
print(f"Found {len(faces)} faces")
129
for i, face in enumerate(faces):
130
print(f"Face {i+1}:")
131
print(f" Age: {face.age}")
132
print(f" Gender: {face.sex}")
133
print(f" Confidence: {face.det_score:.3f}")
134
print(f" Location: {face.bbox}")
135
```
136
137
### GPU Acceleration
138
139
```python
140
# Use GPU for inference (requires CUDA-enabled onnxruntime-gpu)
141
app = FaceAnalysis()
142
app.prepare(ctx_id=0) # Use first GPU, -1 for CPU
143
144
# Process with GPU acceleration
145
faces = app.get(img)
146
```
147
148
### Selective Model Loading
149
150
```python
151
# Load only detection and recognition models
152
app = FaceAnalysis(allowed_modules=['detection', 'recognition'])
153
app.prepare(ctx_id=0)
154
155
faces = app.get(img)
156
# faces will have bbox, det_score, and embedding but no age/gender
157
```
158
159
### Batch Processing
160
161
```python
162
import os
163
from pathlib import Path
164
165
app = FaceAnalysis()
166
app.prepare(ctx_id=0)
167
168
# Process directory of images
169
image_dir = Path('photos/')
170
for img_path in image_dir.glob('*.jpg'):
171
img = cv2.imread(str(img_path))
172
faces = app.get(img)
173
174
if faces:
175
# Save visualization
176
result_img = app.draw_on(img, faces)
177
output_path = f'results/{img_path.stem}_faces.jpg'
178
cv2.imwrite(output_path, result_img)
179
180
# Extract embeddings for face recognition
181
embeddings = [face.embedding for face in faces]
182
print(f"{img_path.name}: {len(faces)} faces, {len(embeddings)} embeddings")
183
```
184
185
### Face Similarity Comparison
186
187
```python
188
# Compare faces between two images
189
img1 = cv2.imread('person1.jpg')
190
img2 = cv2.imread('person2.jpg')
191
192
faces1 = app.get(img1)
193
faces2 = app.get(img2)
194
195
if faces1 and faces2:
196
face1 = faces1[0] # First face in image 1
197
face2 = faces2[0] # First face in image 2
198
199
# Compute cosine similarity
200
embedding1 = face1.normed_embedding
201
embedding2 = face2.normed_embedding
202
similarity = np.dot(embedding1, embedding2)
203
204
print(f"Face similarity: {similarity:.3f}")
205
if similarity > 0.6:
206
print("Likely same person")
207
else:
208
print("Likely different people")
209
```