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.

Trueface::SDK::SDK()

Initialize the SDK using default configuration options.

See

ConfigurationOptions

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

Initialize the SDK using custom configuration options.

Parameters

  • options: custom configuration options.

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

Gets the version-build number of the SDK.

Return

Version Number as a std::string.

enum Trueface::FacialRecognitionModel

Facial recognition models. To compare model performances, refer to http://performance.trueface.ai/. You can also find more information on our FAQ page found here: https://reference.trueface.ai/cpp/dev/latest/usage/faq.html#what-are-the-differences-between-the-face-recognition-models. The current most accurate model is TFv5.

Values:

enumerator LITE

Lightweight model with faster inference time but reduced accuracy, ideal for embedded systems or lightweight CPU only deployments, and for 1 to 1 matching use cases.

enumerator FULL

Full TFv4 model which has better accuracy than the LITE model, but also has greater inference time. Ideal for GPU deployments and for 1 to N use cases. Note, TFv4 has now been deprecated and replaced by TFv5 which has better performance. Despite this, we will continue providing support for TFv4 for clients with existing collections.

enumerator TFV5

TFv5 is currently the highest accuracy model. Ideal for GPU deployments and for 1 to N use cases.

enum Trueface::ObjectDetectionModel

Object detection models

Values:

enumerator ACCURATE
enumerator FAST
enum Trueface::FaceDetectionMode

Face detection modes

Values:

enumerator ROBUST

The ROBUST mode is optimized for face recognition, smallestFaceHeight less than 80 pixels will be overridden.

enumerator VERSATILE

The VERSATILE mode can detect small faces (as small as 16x16 pixel) and can be faster than the ROBUST mode.

enum Trueface::FaceDetectionFilter

Face detection filter

Values:

enumerator HIGH_RECALL

The detected face scores are thresholded to have a low precision and a high recall rate.

enumerator HIGH_PRECISION

The detected face scores are thresholded to have a high precision and a low recall rate.

enumerator BALANCED

The detected face scores are thresholded to have a medium precision and recall rate.

enumerator UNFILTERED

The detected face scores are not thresholded.

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. Ideal for distributed systems requiring synchronization. Not available in Windows SDK.

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::EnableGPU

Enable GPU support (default is false). Note, GPU support requires a different version of the SDK. You are able to enable GPU for all modules or only specific modules.

Public Functions

EnableGPU(bool val)

Enable or disable GPU inference for all modules

Public Members

bool faceDetector = false

Enable GPU inference for face detection

bool faceRecognizer = false

Enable GPU inference for face recognition template generation

Trueface::EnableGPU::EnableGPU() = default
Trueface::EnableGPU::EnableGPU(bool val)

Enable or disable GPU inference for all modules

struct Trueface::ConfigurationOptions

SDK configuration options

Public Members

FacialRecognitionModel frModel = FacialRecognitionModel::LITE

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

ObjectDetectionModel objModel = ObjectDetectionModel::ACCURATE

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

int smallestFaceHeight = 40

The smallest face height that the face detector can detect. (default is 40 pixels, min value is 16 pixels). The face detector has a detection scale range of about 5 octaves. Ex. 40 pixels yields the detection scale range of ~40 pixels to 1280 (=40x2^5) pixels. If set to -1, will dynamically adjusts the face detection scale range from image-height/32 to image-height to ensure that large faces are detected in high resolution images.

FaceDetectionMode fdMode = FaceDetectionMode::VERSATILE

The face detection mode (default is VERSATILE)

FaceDetectionFilter fdFilter = FaceDetectionFilter::BALANCED

The face detection precision-recall mode (default is BALANCED)

DatabaseManagementSystem dbms = DatabaseManagementSystem::SQLITE

Database management system for storing Faceprints (default is SQLITE)

std::string modelsPath = "./"

The directory path containing the model files

bool frVectorCompression = false

Improves the computation speed for 1 to 1 comparisons and 1 to N searches by compressing the feature vector and enabling additional optimizations.

EnableGPU enableGPU = {}

Enable GPU support (default is false). Note, GPU support requires a different version of the SDK. You are able to enable GPU for all modules or only specific modules.

unsigned int deviceIndex = 0

GPU device index

struct Trueface::CollectionMetadata

Collection metadata

Public Members

std::string collectionName = ""

The name of the collection

uint64_t numIdentities = 0

The number of unique identities in the collection

uint64_t numFaceprints = 0

The total number of Faceprints enrolled in the collection

std::string modelName = ""

The name of the face recognition model used to generate the Faceprints enrolled in the collection

uint16_t featureVectorSizeBytes = 0

The size of the Faceprint feature vector in bytes

ModelOptions modelOptions = {}

Additional options which were used to generate Faceprints enrolled in the collection

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