Configuration options¶

The configuration options are provided when the engine is initialized and they are case-sensitive.

Sample (default) config:

{
    "debug_level": "info",
    "debug_write_input_image_enabled": false,
    "debug_internal_data_path": ".",

    "gpu_ctrl_memory_enabled": true,
    "num_threads": -1,
    "max_latency": -1,
    "max_batchsize": -1,
    "asm_enabled": true,
    "intrin_enabled": true,
    "cuda_activation": "auto",
    "backend": "onnx",

    "detect_target_size": 640,
    "detect_size_threshold": 16,
    "detect_score_threshold": 0.5,
    "detect_iou_threshold": 0.4,
    "detect_topk": 1000,

    "avantgarde_score_threshold": 0.5,

    "liveness_genuine_threshold": 0.85,
    "liveness_disputed_threshold": 0.60,

    "deepfake_genuine_threshold": 0.4,

    "disguise_genuine_threshold": 0.4,

    "inject_similarity_threshold": 0.35,
    "inject_genuine_threshold": 0.90,
    "inject_smartpass_enabled": true
}

assets_folder¶

Path to the folder containing the configuration files and deep learning models. Default value is the current folder. The SDK will look for the models in $(assets_folder)/ultimateFace-SDK-Models folder.
type	string
pattern	folder path
default	“”

debug_level¶

Defines the debug level to output on the console. You should use “verbose” for diagnostic, “info” in development stage and “warn” in production.
type	string
pattern	“verbose” \| “info” \| “warn” \| “error” \| “fatal”
default	“info”

debug_write_input_image_enabled¶

Whether to write the transformed input image to the disk. This could be useful for debugging.
type	bool
pattern	true \| false
default	False

debug_internal_data_path¶

Path to the folder where to write the transformed input image. Used only if debug_write_input_image_enabled is true.
type	string
pattern	folder path
default	“”

license_token_file¶

Path to the file containing the license token. First you need to generate a Runtime Key using `requestRuntimeLicenseKey()` function then activate the key to get a token. You should use license_token_file or license_token_data but not both.
type	string
pattern	file path
default	“”

license_token_data¶

Base64 string representing the license token. First you need to generate a Runtime Key using `requestRuntimeLicenseKey()` function then activate the key to get a token. You should use license_token_file or license_token_data but not both.
type	string
pattern	base64
default	“”

num_threads¶

Defines the maximum number of threads to use. You should not change this value unless you know what you’re doing. Set to -1 to let the SDK choose the right value. The right value the SDK will choose will likely be equal to the number of virtual core. For example, on an octa-core device the maximum number of threads will be 8.
type	int
pattern	[-1, +inf[
default	-1

gpu_ctrl_memory_enabled¶

Whether to control the GPU memory usage. This option applies to ONNX RT only and doesn’t apply to TensorRT. By default ONNX RT will allocate as much memory as possible and this could be problematic and produce Out Of Memory (OOM) issues. Enabling memory usage control will ensure that only required memory will be allocated. Restricting the memory usage may slightly slowdown the inference speed but is highly recommended to avoid OOM.
type	bool
pattern	true \| false
default	True

cuda_activation¶

Defines the CUDA activation mode. “auto” means the activation will be based on whether GPU acceleration is possible or not. In “auto” mode the SDK will check if CUDA and cuDNN are correctly installed on the machine and activate CUDA if that’s the case. “on” and “off” modes are hard activation or deactivation of CUDA.
type	string
pattern	“auto” \| “on” \| “off”
default	“auto”

backend¶

Defines the inference engine to use. Possible values are “onnx” for Microsoft ONNX RT, “trt” for NVIDIA TensorRT and “vino” for Intel OpenVINO. The initial version (v0.1) supports a single backend: “onnx”. “trt” backend will be added for NVIDIA Jetson devices in the near future.
type	string
pattern	“onnx” \| “trt” \| “vino”
default	“onnx”

max_latency¶

The parallel processing method could introduce delay/latency in the delivery callback on low-end CPUs. This parameter controls the maximum latency you can tolerate. The unit is number of frames. The default value is -1 which means auto.
type	int
pattern	[0, +inf[
default	-1

max_batchsize¶

Defines the maximum batch size to use for the inference. This option applies to ONNX RT only and doesn’t apply to TensorRT. Set this value to -1 to let the SDK choose the right value.
type	int
pattern	[-1, +inf[
default	-1

asm_enabled¶

Whether to enable assembler code to use SIMD acceleration (SSE, AVX, NEON).
type	bool
pattern	true \| false
default	true

intrin_enabled¶

Whether to enable intrinsic code to use SIMD acceleration (SSE, AVX, NEON).
type	bool
pattern	true \| false
default	true

detect_target_size¶

The face detection modules is a fully convolution neural network which means it accepts any image size as input. The target size option allows resizing the input image to a certain size to speedup the inference or improve the accuracy. Check the section about the face detection module for more information. You can set this value to -1 to avoid any resizing and use the input image “as is”. Read this section for more info about this configuration entry.
type	int
pattern	[-1, +inf[
default	640

detect_size_threshold¶

The face detector may produce false positives on objects looking like very small faces. This configuration entry instructs the detector to ignore any small face with size less than the threshold.
type	int
pattern	[-1, +inf[
default	16

detect_score_threshold¶

Any face detection score (percentage) lower than this threshold will be discarded and and tagged as false-positive.
type	float
pattern	[0, 1]
default	0.5

detect_iou_threshold¶

Defines the maximum IoU (Intersection Over Union) to be used by the NMS (Non Maximal Suppression) module to deal with the overlapping face detection boxes.
type	float
pattern	[0, 1]
default	0.4

detect_topk¶

The faces in the image are sorted from the largest to the smallest. The TopK option instruct the SDK to retain the first K faces only. In most of the scenarios, the smaller this value, the faster the inference will be. You may use K=1 to perform face recognition on the largest face only.
type	int
pattern	]0, +inf[
default	1000

avantgarde_score_threshold¶

Avant-garde is the first module to be invoked to check whether we need to perform liveness detection or not. Check the section about avant-garde for more information. Any image with an avant-garde score (percentage) lower than this threshold will be discarded and and tagged as spoof.
type	float
pattern	[0, 1]
default	0.5

liveness_genuine_threshold¶

Threshold for genuine faces. Any face with liveness score higher than or equal to this threshold will be tagged as genuine.
type	float
pattern	[0, 1]
default	0.85

liveness_disputed_threshold¶

Any non-genuine face with a score higher than or equal to this threshold will be tagged as disputed. The engine will not needlessly compute some extra features (e.g. Deepfake detection, identity concealment detection…) on spoofs. The disputed state is a non-spoof state which means all extra features will be triggered and give you the chance to review a full result.
type	float
pattern	[0, 1]
default	0.6

deepfake_genuine_threshold¶

Threshold for deepfake faces. Any face with deepfake score higher than or equal to this threshold will be tagged as a deepfake.
type	float
pattern	[0, 1]
default	0.5

disguise_genuine_threshold¶

Any face with disguise score higher than or equal to this threshold will be tagged as disguise (identity concealed).
type	float
pattern	[0, 1]
default	0.5

inject_similarity_threshold¶

The stream injection module requires a stereo image. The face in both images must be the same. Face recognition is ran on the background to make sure the faces in the stereo image match. This configuretion entry defines the cosine similarity threshold. The stereo image will be rejected and tagged as “impaired” if the recognition cosine similarity is lower than this threshold.
type	float
pattern	[-1, 1]
default	0.35

inject_genuine_threshold¶

Any stereo image with injection score lower than this threshold will be tagged as a “injected”.
type	float
pattern	[0, 1]
default	0.9

inject_smartpass_enabled¶

Whether to enabled smart-pass module.
type	bool
pattern	true \| false
default	True