CompreFace

Exadel CompreFace is a free and open-source face recognition service.

It provides capabilities for:

Face recognition
Face verification
Face detection
Landmark detection
Mask detection
Head pose detection
Age
Gender recognition

See the getting started guide to learn how to use CompreFace.

Configuration

Configuration example

compreface:
  face_recognition:
    host: compreface
    port: 8000
    recognition_api_key: !secret compreface_api_key
    train: true
    face_plugins: age,gender
    cameras:
      camera_one:
    labels:
      - person

comprefacemap required

CompreFace configuration.

face_recognitionmap (optional)

Face recognition domain config.

camerasmap required

Camera-specific configuration. All subordinate keys corresponds to the camera_identifier of a configured camera.

<CAMERA_IDENTIFIER>map required

Camera identifier. Valid characters are lowercase a-z, numbers and underscores.

labelslist (optional)

A list of labels that when detected will be sent to the post processor. Applies only to this specific camera.

hoststring required

IP or hostname to your CompreFace server.

portinteger required

Port to your CompreFace server.

recognition_api_keystring required

API key to your CompreFace recognition service.

labelslist (optional)

A list of labels that when detected will be sent to the post processor. Applies to all cameras defined under cameras.

face_recognition_pathstring (optional, default: /config/face_recognition/faces)

Path to folder which contains subdirectories with images for each face to track.

save_unknown_facesboolean (optional, default: true)

If set to true, any unrecognized faces will be stored in the database, as well as having a snapshot saved. You can then move this image to the folder of the correct person to improve accuracy.

unknown_faces_pathstring deprecated

DEPRECATED. Config option 'unknown_faces_path' is deprecated and will be removed in a future version.

Path to folder where unknown faces will be stored.

expire_afterfloat (optional, default: 5)

Time in seconds before a detected face is no longer considered detected.

Lowest value: 0

save_facesboolean (optional, default: true)

If set to true, detected faces will be stored in the database, as well as having a snapshot saved.

trainboolean (optional, default: false)

Train CompreFace to recognize faces on Viseron start. Disable this when you have a good model trained.

det_prob_thresholdfloat (optional, default: 0.8)

Minimum required confidence that a recognized face is actually a face.

Lowest value: 0

Highest value: 1

similarity_thresholdfloat (optional, default: 0.5)

CompreFace does not return unknown for faces that it does not recognize. If you upload the faces of two different people, you still receive the result, but the similarity is low. Any similarity below this threshold will be considered as an unknown face.

Lowest value: 0

Highest value: 1

limitinteger (optional, default: 0)

Maximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit.

prediction_countinteger (optional, default: 1)

Maximum number of subject predictions per face. It returns the most similar subjects.

face_pluginsstring (optional)

Comma-separated slugs of face plugins. If empty, no additional information is returned. Learn more

statusboolean (optional, default: false)

If true includes system information like execution_time and plugin_version fields.

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

danger

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

Troubleshooting

To enable debug logging for compreface, add the following to your config.yaml

/config/config.yaml
logger:
  logs:
    viseron.components.compreface: debug

CompreFace

Configuration​

Face recognition​

Labels​

Train​

Troubleshooting​

Configuration

Face recognition

Labels

Train

Troubleshooting