.. TruefaceSDK documentation master file, created by sphinx-quickstart on Mon Sep 16 22:16:39 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Trueface SDK Reference - Beta ============================================== 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 ######### Beta release version ``SDK_VERSION`` 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 <../../dev/latest/index.html>`_ - `Beta <../../staging/latest/index.html>`_ - `Stable <../../master/latest/index.html>`_ 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``. This is only available for Alpha and Beta releases. 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++ ********** .. list-table:: :header-rows: 1 * - Target platform - Notes - SHA256 * - `C++ x86-64 CPU Linux, Ubuntu 18.04 and CentOS 8 `_ - Compiled with gcc 7.5.0, GLIBC 2.27, tested on Ubuntu 18.04 and CentOS 8. - ``SHA256_x86_cpu_linux_cpp...`` * - `C++ x86-64 CPU Linux, Ubuntu 20.04 `_ - Compiled with gcc 9.3.0, GLIBC 2.31, tested on Ubuntu 20.04. - ``SHA256_x86_cpu_ubuntu20_cpp...`` * - `C++ x86-64 GPU cuda-11.8 Linux, Ubuntu 18.04 and CentOS 8 `_ - Must install GPU `dependencies `_. Compiled with gcc 7.5.0, GLIBC 2.27, Cuda 11.8, tested on Ubuntu 18.04 and CentOS 8. - ``SHA256_x86_gpu_cuda11_ubuntu18_04_linux_cpp...`` * - `C++ x86-64 GPU cuda-11.8 Linux, Ubuntu 20.04 `_ - Must install GPU `dependencies `_. Compiled with gcc 9.3.0, GLIBC 2.31, Cuda 11.8, tested on Ubuntu 20.04. - ``SHA256_x86_gpu_cuda11_linux_cpp...`` * - `C++ x86-64 CPU macOS `_ - Compiled with AppleClang 13.0.0. - ``SHA256_x86_cpu_macos_cpp...`` * - `C++ x86-64 CPU Windows `_ - Must install Windows `dependencies `_. Compiled with MSVC 19.35.32217.1 in Release mode. - ``SHA256_x86_cpu_windows_cpp...`` x86-64 Python bindings ********************** | **Python bindings Documentation** | Python bindings documentation can be found `here `_ .. list-table:: :header-rows: 1 * - Target platform - Notes - SHA256 * - `Python 3.6 CPU Linux `_ - For CentOS, must run ``dnf install -y libgomp``. Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. - ``SHA256_x86_cpu_linux_python3_6...`` * - `Python 3.7 CPU Linux `_ - For CentOS, must run ``dnf install -y libgomp``. Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. - ``SHA256_x86_cpu_linux_python3_7...`` * - `Python 3.8 CPU Linux `_ - For CentOS, must run ``dnf install -y libgomp``. Tested on Ubuntu 18.04, Ubuntu 20.04, and CentOS 8. - ``SHA256_x86_cpu_linux_python3_8...`` * - `Python 3.8 CPU macOS `_ - - ``SHA256_x86_cpu_macos_python3_8...`` * - `Python 3.8 GPU cuda-11.8 Linux, Ubuntu 20.04 `_ - Must install GPU `dependencies `_. Tested on Ubuntu 20.04. - ``SHA256_x86_gpu_cuda11_linux_python3_8...`` * - `Python 3.8 GPU cuda-11.8 Linux, Ubuntu 18.04 `_ - Must install GPU `dependencies `_. Tested on Ubuntu 18.04. - ``SHA256_x86_gpu_cuda11_linux_python3_8...`` ARM C++ ******* .. list-table:: :header-rows: 1 * - Target platform - Notes - SHA256 * - `Aarch64 CPU Ubuntu 18.04 `_ - Compiled with aarch64-linux-gnu-g++ 8.4.0, GLIBC 2.27, tested on Ubuntu 18.04. - ``SHA256_aarch64_cpu_linux...`` * - `Aarch64 CPU Ubuntu 20.04 `_ - Compiled with aarch64-linux-gnu-g++ 9.4.0, GLIBC 2.31, tested on Ubuntu 20.04. - ``SHA256_aarch64_cpu_ubuntu20_04...`` * - `Aarch64 GPU CUDA-10.2 Linux, Ubuntu 18.04 `_ - Must install GPU `dependencies `_. Compiled with aarch64-linux-gnu-g++ 8.4.0, GLIBC 2.27, CUDA-10.2, tested on Ubuntu 18.04. - ``SHA256_aarch64_cuda_linux...`` ARM Python Bindings ******************* | **Python bindings Documentation** | Python bindings documentation can be found `here `_ .. list-table:: :header-rows: 1 * - Target platform - Notes - SHA256 * - `Python 3.6 CPU Ubuntu 18.04 Aarch64 `_ - Tested on Ubuntu 18.04. - ``SHA256_python36_aarch64...`` * - `Python 3.6 GPU CUDA-10.2 Ubuntu 18.04 Aarch64 `_ - Must install GPU `dependencies `_. Tested on Ubuntu 18.04. - ``SHA256_aarch64_cuda_linux...`` * - `Python 3.7 CPU Ubuntu 18.04 Aarch64 `_ - Tested on Ubuntu 18.04. - ``SHA256_python37_aarch64...`` * - `Python 3.10 CPU Ubuntu 20.04 Aarch64 `_ - Tested on Ubuntu 20.04. - ``SHA256_aarch64_cpu_ubuntu20_04_python3_10...`` iOS *** | **iOS SDK Documentation** | iOS SDK documentation can be found `here `_ .. list-table:: :header-rows: 1 * - Target platform * - `iOS `_ Android ******* | **Android SDK Documentation** | Android SDK documentation can be found `here `_ .. list-table:: :header-rows: 1 * - Target platform * - `Android `_ NodeJS ****** | The NodeJS SDK can be downloaded from npm by running ``npm install @trueface/trueface-sdk-javascript`` or by visiting `this link `_. | The NodeJS documentation can be found `here `_. SDK Dependencies ################ The SDK has a few external dependencies, including: - OpenMP - libdl - ONNX Runtime When linking against the static Trueface SDK, these dependencies must be manually linked by specifying them in the ``target_link_libraries`` command in the ``CMakeLists.txt`` file. When linking against the dynamic Trueface SDK, they do not need to be manually linked as the dependency linkage has already been set to Public. Before you can run an application linking against the SDK, you will need to add the directory which contains the onnxruntime shared library (shipped as part of the SDK bundle) to you ``LD_LIBRARY_PATH`` environment variable. GPU SDK Dependencies -------------------- In addition to the dependencies listed above, the GPU SDK has a few additional dependencies which must be installed. | **CUDA 11.8 - Ubuntu 18.04** | Start by installing the NVIDIA drivers on your machine by following the instructions `here `_. | Next, you will need to install CUDA 11.8 and CuDNN 8 by following the instructions `here `_ and `here `_. | Alternatively, you can use the ``nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu18.04`` docker image. | Finally, run the following commands: .. code-block:: bash apt-get install -y libomp-dev libopenblas-dev libgomp1 Next, navigate to `this link `_, create an account or login with your existing account, then click on TensorRT 8.6 GA. From there, go ahead an download *TensorRT 8.6 GA for Linux x86_64 and CUDA 11.0, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 11.7 and 11.8 TAR Package*. Once downloaded, extract the package by running ``tar -xzf ./TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz`` then add the full path to the ``TensorRT-8.6.1.6/lib`` directory to your ``LD_LIBRARY_PATH`` environment variable (ex. ``export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/tensorrt/dir/lib``. If you want this change to persist, you should add the command to your ``~/.bashrc``.). | **CUDA 11.8 - Ubuntu 20.04** | Start by installing the NVIDIA drivers on your machine by following the instructions `here `_. | Next, you will need to install CUDA 11.8 and CuDNN 8 by following the instructions `here `_ and `here `_. | Alternatively, you can use the ``nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04`` docker image. | Finally, run the following commands: .. code-block:: bash 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 Next, navigate to `this link `_, create an account or login with your existing account, then click on TensorRT 8.6 GA. From there, go ahead an download *TensorRT 8.6 GA for Linux x86_64 and CUDA 11.0, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 11.7 and 11.8 TAR Package*. Once downloaded, extract the package by running ``tar -xzf ./TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz`` then add the full path to the ``TensorRT-8.6.1.6/lib`` directory to your ``LD_LIBRARY_PATH`` environment variable (ex. ``export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/tensorrt/dir/lib``. If you want this change to persist, you should add the command to your ``~/.bashrc``.). | **AArch64 CUDA 10.2 - Ubuntu 18.04** | The NVIDIA Jetson OS comes with the required version of CUDA, cudnn, and TensorRT pre-installed. Therefore, only the following commands must be run: .. code-block:: bash apt-get install -y libopenblas-dev If you see that your system has ``libnvinfer.so.7`` installed instead of the required ``libnvinfer.so.8``, then you'll need to update the image running on your Jetson. Windows SDK ########### For a full tutorial on how to install the Windows SDK, please consult `this video `_. Our team does the majority of development and testing in a Unix 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``. - :meth:`Trueface::SDK::identifyTopCandidate` and :meth:`Trueface::SDK::identifyTopCandidates` will only use a single thread for search and will therefore be slower than searches run on Unix platforms. However, :meth:`Trueface::SDK::batchIdentifyTopCandidate` is capable of using multiple threads. Dependencies which must be installed. These dependencies will automatically 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. We advise using "Git Bash" when compiling and and running your application to ensure the dependency libraries are properly found. Getting Started Tutorials ######################### Every SDK download package comes bundled with sample code (`C++ `_ and `Python `_) 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@pangiam.com. Please include at minimum the following: - SDK version - SDK target (ex. Python 3.7 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@pangiam.com 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. .. toctree:: :maxdepth: 1 :caption: C++ SDK Modules: usage/general usage/license usage/image usage/face_detection usage/quality usage/face_recognition usage/identification usage/object usage/spoof usage/pose usage/liveness usage/mask usage/eyeglasses usage/draw .. toctree:: :maxdepth: 1 :caption: Resources: usage/environment usage/faq usage/changelog ./releases.rst * :ref:`genindex`