From b6233a6073c6b8dc6e7ad7a63e6174074c349988 Mon Sep 17 00:00:00 2001
From: Robin <robmarkcole@gmail.com>
Date: Wed, 13 Jun 2018 21:17:48 +0100
Subject: [PATCH] Update image_processing.facebox.markdown (#5531)

* Update image_processing.facebox.markdown

* Minor changes

* Update image_processing.facebox.markdown
---
 .../image_processing.facebox.markdown         | 40 +++++++++++++++++--
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/source/_components/image_processing.facebox.markdown b/source/_components/image_processing.facebox.markdown
index 529722d8fbf..480606b6ea1 100644
--- a/source/_components/image_processing.facebox.markdown
+++ b/source/_components/image_processing.facebox.markdown
@@ -1,7 +1,7 @@
 ---
 layout: page
 title: "Facebox"
-description: "Detect and recognise faces with Facebox."
+description: "Detect and recognize faces with Facebox."
 date: 2018-05-03 00:00
 sidebar: true
 comments: false
@@ -13,14 +13,21 @@ featured: false
 ha_release: 0.70
 ---
 
-The `facebox` image processing platform allows you to detect and recognise faces in a camera image using [Facebox](https://machinebox.io/docs/facebox). The state of the entity is the number of faces detected, and recognised faces are listed in the `matched_faces` attribute. 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:
-```
+The `facebox` image processing platform allows you to detect and recognize faces in a camera image using [Facebox](https://machinebox.io/docs/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.
+
+## {% linkable_title 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:
+
+```bash
 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.
+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.
+
+## {% linkable_title Configuration %}
 
 To enable this platform in your installation, add the following to your `configuration.yaml` file:
 
@@ -58,3 +65,28 @@ source:
       required: false
       type: string
 {% endconfiguration %}
+
+## {% linkable_title Automations %}
+
+Use the `image_processing.detect_face` events to trigger automations, and breakout the `trigger.event.data` using a [data_template](https://www.home-assistant.io/docs/automation/templating/). The following example automation sends a notification when Ringo Star is recognized:
+
+{% raw %}
+```yaml
+- 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
+```
+{% endraw %}
+
+## {% linkable_title Optimising resources %}
+
+[Image processing components](https://www.home-assistant.io/components/image_processing/) 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.