New Python API 1.46.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