File containing API of sfe_face library as part of SFE Toolkit. More...

#include "sfe_core.h"

Data Structures
struct	SFEFaceLandmarks
	Face landmarks struct. More...

struct	SFEDetectionInputSize
	Detection input size struct. More...

struct	SFEFaceTemplate
	Face template struct. More...

struct	SFEFaceTemplateVersion
	Face template version struct. More...

struct	SFEFaceLiveness
	Face liveness struct. More...

struct	SFEFaceArea
	Face area struct. More...

struct	SFEFaceHeadPose
	Face head pose struct containing angle rotations of head. More...

struct	SFEFaceQualityAttributes
	Face quality attributes struct. More...

struct	SFEFaceDemographicAttributes
	Demographic attributes of the detected face. More...

struct	SFEFaceCrop
	Face crop struct. More...

Macros
#define	SFE_FACE_LANDMARK_COUNT 23

#define	SFE_FACE_TEMPLATE_SIZE 522

Typedefs
typedef enum SFEFaceLandmarkType	SFEFaceLandmarkType
	Face landmark types.

typedef struct SFEFaceLandmarks	SFEFaceLandmarks
	Face landmarks struct.

typedef struct SFEDetectionInputSize	SFEDetectionInputSize
	Detection input size struct.

typedef struct SFEFaceTemplate	SFEFaceTemplate
	Face template struct.

typedef struct SFEFaceTemplateVersion	SFEFaceTemplateVersion
	Face template version struct.

typedef struct SFEFaceLiveness	SFEFaceLiveness
	Face liveness struct.

typedef struct SFEFaceArea	SFEFaceArea
	Face area struct.

typedef struct SFEFaceHeadPose	SFEFaceHeadPose
	Face head pose struct containing angle rotations of head.

typedef struct SFEFaceQualityAttributes	SFEFaceQualityAttributes
	Face quality attributes struct.

typedef struct SFEFaceDemographicAttributes	SFEFaceDemographicAttributes
	Demographic attributes of the detected face.

typedef enum SFEFaceDetectionAccuracyType	SFEFaceDetectionAccuracyType
	Supported 2 detection accuracy types.

typedef struct SFEFaceCrop	SFEFaceCrop
	Face crop struct.

Enumerations
enum	SFEFaceLandmarkType { SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_OUTER_CORNER = 0 , SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_CENTER = 1 , SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_INNER_CORNER = 2 , SFE_FACE_LANDMARK_TYPE_LEFT_EYE_INNER_CORNER = 3 , SFE_FACE_LANDMARK_TYPE_LEFT_EYE_CENTER = 4 , SFE_FACE_LANDMARK_TYPE_LEFT_EYE_OUTER_CORNER = 5 , SFE_FACE_LANDMARK_TYPE_NOSE_ROOT = 6 , SFE_FACE_LANDMARK_TYPE_NOSE_RIGHT_BOTTOM = 7 , SFE_FACE_LANDMARK_TYPE_NOSE_TIP = 8 , SFE_FACE_LANDMARK_TYPE_NOSE_LEFT_BOTTOM = 9 , SFE_FACE_LANDMARK_TYPE_NOSE_BOTTOM = 10 , SFE_FACE_LANDMARK_TYPE_MOUTH_RIGHT_CORNER = 11 , SFE_FACE_LANDMARK_TYPE_MOUTH_CENTER = 12 , SFE_FACE_LANDMARK_TYPE_MOUTH_LEFT_CORNER = 13 , SFE_FACE_LANDMARK_TYPE_MOUTH_UPPER_EDGE = 14 , SFE_FACE_LANDMARK_TYPE_MOUTH_LOWER_EDGE = 15 , SFE_FACE_LANDMARK_TYPE_RIGHT_EYEBROW_OUTER_END = 16 , SFE_FACE_LANDMARK_TYPE_RIGHT_EYEBROW_INNER_END = 17 , SFE_FACE_LANDMARK_TYPE_LEFT_EYEBROW_INNER_END = 18 , SFE_FACE_LANDMARK_TYPE_LEFT_EYEBROW_OUTER_END = 19 , SFE_FACE_LANDMARK_TYPE_RIGHT_EDGE = 20 , SFE_FACE_LANDMARK_TYPE_CHIN_TIP = 21 , SFE_FACE_LANDMARK_TYPE_LEFT_EDGE = 22 }
	Face landmark types. More...

enum	SFEFaceDetectionAccuracyType { SFE_FACE_DETECT_ACCURACY_TYPE_ACCURATE = 0 , SFE_FACE_DETECT_ACCURACY_TYPE_BALANCED = 1 }
	Supported 2 detection accuracy types. More...

Functions
SFEError	sfeFaceLandmarks (SFESolver solver, SFEImageView image, const SFEDetection *detection, SFEFaceLandmarks out_face_landmarks[SFE_FACE_LANDMARK_COUNT])
	Detect 23 landmarks of the face detected in the area of source image marked with detection.

SFEError	sfeFaceMaskConfidence (const SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], float *out_mask_confidence)
	Get confidence from given landmarks if the face is wearing a face mask.

SFEError	sfeFaceSize (SFEImageView image, SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], float *face_size)
	Get the face size in pixels from the face landmarks and the source image. Face size is defined as a maximum of values of inter eyes centers distance and distance between center of mouth and center point between eyes (nose root): face_size = max(distance(left_eye_center, right_eye_center), distance(mouth_center, eyes_center))

SFEError	sfeFaceTemplateExtract (SFESolver solver, SFEImageView image, const SFEDetection detection, const SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], SFEFaceTemplate out_face_template)
	Extract template from source image and given face landmarks.

SFEError	sfeFaceTemplateMatch (SFEFaceTemplate template1, SFEFaceTemplate template2, float *out_matching_score)
	Match two face templates.

SFEError	sfeFaceTemplateQuality (SFEFaceTemplate face_template, float out_face_template_quality)
	Get template quality.

SFEError	sfeFaceTemplateVersion (SFEFaceTemplate face_template, SFEFaceTemplateVersion out_face_template_version)
	Get face template version.

SFEError	sfeFaceTemplateExport (const SFEFaceTemplate face_template, uint8_t bytes, size_t *size)
	Export face template to bytes that can be shared between Innovatrics components.

SFEError	sfeFaceTemplateImport (const uint8_t bytes, size_t size, SFEFaceTemplate out_face_template)
	Import face template from bytes; format is auto-detected (iface-template protobuf or raw ICF 522-byte).

SFEError	sfeFaceTemplateIdentify (SFEFaceTemplate probe_face_template, SFEFaceTemplate templates_gallery, size_t gallery_size, float matching_score_threshold, SFETemplateIdentificationCandidate out_candidates, size_t in_out_candidates_count, size_t thread_count)
	Get an ordered array of SFETemplateIdentificationCandidate from tested template best matches of probe template with the templates in templates_gallery.

SFEError	sfeFaceEntityIdentify (SFEFaceTemplate probe_face_template, SFEFaceTemplate templates_gallery, SFEEntity entities_gallery, size_t gallery_size, float matching_score_threshold, SFEEntityIdentificationCandidate out_candidates, size_t *in_out_candidates_count, size_t thread_count)
	Get an ordered array of SFEEntityIdentificationCandidate from tested template best matches of probe template with the templates in templates_gallery Entity is then used to group the results by entity using the best score of any template associated with the entity.

SFEError	sfeFaceLivenessPassive (SFESolver solver, SFEImageView image, SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], SFEFaceLiveness *out_liveness)
	Passive liveness score calculation.

SFEError	sfeFaceArea (SFEImageView image, SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], SFEFaceArea *out_area)
	Get face area.

SFEError	sfeFaceHeadPose (SFEImageView image, SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], SFEFaceHeadPose *out_head_pose)
	Calculate angle rotations of head towards camera reference frame from given landmarks.

SFEError	sfeFaceDemographicAttributes (SFESolver solver, SFEImageView image, SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], SFEFaceDemographicAttributes *out_demographic_attributes)
	Estimate demographic attributes (age, gender) from a face image.

SFEError	sfeFaceQualityAttributes (SFEImageView image, SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], SFEFaceQualityAttributes *out_quality_attributes)
	Calculate face image quality attributes from given source image and landmarks data.

SFEError	sfeFaceDetectInputSize (SFEImageView image, SFEFaceDetectionAccuracyType detection_mode, size_t min_face_size, size_t max_face_size, SFEDetectionInputSize *out_input_size)
	Calculation of recommended input image width and height according to desired minimal and maximal size of detected faces. The input combination of required maximal and minimal face sizes is validated against the model constraints. If valid, the recommended width and height of the image are calculated. If invalid, the error is returned. It is recommended to set the max_face_size to `max_face_size < 30 * min_face_size`. Performance could decrease if you do not comply with this requirement.

SFEError	sfeFaceCrop (SFEImageView image, SFEFaceLandmarks face_landmarks[SFE_FACE_LANDMARK_COUNT], float face_size_extension, float max_face_size, SFEFaceCrop *out_crop)
	Crop the face according the given landmarks, the face size extension and the maximal face size. The face size extension defines the size of the crop as an extension of the detection bounding box. The crop will be centered on the detection bounding box and the size will be multiplied by this value. Valid values are 0, 1, 2, 3, 4 and 5.

Detailed Description

File containing API of sfe_face library as part of SFE Toolkit.

Author: Innovatrics - SmartFace Embedded

Date: 16.5.2023

Definition in file sfe_face.h.

Macro Definition Documentation

◆ SFE_FACE_LANDMARK_COUNT

#define SFE_FACE_LANDMARK_COUNT 23

Examples: example_face_demographic_attributes.cpp, example_face_identify.cpp, example_face_identify_entity.cpp, and example_face_liveness.cpp.

Definition at line 17 of file sfe_face.h.

◆ SFE_FACE_TEMPLATE_SIZE

#define SFE_FACE_TEMPLATE_SIZE 522

Definition at line 104 of file sfe_face.h.

Typedef Documentation

◆ SFEDetectionInputSize

typedef struct SFEDetectionInputSize SFEDetectionInputSize

Detection input size struct.

◆ SFEFaceArea

typedef struct SFEFaceArea SFEFaceArea

Face area struct.

◆ SFEFaceCrop

typedef struct SFEFaceCrop SFEFaceCrop

Face crop struct.

◆ SFEFaceDemographicAttributes

typedef struct SFEFaceDemographicAttributes SFEFaceDemographicAttributes

Demographic attributes of the detected face.

◆ SFEFaceDetectionAccuracyType

typedef enum SFEFaceDetectionAccuracyType SFEFaceDetectionAccuracyType

Supported 2 detection accuracy types.

◆ SFEFaceHeadPose

typedef struct SFEFaceHeadPose SFEFaceHeadPose

Face head pose struct containing angle rotations of head.

◆ SFEFaceLandmarks

typedef struct SFEFaceLandmarks SFEFaceLandmarks

Face landmarks struct.

◆ SFEFaceLandmarkType

typedef enum SFEFaceLandmarkType SFEFaceLandmarkType

Face landmark types.

◆ SFEFaceLiveness

typedef struct SFEFaceLiveness SFEFaceLiveness

Face liveness struct.

◆ SFEFaceQualityAttributes

typedef struct SFEFaceQualityAttributes SFEFaceQualityAttributes

Face quality attributes struct.

◆ SFEFaceTemplate

typedef struct SFEFaceTemplate SFEFaceTemplate

Face template struct.

◆ SFEFaceTemplateVersion

typedef struct SFEFaceTemplateVersion SFEFaceTemplateVersion

Face template version struct.

Enumeration Type Documentation

◆ SFEFaceDetectionAccuracyType

enum SFEFaceDetectionAccuracyType

Supported 2 detection accuracy types.

Enumerator
SFE_FACE_DETECT_ACCURACY_TYPE_ACCURATE
SFE_FACE_DETECT_ACCURACY_TYPE_BALANCED

Definition at line 342 of file sfe_face.h.

                                          {
  SFE_FACE_DETECT_ACCURACY_TYPE_ACCURATE = 0,
  SFE_FACE_DETECT_ACCURACY_TYPE_BALANCED = 1,
} SFEFaceDetectionAccuracyType;

◆ SFEFaceLandmarkType

enum SFEFaceLandmarkType

Face landmark types.

Enumerator
SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_OUTER_CORNER
SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_CENTER
SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_INNER_CORNER
SFE_FACE_LANDMARK_TYPE_LEFT_EYE_INNER_CORNER
SFE_FACE_LANDMARK_TYPE_LEFT_EYE_CENTER
SFE_FACE_LANDMARK_TYPE_LEFT_EYE_OUTER_CORNER
SFE_FACE_LANDMARK_TYPE_NOSE_ROOT
SFE_FACE_LANDMARK_TYPE_NOSE_RIGHT_BOTTOM
SFE_FACE_LANDMARK_TYPE_NOSE_TIP
SFE_FACE_LANDMARK_TYPE_NOSE_LEFT_BOTTOM
SFE_FACE_LANDMARK_TYPE_NOSE_BOTTOM
SFE_FACE_LANDMARK_TYPE_MOUTH_RIGHT_CORNER
SFE_FACE_LANDMARK_TYPE_MOUTH_CENTER
SFE_FACE_LANDMARK_TYPE_MOUTH_LEFT_CORNER
SFE_FACE_LANDMARK_TYPE_MOUTH_UPPER_EDGE
SFE_FACE_LANDMARK_TYPE_MOUTH_LOWER_EDGE
SFE_FACE_LANDMARK_TYPE_RIGHT_EYEBROW_OUTER_END
SFE_FACE_LANDMARK_TYPE_RIGHT_EYEBROW_INNER_END
SFE_FACE_LANDMARK_TYPE_LEFT_EYEBROW_INNER_END
SFE_FACE_LANDMARK_TYPE_LEFT_EYEBROW_OUTER_END
SFE_FACE_LANDMARK_TYPE_RIGHT_EDGE
SFE_FACE_LANDMARK_TYPE_CHIN_TIP
SFE_FACE_LANDMARK_TYPE_LEFT_EDGE

Definition at line 20 of file sfe_face.h.

                                 {
  SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_OUTER_CORNER = 0,
  SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_CENTER = 1,
  SFE_FACE_LANDMARK_TYPE_RIGHT_EYE_INNER_CORNER = 2,
  SFE_FACE_LANDMARK_TYPE_LEFT_EYE_INNER_CORNER = 3,
  SFE_FACE_LANDMARK_TYPE_LEFT_EYE_CENTER = 4,
  SFE_FACE_LANDMARK_TYPE_LEFT_EYE_OUTER_CORNER = 5,
  SFE_FACE_LANDMARK_TYPE_NOSE_ROOT = 6,
  SFE_FACE_LANDMARK_TYPE_NOSE_RIGHT_BOTTOM = 7,
  SFE_FACE_LANDMARK_TYPE_NOSE_TIP = 8,
  SFE_FACE_LANDMARK_TYPE_NOSE_LEFT_BOTTOM = 9,
  SFE_FACE_LANDMARK_TYPE_NOSE_BOTTOM = 10,
  SFE_FACE_LANDMARK_TYPE_MOUTH_RIGHT_CORNER = 11,
  SFE_FACE_LANDMARK_TYPE_MOUTH_CENTER = 12,
  SFE_FACE_LANDMARK_TYPE_MOUTH_LEFT_CORNER = 13,
  SFE_FACE_LANDMARK_TYPE_MOUTH_UPPER_EDGE = 14,
  SFE_FACE_LANDMARK_TYPE_MOUTH_LOWER_EDGE = 15,
  SFE_FACE_LANDMARK_TYPE_RIGHT_EYEBROW_OUTER_END = 16,
  SFE_FACE_LANDMARK_TYPE_RIGHT_EYEBROW_INNER_END = 17,
  SFE_FACE_LANDMARK_TYPE_LEFT_EYEBROW_INNER_END = 18,
  SFE_FACE_LANDMARK_TYPE_LEFT_EYEBROW_OUTER_END = 19,
  SFE_FACE_LANDMARK_TYPE_RIGHT_EDGE = 20,
  SFE_FACE_LANDMARK_TYPE_CHIN_TIP = 21,
  SFE_FACE_LANDMARK_TYPE_LEFT_EDGE = 22,
} SFEFaceLandmarkType;

Function Documentation

◆ sfeFaceArea()

SFEError sfeFaceArea	(	SFEImageView	image,
		SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		SFEFaceArea *	out_area
	)

Get face area.

Parameters

[in]	image	source image
[in]	face_landmarks	face landmarks detected in source image
[out]	out_area	OUT: structure containing the face size, the face area relative to the source image, the face area intersected with the source image and relative to the source image.

Returns: Error in case of failed area struct calculations

Examples: example_face_liveness.cpp.

◆ sfeFaceCrop()

SFEError sfeFaceCrop	(	SFEImageView	image,
		SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		float	face_size_extension,
		float	max_face_size,
		SFEFaceCrop *	out_crop
	)

Crop the face according the given landmarks, the face size extension and the maximal face size. The face size extension defines the size of the crop as an extension of the detection bounding box. The crop will be centered on the detection bounding box and the size will be multiplied by this value. Valid values are 0, 1, 2, 3, 4 and 5.

Parameters

[in]	image	Source image
[in]	face_landmarks	Array of face landmarks
[in]	face_size_extension	Defines the size of the crop as an extension of the detection bounding box.
[in]	max_face_size	Defines the maximum size of the face in the crop area. If the actual face size is larger, the crop image will be downscaled.
[out]	out_crop	OUT: Structure containing used crop extension, calculated crop's bounding box and the cropped image of the face

Examples: example_face_identify.cpp.

◆ sfeFaceDemographicAttributes()

SFEError sfeFaceDemographicAttributes	(	SFESolver	solver,
		SFEImageView	image,
		SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		SFEFaceDemographicAttributes *	out_demographic_attributes
	)

Estimate demographic attributes (age, gender) from a face image.

Parameters

[in]	solver	demographic attributes solver
[in]	image	source image
[in]	face_landmarks	face landmarks detected in source image
[out]	out_demographic_attributes	OUT: estimated demographic attributes

Returns: Error in case of failed demographic attributes estimation

Examples: example_face_demographic_attributes.cpp.

◆ sfeFaceDetectInputSize()

SFEError sfeFaceDetectInputSize	(	SFEImageView	image,
		SFEFaceDetectionAccuracyType	detection_mode,
		size_t	min_face_size,
		size_t	max_face_size,
		SFEDetectionInputSize *	out_input_size
	)

Calculation of recommended input image width and height according to desired minimal and maximal size of detected faces. The input combination of required maximal and minimal face sizes is validated against the model constraints. If valid, the recommended width and height of the image are calculated. If invalid, the error is returned. It is recommended to set the max_face_size to max_face_size < 30 * min_face_size. Performance could decrease if you do not comply with this requirement.

Parameters

[in]	image	Source image
[in]	detection_mode	Accuracy type, it can be accurate or balanced
[in]	min_face_size	Desired minimal size of detected face
[in]	max_face_size	Desired maximal size of detected face
[out]	out_input_size	Recommended image dimensions (width and height)

Returns: Error in case of non valid input combination

Examples: example_face_identify.cpp, example_face_identify_entity.cpp, example_face_liveness.cpp, and example_face_track.cpp.

◆ sfeFaceEntityIdentify()

SFEError sfeFaceEntityIdentify	(	SFEFaceTemplate *	probe_face_template,
		SFEFaceTemplate *	templates_gallery,
		SFEEntity *	entities_gallery,
		size_t	gallery_size,
		float	matching_score_threshold,
		SFEEntityIdentificationCandidate *	out_candidates,
		size_t *	in_out_candidates_count,
		size_t	thread_count
	)

Get an ordered array of SFEEntityIdentificationCandidate from tested template best matches of probe template with the templates in templates_gallery Entity is then used to group the results by entity using the best score of any template associated with the entity.

Parameters

[in]	probe_face_template	probe template
[in]	templates_gallery	pointer to an array of SFEFaceTemplate
[in]	entities_gallery	pointer to an array of SFEEntity that corresponds with templates_gallery
[in]	gallery_size	number of templates in gallery
[in]	matching_score_threshold	threshold for matching - range <0,1> Function will return only candidates with score above the threshold
[out]	out_candidates	Pointer to an ordered array of candidates
[in,out]	in_out_candidates_count	IN: Expected number of candidates OUT: Number of found entities with best score above the threshold
[in]	thread_count	Number of threads to use in the identification - 0: use all available cores, 1: use single thread, N: use N number of threads

Returns: Error in case of failed identification

Examples: example_face_identify_entity.cpp.

◆ sfeFaceHeadPose()

SFEError sfeFaceHeadPose	(	SFEImageView	image,
		SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		SFEFaceHeadPose *	out_head_pose
	)

Calculate angle rotations of head towards camera reference frame from given landmarks.

Parameters

[in]	face_landmarks	face landmarks detected in source image
[out]	out_head_pose	OUT: structure containing the angle rotations - roll, yaw and pitch

Returns: Error in case of failed head pose calculationse

Examples: example_face_liveness.cpp.

◆ sfeFaceLandmarks()

SFEError sfeFaceLandmarks	(	SFESolver	solver,
		SFEImageView	image,
		const SFEDetection *	detection,
		SFEFaceLandmarks	out_face_landmarks[SFE_FACE_LANDMARK_COUNT]
	)

Detect 23 landmarks of the face detected in the area of source image marked with detection.

Parameters

[in]	solver	face landmarks solver
[in]	image	source image
[in]	detection	core detection containing the detected face
[out]	out_face_landmarks	OUT: pointer to an array of detected landmarks, the size of the array should be 23 which is the number of landmarks detected by the solver

Returns: Error in case of failed landmarks detection.

Examples: example_face_demographic_attributes.cpp, example_face_identify.cpp, example_face_identify_entity.cpp, and example_face_liveness.cpp.

◆ sfeFaceLivenessPassive()

SFEError sfeFaceLivenessPassive	(	SFESolver	solver,
		SFEImageView	image,
		SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		SFEFaceLiveness *	out_liveness
	)

Passive liveness score calculation.

Parameters

[in]	solver	passive liveness solver
[in]	image	source image
[in]	face_landmarks	face landmarks detected in source image
[out]	out_liveness	OUT: structure containing normalized score of passive liveness

Returns: Error in case of failed passive liveness score calculation

Examples: example_face_liveness.cpp.

◆ sfeFaceMaskConfidence()

SFEError sfeFaceMaskConfidence	(	const SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		float *	out_mask_confidence
	)

Get confidence from given landmarks if the face is wearing a face mask.

Parameters

[in]	face_landmarks	array of detected landmarks, the size of the array should be 23 which is the number of landmarks detected by the solver
[out]	out_mask_confidence	OUT: confidence of wearing a face mask - range <0-1>

Examples: example_face_liveness.cpp.

◆ sfeFaceQualityAttributes()

SFEError sfeFaceQualityAttributes	(	SFEImageView	image,
		SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		SFEFaceQualityAttributes *	out_quality_attributes
	)

Calculate face image quality attributes from given source image and landmarks data.

Parameters

[in]	image	source image
[in]	face_landmarks	face landmarks detected in source image
[out]	out_quality_attributes	structure containing normalized `sharpness`, `brightness`, `contrast` and `unique_intensity_levels`

Returns: Error in case of failed quality attributes calculation

Examples: example_face_liveness.cpp.

◆ sfeFaceSize()

SFEError sfeFaceSize	(	SFEImageView	image,
		SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		float *	face_size
	)

Get the face size in pixels from the face landmarks and the source image. Face size is defined as a maximum of values of inter eyes centers distance and distance between center of mouth and center point between eyes (nose root): face_size = max(distance(left_eye_center, right_eye_center), distance(mouth_center, eyes_center))

Parameters

[in]	image	source image
[in]	face_landmarks	array of face landmarks
[out]	face_size	OUT: size of the face in pixels

Returns: Error

Examples: example_face_liveness.cpp.

◆ sfeFaceTemplateExport()

SFEError sfeFaceTemplateExport	(	const SFEFaceTemplate *	face_template,
		uint8_t *	bytes,
		size_t *	size
	)

Export face template to bytes that can be shared between Innovatrics components.

Parameters

[in]	face_template	face template to export
[in,out]	bytes	buffer to export the face template to
[in,out]	size	IN: capacity of bytes buffer, OUT: number of bytes written

Returns: Error in case of failed export

Examples: example_face_identify.cpp.

◆ sfeFaceTemplateExtract()

SFEError sfeFaceTemplateExtract	(	SFESolver	solver,
		SFEImageView	image,
		const SFEDetection *	detection,
		const SFEFaceLandmarks	face_landmarks[SFE_FACE_LANDMARK_COUNT],
		SFEFaceTemplate *	out_face_template
	)

Extract template from source image and given face landmarks.

Parameters

[in]	solver	template extraction solver
[in]	image	source image
[in]	detection	core detection containing the detected face
[in]	face_landmarks	face landmarks detected in source image
[out]	out_face_template	extracted face template

Returns: Error in case of failed extraction.

Examples: example_face_identify.cpp, and example_face_identify_entity.cpp.

◆ sfeFaceTemplateIdentify()

SFEError sfeFaceTemplateIdentify	(	SFEFaceTemplate *	probe_face_template,
		SFEFaceTemplate *	templates_gallery,
		size_t	gallery_size,
		float	matching_score_threshold,
		SFETemplateIdentificationCandidate *	out_candidates,
		size_t *	in_out_candidates_count,
		size_t	thread_count
	)

Get an ordered array of SFETemplateIdentificationCandidate from tested template best matches of probe template with the templates in templates_gallery.

Parameters

[in]	probe_face_template	probe template
[in]	gallery_size	number of templates in gallery
[in]	templates_gallery	pointer to an array of SFEFaceTemplate
[in]	matching_score_threshold	threshold for matching - range <0,1> Function will return only candidates with score above the threshold
[out]	out_candidates	Pointer to an ordered array of candidates
[in,out]	in_out_candidates_count	IN: Expected number of candidates OUT: Number of found candidates with matching score above the threshold
[in]	thread_count	Number of threads to use in the identification - 0: use all available cores, 1: use single thread, N: use N number of threads

Returns: Error in case of failed identification

Examples: example_face_identify.cpp.

◆ sfeFaceTemplateImport()

SFEError sfeFaceTemplateImport	(	const uint8_t *	bytes,
		size_t	size,
		SFEFaceTemplate *	out_face_template
	)

Import face template from bytes; format is auto-detected (iface-template protobuf or raw ICF 522-byte).

Parameters

[in]	bytes	bytes to import the face template from
[in]	size	size of the bytes
[out]	out_face_template	imported face template

Returns: Error in case of failed import

Examples: example_face_identify.cpp.

◆ sfeFaceTemplateMatch()

SFEError sfeFaceTemplateMatch	(	SFEFaceTemplate *	template1,
		SFEFaceTemplate *	template2,
		float *	out_matching_score
	)

Match two face templates.

Parameters

[in]	template1	first template to match
[in]	template2	second template to match
[out]	out_matching_score	OUT: matching score - range <0,1>

Returns: Error in case of failed matching

Examples: example_face_identify.cpp.

◆ sfeFaceTemplateQuality()

SFEError sfeFaceTemplateQuality	(	SFEFaceTemplate *	face_template,
		float *	out_face_template_quality
	)

Get template quality.

Parameters

[in]	face_template	source template
[out]	out_face_template_quality	OUT: template quality - range <0,1>

Returns: Error in case of template checksum mismatch

◆ sfeFaceTemplateVersion()

SFEError sfeFaceTemplateVersion	(	SFEFaceTemplate *	face_template,
		SFEFaceTemplateVersion *	out_face_template_version
	)

Get face template version.

Parameters

[in]	face_template	source template
[out]	out_face_template_version	OUT: face template version struct

Returns: Error in case of template checksum mismatch

Examples: example_face_identify.cpp.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SFE_FACE_LANDMARK_COUNT

◆ SFE_FACE_TEMPLATE_SIZE

Typedef Documentation

◆ SFEDetectionInputSize

◆ SFEFaceArea

◆ SFEFaceCrop

◆ SFEFaceDemographicAttributes

◆ SFEFaceDetectionAccuracyType

◆ SFEFaceHeadPose

◆ SFEFaceLandmarks

◆ SFEFaceLandmarkType

◆ SFEFaceLiveness

◆ SFEFaceQualityAttributes

◆ SFEFaceTemplate

◆ SFEFaceTemplateVersion

Enumeration Type Documentation

◆ SFEFaceDetectionAccuracyType

◆ SFEFaceLandmarkType

Function Documentation

◆ sfeFaceArea()

◆ sfeFaceCrop()

◆ sfeFaceDemographicAttributes()

◆ sfeFaceDetectInputSize()

◆ sfeFaceEntityIdentify()

◆ sfeFaceHeadPose()

◆ sfeFaceLandmarks()

◆ sfeFaceLivenessPassive()

◆ sfeFaceMaskConfidence()

◆ sfeFaceQualityAttributes()

◆ sfeFaceSize()

◆ sfeFaceTemplateExport()

◆ sfeFaceTemplateExtract()

◆ sfeFaceTemplateIdentify()

◆ sfeFaceTemplateImport()

◆ sfeFaceTemplateMatch()

◆ sfeFaceTemplateQuality()

◆ sfeFaceTemplateVersion()