Face Detection¶

class tfsdk.TFFacechip¶

Example of a Facechip:

TFFacechip.save_image(self: tfsdk.TFFacechip, filepath: str) → None¶

Save the face chip to disk.

Parameters

filepath - the filepath where the face chip should be saved, including the image extension.

TFFacechip.load_image(self: tfsdk.TFFacechip, filepath: str, gpu_memory: bool = False, gpu_index: int = 0) → tfsdk.ERRORCODE ¶

Load the face chip from disk.

Parameters

filepath - the filepath of the facechip to load.

gpu_memory - read the image into GPU memory. This should be set to true when running GPU inference.

gpu_index - the GPU index.

TFFacechip.get_height(self: tfsdk.TFFacechip) → int¶

Get the face chip height in pixels.

Returns: Returns the face chip height in pixels.

TFFacechip.get_width(self: tfsdk.TFFacechip) → int¶

Get the face chip width in pixels.

Returns: Returns the face chip width in pixels.

TFFacechip.as_numpy_array(self: tfsdk.TFFacechip) → numpy.ndarray[numpy.uint8]¶

Get the facechip as a numpy array.

Returns: Returns the facechip as a numpy array in BGR format.

SDK.detect_faces(self: tfsdk.SDK, tf_image: tfsdk.TFImage) → List[tfsdk.FaceBoxAndLandmarks]¶

Detect all the faces in the image and return the bounding boxes and facial landmarks. Use the FACEDETECTIONFILTER configuration option to filter the detected faces. Refer to our FAQ page to understand the impact of face height on similarity score. The face detector is able to detect faces in the following dynamic height range. Smallest detectable face = ((the larger of your image dimensions) / 640 * 20) pixels. Largest detectable face = (your image height) pixels.

Parameters: tf_image – the input tfsdk.TFImage, returned by tfsdk.SDK.preprocess_image().
Returns: A list of FaceBoxAndLandmarks representing each of the detected faces. If no faces are found, the list will be empty. The detected faces are sorted in order of descending face score.

SDK.detect_largest_face(self: tfsdk.SDK, tf_image: tfsdk.TFImage) → Tuple[bool, tfsdk.FaceBoxAndLandmarks]¶

Detect the largest face in the image by area. Use the FACEDETECTIONFILTER configuration option to filter the detected faces. Refer to our FAQ page to understand the impact of face height on similarity score. The face detector is able to detect faces in the following dynamic height range. Smallest detectable face = ((the larger of your image dimensions) / 640 * 20) pixels. Largest detectable face = (your image height) pixels.

Parameters: tf_image – the input tfsdk.TFImage, returned by tfsdk.SDK.preprocess_image().
Returns: A bool indicating if a face was detected and the corresponding tfsdk.FaceBoxAndLandmarks, in that order.

SDK.get_face_landmarks(self: tfsdk.SDK, tf_image: tfsdk.TFImage, face_box_and_landmarks: tfsdk.FaceBoxAndLandmarks) → Tuple[tfsdk.ERRORCODE, List[tfsdk.Point[106]]]¶

Obtain the 106 face landmarks.

Parameters

tf_image - the input tfsdk.TFImage, returned by tfsdk.SDK.preprocess_image().
face_box_and_landmarks - tfsdk.FaceBoxAndLandmarks returned by tfsdk.SDK.detect_faces() or tfsdk.SDK.detect_largest_face().

Returns: The tfsdk.ERRORCODE and list of the 106 face landmark points, returned in that order.

Obtain the 106 face landmarks.

The order of the face landmarks:

SDK.extract_aligned_face(self: tfsdk.SDK, tf_image: tfsdk.TFImage, face_box_and_landmarks: tfsdk.FaceBoxAndLandmarks, margin_left: int = 0, margin_top: int = 0, margin_right: int = 0, margin_bottom: int = 0, scale: float = 1.0) → tfsdk.TFFacechip ¶

Extract the aligned face chip. Changing the margins and scale will change the face chip size. If using the face chip with Trueface algorithms (ex face recognition), do not change the default margin and scale values.

Parameters

tf_image - the input tfsdk.TFImage, returned by tfsdk.SDK.preprocess_image().
face_box_and_landmarks - the tfsdk.FaceBoxAndLandmarks returned by tfsdk.SDK.detect_largest_face() or tfsdk.SDK.detect_faces().
margin_left - adds a margin to the left side of the face chip (default = 0).
margin_top - adds a margin to the top side of the face chip (default = 0).
margin_right - adds a margin to the right side of the face chip (default = 0).
margin_bottom - adds a margin to the bottom side of the face chip (default = 0).
scale - changes the scale of the face chip (default = 1).

Returns

Returns tfsdk.TFFacechip.

SDK.estimate_head_orientation(self: tfsdk.SDK, tf_image: tfsdk.TFImage, face_box_and_landmarks: tfsdk.FaceBoxAndLandmarks, landmarks: List[tfsdk.Point[106]]) → Tuple[tfsdk.ERRORCODE, float, float, float, List[float[3]], List[float[3]]]¶

Estimate the head orientation. Refer to our FAQ page to understand the impact of head orientation on similarity score.

Parameters

tf_image - the input tfsdk.TFImage, returned by tfsdk.SDK.preprocess_image().
face_box_and_landmarks - the tfsdk.FaceBoxAndLandmarks.
landmarks - the detailed landmarks returned by tfsdk.SDK.get_face_landmarks().

Returns

The ERRORCODE, yaw, pitch, roll, rotation_vector, translation_vector, in that order. Angles are in radians. The rotation and translation vectors can be passed to tfsdk.SDK.draw_head_orientation_box() method.

class tfsdk.Point¶

to_dict(self: tfsdk.Point) → dict¶: Return a dictionary representation of the object.

property x¶: Coordinate along the horizontal axis, or pixel column.

property y¶: Coordinate along the vertical axis, or pixel row.

class tfsdk.FaceBoxAndLandmarks¶

property bottom_right¶: The bottom-right corner Point of the bounding box.

get_area(self: tfsdk.FaceBoxAndLandmarks) → float¶: Get the area of the face box in pixels squared.

get_height(self: tfsdk.FaceBoxAndLandmarks) → float¶: Get the the height of the face box in pixels.

property landmarks¶: The list of facial landmark points (Point) in this order: subject right eye, subject left eye, nose, subject right mouth corner, subject left mouth corner.

property score¶: Likelihood of this being a true positive.

to_dict(self: tfsdk.FaceBoxAndLandmarks) → dict¶: Return a dictionary representation of the object.

property top_left¶: The top-left corner Point of the bounding box.

The order of the face landmarks: