Overview

dlib wraps dlib C++ library — a mature machine learning toolkit best known for its state-of-the-art face recognition pipeline. The ResNet-based face recognition model achieves 99.38% accuracy on the Labeled Faces in the Wild benchmark, making it competitive with commercial systems.

The typical pipeline is: load image → detect face rectangles → predict 68 landmarks → extract aligned chip → compute 128-d embedding → compare distances. All steps are exposed as individual functions so you can mix and match.

Quick Start

Full face recognition pipeline

uses dlib;

var detector   := NewHOGDetector;
var predictor  := LoadPredictor('/models/shape_predictor_68_face_landmarks.dat');
var recognizer := LoadRecognizer('/models/dlib_face_recognition_resnet_model_v1.dat');

var img   := LoadImage('/photos/group.jpg');
var faces := DetectFaces(detector, img, 1);
WriteLn('Faces found: ' + IntToStr(Length(faces)));

for var face in faces do
begin
  var landmarks := PredictLandmarks(predictor, img, face);
  var chip      := ExtractFaceChip(img, landmarks);
  var emb       := ComputeEmbedding(recognizer, chip);
  { Store embedding for later comparison }
  WriteLn('Embedding computed, first value: ' + FloatToStr(emb[0]));
end;

FreeImage(img);

Compare two faces

uses dlib;

{ Are these two photos the same person? }
var dist := EmbeddingDistance(emb1, emb2);
WriteLn('Distance: ' + FloatToStr(dist));
if dist < 0.6 then
  WriteLn('Same person (likely)')
else
  WriteLn('Different people');

{ Or use the built-in verifier }
if VerifyFace(emb1, emb2, 0.6) then
  WriteLn('Identity verified');

Image Loading API

Images are loaded into an opaque TDlibImage handle. Always call FreeImage when done to release native memory.

Function	Description
LoadImage(path)	Load JPEG, PNG, BMP, or GIF from disk. Returns a TDlibImage handle.
LoadImageFromBytes(data)	Load image from a TBytes buffer (e.g. downloaded from HTTP)
ImageWidth(img)	Width in pixels
ImageHeight(img)	Height in pixels
SaveImage(img, path)	Save image to disk (JPEG or PNG by extension)
FreeImage(img)	Release native memory for the image handle

Face Detection API

Two detector types are available. HOG is faster and works well on upright frontal faces; CNN is slower but detects faces at unusual angles and partial occlusion.

HOG vs CNN comparison

Property	HOG detector	CNN detector
Speed	Fast (CPU)	Slower (benefits from GPU)
Accuracy	Good for frontal faces	Better at angles and occlusion
Model file	None (built-in)	mmod_human_face_detector.dat
Typical use	Webcam, real-time	Photos, security, biometrics

Function	Description
NewHOGDetector	Create the built-in HOG face detector (no model file needed)
LoadCNNDetector(modelPath)	Load the MMOD CNN detector from a .dat file
DetectFaces(detector, img, upsample)	Returns an array of TDlibRect bounding boxes. upsample=1 improves small-face detection.
DetectFacesCNN(detector, img)	Run CNN detector; returns array of TDlibRect
FreeDetector(detector)	Release detector resources

uses dlib;

{ HOG — fast, good for single frontal faces }
var hog   := NewHOGDetector;
var faces := DetectFaces(hog, img, 1);

{ CNN — slower, better for groups/partial faces }
var cnn   := LoadCNNDetector('/models/mmod_human_face_detector.dat');
var faces := DetectFacesCNN(cnn, img);

WriteLn(IntToStr(Length(faces)) + ' faces detected');

Landmark Prediction API

Given a face bounding box, the shape predictor locates 68 keypoints: eyes, nose tip, mouth corners, jawline, and eyebrows. These landmarks are required to align the face chip before computing embeddings.

Function	Description
LoadPredictor(modelPath)	Load shape predictor from shape_predictor_68_face_landmarks.dat
PredictLandmarks(predictor, img, rect)	Returns a TDlibLandmarks handle with 68 points
LandmarkPoint(landmarks, index)	Get the (x, y) of landmark index (0..67) as a TDlibPoint
FreeLandmarks(landmarks)	Release landmark memory
FreePredictor(predictor)	Release predictor model from memory

Face Recognition API

The ResNet model maps a 150x150 aligned face chip to a 128-dimensional floating-point vector. Two embeddings from the same person will have a Euclidean distance below ~0.6; different people are typically above 0.6.

Function	Description
LoadRecognizer(modelPath)	Load recognition model from dlib_face_recognition_resnet_model_v1.dat
ExtractFaceChip(img, landmarks)	Warp and crop the face to a 150x150 aligned chip. Returns a TDlibImage.
ExtractFaceChipSize(img, landmarks, size)	Extract chip at custom resolution (default 150)
ComputeEmbedding(recognizer, chip)	Returns a array of Double with 128 values (the face descriptor)
EmbeddingDistance(emb1, emb2)	Euclidean distance between two embeddings
VerifyFace(emb1, emb2, threshold)	Returns True if distance < threshold (typically 0.6)
FreeRecognizer(recognizer)	Release recognizer model from memory

Convenience API

High-level helpers that run the full pipeline from a file path in one call.

Function	Description
FaceEmbeddingsFromFile(imagePath, predictorPath, recognizerPath)	Load image, detect all faces, compute embeddings. Returns array of array of Double — one embedding per face found.
FirstFaceEmbedding(imagePath, predictorPath, recognizerPath)	Like above but returns only the first face's embedding, or an empty array if no face found

uses dlib;

var embs := FaceEmbeddingsFromFile(
  '/photos/alice.jpg',
  '/models/shape_predictor_68_face_landmarks.dat',
  '/models/dlib_face_recognition_resnet_model_v1.dat'
);

if Length(embs) = 0 then
  WriteLn('No faces found')
else
  WriteLn('Got ' + IntToStr(Length(embs)) + ' embedding(s)');

Object Detection API

Train a custom sliding-window object detector using HOG features and a linear SVM. Suitable for rigid objects with a consistent appearance (faces, car logos, signs).

Function	Description
NewObjectDetector	Create an empty trainable object detector
AddTrainingSample(det, img, boxes)	Add a labeled image with bounding box annotations
TrainDetector(det, threads)	Train the SVM on accumulated samples
SaveDetector(det, path)	Save trained detector to a .svm file
LoadObjectDetector(path)	Load a previously trained .svm detector
DetectObjects(det, img)	Run detection; returns array of TDlibRect
FreeObjectDetector(det)	Release detector memory

Image Augmentation API

Simple transforms to prepare images or augment training sets.

Function	Description
ResizeImage(img, width, height)	Resize to exact dimensions, returns a new TDlibImage
CropImage(img, rect)	Crop to the given TDlibRect, returns a new image
FlipHorizontal(img)	Mirror the image left-to-right
ToGrayscale(img)	Convert to single-channel grayscale
AdjustBrightness(img, delta)	Add delta (-255..255) to all pixel intensities
RotateImage(img, angleDeg)	Rotate by degrees, clipping to original canvas size

Model Files

Download pre-trained model files from dlib.net/files/. All files are bzip2-compressed; extract before use.

File	Size	Used for
shape_predictor_68_face_landmarks.dat	~100 MB	68-point landmark prediction (required for embeddings)
shape_predictor_5_face_landmarks.dat	~9 MB	5-point landmarks (faster, for alignment only)
dlib_face_recognition_resnet_model_v1.dat	~22 MB	128-d face embedding computation
mmod_human_face_detector.dat	~0.7 MB	CNN face detector (more accurate than HOG)

Distance Thresholds Guide

Euclidean distance between two 128-d embeddings produced by dlib_face_recognition_resnet_model_v1.dat:

Distance	Interpretation
< 0.4	Very likely the same person (high-confidence match)
< 0.6	Probably the same person (standard threshold for most applications)
0.6 – 0.8	Uncertain — consider flagging for human review
> 0.8	Almost certainly different people