General

Before you can call the SDK functions, you must first initialize the SDK with your desired configuration options. These configuration options will ultimately impact the behaviour of the SDK, so be sure to read through what each one does carefully.

Once you have initialized the SDK, then proceed to the the License section.

class SDK

Trueface::SDK::SDK()

Initialize the SDK using default ConfigurationOptions.

See

ConfigurationOptions

Trueface::SDK::SDK(const ConfigurationOptions &options)

Initialize the SDK using custom ConfigurationOptions.

Parameters

options – custom configuration options.

static std::string Trueface::SDK::getVersion()

Gets the version-build number of the SDK.

Returns

Version Number as a string.

enum Trueface::FacialRecognitionModel

Facial recognition models. Refer to our ROC curves to compare model accuracy and our benchmarks page to compare inference speed. The current most accurate model is TFV7.

Values:

enumerator LITE

Our most lightweight model with fastest inference time but lowest accuracy, ideal for embedded systems or lightweight CPU only deployments, prototyping, and some 1 to 1 matching use cases.

enumerator LITE_V2

Lightweight model which has improved accuracy over the LITE model, though does have slightly greater inference time. Ideal for embedded systems or lightweight CPU only deployments, prototyping, and some 1 to 1 matching use cases.

enumerator TFV5_2

TFV5_2 is a substitute for our TFV5 model which was available up until SDK version 1.8. This substitution was required due to model incompatibility with our new inference framework. The accuracy and inference speed are both comparable to TFV5. However, Faceprints are not compatible between the two models; if you would like to upgrade a collection containing TFV5 Faceprints to TFV5_2 Faceprints, you will need to regenerate and re-enroll Faceprints for all your images. TFV5_2 is currently the second highest accuracy model for unmasked face images. Inference time is faster than TFV7, but comparable to TFV6. Ideal for GPU deployments and for 1 to N use cases.

enumerator TFV6

TFV6 is currently the second highest accuracy model for masked face images. Use TFV6 in situations where it is anticipated that the probe image contains a masked face (for 1 to N search), or where one or both face images are masked (for 1 to 1 comparisons). TFV6 has comparable inference time to TFV5_2, and is faster than TFV7.

enumerator TFV7

TFV7 is currently our overall highest accuracy model, but it is also our slowest model. Ideal for GPU deployments and for 1 to N use cases.

enum Trueface::ObjectDetectionModel

Object detection models.

Values:

enumerator ACCURATE

Resizes the input image to 1280x1280 (uses letterbox padding to maintain aspect ratio). Should be used for image where one or both dimensions are greater than 1280, and images with small objects.

enumerator FAST

Resizes the input image to 640x640 (uses letterbox padding to maintain aspect ratio). Should be used for smaller images, or images with large objects.

enum Trueface::FaceDetectionModel

The face detection model. For most use cases, the face model is optimal.

Values:

enumerator FAST

Fast model using a retinaface backbone.

enumerator ACCURATE

Accurate model using scrfd backbone.

enum Trueface::FaceDetectionFilter

Filters the detected faces based on face detection score.

Values:

enumerator HIGH_RECALL

Filter the detected faces based on a low score threshold. Limits false negatives (does not detect a face), but may have more false positives (classifies a non-face as a face).

enumerator HIGH_PRECISION

Filter the detected faces based on a high score threshold. Limits false positives (classifies a non-face as a face), but may have more false negatives (does not detect a face).

enumerator BALANCED

Filter the detected faces based on a medium score threshold to balance false positives and false negatives. We advise using this option most of the time.

enumerator UNFILTERED

Do not filter the detected faces by score. Will have a large number of false positives (classifies a non-face as a face).

enum Trueface::Precision

Precision to use for GPU inference.

Values:

enumerator FP32

32 bit floating point. Allows for highest accuracy but slower inference.

enumerator FP16

16 bit floating point. Allows for faster inference but lower accuracy.

enum Trueface::DatabaseManagementSystem

Database Management System for storing Faceprints.

Values:

enumerator SQLITE

Use sqlite backend. Write Faceprints to local disk. Ideal for embedded systems or use cases where only one process connects to the database.

enumerator POSTGRESQL

Use a PostgreSQL backend. You must use PostgreSQL version 15. Ideal for distributed systems requiring synchronization. \

enumerator NONE

Do not write Faceprints to disk, only store in ram. Warning, enrolled Faceprints will not be saved after the program terminates. Switching to a new collections will also delete all enrolled templates.

struct Trueface::GPUModuleOptions

GPU options for a specific module (ex. face detector).

Public Members

Precision precision = Precision::FP16

Precision level used for inference.

int32_t maxBatchSize = 4

The maximum batch size which will be used.

int32_t optBatchSize = 1

The batch size which should be optimized for. Must be less than or equal to Trueface::GPUModuleOptions.maxBatchSize.

size_t maxWorkspaceSizeMb = 2000

The maximum allowable GPU memory to be used for model conversion, in Mb. Applications should allow the engine builder as much workspace as they can afford. At runtime, the SDK allocated no more than this and typically less.

struct Trueface::GPUOptions

GPU options for the SDK. Note, GPU support requires a different version of the SDK. Default uses CPU for inference.

Public Functions

inline GPUOptions(bool val)

Enable or disable GPU inference for all supported modules.

Public Members

bool enableGPU = false

Enable GPU inference for all supported modules.

unsigned int deviceIndex = 0

GPU device index.

GPUModuleOptions faceDetectorGPUOptions = {}

Options for face detector GPU inference.

GPUModuleOptions faceLandmarkDetectorGPUOptions = {}

Options for 106 face landmark detector GPU inference.

GPUModuleOptions faceRecognizerGPUOptions = {}

Options for face recognizer GPU inference.

GPUModuleOptions maskDetectorGPUOptions = {}

Options for mask detector GPU inference.

GPUModuleOptions objectDetectorGPUOptions = {}

Options for object detector GPU inference.

GPUModuleOptions faceOrientationDetectorGPUOptions = {}

Options for face orientation detector GPU inference.

GPUModuleOptions faceBlurDetectorGPUOptions = {}

Options for face blur detector GPU inference.

GPUModuleOptions spoofDetectorGPUOptions = {}

Options for spoof detector GPU inference.

GPUModuleOptions blinkDetectorGPUOptions = {}

Options for blink detector GPU inference

Trueface::GPUOptions::GPUOptions() = default

inline Trueface::GPUOptions::GPUOptions(bool val)

Enable or disable GPU inference for all supported modules.

struct Trueface::InitializeModule

Initialize module in SDK constructor. By default, the SDK uses lazy initialization, meaning modules are only initialized when they are first used (on first inference). This is done so that modules which are not used do not load their models into memory, and hence do not utilize memory. The downside to this is that the first inference will be much slower as the model file is being decrypted and loaded into memory. Therefore, if you know you will use a module, choose to pre-initialize the module, which reads the model file into memory in the SDK constructor.

Public Members

bool faceDetector = false

Face detector.

bool faceRecognizer = false

Face recognizer.

bool objectDetector = false

Object detector.

bool bodyposeEstimator = false

Bodypose estimator.

bool blinkDetector = false

Blink detector.

bool activeSpoof = false

Active spoof.

bool passiveSpoof = false

Passive spoof.

bool landmarkDetector = false

106 face point landmark detector.

bool maskDetector = false

Mask detector.

bool faceOrientationDetector = false

Face orientation detector.

bool faceBlurDetector = false

Face blur detector.

bool eyeglassDetector = false

Eyeglass detector.

struct Trueface::EncryptDatabase

Encrypt the biometric templates and identity strings when storing in the database using AES encryption. Note, enabling this option does add overhead to Faceprint enrollment as well as loading a collection from a database into memory. Enabling encryption does not increase the 1 to N identification time.

Public Members

bool enableEncryption = false

Enable database encryption. Must provide encryption key if encryption is enabled. If enabling encryption with PostgreSQL backend, it is strongly advised to require SSL for PostgreSQL connection.

std::string key

Encryption key. The key is hashed to a fixed length before being used for encryption.

struct Trueface::ConfigurationOptions

SDK configuration options.

Public Members

int mobilePowerSave = 0

Android Only Power saving mode. 0 = all cores enabled (default). 1 = only little clusters enabled. 2 = only big clusters enabled.

int mobileThreads = 4

Mobile Only Set the number of threads used for inference. For non-mobile platforms, should use the OMP_NUM_THREADS environment variable.

size_t mobileAvailableMemory = 0

iOS Only SDK user must define how much memory is available for iOS application. Should be set using the following code: #include <os/proc.h> options.mobileAvailableMemory = os_proc_available_memory();

FacialRecognitionModel frModel = FacialRecognitionModel::TFV5_2

The model to be used for facial recognition (default is TFV5_2).

FaceDetectionModel fdModel = FaceDetectionModel::FAST

The model to be used for face detection (default is FAST).

ObjectDetectionModel objModel = ObjectDetectionModel::ACCURATE

The model to be used for object detection (default is ACCURATE model).

int smallestFaceHeight = 40

Filter the detected faces based on face height. (default is 40 pixels). You may choose to filter on size to reject faces which are too small as they may cause false positives. Note, the detector itself has inherent restrictions and can only detect faces in the following dynamic height range. Smallest detectable face = ((the larger of your image dimensions) / 640 * 20) pixels. Largest detectable face = (your image height) pixels.

FaceDetectionFilter fdFilter = FaceDetectionFilter::BALANCED

The face detection filter (default is BALANCED).

DatabaseManagementSystem dbms = DatabaseManagementSystem::SQLITE

Database management system for storing Faceprints (default is SQLITE).

std::string modelsPath = "./"

Path specifying the directory which contains the model files.

bool frVectorCompression = false

Improves 1 to 1 Faceprint comparison times and 1 to N search speeds by compressing the feature vector and enabling additional optimizations. Also reduces the memory required to store each Faceprint. (default is false)

GPUOptions gpuOptions = GPUOptions{false}

Options for enabling and configuring GPU inference. Default uses CPU inference. Note, GPU support requires a different version of the SDK. You can easily enable GPU inference for all supported modules by setting this option to true.

InitializeModule initializeModule = {}

Initialize specified modules in the SDK constructor (default uses lazy initialization).

EncryptDatabase encryptDatabase = {}

Encrypt the biometric templates and identity strings when storing in the database using AES encryption (default is disabled).

bool useGlobalInferenceThreadpool = true

Enable the use of a global inference threadpool. Should be enabled on machines with less than 32 threads or when running a sequential inference pipeline. For more information on this option, refer to our FAQ page.

enum Trueface::ErrorCode

Error codes returned by methods.

Values:

enumerator NO_ERROR

enumerator INVALID_LICENSE

enumerator FILE_READ_FAIL

enumerator UNSUPPORTED_IMAGE_FORMAT

enumerator UNSUPPORTED_MODEL

enumerator NO_FACE_IN_FRAME

enumerator FAILED

enumerator COLLECTION_CREATION_ERROR

enumerator DATABASE_CONNECTION_ERROR

enumerator ENROLLMENT_ERROR

enumerator MAX_COLLECTION_SIZE_EXCEEDED

enumerator NO_RECORD_FOUND

enumerator NO_COLLECTION_FOUND

enumerator COLLECTION_DELETION_ERROR

enumerator EXTREME_FACE_ANGLE

enumerator FACE_TOO_CLOSE

enumerator FACE_TOO_FAR

enumerator FACE_TOO_SMALL

enumerator FACE_NOT_CENTERED

enumerator EYES_CLOSED

enumerator MASK_DETECTED

enumerator TOO_DARK

enumerator TOO_BRIGHT

enumerator DATABASE_NOT_CONNECTED

enumerator COLLECTION_NOT_LOADED

enumerator FEATURE_NOT_SUPPORTED

enumerator COLLECTION_IS_EMPTY

enumerator INPUT_IS_EMPTY

enumerator STRING_CANNOT_CONTAIN_HYPHEN

enumerator STRING_CANNOT_CONTAIN_UPPERCASE

enumerator NO_COLLECTION_SPECIFIED

enumerator POSTGRESQL_VERSION_MISMATCH

enumerator INVALID_ARGUMENT