dlib - Machine Learning Toolkit

Warnings

• breaking Version 20.0 introduced several breaking changes. `dlib.fhog_object_detector` was moved to `dlib.image_processing.fhog_object_detector`. The `num_threads` argument was removed from `train_shape_predictor` and `train_object_detector`, which now use the global dlib thread pool configurable via `dlib.set_thread_pool_size()`.
  Fix: Update import paths (e.g., for `fhog_object_detector`) and replace `num_threads` arguments with calls to `dlib.set_thread_pool_size()` or remove them if global threading is acceptable.
• gotcha Installation via `pip install dlib` often requires system-level prerequisites for compilation (C++ compiler, CMake, Boost development libraries). Pre-built wheels are not available for all platforms/Python versions, leading to a source build.
  Fix: Ensure you have C++ build tools (e.g., Visual C++ Build Tools on Windows, `build-essential` on Linux) along with CMake and Boost development headers (e.g., `libboost-python-dev`, `libboost-all-dev` on Linux) installed before attempting `pip install dlib`.
• gotcha Pre-trained models (e.g., for facial landmarks, object detection) are not included in the pip package and must be downloaded manually from dlib's website (dlib.net/files) before use. Attempting to initialize predictors without the model file will result in runtime errors.
  Fix: Download the required `.dat` model files (often distributed as `.bz2` archives) from the official dlib website and provide the correct local path to functions like `dlib.shape_predictor()`.

Install

• pip install dlib Basic Install

Imports

• dlib

  import dlib

  The primary import for accessing all dlib functionalities.
• get_frontal_face_detector

  detector = dlib.get_frontal_face_detector()

• shape_predictor

  predictor = dlib.shape_predictor('model.dat')

Quickstart

Demonstrates how to use dlib for frontal face detection and facial landmark prediction. Note that for meaningful results, you must provide a real image and download a pre-trained shape predictor model file separately, as these are not bundled with the pip package. The example includes error handling for missing files.

import dlib
import numpy as np # Used for dummy image

# --- Quickstart: Face Detection and Landmark Prediction API Usage ---
# Note: For this example to produce meaningful results, you need:
# 1. A pre-trained facial landmark predictor model file (e.g., 'shape_predictor_68_face_landmarks.dat').
#    Download from: http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2
#    Then decompress it using 'bunzip2'.
# 2. An actual image file. Replace 'path/to/your/image.jpg' below.

# --- 1. Face Detection ---
# Initialize the frontal face detector
detector = dlib.get_frontal_face_detector()

# Load an image (replace with your actual image file path)
# For demonstration, we use a placeholder:
try:
    img = dlib.load_rgb_image("path/to/your/image.jpg")
except RuntimeError:
    print("Warning: Could not load dummy image 'path/to/your/image.jpg'.")
    print("Using a blank NumPy array for demonstration purposes. Face detection will likely find nothing.")
    img = np.zeros((400, 400, 3), dtype=np.uint8) # Create a 400x400 black image

# Detect faces in the image. The '1' argument means to upsample the image 1 time
# (make it larger) to find smaller faces.
dets = detector(img, 1)
print(f"Detected {len(dets)} faces (or regions of interest) in the image.")

# --- 2. Facial Landmark Prediction ---
# Initialize the shape predictor (requires a downloaded model file)
model_path = "shape_predictor_68_face_landmarks.dat" # Replace with actual path
try:
    predictor = dlib.shape_predictor(model_path)
except dlib.set_level_error as e:
    print(f"Error: Could not load shape predictor model from '{model_path}'.")
    print("Please download 'shape_predictor_68_face_landmarks.dat' and provide the correct path.")
    predictor = None # Prevent further errors if model loading failed

if predictor:
    for i, d in enumerate(dets):
        # Predict landmarks for each detected face
        print(f"  Processing face {i+1} at bounding box: Left: {d.left()}, Top: {d.top()}, Right: {d.right()}, Bottom: {d.bottom()}")
        try:
            shape = predictor(img, d)
            print(f"  Found {shape.num_parts} facial landmarks for face {i+1}.")
            if shape.num_parts > 0:
                print(f"  Example: First landmark point: ({shape.part(0).x}, {shape.part(0).y})")
        except Exception as e:
            print(f"  Could not find landmarks for face {i+1}. This is expected if the image is blank or model is incorrect. Error: {e}")
else:
    print("Skipping facial landmark prediction due to missing or invalid model.")

print("\ndlib quickstart example finished.")