Environment Variables

The following environment variables can change the runtime behaviour of the SDK. Note, the variables must be set prior to initializing the SDK.

To set an environment variable in your shell, run export VARIABLE_NAME=VARIABLE_VALUE.

OMP_NUM_THREADS

Used to limit the maximum number of threads used by the SDK. The SDK inference engines can use up to 8 threads each, but this is dependant on the number of cores your system has. The batchIdentifyTopCandidate function is capable of using all cores on your machine, depending on the number of probe Faceprints provided. To limit the number of threads used by the SDK, use the OMP_NUM_THREADS environment variable. The SDK has been optimized to reduce latency. If you instead want to increase throughput, then limit the number of threads and instead run inference using multiple instances of the SDK in parallel.

The following graph shows the impact of threads on inference speed.

As can be seen, the graph follows an exponential decay pattern, with the greatest reduction in latency being experiences when moving from 1 thread to 2 threads. The significance of this is that we can actually enforce a reduced thread count in order to increase the CPU throughput. Consider an example where we have a CPU with 8 threads.

Scenario 1: Latency Optimized: In this scenario, we have 1 instance running inference using all 8 threads. Using the chart above, we can approximate the latency to be 75ms - given a single input image, inference can be performed in 75ms. Therefore, this scheme optimizes to reduce latency as much as possible. However, if the instance is provided with 100 input images to process, then it will take a total of 7.5s (100 images * 75ms ) to run inference.

Scenario 2: Throughput Optimized: In this scenario, we have 8 instances running inference using only 1 thread each. Using the chart above, we can approximate the latency to be 400ms - given a single input image, inference will be performed in 400ms. Although this seems like a bad tradeoff compared to scenario 1, scenario 2 shines when we have many input samples. If the instances are provided with 100 input images to process, then it will take a total of 5s (100 images * 400ms / 8 instances) to run inference.

Hence, by running more instances in parallel and reducing the number of threads per instance, we have increased the latency but also increased the overall throughput.

ex. export OMP_NUM_THREADS=4

TF_LOG_LEVEL

Used to set the log level of the SDK. Options include TRACE, DEBUG, INFO, WARN, ERROR, and OFF. Default log level is INFO.

ex. export TF_LOG_LEVEL=WARN

HOSTED_DATABASE

Specify if the PostgreSQL database is hosted by a service provider such as Digital Ocean, AWS, etc. A call to Trueface::SDK::createDatabaseConnection() first connects to the template1 database and then queries to see if the specified database exists, and if not, creates it. Hosted databases often don’t allow connections to this template1 database, therefore throwing an exception on the above SDK method call. By setting this option to true, the SDK will bypass this initial connection to the template1 database, and will connect directly to the specified database name. Therefore, if setting this option to true, you must ensure that the specified database exists. This means you must manually create the desired database within your database before the SDK can connect to said database.

Possible values include true and false. Default value is false.

ex. export HOSTED_DATABASE=true

REQUIRE_STRICT_COLLECTION_SYNC

The PostgreSQL DatabaseManagementSystem has synchronization built-in, in which the database will propagate any notifications to to any of the connected clients. Even if the network connection is interrupted, any notifications which were sent out during this period will be received when the network connection is reestablished, ensuring the client collection remains synchronized. Under rare circumstances, the connection to the database may be broken entirely. If any notifications are sent out during this period, the client will not know about them, and will still not know about them when database connection is reestablished. In this rare occurrence, it is possible for a client collection to go out of sync with the database (only if another client made any collection modifications during the time when the connection was broken).

By setting this environment variable to true, the SDK will throw an exception if the database connection is ever broken. The exception will be thrown on the subsequent call to any method that operates on the collection (ex. SDK::identifyTopCandidate(), SDK::enrollFaceprint(), etc). This allows the user to call Trueface::SDK::loadCollection() if desired to re-load the collection, ensuring it is once again synchronized. Note, even if the exception is thrown, it does not necessarily mean that the collection has gone out of sync - it simply means that the connection has been broken. Even if Trueface::SDK::loadCollection() is not called by the user when this occurs, the SDK will try to re-connect automatically.

Possible values include true and false. Default value is false.

ex. export REQUIRE_STRICT_COLLECTION_SYNC=true

DB_NOTIFICATION_CHECK_FREQUENCY

When using the PostgreSQL DatabaseManagementSystem, the SDK launches a background thread to check for any notifications sent out by the database. This ensures that the client node remains in sync with the database. By default, the background thread checks for notifications every 30 seconds. This means that it may take up to 30 seconds for all clients connected to the same database to fall into sync.

This environment variable allows you to dictate how often the SDK checks for notifications, defined as every n seconds. Hence, setting this environment variable to 5 would mean that the SDK checks for notifications every 5 seconds. Do note that the main execution thread is blocked while the background thread checks for notifications, hence why we do not check for notifications all the time.

Must be an integer value greater than 0. Default value is 30.

ex. export DB_NOTIFICATION_CHECK_FREQUENCY=10

NUM_DB_RETRIES

The number of times the SDK should try to reconnect to the database when a disconnect is detected. The SDK will wait 5 seconds between each retry. Hence, if the number of retires is set to 6, then the SDK will try to reconnect 6 times over a total period of 30 seconds. Can be set to 0, in which case the SDK will not try to reconnect to the database.

Must be an integer of value 0 or greater. Default is 6.

ex. export NUM_DB_RETRIES=12

INIT_FD_IMG_WIDTH and INIT_FD_IMG_HEIGHT

If Trueface::ConfigurationOptions.initialzeModule.faceDetector is set to true for GPU inference, then the SDK will run face detection inference on a blank image during the SDK constructor in order to warm up the weights. With the GPU face detector, anytime there is a change in the image size, there will be an initial slowdown as the GPU buffers need to be recreated. The blank image which is run during the SDK constructor has a size of 1280x720 (width x height). Therefore, if the subsequent images on which inference are run do not have these same dimensions, there will be an initial slowdown on the first inference sample. In order to avoid this, you can manually specify the image dimensions which will be run using these environment variables.

Must be an integer value greater than 0. Default is 1280 and 720.

ex, export INIT_FD_IMG_WIDTH=2048