New Python API 1.47.0¶

`idliveface.get_release_info`	Returns information about this IDLive Face release.
`idliveface.LicenseFeature`	IDLive Face license features.
`idliveface.LicenseFeatureInfo`	IDLive Face license feature info.
`idliveface.ReleaseInfo`	Information about the IDLive Face release.
`idliveface.Blueprint`	Factory for the IDLive Face's objects.
`idliveface.RuntimeConfiguration`	The resource management and performance configuration.
`idliveface.Image`	Contains the content of the decoded image.
`idliveface.PixelFormat`	The format of the image pixel.
`idliveface.ImageAttributes`	General attributes of the image.
`idliveface.ImageDecoder`	Decodes compressed images.
`idliveface.FaceAnalyzer`	Detects face on the image and analyzes if it belongs to a real person or or not.
`idliveface.FaceAnalysisResult`	The result of the face analysis.
`idliveface.FaceStatus`	The status of the analyzed face.
`idliveface.Domain`	Defines a subset of characteristics that the face analysis should be sensitive to.
`idliveface.Tolerance`	Defines how strict the face analysis should be, which in return affects APCER / BPCER balance.
`idliveface.Validation`	All criteria the image is being validated on.
`idliveface.FaceDetector`	Detects and validates faces and their attributes.
`idliveface.FaceDetectionResult`	The result of the face detection.
`idliveface.DetectedFace`	The information about the detected face.
`idliveface.FaceAttributes`	Attributes of the detected face.
`idliveface.HeadPose`	The roll, pitch and yaw angles of the head, in degrees.
`idliveface.BoundingBox`	The bounding box around the face.
`idliveface.Point`	Two-dimensional point.
`idliveface.ImageQualityAttributes`	Quality attributes of the image.

Initialization¶

get_release_info() → ReleaseInfo¶: Returns information about this IDLive Face release.

class LicenseFeature(value: int)¶

IDLive Face license features.

Members:

PAD : Presentation attack detection functionality.

DFD : Deepfake detection functionality.

class 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 ReleaseInfo¶

Information about the IDLive Face release.

property license_info¶: License info per feature.

property version¶: The IDLive Face version.

class Blueprint(init_data_path, runtime_config=None)¶

Factory for the IDLive Face’s objects.

Initializes the instance using the provided init data.

The init data is located in the data directory of the IDLive Face bundle.

Parameters:

init_data_path (str | Path) – Path to the init data.
runtime_config (RuntimeConfiguration | None) – Optional custom runtime configuration.

Raises:

IDLiveFaceException – The provided path is invalid or the runtime configuration contains invalid values.

property available_pipelines: List[str]¶

Returns all available pipelines.

The first one in the list is the default pipeline, which will be used by create_face_analyzer() if no other pipeline is specified.

create_face_analyzer(pipeline=None)¶

Creates new FaceAnalyzer.

Parameters:: pipeline (str | None) – The name of the pipeline to use. If not specified uses the first one returned by available_pipelines property.
Return type:: FaceAnalyzer

create_face_detector()¶

Creates new FaceDetector.

Return type:: FaceDetector

create_image_decoder()¶

Creates new ImageDecoder.

Return type:: ImageDecoder

override_validation_parameters(parameters, domain=None)¶

Overrides validation parameters.

If the domain is specified, overrides parameters for this domain only. Otherwise overrides parameters for all domains.

Available parameters:

min_face_size: Minimal width and height of the face box, in pixels.
min_face_padding: Minimal distance from the image’s border to the face box, in pixels.
min_pupillary_distance: Minimal distance between the pupils on the face, in pixels.
min_face_size_relative: Minimal relative face’s width and height.
detectable_face_size_relative: Minimal relative face’s width and height for the face to be detected.
max_yaw: Max yaw angle of the head.
max_pitch: Max pitch angle of the head.
max_roll: Max roll angle of the head.

Parameters:

parameters (dict) – Custom validation parameters.
domain (Domain | None) – Optional analysis domain.

Raises:

IDLiveFaceException – Unknown validation parameter provided.

set_domain(domain)¶

Sets the analysis domain.

Parameters:: domain (Domain) – Analysis domain.

set_tolerance(tolerance)¶

Sets the analysis tolerance.

Parameters:: tolerance (Tolerance) – Analysis tolerance.

suppress_validation(validation, suppress=True)¶

Suppresses (or unsuppresses) the validation.

You can suppress these validations:

FACE_OCCLUDED
EYES_CLOSED
DARK_IMAGE

Parameters:

validation (Validation) – The validation to suppress.
suppress (bool) – True will suppress the validation, False will clear the suppression status.

Raises:

IDLiveFaceException – The validation can’t be suppressed.

class RuntimeConfiguration(effective_cpu_cores: int = 0)¶

The resource management and performance configuration.

Creates RuntimeConfiguration with the fields set to optimized defaults.

By default assumes all CPU cores should be used. If there is a need to use CPU resources, the number of cores can be limited with the effective_cpu_cores parameter.

Parameters:: effective_cpu_cores – Number of CPU cores to use. 0 means “use all”.

property backend_invocations¶

The maximum number of the concurrent Neural Network Backend’s invocations.

Logically represent the number of Neural Networks that can be run at once.

property backend_threads¶

The number of threads used by the Neural Network Backend.

Defines the number of active threads executed simultaneously by the Neural Network Backend. Depending on the backend it may be CPU threads or something else entirely.

property parameters¶: Other runtime parameters.

property worker_threads¶

The number of threads used by IDLive Face for internal tasks.

These tasks are always run on CPU.

Image¶

class Image(data, pixel_format=None)¶

Contains the content of the decoded image.

Initializes the instance with the content of the NumPy array.

Expects the NumPy array returned by OpenCV in the BGR format. If you have an image in the RGB format, you need to set the pixel_format parameter accordingly. Grayscale images are also supported.

Parameters:

data – 3dim or 2dim NumPy array (like the one returned by OpenCV). Note that ROI is not supported.
pixel_format (PixelFormat) – The pixel format for the images with 3 color channels.

property attributes: ImageAttributes¶: Returns image attributes.

class PixelFormat(value: int)¶

The format of the image pixel.

Members:

RGB : Red-Green-Blue, three bytes per pixel.

BGR : Blue-Green-Red, three bytes per pixel (used by OpenCV).

class ImageAttributes¶

General attributes of the image.

property height¶: The height of the image.

property source_format¶: The compression format of the source image.

property width¶: The width of the image.

class ImageDecoder(native)¶

Decodes compressed images.

decode(data)¶

Decodes the image from the memory.

Parameters:: data (bytes | bytearray) – Image content.
Raises:: ImageDecodingException – The image can’t be decoded.
Return type:: Image

decode_file(file_path)¶

Loads and decodes the image from the file.

Parameters:: file_path (str | Path) – Path to the image file.
Raises:: ImageDecodingException – The image can’t be decoded or the invalid path is provided.
Return type:: Image

Face analysis¶

class FaceAnalyzer(native)¶

Detects face on the image and analyzes if it belongs to a real person or or not.

analyze(image, domain=None, tolerance=None)¶

Runs the face analysis.

Parameters:

image (Image) – Source image.
domain (Domain | None) – Optional analysis domain.
tolerance (Tolerance | None) – Optional analysis tolerance.

Raises:

LicenseException – The license has expired.

Return type:

FaceAnalysisResult

property pipeline: str¶: Returns the pipeline used.

class FaceAnalysisResult¶

The result of the face analysis.

asdict() → dict¶: Returns content of the object as a serializable dictionary.

property box¶

The bounding box around the detected face.

Filled when the face was detected, even when the resulting status is INVALID. None if no faces were detected.

property failed_validations¶

List of failed validations, if the image was rejected.

Only filled when the status is set to INVALID.

property genuine_probability¶

The probability that the face is genuine and belongs to a real person.

Ranges from 0 (not genuine) to 1 (genuine). The face can be considered genuine when the probability is higher or equal to 0.5.

Set to None when status is INVALID.

property status¶

The status of the analyzed face.

Set to GENUINE when genuine_probability is higher or equal to 0.5, and to NOT_GENUINE otherwise. The status INVALID means some validations did non pass. They can be found in the failed_validation.

class FaceStatus(value: int)¶

The status of the analyzed face.

Members:

GENUINE : The face on the image is genuine and belongs to a real person.

NOT_GENUINE : The face on the image is not genuine, which can be a result of the presentation attack.

INVALID : The face on the image is not suitable for the analysis or not present at all.

class Domain(value: int)¶

Defines a subset of characteristics that the face analysis should be sensitive to.

Correctly specified domain leads to more precise analysis results.

Members:

GENERAL : General case. Used by default.

DESKTOP : Targets images taken via desktop web-camera.

class Tolerance(value: int)¶

Defines how strict the face analysis should be, which in return affects APCER / BPCER balance.

Members:

REGULAR : Targets low APCER. Used by default.

SOFT : Achieves lower BPCER while still having acceptable APCER.

HARDENED : Targets extra low APCER with higher BPCER.

class Validation(value: int)¶

All criteria the image is being validated on. The image is considered rejected if any of the validations fail.

Members:

FACE_NOT_FOUND : No faces are found on the image.

TOO_MANY_FACES : There is more than one face on the image.

SMALL_FACE_SIZE : The face box is too small.

SMALL_RELATIVE_FACE_SIZE : The face relative size is too small.

SMALL_PUPILLARY_DISTANCE : The distance between pupils on the face is too small.

LARGE_FACE_ROTATION_ANGLE : The rotation angle of the head (inc. roll, pitch an yaw) is too big.

FACE_TOO_CLOSE : The face is too close to the camera.

FACE_CLOSE_TO_BORDER : The face is too close to one or more image borders.

FACE_CROPPED : The face is cropped.

FACE_OCCLUDED : The face is occluded, for example with a medical mask.

EYES_CLOSED : The eyes are closed.

DARK_IMAGE : The image is too dark.

Face detection¶

class FaceDetector(native)¶

Detects and validates faces and their attributes.

detect_faces(image)¶

Runs the face detection.

Parameters:: image (Image) – Source image.
Raises:: LicenseException – The license has expired.
Return type:: FaceDetectionResult

class FaceDetectionResult¶

The result of the face detection.

asdict() → dict¶: Returns content of the object as a serializable dictionary.

property faces¶

The detected faces.

When no faces are detected, the list will be empty and the failed_validation will contain Validation.FACE_NOT_FOUND.

property failed_validations¶

All failed validations.

Contains global failed validations and ones from all the faces.

property image_quality_attributes¶: Quality attributes of the image.

class DetectedFace¶

The information about the detected face.

property attributes¶: Attributes of the detected face.

property failed_validations¶: Validations that are failed to pass for this particular face.

class FaceAttributes¶

Attributes of the detected face.

property box¶: The bounding box around the face.

property eyes_closed¶: The probability that the eyes are closed, from 0 (open) to 1 (closed).

property head_pose¶: The roll, pitch and yaw rotation angles of the head.

property landmarks¶: The facial landmark points.

property occlusion¶: The probability that the face is occluded (for example with medical mask), from 0 (not occluded) to 1 (occluded).

property orientation¶

The orientation of the face, in degrees.

It’s a roll angle rounded to a nearest multiply of 90. Can be -90, 0, 90 or 180.

property pupillary_distance¶: The distance between the centers of pupils, in pixels.

class HeadPose¶

The roll, pitch and yaw angles of the head, in degrees.

property pitch¶: The pitch angle, ranges from -180 to 180.

property roll¶: The roll angle, ranges from -180 to 180.

property yaw¶: The yaw angle, ranges from -180 to 180.

class BoundingBox(x: int = 0, y: int = 0, width: int = 0, height: int = 0)¶

The bounding box around the face.

Creates bounding box with the provided dimensions and coordinates.

property height¶: The height of the box.

property width¶: The width of the box.

property x¶: The x coordinate of the top-left point.

property y¶: The y coordinate of the top-left point.

class Point(x: int = 0, y: int = 0)¶

Two-dimensional point.

Creates point with the provided coordinates.

property x¶: The x coordinate of the point.

property y¶: The y coordinate of the point.

class ImageQualityAttributes¶

Quality attributes of the image.

property underexposure¶: How dark the image is, from 0 (normal) to 1 (too dark).

Exceptions¶

exception IDLiveFaceException¶

exception ImageDecodingException¶

exception LicenseException¶