Facebox


The facebox image processing platform allows you to detect and recognize faces in a camera image using Facebox. The state of the entity is the number of faces detected, and recognized faces are listed in the matched_faces attribute. An image_processing.detect_face event is fired for each recognized face, and the event data provides the confidence of recognition, the name of the person, the image_id of the image associated with the match, the bounding_box that contains the face in the image, and the entity_id that processing was performed on.

Setup

Facebox runs in a Docker container and it is recommended that you run this container on a machine with a minimum of 2 GB RAM. On your machine with Docker, run the Facebox container with:

MB_KEY="INSERT-YOUR-KEY-HERE"

sudo docker run --name=facebox --restart=always -p 8080:8080 -e "MB_KEY=$MB_KEY"  machinebox/facebox

If you only require face detection (number of faces) you can disable face recognition by adding -e "MB_FACEBOX_DISABLE_RECOGNITION=true" to the docker run command.

Configuration

To enable this platform in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
image_processing:
  - platform: facebox
    ip_address: 192.168.0.1
    port: 8080
    source:
      - entity_id: camera.local_file
        name: my_custom_name

Configuration Variables

ip_address

(string)(Required)The IP address of your machine hosting Facebox.

port

(string)(Required)The port which Facebox is exposed on.

source

(map)(Required)The list of image sources.

entity_id

(string)(Required)A camera entity id to get picture from.

name

(string)(Optional)This parameter allows you to override the name of your image_processing entity.

Automations

Use the image_processing.detect_face events to trigger automations, and breakout the trigger.event.data using a data_template. The following example automation sends a notification when Ringo Star is recognized:

- id: '12345'
  alias: Ringo Starr recognised
  trigger:
    platform: event
    event_type: image_processing.detect_face
    event_data:
      name: 'Ringo_Starr'
  action:
    service: notify.platform
    data_template:
      message: Ringo_Starr recognised with probability {{ trigger.event.data.confidence }}
      title: Door-cam notification

Service facebox_teach_face

The service facebox_teach_face can be used to teach Facebox faces.

Service data attribute Optional Description
entity_id no Entity ID of Facebox entity.
name no The name to associate with a face.
file_path no The path to the image file.

A valid service data example:

{
  "entity_id": "image_processing.facebox_local_file",
  "name": "superman",
  "file_path": "/images/superman_1.jpeg"
}

An image_processing.teach_classifier event is fired for each service call, providing feedback on whether teaching has been successful or unsuccessful. In the unsuccessful case, the message field of the event_data will contain information on the cause of failure, and a warning is also published in the logs. An automation can be used to receive alerts on teaching, for example, the following automation will send a notification with the teaching image and a message describing the status of the teaching:

- id: '11200961111'
  alias: Send facebox teaching result
  trigger:
    platform: event
    event_type: image_processing.teach_classifier
    event_data:
      classifier: facebox
  action:
    service: notify.platform
    data_template:
      title: Facebox teaching
      message: Name  teaching was successful? 
      data:
        file: '  '

Optimising resources

Image processing components process the image from a camera at a fixed period given by the scan_interval. This leads to excessive processing if the image on the camera hasn’t changed, as the default scan_interval is 10 seconds. You can override this by adding to your config scan_interval: 10000 (setting the interval to 10,000 seconds), and then call the image_processing.scan service when you actually want to perform processing.