Trueface SDK Reference - Stable

Welcome to the Trueface SDK. The SDK allows you to integrate Trueface’s AI models directly into your application while ensuring maximum performance and flexibility. Start by downloading the correct version of the SDK for your target platform and desired language. Next, refer to the General section for guidance on how to initialize the SDK.

Downloads

Stable release version 0.29.12111

Choosing Your Release Type

Alpha contains the absolute latest features (updated daily), but may also contain bugs. Beta contains fewer bugs while still having relatively new features. Stable will contain the fewest bugs but will take the longest to get new features. You will generally want to choose the Beta or Stable releases.

• Alpha

• Beta

• Stable

Note, if downloading the SDK in an automated manner (ex. building docker images) and you always require the latest SDK version, then replace the postfix in the download link (SDK version) with _latest.zip instead. So for example, https://reference.trueface.ai/cpp/staging/latest/uploads/truefaceSDK_v0.10.5483.zip would become https://reference.trueface.ai/cpp/staging/latest/uploads/truefaceSDK_latest.zip.

If you require a previous version of the documentation or SDK downloads, refer to the Previous Stable Releases tab on the left.

x86-64 C++

Target platform	SHA256	Notes
C++ x86-64 CPU Linux, Ubuntu 18.04 and CentOS 8	0c9a46e573...	Compiled with gcc 7.5.0, GLIBC 2.27, tested on Ubuntu 18.04 and CentOS 8.
C++ x86-64 CPU Linux, Ubuntu 20.04	e039846514...	Compiled with gcc 9.3.0, GLIBC 2.31, tested on Ubuntu 20.04.
C++ x86-64 GPU CUDA-10.1 Linux, Ubuntu 18.04 and CentOS 8	0d49e5c4b3...	Compiled with gcc 7.5.0, GLIBC 2.27, Cuda 10.1, tested on Ubuntu 18.04 and CentOS 8. Must install GPU dependencies.
C++ x86-64 GPU CUDA-11.2 Linux, Ubuntu 18.04 and CentOS 8	8a69980661...	Compiled with gcc 7.5.0, GLIBC 2.27, Cuda 10.1, tested on Ubuntu 18.04 and CentOS 8. Must install GPU dependencies.
C++ x86-64 GPU CUDA-11.2 Linux, Ubuntu 20.04	d6953a7e26...	Compiled with gcc 9.3.0, GLIBC 2.31, Cuda 11.2, tested on Ubuntu 20.04. Must install GPU dependencies.
C++ x86-64 CPU macOS	dd6e9b7ec9...	Compiled with AppleClang 11.
C++ x86-64 CPU Windows	4420c03e09...	Compiled with MSVC 19.28.29913.0 in Release mode. More info.

x86-64 Python bindings

Python bindings Documentation

Python bindings documentation can be found here

Target platform	SHA256	Notes
Python 3.6 64Bit CPU Linux	50f04b5ae3...	Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. For CentOS, must run dnf install -y libgomp.
Python 3.6 64Bit GPU CUDA-10.1 Linux	2a7c2870df...	Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. Must install GPU dependencies.
Python 3.7 64Bit CPU Linux	7e50b83bc5...	Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. For CentOS, must run dnf install -y libgomp.
Python 3.7 64Bit CPU macOS	5c97d44c5b...
Python 3.7 64Bit GPU CUDA-10.1 Linux	5fb29100f3...	Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. Must install GPU dependencies.
Python 3.8 64Bit CPU Linux	adb0644b0a...	Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. For CentOS, must run dnf install -y libgomp.
Python 3.8 64Bit CPU macOS	635975803d...
Python 3.8 64Bit GPU CUDA-10.1 Linux	b0819de919...	Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. Must install GPU dependencies.
Python 3.8 64Bit GPU CUDA-11.2 Linux	5ece232d7c...	Tested on Ubuntu 20.04. Must install GPU dependencies.

ARM C++

Target platform	SHA256	Notes
Aarch64 CPU Linux	e1d8ac8188...	Compiled with aarch64-linux-gnu-g++ 7.5.0, GLIBC 2.27, tested on Ubuntu 18.04.
Aarch64 GPU CUDA-10.2 Linux, Ubuntu 18.04	098f2262ae...	Compiled with aarch64-linux-gnu-g++ 7.5.0, GLIBC 2.27, CUDA-10.2, tested on Ubuntu 18.04. Must install GPU dependencies
Aarch32 CPU Linux	0acec1fca5...	Compiled with arm-linux-gnueabihf-g++ 7.5.0, GLIBC 2.27, tested on Ubuntu 18.04.

ARM Python Bindings

Python bindings Documentation

Python bindings documentation can be found here

Target platform	SHA256	Notes
Python 3.6 64Bit CPU Linux Aarch64	115d2314ac...	Tested on Ubuntu 18.04.
Python 3.6 64Bit GPU CUDA-10.2 Linux Aarch64	098f2262ae...	Tested on Ubuntu 18.04. Must install GPU dependencies.
Python 3.6 32Bit CPU Linux Aarch32	bdd30ad4a3...	Tested on Ubuntu 18.04.
Python 3.7 64Bit CPU Linux Aarch64	3049d870b8...	Tested on Ubuntu 18.04.
Python 3.7 32Bit CPU Linux Aarch32	bc56650f16...	Tested on Ubuntu 18.04.

iOS

iOS SDK Documentation

iOS SDK documentation can be found here

Target platform	SHA256	Notes
iOS	33956ce5b2...	Package contains both ARM64 and X86_64 SDK.

Android

Target platform	SHA256
Android	N/A

GPU SDK Dependencies

While the CPU SDK is dependency free (only requires OpenMP for Linux and Windows), the GPU SDK does have a few dependencies which must be installed. As of right now, the CUDA 10.1 SDK supports Ubuntu and CentOS, while the CUDA 11.2 SDK only supports Ubuntu (this is due to GLIBC versions). We will assume you already have the nvidia drivers installed on your machine.

CUDA 10.1 - Ubuntu

You will need to install CUDA 10.1, cudnn7, libomp, libgomp, and libopenblas.

All the necessary runtime dependencies can be installed on Ubuntu 18.04 by running the following commands:

apt-get install -y libomp-dev libopenblas-dev software-properties-common libgomp1
add-apt-repository ppa:graphics-drivers
apt-key adv --fetch-keys  http://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/7fa2af80.pub
bash -c 'echo "deb http://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64 /" > /etc/apt/sources.list.d/cuda.list'
bash -c 'echo "deb http://developer.download.nvidia.com/compute/machine-learning/repos/ubuntu1804/x86_64 /" > /etc/apt/sources.list.d/cuda_learn.list'
apt update
apt install cuda-10-1
apt install libcudnn7
export PATH=/usr/local/cuda-10.1/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda-10.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda-10.2/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

If using docker, we advise using the nvidia/cuda:10.1-cudnn7-runtime-ubuntu18.04 docker image.

If using Ubuntu 20.04 (for python bindings library), then you may have to run sudo ln -s /usr/lib/x86_64-linux-gnu/libomp.so.5 /usr/lib/x86_64-linux-gnu/libomp.so.

CUDA 10.1 - CentOS

Starting from the nvidia/cuda:10.1-cudnn7-runtime-centos8 docker image, run the following commands:

dnf --enablerepo=powertools install -y openblas-devel
dnf install -y libgomp libomp

CUDA 11.2 - Ubuntu 18.04

Starting from the nvidia/cuda:11.2.0-cudnn8-runtime-ubuntu18.04 docker image, run the following commands:

apt-get install -y libomp-dev libopenblas-dev libgomp1

CUDA 11.2 - Ubuntu 20.04

Starting from the nvidia/cuda:11.2.0-cudnn8-runtime-ubuntu20.04 docker image, run the following commands:

apt-get install -y libomp-dev libopenblas-dev libgomp1
ln -s /usr/lib/x86_64-linux-gnu/libomp.so.5 /usr/lib/x86_64-linux-gnu/libomp.so

AArch64 CUDA 10.2 - Ubuntu 18.04

The NVIDIA Jetson OS comes with the required version of CUDA and cudnn pre-installed. Therefore, only the following commands must be run:

apt-get install -y libomp-dev libopenblas-dev libgomp1

Windows SDK

Our team does the majority of development and testing in a Linux environment. The Windows SDK may therefore contain more bugs than the other platform releases and may be lacking in a few features. The current known issues and limitations are as follows:

• Any file including winerror.h must have #undef NO_ERROR as the NO_ERROR defined in winerror.h conflicts with Trueface::ErrorCodes::NO_ERROR.

• TFV5 inference is slower than FULL model inference and is under investigation.

• Trueface::SDK::identifyTopCandidate() and Trueface::SDK::identifyTopCandidates() will only use a single thread for search and will therefore be slower than searches run on Unix platforms. However, Trueface::SDK::batchIdentifyTopCandidate() is capable of using multiple threads.

Dependencies which must be installed. They can easily be installed by installing Git for Windows:

• libintl-8.dll

• libcrypto-1_1-x64.dll

• libsll-1_1-x64.dll

As of this time, we are only supporting a release configured version of the library (and not a debug version). The library is built as a dynamic library; therefore, you must link against libtf.lib when compiling your application and must ensure that libtf.dll is in the same directory as your executable.

Getting Started Tutorials

Every SDK download package comes bundled with sample code demonstrating proper usage of the SDK for various tasks such as face detection, face recognition, object detection, mask detection, and more. Start by understanding how the sample code works by reading the comments in the code.

Sample Apps

Sample Apps demonstrate full working applications. These extend the scope of the sample code which comes shipped with the SDK.

Reporting SDK Bugs and Documentation Errors

If you encounter a bug in the SDK, please send an email to support@trueface.ai. Please include at minimum the following:

• SDK version

• SDK target (ex. Python 3.7 64Bit CPU Linux)

• Expected behaviour

• Observed behaviour

• A minimal reproducible code example showing how to replicate the bug

• Any input images used

The more information you provide, the faster we can diagnose the issue and push out a fix.

If you happen to find a mistake (spelling, syntax error, etc.) in the latest Alpha, Beta, or Stable documentation, please email support@trueface.ai with a screenshot of the mistake, documentation version number (same as SDK version), and the release type (Alpha, Beta, or Stable). We will push out a fix as soon as we can.

C++ (Stable) - Contents:

• General
  • Deprecated
• License Validation
• Input Image
• Face Detection
• 1 to 1 Face Recognition
• 1 to N Identification
  • Overview
  • Using Multiple SDK Instances in a Single Process
  • Database Management Systems and Collection Synchronization
  • Memory Requirements and Workarounds
  • Selecting the Best Enrollment Image
• Object Detection
• Spoof Detection
  • Active Spoof
  • Passive Spoof
• Body Pose Estimation
• Liveness
• Mask Detection
• Eye glasses Detection
• Environment Variables
• Frequently Asked Questions
  • How many threads does the SDK use for inference?
  • How can I reduce the number of threads used by the SDK?
  • How can I run inference with multiple instances of the SDK on a single CPU?
  • How can I increase throughput?
  • Is the SDK threadsafe?
  • What architecture should I use when I have multiple camera streams producing lots of data?
  • What is the difference between the static library and the dynamic library?
  • What hardware does the GPU library support?
  • Why is my license key not working with the GPU library?
  • Why does the first call to an inference function take much longer than the subsequent calls?
  • How do I use the python bindings for the SDK?
  • How do I choose a similarity threshold for face recognition?
  • What are the differences between the face recognition models?
  • Are Faceprints compatible between models?
  • How can I upgrade my collection if is filled with Faceprints from a deprecated model?
  • What is the difference between similarity score and match probability?
  • There are many face detection and recognition functions. Which should I use?
  • How do createDatabaseConnection and createLoadCollection work?
  • Why are no faces being detected in my large images?
  • How can I speed up face detection?
  • What does the frVectorCompression flag do? When should I use it?
• Changelog
  • v0.29: September 13, 2021
  • v0.28: August 18, 2021
  • v0.27: August 2, 2021
  • v0.26: July 6, 2021
  • v0.25: June 22, 2021
  • v0.24: June 8, 2021
  • v0.23: May 27, 2021
  • v0.22: May 12, 2021
  • v0.21: May 4, 2021
  • v0.20: April 26, 2021
  • v0.19: April 14, 2021
  • v0.18: March 29, 2021
  • v0.17: March 11, 2021
  • v0.16: February 25, 2021
  • v0.15: February 16, 2021
  • v0.14: January 25, 2021
  • v0.13: January 15, 2021
  • v0.12: January 4, 2021
  • v0.11: December 23, 2020
  • v0.10: December 11, 2020
  • v0.9: November 20, 2020
  • v0.8: November 9, 2020
  • v0.7: August 14, 2020
  • v0.6: July 7, 2020
• Previous Stable Releases
  • 0.28.11386
  • 0.27.10876
  • 0.26.10390
  • 0.25.10099
  • 0.24.9786
  • 0.24.9740
  • 0.23.9508
  • 0.23.9476
  • 0.22.9292
  • 0.22.9196
  • 0.21.8922
  • 0.20.8553
  • 0.19.8416
  • 0.18.7976
  • 0.17.7745
  • 0.17.7722
  • 0.16.7561
  • 0.16.7542
  • 0.15.7233
  • 0.15.7198
  • 0.15.7184
  • 0.14.6743
  • 0.14.6732
  • 0.14.6709
  • 0.14.6699
  • 0.13.6676
  • 0.13.6670
  • 0.13.6500
  • 0.12.6330
  • 0.12.6300
  • 0.11.6229
  • 0.10.5855
  • 0.10.5732
  • 0.9.5131
  • 0.8.4786
  • 0.7.3005

• Index