Face Detection

class tfsdk.TFFacechip

Example of a Facechip:

_images/chip.jpg
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, Annotated[List[tfsdk.Point], FixedSize(106)]]

Obtain the 106 face landmarks.

Parameters

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:

_images/landmarks.png
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
Returns

Returns tfsdk.TFFacechip.

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

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

Parameters
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:

_images/landmarks2.jpg