Skip to main content

dlib

Face Recognition
dlib
Created: 12/27/2021
Updated: 8/22/2026

dlib is an open-source, C++ toolkit containing machine learning algorithms and other tools.

The dlib implementation in Viseron provides face recognition capabilities.

Configuration​

Configuration example
/config/config.yaml
dlib:
  face_recognition:
    model: cnn
    expire_after: 10
    cameras:
      camera_one:
        labels:
          - person
dlib​map required
dlib configuration.

Face recognition​

Face recognition runs as a post processor when a specific object is detected.

Labels​

Labels are used to tell Viseron when to run a post processor.

Any label configured under the object_detector for your camera can be added to the post processors labels section.

note

Only objects that are tracked by an object_detector can be sent to a post_processor. The object also has to pass all of its filters (confidence, height, width etc).

Train​

On startup images are read from face_recognition_path and a model is trained to recognize these faces.
The folder structure of the faces folder is very strict. Here is an example of the default one:

/config
|── face_recognition
|   └── faces
|       ├── person1
|       |   ├── image_of_person1_1.jpg
|       |   ├── image_of_person1_2.png
|       |   └── image_of_person1_3.jpg
|       └── person2
|       |   ├── image_of_person2_1.jpeg
|       |   └── image_of_person2_2.jpg
warning

You need to follow this folder structure, otherwise training will not be possible.

Models​

dlib implements two different models for face recognition, hog and cnn.
hog is less accurate but faster on CPUs.
cnn is a more accurate deep-learning model which is GPU/CUDA accelerated (if available).

If you have a CUDA compatible GPU, dlib will run the cnn model by default. Otherwise the hog model is used.

Troubleshooting​

To enable debug logging for dlib, add the following to your config.yaml
/config/config.yaml
logger:
  logs:
    viseron.components.dlib: debug