Face Recognition in Pegasus: setup guide

This guide explains how to register your drivers and create the trigger so Pegasus automatically identifies who is driving a vehicle, using the photo sent by the camera.

How it works

When the vehicle's camera takes a photo (for example, when the vehicle is turned on or the panic button is pressed), Pegasus compares it with the photos of your registered drivers. If it finds a match, it assigns that driver to the vehicle.

Before you start

Important: face recognition only works with photos, not video. Make sure the camera events you will use (for example, ignition or panic) are set to capture a photo. If an event only sends video, there is nothing to compare and the driver will not be assigned.

Your Pegasus user must have write permissions for assets.

You need a camera facing the driver's face (cabin camera or DMS), from any brand integrated with Pegasus. The camera must send PHOTOS, not video: face recognition only works with photos. If the camera is set to send video for the events you will use, change them to photo (for example, the ignition event or the button-pressed event).

Have a photo of each driver ready: 300 x 300 pixels, front-facing, with the face filling most of the image.

We recommend letting your drivers know, before you turn on face recognition, that their photo will be used to identify them.

Part 1: Register your drivers

Drivers are registered in the Assets module. Each driver's photo is used as the reference for recognition.

Step 1. Go to Organization, then Assets, and click the + button (bottom right).

Step 2. Select Regular Asset and fill in the details. Required fields: First Name, Last Name and License Number. The license number is used to register the driver in the recognition system and must be unique for each driver. If it is missing, Pegasus will not let you turn on face recognition.
Why the license number is required: when you turn on Face Recognition, Pegasus sends the driver's photo together with their first name, last name and license number to the recognition service, where they are stored as the driver's profile. The license number is part of that profile, so it must be filled in and unique for each driver. Without it, the toggle cannot be turned on.

Step 3. In the Groups tab, add at least one group that also contains the vehicles this driver can drive. If the driver and the vehicle do not share a group, the driver will not be assigned. Then click Create.

Once created, you will see the asset detail screen:

Step 4. Click the + button on the photo and upload the 300 x 300 pixel image.
Photo tips: use a white or plain background, no glasses, cap or accessories, and the face looking straight at the camera with good front lighting. Ideally, it should look like the driver's license photo. Use JPG or PNG format.

Step 5. Turn on the Face Recognition toggle. This registers the photo as the reference. If the toggle does not turn on, check that first name, last name, license number and photo are all filled in.
Changing the photo later: if you replace the driver's photo while face recognition is on, Pegasus updates the reference automatically. If that update fails, the toggle turns off by itself. Just turn it back on.

Repeat these steps for each driver.

Part 2: Create the trigger

Step 1. Go to Automation, then Triggers, and create a new trigger with a name that is easy to identify, for example "Face recognition".

Step 2. Condition: choose one of these two options. Takes a photo or video, to request recognition every time a photo arrives (you can filter by the labels ignon or ftgdistrct). Or Panic, to request it when the driver presses the panic button, if your camera has one.

Step 3. Entities: select the vehicles or groups that will use face recognition.

Step 4. Optional: under Options, add a 1 to 2 minute Countdown. Some cameras take a while to upload the photo, and this keeps recognition from running before the photo arrives.
Step 5. Action: add an action of type External Integration.

Step 6. Configure the External Integration with the details in the next section.

External Integration settings

Method: POST
URL: https://9xaz3r6e1k.execute-api.us-east-2.amazonaws.com/faces/recognize
Header: Content-Type: application/json
Body: copy the one that matches your camera.

Cameras that send 2 photos per event (for example, Lytx Surfsight)

Cameras that send 1 photo per event (for example, Movon or Cipia)

{
"site": {{body.pid}},
"entity": {{object.id}},
"photoURL": "https://pegasus{{body.pid}}.peginstances.com/api/event-photos.jpeg?entity_id={{object.id}}&event_id={{body.id}}&event_time={{body.event_time|date:"Y-m-d\TH:i:s"}}&session=pegapp&photo=0"
}
The only difference between the two is the end of the URL: photo=1 or photo=0. Do not change anything else in the text.
Save the trigger.

Test

With a registered driver in the vehicle, generate the event you chose (turn on the vehicle or press the panic button).

Wait a few minutes and check in Pegasus that the driver was assigned to the vehicle.

If another authorized driver is identified in the same vehicle, they replace the previous one.

If it does not work, check the following

The camera event is set to photo, not video.

The driver and the vehicle share at least one group.

The driver's photo is 300 x 300 pixels, front-facing and well lit.

The asset has first name, last name and license number filled in, and the Face Recognition toggle is on.

The trigger body uses the right photo number for your camera (photo=1 or photo=0).

Note: a driver with face recognition turned on cannot be deleted. Turn off the Face Recognition toggle first, then delete the asset. Turning off the toggle also deletes the driver's photo and data from the recognition service.
If it still does not work after these checks, contact support with the vehicle, the driver and the time of the event.