The Trueface Elevated Body Temperature (EBT) software uses the inner canthus (eyeduct) to measure a persons temperature.

The EBT software is currently supported by the iryx thermal camera and FLIR A400 thermal camera. With the iryx thermal camera, the Trueface software runs directly onboard the camera at the edge. With the A400 camera, the software runs on a computer which is connected to the same network as the camera.

Regardless of which camera you use, the usage interface is the exact same. The Trueface Software consists of three main interfaces: a websocket stream which sends all the event data for every frame, an http configuration server used to modify the behaviour of the app, and finally a token validation micro app which can be used to obtain and validate the token. Additionally, all important information such as facial bounding boxes and temperature is drawn directly on the RTSP stream (iryx) or snapshot frame (A400).

This document describes the installation process and developer APIs for the solution.

If you encounter any bugs / mistakes in this documentation, please reach out to cyrus@trueface.ai and the issues will be fixed promptly.

The Trueface iryx solutions runs directly onboard the camera. Therefore, the software and license token must be copied and installed to the device. To receive a token, please contact sales@trueface.ai

If this is your first time using a newly purchased IRYX camera, please ensure that the thermal camera is working correctly. To do so, navigate to the web interface (enter the camera IP address in a web browser) then log in with the following web interface credentials:

Username: root

Password: admin

Next, navigate to the thermal overlay tab (one of the tabs on the left), which should display a live video of the thermal stream overlaid on the visible stream. Click anywhere on the video and it should display the temperature at the selected point in the bottom left. Check that the reported temperature is roughly correct. If the temperature is obviously incorrect (ex. Displays 50 degrees c in your office, shows the same temp no matter where you click, etc) then please contact Trueface and do not proceed with installing the software.

Note: Please avoid changing any of the default settings from the IRYX web interface as it may interfere with the Trueface software.

The default SSH username and password are as follows:

Username: root

Password: !admin This is different from the web interface password, note the extra !.

New versions of the IRYX camera come with the Trueface software already installed. However, you will need to check that the installed version is up to date, as new features and improvements are continuously being added.

To determine if the Trueface software is already installed and if so, what version, run the following command (replace <ip_addr> with your camera IP address):

The output should look something like this, where X.X indicates the version number:

trueface_temp_reader_vX.X

If the output is blank or there is a “No such file or directory” error, then the software was either not installed, or it was not installed correctly. If that is the case, refer to the Installation Instructions section below and perform all the steps.

If the output is present, then check that the installed library is most up to date. Compare the library version (indicated by the X.X) to our releases page and ensure that it is the most up to date. The releases page can be found here:

If the Trueface software version on the camera is already up to date, then you will only need to perform step 3 below, then reboot the camera. If the version is not up to date, then perform all the steps below (installing a new version of the Trueface software will remove the old version).

The following video demonstrates how to perform the instructions below:

In the following instructions, X.X should be replaced by your library version number, and <ip_addr> should be replaced by your camera IP address.

1. Navigate to the releases page and download the latest release.

2. Copy the trueface_dist_IRYX_vX.X.tgz to /mnt/data on the camera

3. Paste your Trueface token into a file called token.txt if you did not already receive it in this format (only the token itself, no quotations around the token, no json, nothing else).

Next, copy token.txt to /mnt/data on the camera

4. SSH into the camera

5. Navigate to /mnt/data

6. Extract the tarball

7. Enter the trueface_dist_IRYX_vX.X directory

8. Run the installation shell script

./install.sh

Note: Ensure the installation is successful based on the output from the shell script. If it is not successful, notify our engineers.

At this point, the camera will automatically reboot.

It will take 30 seconds after rebooting the camera for the application to start running. It will generally take 2 minutes after a reboot for the application to run at full speed (before this it will run at reduced speed while things initialize on the camera).

Note: After a cold boot, the camera will take up to 20 minutes for the temperature measurements to stabilize due to the thermal lens heating up. With a reboot, this will only take 5 minutes.

To view the stream, open a web browser and enter the IP address of the camera. Next, click settings and (after entering the username and password) navigate to the thermal overlay tab on the left. It should display a video with the bounding box and temperature drawn onto the video stream.

Alternatively, you can view the stream from VLC or another RTSP client by connecting to rtsp://root:admin@<ip_addr>/stream<stream_number> (learn more about stream_number here)

If the app installed correctly, the stream should look something like this:

The FLIR A400 software runs on a (x86) computer which is connected to the same network as the camera. This device can be running any OS, as long as it has docker installed.

Start by navigating to the web interface (enter the camera IP address in the browser). Use the login credentials provided by FLIR. They can be found inside the getting started manual provided by FLIR.

On the left hand tab, under the “Data presentation modes” section, click on “Image mode”, then ensure “Visual” is selected. Refer to the following image:

Note: You must have docker installed to proceed.

To obtain Trueface software, run the following command. For a list of all releases, please visit https://hub.docker.com/r/trueface/flir-a400/tags

To run the Trueface software, run the following command. You will need to replace ${YOUR_TOKEN} with your license token and ${A400_IP} with the IP address of the A400 camera.

Some other things to note. In the above command, we mount the /trueface_a400 directory in the container to the $(pwd)/trueface_a400 directory on the host. This is necessary so that the configuration options and log file persist even after the container is removed. It also allows the log files to be viewed while outside of the container. Additionally, we detach the process using the docker -d flag and we assign the container the name tf-flir-a400.

The Trueface application has a configuration HTTP server running on port 8090. This configuration server can be used to both configure the application, and also to generate face recognition templates. For the IRYX camera, the configuration server will be running on the camera. For the FLIR A400 solution, the configuration server will be running on the same computer which is running the Trueface software.

For full documentation of all the endpoints (with sample CURL requests) please refer to our postman collection.

Once changes are made using the configuration API, the camera must be rebooted for the changes to take effect. Alternatively, you can run the following command from on the camera to restart the service:

/etc/init.d/S98trueface restart

It will take 30 seconds after rebooting the camera / restarting the service for the application to start.

Note: After a cold boot, the camera will take up to 20 minutes for the temperature measurements to stabilize due to the thermal lens heating up. With a reboot, this will only take 5 minutes.

Once changes are made using the configuration API, the application must be restarted. To do so, stop and restart the container.

To stop the container, run docker kill tf-flir-a400

To start the container again (with the new config options), run docker start tf-flir-a400

If you need to enter the running container (to debug, view logs, etc), run docker exec -it tf-flir-a400 bash

The Trueface application will stream event data over websocket on default port 8091 (can be changed from config server).

Websocket URL: ws://<ip_address>:<port>

For the IRYX camera, the websocket server will be running on the camera. For the FLIR A400 solution, the websocket server will be running on the same computer which is running the Trueface software (localhost).

At first glance, the IRYX and A400 websocket packets may look quite similar; however, there are some notable differences. With the A400 application, the temperature detection is running asynchronously and is separate from the main face detection loop. Therefore, there can be instances where a face and eyeduct are detected in the main loop, but no face is detected in the asynchronous temperature detection loop. Therefore, there is an additional field called temp_detected which should be checked.

Additionally, since Trueface cannot draw directly on the A400 RTSP streams like is done with the IRYX RTSP streams, there is an additional field in the websocket packet called snapshot. This is a base64 encoded RGB jpg image of the entire frame with the bounding box and overlay temperature text. Display this image to simulate a video stream. Refer to the sample frontend app for an example of how to do this.

As mentioned, all important information such as facial bounding boxes and temperature is drawn directly on the RTSP stream (IRYX) or snapshot frame (A400).

The green bounding box will surround either the left or right eye duct, based on the orientation of the head:

If the bounding box around the face is red, it indicates that the eye duct is not fully visible or its position could not be computed accurately. This can be resolved by facing the camera directly, and ensuring to stay in the center of the frame.

If no bounding box is drawn, it indicates that the face did not pass the liveness test (and there may be a spoof attempt). Note, the liveness test may fail (and consequently no bounding box is drawn) if the face is moving in the frame quickly. For best results, ensure the face is centered in the frame and not moving for at least 1 second.

There are currently three sample apps:

The sample apps can be found here.

The following is a demo of the sample front end app which demonstrates how to display the RTSP / snapshot in a web browser.

Some license agreement schemes may required you to lock each individual token to a specific camera. If this is the case, then you must run an executable to generate a fingerprint ID for the camera. This fingerprint ID must be provided to Trueface then the token will then be locked to this fingerprint ID.

If the Trueface software has not already been installed to the IRYX camera then be sure to first install the Trueface software (instructions here).

To generate the fingerprint, ssh into the camera and navigate to /mnt/data/trueface_dist_IRYX_vX.X , then run the executable called generateFingerprintIRYX. Note, this executable is only available in v1.8.1 a newer, so upgrade your version if necessary.

Running the executable will print the device fingerprint to the console. Provide this to Trueface and the appropriate token will be generated.

In order to generate a fingerprint ID for the A400 camera, start by pulling the trueface/flir-a400-generate-fingerprint dockerhub image. Next, run the following command, substituting ${A400_IP} for your camera's IP address.

If the executable runs successfully, it will print the device fingerprint to the console. Provide this to Trueface and the appropriate token will be generated.

The IRYX camera has a standard ¼ - 20 mounting thread on the backside and is therefore compatible with most camera mounts / tripods.

We advise you to calibrate your camera to work best at your operating distance (we suggest ~2 feet). To do so, start by running the re-enable_overlay_for_calibration.sh shell script which comes in the distribution package. If the Trueface software has been installed to the camera, this script can be found at /mnt/data/trueface_dist_IRYX_vX.X/ . This will re-enable the thermal overlay (and disable the Trueface software ... we'll cover re-enabling it later) and will allow you to calibrate the thermal and visible offset. Next, navigate to http://<ip_addr>/priv/toverlay_adjust.html and then press the up / down / left / right buttons until the thermal and visible frames align correctly (note you may need to refresh the page to see live changes). Do not press the bigger / smaller buttons. Once you are happy with the changes, re-install the Trueface software on the camera by running install.sh (which is also in the distribution package) and you should be good to go.

Poor Alignment of thermal an visual images, adjustment buttons are in the top-left corner.

Better Alignment

Next, you should also be sure to specify the operating distance of the camera for best performance.

Navigate to the thermal tab, then set the distance to your operating distance:

If the camera requires further tuning, you can add a "manual temperature" to the temperature from the same tab on the web interface. Alternatively, you can achieve this using the /config endpoint and setting the offset_temperature value appropriately.

If you encounter any bugs or unexpected behaviour while running the application, please send the log files to the Trueface engineering team. On the IRYX device, the log files can be found in /var/trueface_logs/. In the A400 docker container, the log files can be found in /trueface_a400/trueface_logs/. The team will help you debug the problem.

Version v1.10 adds a micro server for token validation. This server runs on port 8092 and supports a single endpoint GET /token

This endpoint can be used to retrieve the token on the camera. This is helpful as this same token can be used for the Trueface SDK, thus more complex applications which utilize both the EBT solution and SDK can share a single token. In addition, the endpoint can be used to validate the token. This is helpful as this endpoint will run even when the main temperature app itself may have crashed (due to an invalid token for example).

curl --location --request GET "http://{camera_ip}:8092/token"

valid (boolean) - Returns true of the token is of the correct format, or false if the token has been corrupted, is missing fields, has an incorrect signature, etc. Note, an expired token (which is still a valid token) will return true.

message (string) - Will return "Success" if the token has passed all the checks and has not expired. Otherwise, will return the error message.

token (string) - The token. Will be an empty string if no token was found on the device.

days_remaining (int) - The number of days remaining for the token. An expired token will return 0.

So to check if a token is usable, you should check that valid is true and that days_remaining > 0.

Fixed

Added

Fixed

Added

Changed

Changed

Added

Fixed

Added

Added

Changed

Fixed

Fixed

Fixed

Breaking

Added

Changed

Added

Changed

Added

Added

Added

Changed

Fixed

Added

Added