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 tfsdk.SDK
SDK.__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: tfsdk.SDK) -> None

Initialize the SDK using default configuration options.

  1. __init__(self: tfsdk.SDK, configuration_options: tfsdk.ConfigurationOptions) -> None

    Initialize the SDK using custom configuration options.

    Parameters

    configuration_options - custom configuration options.

static SDK.get_version() → str

Gets the version-build number of the SDK.

Returns

The SDK version.

class tfsdk.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.

Members:

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.

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

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. Ideal for GPU deployments and for 1 to N use cases. Inference time is faster than TFV7, but comparable to TFV6.

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.

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.

class tfsdk.FACEDETECTIONMODEL

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

Members:

FAST : Fast model using a retinaface backbone.

ACCURATE : Accurate model using scrfd backbone.

class tfsdk.OBJECTDETECTIONMODEL

Object detection models.

Members:

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.

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.

class tfsdk.FACEDETECTIONFILTER

Filters the detected faces based on face detection scores.

Members:

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).

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).

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.

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

class tfsdk.PRECISION

Precision to use for GPU inference.

Members:

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

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

class tfsdk.DATABASEMANAGEMENTSYSTEM

Database Management System for storing Faceprints

Members:

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

POSTGRESQL : Use PostgreSQL backend. You must use PostgreSQL version 15. Ideal for distributed systems requiring synchronization.

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.

class tfsdk.PRECISION

Precision to use for GPU inference.

Members:

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

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

class tfsdk.GPUModuleOptions
property max_batch_size

The maximum batch size which will be used (default is 4).

property max_workspace_size

The maximum allowable GPU memory to be used for model conversion, in Mb (default is 2000). 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.

property opt_batch_size

The batch size which should be optimized for (default is 1). Must be less than or equal to tfsdk.GPUModuleOptions.max_batch_size.

property precision

Precision level used for inference, see PRECISION (default is FP16).

GPUModuleOptions.__init__(self: tfsdk.GPUModuleOptions) → None
class tfsdk.GPUOptions

Options for blink detector GPU inference, see tfsdk.GPUModuleOptions.

property device_index

GPU device index.

property enable_GPU

Enable GPU inference for all supported modules.

property face_blur_detector_GPU_options

Options for face blur detector GPU inference, see tfsdk.GPUModuleOptions.

property face_detector_GPU_options

Options for face detector GPU inference, see tfsdk.GPUModuleOptions.

property face_landmark_detector_GPU_options

Options for 106 face landmark detector GPU inference, see tfsdk.GPUModuleOptions.

property face_orientation_detector_GPU_options

Options for face orientation detector GPU inference, see tfsdk.GPUModuleOptions.

property face_recognizer_GPU_options

Options for face recognizer GPU inference, see tfsdk.GPUModuleOptions.

property mask_detector_GPU_options

Options for mask detector GPU inference, see tfsdk.GPUModuleOptions.

property object_detector_GPU_options

Options for object detector GPU inference, see tfsdk.GPUModuleOptions.

property spoof_detector_GPU_options

Options for spoof detector GPU inference, see tfsdk.GPUModuleOptions.

GPUOptions.__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: tfsdk.GPUOptions) -> None

  2. __init__(self: tfsdk.GPUOptions, val: bool) -> None

    Enable or disable GPU inference for all supported modules.

    Parameters

    val - enable GPU inference for all modules.

class tfsdk.InitializeModule
property active_spoof

Active spoof.

Blink detector.

property bodypose_estimator

Bodypose estimator.

property eyeglass_detector

Eyeglass detector.

property face_blur_detector

Face blur detector.

property face_detector

Face detector.

property face_orientation_detector

Face orientation detector.

property face_recognizer

Face detector.

property landmark_detector

Landmark detector.

property mask_detector

Mask detector.

property object_detector

Object detector.

property passive_spoof

Passive spoof.

class tfsdk.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.

property enable_encryption

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.

property key

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

class tfsdk.ConfigurationOptions
property GPU_options

GPU options for the SDK. Note, GPU support requires a different version of the SDK. You can enable GPU inference for all supported modules by setting this option to True. Default uses CPU for inference. See tfsdk.GPUOptions.

property dbms

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

property encrypt_database

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

property fd_filter

The threshold level to use when filtering detected faces (default is BALANCED). See FACEDETECTIONFILTER.

property fd_model

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

property fr_model

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

property fr_vector_compression

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).

property initialize_module

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. See InitializeModule.

property models_path

Path specifying the directory which contains the model files (default is ./ ).

property obj_model

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

property smallest_face_height

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.

property use_global_inference_threadpool

Enable the use of a global inference threadpool (default is True). 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.

class tfsdk.ERRORCODE

Members:

NO_ERROR

EXTREME_FACE_ANGLE

INVALID_LICENSE

FILE_READ_FAIL

UNSUPPORTED_IMAGE_FORMAT

UNSUPPORTED_MODEL

NO_FACE_IN_FRAME

FACE_TOO_CLOSE

FACE_TOO_FAR

FACE_TOO_SMALL

FACE_NOT_CENTERED

COLLECTION_CREATION_ERROR

DATABASE_CONNECTION_ERROR

ENROLLMENT_ERROR

FAILED

NO_RECORD_FOUND

NO_COLLECTION_FOUND

MAX_COLLECTION_SIZE_EXCEEDED

EYES_CLOSED

COLLECTION_DELETION_ERROR

MASK_DETECTED

TOO_DARK

TOO_BRIGHT

DATABASE_NOT_CONNECTED

COLLECTION_NOT_LOADED

FEATURE_NOT_SUPPORTED

STRING_CANNOT_CONTAIN_HYPHEN

STRING_CANNOT_CONTAIN_UPPERCASE

COLLECTION_IS_EMPTY

INPUT_IS_EMPTY

NO_COLLECTION_SPECIFIED

POSTGRESQL_VERSION_MISMATCH

INVALID_ARGUMENT