0
# Object Detection
1

2
Training and inference for custom object detection models, including dataset handling, evaluation metrics, and sliding window-based detection approaches.
3

4
## Capabilities
5

6
### Object Detection Training
7

8
Comprehensive training pipeline for custom object detectors using HOG features and SVM classification.
9

10
```python { .api }
11
class simple_object_detector_training_options:
12
    """Training configuration for object detectors."""
13
    
14
    be_verbose: bool                           # Enable verbose training output
15
    add_left_right_image_flips: bool           # Add horizontal flip augmentation
16
    detection_window_size: int                 # Size of detection window
17
    nuclear_norm_regularization_strength: float # Nuclear norm regularization
18
    max_runtime_seconds: float                 # Maximum training time
19
    C: float                                  # SVM C parameter
20
    epsilon: float                            # SVM epsilon parameter  
21
    num_threads: int                          # Number of training threads
22
    upsample_limit: int                       # Image upsampling limit
23

24
def train_simple_object_detector(
25
    dataset_filename: str, 
26
    detector_output_filename: str, 
27
    options: simple_object_detector_training_options
28
):
29
    """
30
    Train object detector from XML dataset file.
31
    
32
    Args:
33
        dataset_filename: Path to XML dataset file with annotations
34
        detector_output_filename: Output path for trained detector
35
        options: Training configuration options
36
    """
37

38
def train_simple_object_detector(
39
    images: list, 
40
    boxes: list, 
41
    options: simple_object_detector_training_options
42
):
43
    """
44
    Train object detector from image arrays and bounding boxes.
45
    
46
    Args:
47
        images: List of training images
48
        boxes: List of bounding box lists (one per image)
49
        options: Training configuration options
50
    
51
    Returns:
52
        Trained detector object
53
    """
54
```
55

56
**Usage Example:**
57
```python
58
import dlib
59
import cv2
60

61
# Configure training options
62
options = dlib.simple_object_detector_training_options()
63
options.be_verbose = True
64
options.add_left_right_image_flips = True
65
options.C = 10.0
66
options.num_threads = 4
67
options.detection_window_size = 80 * 80
68

69
# Train from XML dataset
70
dlib.train_simple_object_detector(
71
    "training_dataset.xml",
72
    "my_detector.svm", 
73
    options
74
)
75

76
# Or train from image arrays
77
training_images = []
78
training_boxes = []
79

80
for img_file in ["img1.jpg", "img2.jpg", "img3.jpg"]:
81
    img = cv2.imread(img_file)
82
    training_images.append(img)
83
    
84
    # Define bounding boxes for this image
85
    boxes = [dlib.rectangle(50, 50, 150, 200)]  # Example box
86
    training_boxes.append(boxes)
87

88
detector = dlib.train_simple_object_detector(training_images, training_boxes, options)
89
```
90

91
### Object Detection Testing and Evaluation
92

93
Functions for evaluating trained detectors and computing performance metrics.
94

95
```python { .api }
96
class simple_test_results:
97
    """Detection evaluation results."""
98
    
99
    @property
100
    def precision(self) -> float:
101
        """Precision score."""
102
    
103
    @property
104
    def recall(self) -> float:
105
        """Recall score."""
106
    
107
    @property
108
    def average_precision(self) -> float:
109
        """Average precision score."""
110

111
def test_simple_object_detector(
112
    dataset_filename: str, 
113
    detector_filename: str, 
114
    upsampling_amount: int = -1
115
) -> simple_test_results:
116
    """
117
    Test object detector on dataset and compute metrics.
118
    
119
    Args:
120
        dataset_filename: Path to test dataset XML file
121
        detector_filename: Path to trained detector file
122
        upsampling_amount: Image upsampling for detection (-1 = auto)
123
    
124
    Returns:
125
        Test results with precision, recall, and AP metrics
126
    """
127
```
128

129
**Usage Example:**
130
```python
131
import dlib
132

133
# Test trained detector
134
results = dlib.test_simple_object_detector(
135
    "test_dataset.xml",
136
    "my_detector.svm",
137
    upsampling_amount=1
138
)
139

140
print(f"Precision: {results.precision:.3f}")
141
print(f"Recall: {results.recall:.3f}")
142
print(f"Average Precision: {results.average_precision:.3f}")
143
```
144

145
### Object Detection Inference
146

147
Using trained detectors for object detection in new images.
148

149
```python { .api }
150
class simple_object_detector:
151
    """Trained object detector for inference."""
152
    
153
    def __init__(self, detector_filename: str):
154
        """
155
        Load trained detector from file.
156
        
157
        Args:
158
            detector_filename: Path to detector file
159
        """
160
    
161
    def __call__(self, img, upsampling_amount: int = 0) -> list:
162
        """
163
        Detect objects in image.
164
        
165
        Args:
166
            img: Input image
167
            upsampling_amount: Image upsampling factor
168
        
169
        Returns:
170
            List of detection rectangles
171
        """
172

173
def load_object_detector(detector_filename: str):
174
    """
175
    Load trained object detector from file.
176
    
177
    Args:
178
        detector_filename: Path to detector file
179
    
180
    Returns:
181
        Loaded detector object
182
    """
183
```
184

185
**Usage Example:**
186
```python
187
import dlib
188
import cv2
189

190
# Load trained detector
191
detector = dlib.simple_object_detector("my_detector.svm")
192

193
# Detect objects in image
194
img = cv2.imread("test_image.jpg")
195
detections = detector(img, upsampling_amount=1)
196

197
print(f"Found {len(detections)} objects")
198

199
# Draw detections
200
for detection in detections:
201
    cv2.rectangle(img, 
202
                 (detection.left(), detection.top()),
203
                 (detection.right(), detection.bottom()),
204
                 (0, 255, 0), 2)
205

206
cv2.imshow("Detections", img)
207
cv2.waitKey(0)
208
cv2.destroyAllWindows()
209
```
210

211
### Selective Search for Object Proposals
212

213
Algorithm for generating object detection candidates using selective search.
214

215
```python { .api }
216
def find_candidate_object_locations(
217
    image, 
218
    rects: rectangles, 
219
    kvals: tuple = (50, 200, 3), 
220
    min_size: int = 20, 
221
    max_merging_iterations: int = 50
222
) -> rectangles:
223
    """
224
    Find candidate object locations using selective search.
225
    
226
    Args:
227
        image: Input image
228
        rects: Output container for candidate rectangles
229
        kvals: K-means parameters (min_k, max_k, num_k)
230
        min_size: Minimum region size
231
        max_merging_iterations: Maximum merge iterations
232
    
233
    Returns:
234
        Container filled with candidate rectangles
235
    """
236
```
237

238
**Usage Example:**
239
```python
240
import dlib
241
import cv2
242

243
# Load image
244
img = cv2.imread("complex_scene.jpg")
245

246
# Find object candidates
247
candidates = dlib.rectangles()
248
dlib.find_candidate_object_locations(
249
    img, 
250
    candidates,
251
    kvals=(50, 200, 5),
252
    min_size=50,
253
    max_merging_iterations=100
254
)
255

256
print(f"Found {len(candidates)} candidate regions")
257

258
# Visualize candidates
259
for i, candidate in enumerate(candidates[:20]):  # Show first 20
260
    cv2.rectangle(img,
261
                 (candidate.left(), candidate.top()),
262
                 (candidate.right(), candidate.bottom()),
263
                 (255, 0, 0), 1)
264

265
cv2.imshow("Object Candidates", img)
266
cv2.waitKey(0)
267
```
268

269
### Advanced Detection Configuration
270

271
Fine-tuning detection parameters and post-processing options.
272

273
```python { .api }
274
def adjust_non_max_suppression_threshold(detector, threshold: float):
275
    """
276
    Adjust non-maximum suppression threshold for detector.
277
    
278
    Args:
279
        detector: Object detector
280
        threshold: NMS threshold (0-1, lower = more aggressive)
281
    """
282

283
def set_detection_threshold(detector, threshold: float):
284
    """
285
    Set detection confidence threshold.
286
    
287
    Args:
288
        detector: Object detector  
289
        threshold: Detection threshold
290
    """
291

292
def get_detection_window_size(detector) -> int:
293
    """
294
    Get detection window size for detector.
295
    
296
    Args:
297
        detector: Object detector
298
    
299
    Returns:
300
        Detection window size in pixels
301
    """
302
```
303

304
### Multi-Scale Detection
305

306
Techniques for detecting objects at multiple scales and orientations.
307

308
```python { .api }
309
def detect_objects_multi_scale(
310
    detector, 
311
    img, 
312
    scale_factor: float = 1.2, 
313
    min_window_size: int = 40,
314
    max_window_size: int = 300
315
) -> list:
316
    """
317
    Detect objects at multiple scales.
318
    
319
    Args:
320
        detector: Object detector
321
        img: Input image
322
        scale_factor: Scale multiplication factor
323
        min_window_size: Minimum detection window size
324
        max_window_size: Maximum detection window size
325
    
326
    Returns:
327
        List of detections across all scales
328
    """
329

330
def pyramid_detection(
331
    detector, 
332
    img, 
333
    pyramid_levels: int = 5
334
) -> list:
335
    """
336
    Detect objects using image pyramid.
337
    
338
    Args:
339
        detector: Object detector
340
        img: Input image
341
        pyramid_levels: Number of pyramid levels
342
    
343
    Returns:
344
        List of detections from pyramid
345
    """
346
```
347

348
**Usage Example:**
349
```python
350
import dlib
351
import cv2
352

353
# Load detector and image
354
detector = dlib.simple_object_detector("car_detector.svm")
355
img = cv2.imread("parking_lot.jpg")
356

357
# Single scale detection
358
detections = detector(img)
359

360
# Multi-scale detection for better coverage
361
multi_scale_detections = dlib.detect_objects_multi_scale(
362
    detector, 
363
    img,
364
    scale_factor=1.15,
365
    min_window_size=60,
366
    max_window_size=400
367
)
368

369
print(f"Single scale: {len(detections)} detections")
370
print(f"Multi-scale: {len(multi_scale_detections)} detections")
371

372
# Adjust detection parameters
373
dlib.set_detection_threshold(detector, -0.5)  # Lower threshold = more detections
374
dlib.adjust_non_max_suppression_threshold(detector, 0.3)  # More aggressive NMS
375
```
376

377
### Dataset Utilities
378

379
Helper functions for working with training datasets and annotations.
380

381
```python { .api }
382
def save_image_dataset_metadata(dataset, filename: str):
383
    """
384
    Save dataset metadata to XML file.
385
    
386
    Args:
387
        dataset: Dataset metadata structure
388
        filename: Output XML filename
389
    """
390

391
def load_image_dataset_metadata(filename: str):
392
    """
393
    Load dataset metadata from XML file.
394
    
395
    Args:
396
        filename: Input XML filename
397
    
398
    Returns:
399
        Dataset metadata structure
400
    """
401

402
def create_detection_dataset(
403
    image_filenames: list, 
404
    bounding_boxes: list, 
405
    output_filename: str
406
):
407
    """
408
    Create XML dataset file from images and annotations.
409
    
410
    Args:
411
        image_filenames: List of image file paths
412
        bounding_boxes: List of bounding box lists
413
        output_filename: Output XML filename
414
    """
415
```
416

417
**Complete Object Detection Pipeline Example:**
418
```python
419
import dlib
420
import cv2
421
import os
422
from glob import glob
423

424
def train_custom_detector():
425
    """Complete pipeline for training custom object detector."""
426
    
427
    # Prepare training data
428
    training_images = []
429
    training_boxes = []
430
    
431
    # Load training images and annotations
432
    for img_file in glob("training_images/*.jpg"):
433
        img = cv2.imread(img_file)
434
        training_images.append(img)
435
        
436
        # Load corresponding annotations (example format)
437
        annotation_file = img_file.replace('.jpg', '.txt')
438
        boxes = []
439
        
440
        if os.path.exists(annotation_file):
441
            with open(annotation_file, 'r') as f:
442
                for line in f:
443
                    x, y, w, h = map(int, line.strip().split())
444
                    boxes.append(dlib.rectangle(x, y, x+w, y+h))
445
        
446
        training_boxes.append(boxes)
447
    
448
    # Configure training
449
    options = dlib.simple_object_detector_training_options()
450
    options.be_verbose = True
451
    options.add_left_right_image_flips = True
452
    options.C = 5.0
453
    options.num_threads = 4
454
    options.detection_window_size = 6400  # 80x80 window
455
    
456
    # Train detector
457
    print("Training object detector...")
458
    detector = dlib.train_simple_object_detector(
459
        training_images, 
460
        training_boxes, 
461
        options
462
    )
463
    
464
    # Save detector
465
    detector.save("custom_detector.svm")
466
    
467
    return detector
468

469
def test_detector(detector_file, test_images_dir):
470
    """Test trained detector on new images."""
471
    
472
    # Load detector
473
    detector = dlib.simple_object_detector(detector_file)
474
    
475
    # Test on images
476
    for img_file in glob(f"{test_images_dir}/*.jpg"):
477
        img = cv2.imread(img_file)
478
        
479
        # Detect objects
480
        detections = detector(img, upsampling_amount=1)
481
        
482
        print(f"{os.path.basename(img_file)}: {len(detections)} detections")
483
        
484
        # Draw detections
485
        for detection in detections:
486
            cv2.rectangle(img,
487
                         (detection.left(), detection.top()),
488
                         (detection.right(), detection.bottom()),
489
                         (0, 255, 0), 2)
490
        
491
        # Show result
492
        cv2.imshow(f"Detections - {os.path.basename(img_file)}", img)
493
        cv2.waitKey(1000)
494
    
495
    cv2.destroyAllWindows()
496

497
# Usage
498
if __name__ == "__main__":
499
    # Train detector
500
    detector = train_custom_detector()
501
    
502
    # Test detector
503
    test_detector("custom_detector.svm", "test_images")
504
```
505

506
This object detection capability provides a complete framework for training custom detectors for specific objects or scenarios, with comprehensive evaluation and deployment tools.