0
# Dlib
1

2
A modern C++ toolkit containing machine learning algorithms and tools for creating complex software to solve real world problems. Dlib provides comprehensive functionality for computer vision, machine learning, image processing, and mathematical operations with a focus on real-world applications and high performance.
3

4
## Package Information
5

6
- **Package Name**: dlib
7
- **Language**: Python (with C++ implementation)
8
- **Installation**: `pip install dlib`
9
- **Documentation**: http://dlib.net
10

11
## Core Imports
12

13
```python
14
import dlib
15
```
16

17
All functionality is available directly from the dlib module:
18

19
```python
20
# Face detection and recognition
21
detector = dlib.get_frontal_face_detector()
22
predictor = dlib.shape_predictor("shape_predictor_68_face_landmarks.dat")
23
face_rec = dlib.face_recognition_model_v1("dlib_face_recognition_resnet_model_v1.dat")
24

25
# Image processing
26
img = dlib.load_rgb_image("image.jpg")
27
gray = dlib.as_grayscale(img)
28

29
# Machine learning
30
trainer = dlib.svm_c_trainer_linear()
31
```
32

33
## Basic Usage
34

35
```python
36
import dlib
37
import cv2
38

39
# Load an image
40
img = cv2.imread("faces.jpg")
41
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
42

43
# Initialize face detector and landmark predictor
44
detector = dlib.get_frontal_face_detector()
45
predictor = dlib.shape_predictor("shape_predictor_68_face_landmarks.dat")
46

47
# Detect faces
48
faces = detector(gray)
49

50
for face in faces:
51
    # Get facial landmarks
52
    landmarks = predictor(gray, face)
53
    
54
    # Extract face chip for recognition
55
    face_chip = dlib.get_face_chip(img, landmarks)
56
    
57
    print(f"Found face at: {face}")
58
```
59

60
## Architecture
61

62
Dlib's architecture is organized around several core components:
63

64
- **Core Data Types**: Matrix, vector, point types for mathematical operations
65
- **Image Processing**: Filtering, transformations, and basic computer vision operations  
66
- **Object Detection**: Face detection, custom object detection training and inference
67
- **Machine Learning**: SVM trainers, clustering algorithms, optimization functions
68
- **Geometric Operations**: Rectangle manipulation, line operations, projective transforms
69

70
The library is designed for performance with optimized C++ implementations exposed through Python bindings, supporting CUDA acceleration, BLAS/LAPACK integration, and CPU instruction optimizations (AVX, NEON).
71

72
## Capabilities
73

74
### Linear Algebra and Core Data Types
75

76
Essential mathematical data structures and operations including matrices, vectors, points, and linear algebra functions.
77

78
```python { .api }
79
class matrix:
80
    def __init__(self, rows: int, cols: int): ...
81
    def set_size(self, rows: int, cols: int): ...
82
    def nr(self) -> int: ...
83
    def nc(self) -> int: ...
84

85
class vector:
86
    def __init__(self, size: int = 0): ...
87
    def set_size(self, size: int): ...
88

89
class point:
90
    def __init__(self, x: int, y: int): ...
91
    x: int
92
    y: int
93

94
class dpoint:
95
    def __init__(self, x: float, y: float): ...
96
    x: float
97
    y: float
98

99
def dot(a, b): ...
100
def length(point) -> float: ...
101
```
102

103
[Linear Algebra](./linear-algebra.md)
104

105
### Geometric Operations
106

107
Rectangle manipulation, line operations, transformations, and geometric utilities for computer vision applications.
108

109
```python { .api }
110
class rectangle:
111
    def __init__(self, left: int, top: int, right: int, bottom: int): ...
112
    def left(self) -> int: ...
113
    def top(self) -> int: ...
114
    def right(self) -> int: ...
115
    def bottom(self) -> int: ...
116
    def width(self) -> int: ...
117
    def height(self) -> int: ...
118
    def area(self) -> int: ...
119

120
class line:
121
    def __init__(self, p1: point, p2: point): ...
122
    p1: point
123
    p2: point
124

125
def translate_rect(rect: rectangle, point: point) -> rectangle: ...
126
def centered_rect(center: point, width: int, height: int) -> rectangle: ...
127
def intersect(line_a: line, line_b: line) -> point: ...
128
```
129

130
[Geometric Operations](./geometric-operations.md)
131

132
### Image Processing
133

134
Image filtering, transformations, morphological operations, and computer vision preprocessing functions.
135

136
```python { .api }
137
class rgb_pixel:
138
    def __init__(self, red: int, green: int, blue: int): ...
139
    red: int
140
    green: int  
141
    blue: int
142

143
def threshold_image(img, threshold: float = None): ...
144
def gaussian_blur(img, sigma: float, max_size: int = 1000): ...
145
def skeleton(img): ...
146
def label_connected_blobs(img, zero_pixels_are_background: bool = True): ...
147
def as_grayscale(img): ...
148
def jet(img): ...
149
```
150

151
[Image Processing](./image-processing.md)
152

153
### Face Detection and Recognition
154

155
Comprehensive face detection, landmark prediction, and face recognition capabilities using state-of-the-art deep learning models.
156

157
```python { .api }
158
def get_frontal_face_detector(): ...
159

160
class shape_predictor:
161
    def __init__(self, predictor_path: str): ...
162
    def __call__(self, img, detection: rectangle): ...
163

164
class face_recognition_model_v1:
165
    def __init__(self, model_filename: str): ...
166
    def compute_face_descriptor(self, img, face, num_jitters: int = 0, padding: float = 0.25): ...
167

168
class cnn_face_detection_model_v1:
169
    def __init__(self, model_filename: str): ...
170
    def __call__(self, img, upsample_num_times: int = 0): ...
171

172
def chinese_whispers_clustering(descriptors, threshold: float): ...
173
def save_face_chip(img, face, filename: str, size: int = 150, padding: float = 0.25): ...
174
```
175

176
[Face Detection and Recognition](./face-detection.md)
177

178
### Object Detection
179

180
Training and inference for custom object detection models, including dataset handling and evaluation metrics.
181

182
```python { .api }
183
class simple_object_detector_training_options:
184
    be_verbose: bool
185
    add_left_right_image_flips: bool
186
    detection_window_size: int
187
    C: float
188
    epsilon: float
189
    num_threads: int
190
    upsample_limit: int
191

192
def train_simple_object_detector(dataset_filename: str, detector_output_filename: str, options): ...
193
def test_simple_object_detector(dataset_filename: str, detector_filename: str, upsampling_amount: int = -1): ...
194
def find_candidate_object_locations(image, rects, kvals=(50, 200, 3), min_size: int = 20): ...
195
```
196

197
[Object Detection](./object-detection.md)
198

199
### Machine Learning
200

201
Support Vector Machines, clustering algorithms, optimization functions, and other machine learning tools.
202

203
```python { .api }
204
class svm_c_trainer_linear:
205
    def __init__(self): ...
206
    def set_c(self, c: float): ...
207
    def train(self, samples, labels): ...
208

209
class svm_c_trainer_radial_basis:
210
    def __init__(self): ...
211
    def set_gamma(self, gamma: float): ...
212
    def set_c(self, c: float): ...
213
    def train(self, samples, labels): ...
214

215
class correlation_tracker:
216
    def __init__(self): ...
217
    def start_track(self, img, bounding_box: rectangle): ...
218
    def update(self, img): ...
219

220
def find_min_global(func, bounds, num_function_calls: int): ...
221
def max_cost_assignment(cost_matrix): ...
222
```
223

224
[Machine Learning](./machine-learning.md)
225

226
### Utilities and Data Handling
227

228
File I/O, statistical analysis, filtering functions, and various utility operations.
229

230
```python { .api }
231
def load_libsvm_formatted_data(filename: str): ...
232
def save_libsvm_formatted_data(filename: str, samples, labels): ...
233
def count_steps_without_decrease(time_series, probability: float = 0.51): ...
234
def hit_enter_to_continue(): ...
235

236
class momentum_filter:
237
    def __init__(self, measurement_noise: float, typical_acceleration: float, max_measurement_deviation: float): ...
238
    def __call__(self, measurement): ...
239
```
240

241
[Utilities](./utilities.md)
242

243
### GUI and Interactive Components
244

245
Interactive visualization components for image display, user interaction, and real-time visualization of computer vision results.
246

247
```python { .api }
248
class image_window:
249
    def __init__(self, img=None, title: str = None): ...
250
    def set_image(self, img): ...
251
    def set_title(self, title: str): ...
252
    def add_overlay(self, objects, color): ...
253
    def add_overlay_circle(self, center: point, radius: int, color): ...
254
    def clear_overlay(self): ...
255
    def wait_until_closed(self): ...
256
    def is_closed(self) -> bool: ...
257
    def get_next_double_click(self) -> point: ...
258
    def wait_for_keypress(self, key): ...
259
    def get_next_keypress(self, get_keyboard_modifiers: bool = False): ...
260

261
class non_printable_keyboard_keys:
262
    KEY_BACKSPACE: int
263
    KEY_ESC: int
264
    KEY_F1: int
265
    KEY_F2: int
266
    # ... (all special keys)
267

268
class keyboard_mod_keys:
269
    KBD_MOD_NONE: int
270
    KBD_MOD_SHIFT: int
271
    KBD_MOD_CONTROL: int
272
    KBD_MOD_ALT: int
273
```
274

275
[GUI Components](./gui-components.md)
276

277
## Module Constants
278

279
```python { .api }
280
__version__: str  # Dlib version
281
__time_compiled__: str  # Compilation timestamp
282
DLIB_USE_CUDA: bool  # CUDA support availability  
283
DLIB_USE_BLAS: bool  # BLAS support availability
284
DLIB_USE_LAPACK: bool  # LAPACK support availability
285
USE_AVX_INSTRUCTIONS: bool  # AVX instruction support
286
USE_NEON_INSTRUCTIONS: bool  # NEON instruction support
287
```