Python API 1.47.0¶

`PythonFaceSDK.BoundingBox`	Face rectangle bounding box.
`PythonFaceSDK.DetectEngine`	Face detection engine.
`PythonFaceSDK.DetectionResult`	Result of DetectEngine.
`PythonFaceSDK.FaceException`	Custom runtime exception for FaceSDK methods.
`PythonFaceSDK.FaceParameters`	Structure for storing facial parameters.
`PythonFaceSDK.FaceSDK`	Face engines and pipelines aggregator.
`PythonFaceSDK.HeadPose`	Set of yaw, pith, and roll angles (in degrees).
`PythonFaceSDK.Image`	FaceSDK Image
`PythonFaceSDK.ImageBatch`	C++ image batch (image sequence).
`PythonFaceSDK.ImageBatchWrapper`	Python Wrapper for C++ image batch.
`PythonFaceSDK.InitConfig`	Configuration file parser.
`PythonFaceSDK.Keypoints`	Keypoints structure which is returned by DetectEngine.
`PythonFaceSDK.LICENSE_FEATURE`	IDLive Face license features enum.
`PythonFaceSDK.LicenseFeatureInfo`	IDLive Face license feature info.
`PythonFaceSDK.LivenessResult`	Liveness detection result.
`PythonFaceSDK.Meta`	Meta information provided for calibration.
`PythonFaceSDK.Pipeline`	Liveness detection pipeline.
`PythonFaceSDK.PipelineResult`	Liveness detection result.
`PythonFaceSDK.QualityEngine`	Quality estimation engine.
`PythonFaceSDK.QualityResult`	Quality estimation result.
`PythonFaceSDK.STATUS`	Error code enum.

class PythonFaceSDK.BoundingBox¶

Face rectangle bounding box.

property bottom_right_x¶

X position of right bottom corner.

Type:: int

property bottom_right_y¶

Y position of right bottom corner.

Type:: int

property left_top_x¶

X position of left top corner.

Type:: int

property left_top_y¶

Y position of left top corner.

Type:: int

class PythonFaceSDK.DetectEngine¶

Face detection engine.

detect(image: facesdk::Image) → PythonFaceSDK.DetectionResult¶

Facial keypoints and bbox detecting method.

Parameters:: image (Image) – Image object.
Returns:: Detection result.
Return type:: DetectionResult

detectBatch(images: list[facesdk::Image]) → list[PythonFaceSDK.OptionalDetectionResult]¶

Facial keypoints and bbox batch detecting method.

Parameters:: images (list) – List of Image object.
Returns:: List of optional detection results. The size of the result vector is guaranteed equal to images list size.
Return type:: list

detectOnlyBoundingBox(image: facesdk::Image) → list[PythonFaceSDK.BoundingBox]¶

Facial bbox detecting method.

Parameters:: image (Image) – Image object.
Returns:: List of detected bounding boxes.
Return type:: list

detectOnlyBoundingBoxBatch(images: list[facesdk::Image]) → list[PythonFaceSDK.OptionalBoundingBoxes]¶

Facial bbox batch detecting method.

Parameters:: images (list) – List of Image object.
Returns:: List of optional lists of detected bounding boxes results. The size of the result vector is guaranteed equal to images list size.
Return type:: list

class PythonFaceSDK.DetectionResult¶

Result of DetectEngine.

get_faces() → list¶

Returns a list of FaceParameters.

Returns:: List of FaceParameters corresponding to detected faces.
Return type:: list

property orientation¶

Approximated image or face orientation in degrees.

Type:: int

exception PythonFaceSDK.FaceException(arg0: str, arg1: PythonFaceSDK.STATUS)¶

Custom runtime exception for FaceSDK methods.

status() → PythonFaceSDK.STATUS¶

Get error code.

Returns:: Error code from STATUS enum.
Return type:: STATUS

what() → str¶

Get error message as string.

Returns:: Error message in string format.
Return type:: str

class PythonFaceSDK.FaceParameters¶

Structure for storing facial parameters.

property bounding_box¶

Facial bounding box.

Type:: BoundingBox

property closed_eyes_probability¶

Closed eyes probability from 0 to 1.

Type:: float

property head_pose¶

Facial head pose (yaw, pitch, roll).

Type:: HeadPose

property interpupillary_distance¶

Distance between pupils.

Type:: float

property keypoints¶

Facial keypoints.

Type:: Keypoints

property occlusion_probability¶

Face occlusion probability from 0 to 1.

Type:: float

class PythonFaceSDK.FaceSDK¶

Face engines and pipelines aggregator.

static getDetectEngine(name: str, config: PythonFaceSDK.InitConfig) → DetectEngineWrapper¶

Return face detection engine by name.

Parameters:

name (str) – Engine name.
config (InitConfig) – Configuration object

Returns:

Created face detection instance.

Return type:

DetectEngine

static getLicenseFeaturesInfo() → list[PythonFaceSDK.LicenseFeatureInfo]¶: Returns information about all available licensed features.

static getLicenseInfo() → str¶: Deprecated, use getLicenseFeaturesInfo. Returns information about a license if available.

static getPipeline(name: str, config: PythonFaceSDK.InitConfig) → PipelineWrapper¶

Return pipeline engine by name.

Parameters:

name (str) – Engine name.
config (InitConfig) – Configuration object

Returns:

Created pipeline engine instance.

Return type:

Pipeline

static getQualityEngine(name: str, config: PythonFaceSDK.InitConfig) → QualityEngineWrapper¶

Return face quality engine by name.

Parameters:

name (str) – Engine name.
config (InitConfig) – Configuration object

Returns:

Created face quality instance.

Return type:

QualityEngine

static getVersion() → str¶: Returns the release version.

static setEnableClosedEyesDetection(enabled: bool) → None¶

Toggles closed eyes detection. When enabled the faces with closed eyes will be rejected.

Parameters:: enabled (bool) – Whether to enable the detection or not.

Note: Function call is equivalent to setting FACESDK_ENABLE_CLOSED_EYES_DETECTION environment variable before loading FaceSDK library. Function call takes precedence over environment variables.

static setEnableFaceOcclusionDetection(enabled: bool) → None¶

Toggles face occlusion detection. When enabled the occluded faces will be rejected.

Parameters:: enabled (bool) – Whether to enable the detection or not.

Note: Function call is equivalent to setting FACESDK_ENABLE_FACE_OCCLUSION_DETECTION environment variable before loading FaceSDK library. Function call takes precedence over environment variables.

static setEnableLogging(enable_logging: bool) → None¶

Sets whether to enable FaceSDK logging. Logging is enabled by default.

Parameters:: enable_logging (bool) – Whether to enable logging or not.

Note: Function call is equivalent to setting FACESDK_ENABLE_LOGGING environment variable before loading FaceSDK library. Function call takes precedence over environment variables.

static setLicense(arg0: str) → None¶: Sets a new license.

static setNumThreads(num_threads: int, threading_level: PythonFaceSDK.ThreadingLevel) → None¶

Sets the maximum number of threads available for FaceSDK at the specified level.If 0 is passed, then the optimal number of threads is detected automatically (the same effect is achieved if setNumThreads is not called).

Parameters:

num_threads (int) – Maximum number of threads available for FaceSDK at the specified level.
threading_level (ThreadingLevel) – Threading level to apply setting.

Note: Function call is equivalent to setting FACESDK_NUM_THREADS_PIPELINE, FACESDK_NUM_THREADS_ENGINE or FACESDK_NUM_THREADS_OPERATOR environment variable before loading FaceSDK library. Function call takes precedence over environment variables.

static setOvBindThreads(ov_bind_threads: bool) → None¶

Sets the CPU bind setting for OpenVINO backend.

Parameters:: ov_bind_threads (bool) – Whether bind execution threads to CPU physical cores or not.

Note: Function call is equivalent to setting FACESDK_OV_BIND_THREADS environment variable before loading FaceSDK library. Function call takes precedence over environment variables. Function does not take effect if FaceSDK build does not use OpenVINO.

static setOvMaxBatchSize(ov_max_batch_size: int) → None¶: Function does not take effect if FaceSDK build does not use OpenVINO.

static setOvNumThroughputStreams(ov_num_throughput_streams: int) → None¶

Sets the number of CPU execution streams for OpenVINO backend.

Parameters:: ov_num_throughput_streams (int) – Number of CPU execution streams, valid values are -1 (auto-tune number of streams), 0 (use the default setting) and any positive value, other values are dropped without an error.

Note: Function call is equivalent to setting FACESDK_OV_NUM_THROUGHPUT_STREAMS environment variable before loading FaceSDK library. Function call takes precedence over environment variables. Function does not take effect if FaceSDK build does not use OpenVINO.

class PythonFaceSDK.HeadPose¶

Set of yaw, pith, and roll angles (in degrees).

property pitch¶

Yaw angle in degrees.

Type:: float

property roll¶

Roll angle in degrees.

Type:: float

property yaw¶

Pitch angle in degrees.

Type:: float

class PythonFaceSDK.Image¶

FaceSDK Image

static createImage(*args, **kwargs)¶

Overloaded function.

createImage() -> PythonFaceSDK.Image

Create empty Image object.

Returns:: Created image object.
Return type:: Image

createImage(bytes: list) -> PythonFaceSDK.Image

Create Image object from binary file in memory buffer.

Parameters:: bytes (list) – List of bytes.
Returns:: Created image object.
Return type:: Image

createImage(path: str) -> PythonFaceSDK.Image

Create Image object from disk.

Parameters:: path (str) – Path to image file on disk.
Returns:: Created image object.
Return type:: Image

createImage(pixels: numpy.ndarray[numpy.uint8], rows: int, cols: int, format: PythonFaceSDK.COLOR_ENCODING) -> PythonFaceSDK.Image

Create Image object from memory buffer.

Parameters:

pixels (np.array) – uint8 Numpy array containig raw pixel values.
rows (int) – Number of image rows.
cols (int) – Number of image cols.
format (COLOR_ENCODING) – Color encoding format of input buffer.

Returns:

Created image object.

Return type:

Image

class PythonFaceSDK.ImageBatch¶

C++ image batch (image sequence).

property n_images¶

Number of images in ImageBatch.

Type:: int

class PythonFaceSDK.ImageBatchWrapper¶

Python Wrapper for C++ image batch.

assign(images: list) → None¶

Assign images to image batch.

Parameters:: images (list) – List of images.

getCppBatch() → PythonFaceSDK.ImageBatch¶

Get C++ instance of ImageBatch.

Returns:: C++ image batch instance.
Return type:: ImageBatch

class PythonFaceSDK.InitConfig¶

Configuration file parser.

static createConfig(*args, **kwargs)¶

Overloaded function.

createConfig(dir: str, config_file_name: str) -> PythonFaceSDK.InitConfig

Configuration object creator.

Parameters:

dir (str) – Path to directory with configuration files.
config_file_name (str) – Configuration file name.

Returns:

Created init config instance.

Return type:

InitConfig

createConfig(file_path: str) -> PythonFaceSDK.InitConfig

Configuration object creator.

Parameters:: file_path (str) – Full path to configuration file.
Returns:: Created init config instance.
Return type:: InitConfig

class PythonFaceSDK.Keypoints¶

Keypoints structure which is returned by DetectEngine.

get_landmarks68() → numpy.ndarray¶

Returns coordinates of 68 facial landmarks.

Returns:: 2D int32 Numpy array representing 68 facial landmarks.
Return type:: np.array

set_landmarks68(landmarks68: numpy.ndarray[numpy.int32]) → None¶

Set coordinates of 68 facial landmarks.

Parameters:: landmarks68 (np.array) – 2D int32 Numpy array representing 68 facial landmarks.

class PythonFaceSDK.LicenseFeatureInfo¶

IDLive Face license feature info.

property expiration_date¶: The license expiration date. The format is the ISO-8601 instant, such as 2023-12-03T23:59:59Z.

property feature¶: License feature.

class PythonFaceSDK.LivenessResult¶

Liveness detection result.

property probability¶

Probability of liveness in range=[0, 1].

Type:: float

property score¶

Classifiers RAW output.

Type:: float

class PythonFaceSDK.Meta¶

Meta information provided for calibration.

class CALIBRATION(value: int)¶

Liveness checking threshold calibration type.

property name¶

class MANUFACTURE(value: int)¶

Device manufacture.

property name¶

class MODEL(value: int)¶

Device model

property name¶

class OS(value: int)¶

OS type for calibration.

property name¶

property calibration¶

Liveness checking threshold calibration type to use.

Type:: CALIBRATION

property manufacture¶

Device manufacture type.

Type:: MANUFACTURE

property model¶

Device model type.

Type:: MODEL

property os¶

Device OS type.

Type:: OS

property os_version¶

OS version.

Type:: str

class PythonFaceSDK.Pipeline¶

Liveness detection pipeline.

checkLiveness(*args, **kwargs)¶

Overloaded function.

checkLiveness(self: PythonFaceSDK.Pipeline, image: PythonFaceSDK.Image) -> PythonFaceSDK.PipelineResult

Check liveness of face from input image.

Parameters:: image (Image) – Input image.
Returns:: Result of liveness detection.
Return type:: PipelineResult

checkLiveness(self: PythonFaceSDK.Pipeline, image: PythonFaceSDK.Image, meta: PythonFaceSDK.Meta) -> PythonFaceSDK.PipelineResult

Check liveness of face from input image.

Parameters:

image (Image) – Input image.
meta (Meta) – Meta information about device.

Returns:

Result of liveness detection.

Return type:

PipelineResult

checkLiveness(self: PythonFaceSDK.Pipeline, image_batch: PythonFaceSDK.ImageBatch) -> PythonFaceSDK.PipelineResult

Perform liveness check on a sequence of photos (image batch). A single results corresponding to the whole image batch will be produced.

Parameters:: image_batch (ImageBatch) – Input batch of images (a sequence of photos).
Returns:: A single liveness result for a given sequence of photos.
Return type:: PipelineResult

checkLiveness(self: PythonFaceSDK.Pipeline, image_batch: PythonFaceSDK.ImageBatch, meta: PythonFaceSDK.Meta) -> PythonFaceSDK.PipelineResult

Perform liveness check on a sequence of photos (image batch). A single results corresponding to the whole image batch will be produced.

Parameters:

image_batch (ImageBatch) – Input batch of images (a sequence of photos).
meta (Meta) – Meta information about device.

Returns:

: A single liveness result for a given sequence of photos.

Return type:

PipelineResult

checkLivenessBatch(*args, **kwargs)¶

Overloaded function.

checkLivenessBatch(self: PythonFaceSDK.Pipeline, images: list[PythonFaceSDK.Image]) -> list[PythonFaceSDK.OptionalPipelineResult]

This method implements batched liveness check.

Parameters:: images (list) – List of Image object.
Returns:: List of optional liveness check results. The size of the result vector is guaranteed equal to images list size.
Return type:: list

checkLivenessBatch(self: PythonFaceSDK.Pipeline, images: list[PythonFaceSDK.Image], meta: list[PythonFaceSDK.Meta]) -> list[PythonFaceSDK.OptionalPipelineResult]

This method implements batched liveness check.

Parameters:

images (list) – List of Image object.
meta (list) – List of Meta information about device for each provided image.

Returns:

List of optional liveness check results. The size of the result vector is guaranteed equal to images list size.

Return type:

list

class PythonFaceSDK.PipelineResult¶

Liveness detection result.

property liveness_result¶

Liveness result.

Type:: LivenessResult

property quality_result¶

Quality result.

Type:: QualityResult

class PythonFaceSDK.QualityEngine¶

Quality estimation engine.

checkQuality(image: PythonFaceSDK.Image) → PythonFaceSDK.QualityResult¶

Check quality of face from input image.

Parameters:: image (Image) – Input image
Returns:: Result of quality estimation.
Return type:: QualityResult

checkQualityBatch(images: list[PythonFaceSDK.Image]) → list[PythonFaceSDK.OptionalQualityResult]¶

Check quality of face from input images batch.

Parameters:: images (list) – List of Image object.
Returns:: List of optional quality check results. The size of the result vector is guaranteed equal to images list size.
Return type:: list

class PythonFaceSDK.QualityResult¶

Quality estimation result.

property class_¶

Class, 0 - bad image, 1 - good image.

Type:: bool

property score¶

Quality RAW output.

Type:: float

class PythonFaceSDK.STATUS(value: int)¶

Error code enum.

FACE_TOO_CLOSE¶: A distance between face and image border is too small for preprocessing issues.

FACE_CLOSE_TO_BORDER¶: Face is too close to one or more borders. May reduce the accuracy ofspoofing detection because edges of face may not be seen.

FACE_CROPPED¶: Face is cropped. May reduce the accuracy of spoofing detection because edges of face may not be seen.

FACE_NOT_FOUND¶: Face detector can’t find face on image.

TOO_MANY_FACES¶: Face detector found more than one face on image.

FACE_TOO_SMALL¶: Facial area is not big enough for analysis.

FACE_ANGLE_TOO_LARGE¶: Facial out-of-plane rotation angle is extremely large.

FAILED_TO_READ_IMAGE¶: File decoding error.

FAILED_TO_WRITE_IMAGE¶: File encoding error.

FAILED_TO_READ_MODEL¶: Model deserializing error.

FAILED_TO_BUILD_INTERPRETER¶: tflite::Interpreter building error.

FAILED_TO_INVOKE_INTERPRETER¶: tflite::Interpreter invoking error.

FAILED_TO_ALLOCATE¶: Memory allocation error.

INVALID_CONFIG¶: Config deserializing error.

NO_SUCH_OBJECT_IN_BUILD¶: Engine or backend is not supported by the build.

FAILED_TO_PREPROCESS_IMAGE_WHILE_PREDICT¶: Liveness prediction error.

FAILED_TO_PREPROCESS_IMAGE_WHILE_DETECT¶: Face detection error.

FAILED_TO_PREDICT_LANDMARKS¶: Landmarks prediction error.

INVALID_FUSE_MODE¶: Invalid fuse mode provided.

NULLPTR¶: Nullptr provided.

LICENSE_ERROR¶: Some error occurred during license checking.

INVALID_META¶: Invalid Meta value.

UNKNOWN¶: Unhandled exception in the code.

OK¶: No errors.

FACE_IS_OCCLUDED¶: The biggest face on the input image is occluded, so liveness check is not possible.

FAILED_TO_FETCH_COREML_DECRYPTION_KEY¶: Failed to fetch CoreML model decryption key from Apple servers.

EYES_CLOSED¶: Eyes are closed.

property name¶