Face ID - API Workflow

Facial Identification API and Facial ID Overview

This article will summarize how Facial ID works within our application and provide you with the FID error codes.

Four Parties Involved in Facial Indentification:

  1. CustomerThis is the person who pays monthly for the subscription service to access hdfleet.net and has requested the add-on service called Facial ID. The need to assign the facial ID profiles to driver profiles, so that matching can occur at a trip level.

  2. HD Fleet ApplicationThis is the application that stores the trip data, provides a graphical interface for customers to interact with, and sends video of the driver on every trip, so that the Facial ID team can review the video for a face and reply back with an existing FID (Facial Indentification) Profile number, a new FID Profile number or an error code.  HD Fleet may send up to 3 videos per trip to provide the system the opportunity to assign the correct driver.

  3. EdgeTensor Facial ID APIThis is an API service that HD Fleet Application interacts with involving Facial ID profiles. No facial ID profiles are stored within the HD Fleet Application, just a Facial ID # that is shared between HD Fleet and EdgeTensor. No driver personal information is shared with EdgeTensor API, only driver-facing videos, so it can build a unique facial ID profile or verify if they have seen this facial profile prior and return the existing FID Profile number. We will provide trip name, vehicle name, and other infromation to provide contextal information to assist in identifying installation issue or driver adherance to the program.  For example, if one vehicle has never identified a person regardless of the number of videos sent it might mean that the camera is blocked or not placed well.

  4. Driver - People that drive the vehicles, are assigned unique Facial ID profiles, and later linked by the customer to the Facial ID #.

FID Error Codes:

  1. N/A - No response from FID Video Processing Matching Servers.  It must have exceeded the 10-minute wait time we have set for maximum returned results.  No action is needed from the customer, but operations will be notified to review whether the FID Application is functioning properly.

  2. 139 - The video quality is poor.

  3. 113 - The video was obstructed, and no Face Profile ID could be created or matched.  

How to Enable Facial ID:

  1. Contact us or your local sales representative in your area. We will turn on the feature or enroll you in the Facial ID program.
    Info
    Note
    The link to enable FID by reseller is in your secure portal.

  2. To turn it on within our application, go to Settings, then click Customers.



  3. Find the customer you want to enable Facial ID for and click the Edit button.



  4. Check the box that state Enable Facial ID.



After enabling the API, you have to enroll the vehicles you want to participate in the Facial ID program. The vehicles must have a properly mounted camera and the drivers should sign a 'Facial Release Document' since facial features and measurements will be collected and secured for future matching.

Notes
 We suggest that you get 80% of your drivers assigned a FID Profile # before turning it on at the vehicle level.
Warning
Once the Facial ID is enabled at the customer level, HD Fleet will start sending videos so that EdgeTensor can begin to build FID Profiles.  We won't assign an FID Profile # to a trip until the vehicle itself is enabled.
Notes
Your HR Handbook is the suggested location where you add your Facial Release Form or to your new employee on-boarding documents that are signed.  
Alert
Warning
Make sure you are legally allowed to collect data from your employees.

How to Enroll Your Vehicles:

  1. Within our platform, go to Settings, and then Vehicles.


  2. Edit the vehicle you would like to enroll.



  3. Change the slider named Driver ID Enabled to Yes. The other items should default to Enrollment and Disabled.


    Info
    Note
    When Driver ID is enabled, the default driver is cleared, if set prior. It is neither unassigned nor unrecognized. It will go blank or state that Facial ID is enabled.

    Notes
    It is suggested to have your drivers built prior to turning on FID. If you need help creating drivers, check out this article.

How It Works:

  1. All trips for the enrolled vehicles send up to 3 videos per trip to the EdgeTensor API for enrollment or verification
  2. The vehicle will stay in the enrollment phase until a Facial ID # is returned for that vehicle. This assists all parties knowing if the camera is not blocked and can produce a video that can capture the facial charcteristic to produce a FID Profile #.
  3. After a Facial ID # is returned, it moves from Enrollment to Verification status, notifying our platform that the vehicle has met the minimum requirements to acknowledge future drivers.

A report can be run to determine the state of the vehicle's Facial ID status to assist in the deployment and rollout of the program.

Facial ID Report:

  1. From our platform, go to Reports and find Facial ID API Status.

  2. In the Driver ID Enabled column, there are 6 possible states.

  3. Facial ID - Calibrating.
    Info
    Note
    In this state, it may take a while for the API to identify the driver. We will attempt to identify the Facial ID # for this trip, however, after 3 attempts, it will move from unrecognized to unassigned and await manual assignment. If a Facial ID # is created while being in the Enrollment State, we will provide a Facial ID # and change the state to Verification. Otherwise, there will be an error code in the FID Code column for review.

  4. Facial ID - Identifying.
    Info
    Note
    The system is attempting to identify the driver within the trip, sending 3 videos to the API. If nothing is returned, there will be an error code letting the customer know why a match was not found, and they will have to be manually assigned. If a Facial ID # is returned, then we will attempt to link it to a Driver profile. If there isn't one found, then we will place a link to the Facial Identification Module for future matching to a driver. 

  5. Facial ID #. (It links to the Facial Identification Progroam for linking)

  6. Driver Name Matched to Facial ID #.

  7. Unrecognized. (It links to the Change Driver pop-up)

  8. Unassigned. (It links to the Change Driver Pop-up)
The Cloud AI column contains FID codes and links to the videos that were sent to the EdgeTensor API. The videos may assist you in manually assigning the driver to the trip.

Logic for AI Resolution to Unrecognized Drivers:

  1. All trips that were flagged with Unrecognized Driver would be in your Alert Board and are waiting for manual assignment after the trip is complete and marked with a review status as Not Reviewed and the driver assigned would continue to state Unreconzied Driver.



  2. If a trip was identified in the same 24-hour period, then it will assign the same Facial ID for all trips that took place prior with the same ID.  A 24-hour period is 12:00am-11:59PM.

Special Use Cases:

  1. If only 1 Facial ID # was found within the same day, then all previous trips and proceeding trips would be assigned to that same Facial ID # at the end of day.

  2. If 2 or more Facial ID #'s were found on trips throughout the day, then the logic would be all previous trips prior to the Facial ID # being assigned would be assigned to the first facial ID #, and all the proceeding trips would be assigned to the most recent Facial ID #.

  3. If no Facial ID #'s were assigned that day, then the application would keep the trips as unrecognized and is awaiting for them to be assigned manually.

When the Facial Identification module is activated, two alerts are added to the system automatically.

Assigning Facial ID #'s to Drivers:

  1. Alert of Facial ID #'s that need to be matched with Drivers. This report is scheduled at 7am CST time and sent to the customer admin on the account that their are FID Videos that need to be linked to Drivers.

  2. Alert for Unrecognized Drivers, but this alert only needs to be sent the following day, since other jobs may correct the issue and no need to report the trip on the alert board until all available methods have been exhausted. Also, the alert needs to be consolidated into one alert since we would not want an email going out 24 hours later that 1000 trips need to be assigned. It most likly should be a summary alert with an attachment if their are more than one trip that needs to be manually updated.

Videos Being Sent to EdgeTensor:

Videos will be sent 30 seconds after the vehicle starts and exceeds 5 mph. The second video is triggered based on EdgeTensor’s response and the messages received by HD Fleet.

If no messages are returned, we will wait up to 10 minutes before sending another video for review.
If a profile number is received at any time, we will cancel any future video requests.
If a second video was already sent because the first request exceeded its threshold, we may add the FID Profile number for driver matching, but it will not be assigned to the trip. Instead, we will wait for the second request to be processed.
    • Related Articles

    • Drivers Help

      The Drivers page allows you to add/edit driver profiles. You can set custom profile pictures, keep track of the number of accidents on the job, add custom notes and more. How to Add a New Driver: Log in to our platform at https://hdfleet.net and ...
    • Vehicle Pop-Up Overview

      From the vehicle pop-up window, you can view driver snapshots and HD video, live stream your driver's trips, pull up trip history, and check maintenance reminders. View Snapshots and HD Video: Click on either the Snapshots or HD Video tab to pull up ...
    • How to Create a Driver ID QR Code

      These steps will demonstrate how to create a QR code to assign a driver to their respective vehicle within the platform. They will be using the in-cab lens on the dash cam to sign in. Creating a QR Code: To create a QR code for a driver, first login ...
    • Alert Triggers

      This guide will give an in-depth explanation of our alert types and their triggers. Alert Types and Actions: Alert Types: Actions: Description: After Hours After Business Hours Sends notification that a vehicle was moving after hours Asset Event ...
    • Action Board Help

      This guide will show you how to navigate our Action Board, so you can view the most recent snapshots/videos and event history of your vehicles. Navigating the Action Board: First, log in to https://hdfleet.net. From here, click on the Action Board ...