tessl/pypi-dlib

A modern C++ toolkit containing machine learning algorithms and tools for creating complex software to solve real world problems

—

Pending

Overview

Eval results

Files

Object Detection

Name: tessl/pypi-dlib
Author: tessl

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

Capabilities

Object Detection Training

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

class simple_object_detector_training_options:
    """Training configuration for object detectors."""
    
    be_verbose: bool                           # Enable verbose training output
    add_left_right_image_flips: bool           # Add horizontal flip augmentation
    detection_window_size: int                 # Size of detection window
    nuclear_norm_regularization_strength: float # Nuclear norm regularization
    max_runtime_seconds: float                 # Maximum training time
    C: float                                  # SVM C parameter
    epsilon: float                            # SVM epsilon parameter  
    num_threads: int                          # Number of training threads
    upsample_limit: int                       # Image upsampling limit

def train_simple_object_detector(
    dataset_filename: str, 
    detector_output_filename: str, 
    options: simple_object_detector_training_options
):
    """
    Train object detector from XML dataset file.
    
    Args:
        dataset_filename: Path to XML dataset file with annotations
        detector_output_filename: Output path for trained detector
        options: Training configuration options
    """

def train_simple_object_detector(
    images: list, 
    boxes: list, 
    options: simple_object_detector_training_options
):
    """
    Train object detector from image arrays and bounding boxes.
    
    Args:
        images: List of training images
        boxes: List of bounding box lists (one per image)
        options: Training configuration options
    
    Returns:
        Trained detector object
    """

Usage Example:

import dlib
import cv2

# Configure training options
options = dlib.simple_object_detector_training_options()
options.be_verbose = True
options.add_left_right_image_flips = True
options.C = 10.0
options.num_threads = 4
options.detection_window_size = 80 * 80

# Train from XML dataset
dlib.train_simple_object_detector(
    "training_dataset.xml",
    "my_detector.svm", 
    options
)

# Or train from image arrays
training_images = []
training_boxes = []

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

detector = dlib.train_simple_object_detector(training_images, training_boxes, options)

Object Detection Testing and Evaluation

Functions for evaluating trained detectors and computing performance metrics.

class simple_test_results:
    """Detection evaluation results."""
    
    @property
    def precision(self) -> float:
        """Precision score."""
    
    @property
    def recall(self) -> float:
        """Recall score."""
    
    @property
    def average_precision(self) -> float:
        """Average precision score."""

def test_simple_object_detector(
    dataset_filename: str, 
    detector_filename: str, 
    upsampling_amount: int = -1
) -> simple_test_results:
    """
    Test object detector on dataset and compute metrics.
    
    Args:
        dataset_filename: Path to test dataset XML file
        detector_filename: Path to trained detector file
        upsampling_amount: Image upsampling for detection (-1 = auto)
    
    Returns:
        Test results with precision, recall, and AP metrics
    """

Usage Example:

import dlib

# Test trained detector
results = dlib.test_simple_object_detector(
    "test_dataset.xml",
    "my_detector.svm",
    upsampling_amount=1
)

print(f"Precision: {results.precision:.3f}")
print(f"Recall: {results.recall:.3f}")
print(f"Average Precision: {results.average_precision:.3f}")

Object Detection Inference

Using trained detectors for object detection in new images.

class simple_object_detector:
    """Trained object detector for inference."""
    
    def __init__(self, detector_filename: str):
        """
        Load trained detector from file.
        
        Args:
            detector_filename: Path to detector file
        """
    
    def __call__(self, img, upsampling_amount: int = 0) -> list:
        """
        Detect objects in image.
        
        Args:
            img: Input image
            upsampling_amount: Image upsampling factor
        
        Returns:
            List of detection rectangles
        """

def load_object_detector(detector_filename: str):
    """
    Load trained object detector from file.
    
    Args:
        detector_filename: Path to detector file
    
    Returns:
        Loaded detector object
    """

Usage Example:

import dlib
import cv2

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

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

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

# Draw detections
for detection in detections:
    cv2.rectangle(img, 
                 (detection.left(), detection.top()),
                 (detection.right(), detection.bottom()),
                 (0, 255, 0), 2)

cv2.imshow("Detections", img)
cv2.waitKey(0)
cv2.destroyAllWindows()

Selective Search for Object Proposals

Algorithm for generating object detection candidates using selective search.

def find_candidate_object_locations(
    image, 
    rects: rectangles, 
    kvals: tuple = (50, 200, 3), 
    min_size: int = 20, 
    max_merging_iterations: int = 50
) -> rectangles:
    """
    Find candidate object locations using selective search.
    
    Args:
        image: Input image
        rects: Output container for candidate rectangles
        kvals: K-means parameters (min_k, max_k, num_k)
        min_size: Minimum region size
        max_merging_iterations: Maximum merge iterations
    
    Returns:
        Container filled with candidate rectangles
    """

Usage Example:

import dlib
import cv2

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

# Find object candidates
candidates = dlib.rectangles()
dlib.find_candidate_object_locations(
    img, 
    candidates,
    kvals=(50, 200, 5),
    min_size=50,
    max_merging_iterations=100
)

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

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

cv2.imshow("Object Candidates", img)
cv2.waitKey(0)

Advanced Detection Configuration

Fine-tuning detection parameters and post-processing options.

def adjust_non_max_suppression_threshold(detector, threshold: float):
    """
    Adjust non-maximum suppression threshold for detector.
    
    Args:
        detector: Object detector
        threshold: NMS threshold (0-1, lower = more aggressive)
    """

def set_detection_threshold(detector, threshold: float):
    """
    Set detection confidence threshold.
    
    Args:
        detector: Object detector  
        threshold: Detection threshold
    """

def get_detection_window_size(detector) -> int:
    """
    Get detection window size for detector.
    
    Args:
        detector: Object detector
    
    Returns:
        Detection window size in pixels
    """

Multi-Scale Detection

Techniques for detecting objects at multiple scales and orientations.

def detect_objects_multi_scale(
    detector, 
    img, 
    scale_factor: float = 1.2, 
    min_window_size: int = 40,
    max_window_size: int = 300
) -> list:
    """
    Detect objects at multiple scales.
    
    Args:
        detector: Object detector
        img: Input image
        scale_factor: Scale multiplication factor
        min_window_size: Minimum detection window size
        max_window_size: Maximum detection window size
    
    Returns:
        List of detections across all scales
    """

def pyramid_detection(
    detector, 
    img, 
    pyramid_levels: int = 5
) -> list:
    """
    Detect objects using image pyramid.
    
    Args:
        detector: Object detector
        img: Input image
        pyramid_levels: Number of pyramid levels
    
    Returns:
        List of detections from pyramid
    """

Usage Example:

import dlib
import cv2

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

# Single scale detection
detections = detector(img)

# Multi-scale detection for better coverage
multi_scale_detections = dlib.detect_objects_multi_scale(
    detector, 
    img,
    scale_factor=1.15,
    min_window_size=60,
    max_window_size=400
)

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

# Adjust detection parameters
dlib.set_detection_threshold(detector, -0.5)  # Lower threshold = more detections
dlib.adjust_non_max_suppression_threshold(detector, 0.3)  # More aggressive NMS

Dataset Utilities

Helper functions for working with training datasets and annotations.

def save_image_dataset_metadata(dataset, filename: str):
    """
    Save dataset metadata to XML file.
    
    Args:
        dataset: Dataset metadata structure
        filename: Output XML filename
    """

def load_image_dataset_metadata(filename: str):
    """
    Load dataset metadata from XML file.
    
    Args:
        filename: Input XML filename
    
    Returns:
        Dataset metadata structure
    """

def create_detection_dataset(
    image_filenames: list, 
    bounding_boxes: list, 
    output_filename: str
):
    """
    Create XML dataset file from images and annotations.
    
    Args:
        image_filenames: List of image file paths
        bounding_boxes: List of bounding box lists
        output_filename: Output XML filename
    """

Complete Object Detection Pipeline Example:

import dlib
import cv2
import os
from glob import glob

def train_custom_detector():
    """Complete pipeline for training custom object detector."""
    
    # Prepare training data
    training_images = []
    training_boxes = []
    
    # Load training images and annotations
    for img_file in glob("training_images/*.jpg"):
        img = cv2.imread(img_file)
        training_images.append(img)
        
        # Load corresponding annotations (example format)
        annotation_file = img_file.replace('.jpg', '.txt')
        boxes = []
        
        if os.path.exists(annotation_file):
            with open(annotation_file, 'r') as f:
                for line in f:
                    x, y, w, h = map(int, line.strip().split())
                    boxes.append(dlib.rectangle(x, y, x+w, y+h))
        
        training_boxes.append(boxes)
    
    # Configure training
    options = dlib.simple_object_detector_training_options()
    options.be_verbose = True
    options.add_left_right_image_flips = True
    options.C = 5.0
    options.num_threads = 4
    options.detection_window_size = 6400  # 80x80 window
    
    # Train detector
    print("Training object detector...")
    detector = dlib.train_simple_object_detector(
        training_images, 
        training_boxes, 
        options
    )
    
    # Save detector
    detector.save("custom_detector.svm")
    
    return detector

def test_detector(detector_file, test_images_dir):
    """Test trained detector on new images."""
    
    # Load detector
    detector = dlib.simple_object_detector(detector_file)
    
    # Test on images
    for img_file in glob(f"{test_images_dir}/*.jpg"):
        img = cv2.imread(img_file)
        
        # Detect objects
        detections = detector(img, upsampling_amount=1)
        
        print(f"{os.path.basename(img_file)}: {len(detections)} detections")
        
        # Draw detections
        for detection in detections:
            cv2.rectangle(img,
                         (detection.left(), detection.top()),
                         (detection.right(), detection.bottom()),
                         (0, 255, 0), 2)
        
        # Show result
        cv2.imshow(f"Detections - {os.path.basename(img_file)}", img)
        cv2.waitKey(1000)
    
    cv2.destroyAllWindows()

# Usage
if __name__ == "__main__":
    # Train detector
    detector = train_custom_detector()
    
    # Test detector
    test_detector("custom_detector.svm", "test_images")

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

Install with Tessl CLI