AlignedFace

class lib.align.aligned_face.AlignedFace(landmarks: ndarray, image: ndarray | None = None, centering: Literal['face', 'head', 'legacy'] = 'face', size: int = 64, coverage_ratio: float = 1.0, y_offset: float = 0.0, dtype: str | None = None, is_aligned: bool = False, is_legacy: bool = False)

Bases: object

Class to align a face.

Holds the aligned landmarks and face image, as well as associated matrices and information about an aligned face.

Parameters:

landmarks (np.ndarray) – The original 68 point landmarks that pertain to the given image for this face
image (np.ndarray | None) – The original frame that contains the face that is to be aligned. Pass None if the aligned face is not to be generated, and just the co-ordinates should be calculated.
centering (CenteringType) – The type of extracted face that should be loaded. “legacy” places the nose in the center of the image (the original method for aligning). “face” aligns for the nose to be in the center of the face (top to bottom) but the center of the skull for left to right. “head” aligns for the center of the skull (in 3D space) being the center of the extracted image, with the crop holding the full head. Default: “face”
size (int) – The size in pixels, of each edge of the final aligned face. Default: 64
coverage_ratio (float) – The amount of the aligned image to return. A ratio of 1.0 will return the full contents of the aligned image. A ratio of 0.5 will return an image of the given size, but will crop to the central 50%% of the image.
y_offset (float) – Amount to adjust the aligned face along the y-axis in the range -1. to 1. Default: 0.0
dtype (str | None) – Set a data type for the final face to be returned as. Passing None will return a face with the same data type as the original image. Default: None
is_aligned_face – Indicates that the image is an aligned face rather than a frame. Default: False
is_legacy (bool) – Only used if is_aligned is True. True indicates that the aligned image being loaded is a legacy extracted face rather than a current head extracted face
is_aligned (bool)

Attributes Summary

`adjusted_matrix`	The 3x2 transformation matrix for extracting and aligning the core face area out of the original frame with padding and sizing applied.
`average_distance`	The average distance of the core landmarks (18-67) from the mean face that was used for aligning the image.
`centering`	The centering of the Aligned Face.
`face`	The aligned face at the given `size` at the specified `coverage` in the given `dtype`.
`interpolators`	(interpolator and reverse interpolator) for the `adjusted matrix`.
`landmark_type`	The type of landmarks that generated this aligned face
`landmarks`	The 68 point facial landmarks aligned to the extracted face box.
`matrix`	The 3x2 transformation matrix for extracting and aligning the core face area out of the original frame, with no padding or sizing applied.
`normalized_landmarks`	The 68 point facial landmarks normalized to 0.0 - 1.0 as aligned by Umeyama.
`original_roi`	The location of the extracted face box within the original frame.
`padding`	The amount of padding (in pixels) that is applied to each side of the extracted face image for the selected extract type.
`pose`	The estimated pose in 3D space.
`relative_eye_mouth_position`	Value representing the relative position of the lowest eye/eye-brow point to the highest mouth point.
`size`	The size (in pixels) of one side of the square extracted face image.
`y_offset`	Additional offset applied to the face along the y-axis in -1.

Methods Summary

`extract_face`(image)	Extract the face from a source image and populate `face`.
`get_landmark_mask`(area[, dilation, ...])	Obtain a `LandmarksMask` based mask for this face
`split_mask`()	Remove the mask from the alpha channel of `face` and return the mask
`transform_points`(points[, invert])	Perform transformation on a series of (x, y) co-ordinates in world space into aligned face space.

Attributes Documentation

adjusted_matrix: The 3x2 transformation matrix for extracting and aligning the core face area out of the original frame with padding and sizing applied.

average_distance: The average distance of the core landmarks (18-67) from the mean face that was used for aligning the image.

centering: The centering of the Aligned Face. One of “legacy”, “head”, “face”.

face: The aligned face at the given size at the specified coverage in the given dtype. If an image has not been provided then an the attribute will return None.

interpolators: (interpolator and reverse interpolator) for the adjusted matrix.

landmark_type: The type of landmarks that generated this aligned face

landmarks: The 68 point facial landmarks aligned to the extracted face box.

matrix: The 3x2 transformation matrix for extracting and aligning the core face area out of the original frame, with no padding or sizing applied. The returned matrix is offset for the given centering.

normalized_landmarks: The 68 point facial landmarks normalized to 0.0 - 1.0 as aligned by Umeyama.

original_roi: The location of the extracted face box within the original frame.

padding: The amount of padding (in pixels) that is applied to each side of the extracted face image for the selected extract type.

pose: The estimated pose in 3D space.

relative_eye_mouth_position: Value representing the relative position of the lowest eye/eye-brow point to the highest mouth point. Positive values indicate that eyes/eyebrows are aligned above the mouth, negative values indicate that eyes/eyebrows are misaligned below the mouth.

size: The size (in pixels) of one side of the square extracted face image.

y_offset: Additional offset applied to the face along the y-axis in -1. to 1. range

Methods Documentation

extract_face(image: ndarray | None) → ndarray | None

Extract the face from a source image and populate face. If an image is not provided then None is returned.

Parameters:

image (ndarray | None) – The original frame to extract the face from. None if the face should not be extracted

Returns:

The extracted face at the given size, with the given coverage of the given dtype or
None if no image has been provided.

Return type:

ndarray | None

get_landmark_mask(area: T.Literal['eye', 'mouth', 'face', 'face_extended'], dilation: float = 0, blur_kernel: int = 0, blur_type: T.Literal['gaussian', 'normalized'] | None = 'gaussian', blur_passes: int = 1) → npt.NDArray[np.uint8]

Obtain a LandmarksMask based mask for this face

Landmark based masks are generated from Aligned Face landmark points.

Parameters:

area (T.Literal['eye', 'mouth', 'face', 'face_extended']) – The type of mask to obtain. face is a full face mask, face_extended is a face mask that extends above the eyebrows. The others are masks for those specific areas
dilation (float) – The amount of dilation to apply to the mask. as a percentage of the mask size. Default: 0
blur_kernel (int) – The kernel size, in pixels to apply gaussian blurring to the mask. Set to 0 for no blurring. Should be odd, if an even number is passed in (outside of 0) then it is rounded up to the next odd number. Default: 0
blur_type (T.Literal['gaussian', 'normalized'] | None) – The blur type to use. gaussian or normalized box filter. Default: gaussian
blur_passes (int) – The number of passed to perform when blurring. Default: 1

Return type:

The requested Landmarks Mask

split_mask() → ndarray

Remove the mask from the alpha channel of face and return the mask

Return type:: The mask that was stored in the face’s alpha channel
Raises:: AssertionError – If face does not contain a mask in the alpha channel

transform_points(points: ndarray, invert: bool = False) → ndarray

Perform transformation on a series of (x, y) co-ordinates in world space into aligned face space.

Parameters:

points (ndarray) – The points to transform
invert (bool) – True to reverse the transformation (i.e. transform the points into world space from aligned face space). Default: False

Return type:

The transformed points

property adjusted_matrix: ndarray: The 3x2 transformation matrix for extracting and aligning the core face area out of the original frame with padding and sizing applied.

property average_distance: float: The average distance of the core landmarks (18-67) from the mean face that was used for aligning the image.

property centering: Literal['legacy', 'head', 'face']: The centering of the Aligned Face. One of “legacy”, “head”, “face”.

extract_face(image: ndarray | None) → ndarray | None

Extract the face from a source image and populate face. If an image is not provided then None is returned.

Parameters:

image (ndarray | None) – The original frame to extract the face from. None if the face should not be extracted

Returns:

The extracted face at the given size, with the given coverage of the given dtype or
None if no image has been provided.

Return type:

ndarray | None

property face: ndarray | None: The aligned face at the given size at the specified coverage in the given dtype. If an image has not been provided then an the attribute will return None.

get_landmark_mask(area: T.Literal['eye', 'mouth', 'face', 'face_extended'], dilation: float = 0, blur_kernel: int = 0, blur_type: T.Literal['gaussian', 'normalized'] | None = 'gaussian', blur_passes: int = 1) → npt.NDArray[np.uint8]

Obtain a LandmarksMask based mask for this face

Landmark based masks are generated from Aligned Face landmark points.

Parameters:

area (T.Literal['eye', 'mouth', 'face', 'face_extended']) – The type of mask to obtain. face is a full face mask, face_extended is a face mask that extends above the eyebrows. The others are masks for those specific areas
dilation (float) – The amount of dilation to apply to the mask. as a percentage of the mask size. Default: 0
blur_kernel (int) – The kernel size, in pixels to apply gaussian blurring to the mask. Set to 0 for no blurring. Should be odd, if an even number is passed in (outside of 0) then it is rounded up to the next odd number. Default: 0
blur_type (T.Literal['gaussian', 'normalized'] | None) – The blur type to use. gaussian or normalized box filter. Default: gaussian
blur_passes (int) – The number of passed to perform when blurring. Default: 1

Return type:

The requested Landmarks Mask

property interpolators: tuple[int, int]: (interpolator and reverse interpolator) for the adjusted matrix.

property landmark_type: LandmarkType: The type of landmarks that generated this aligned face

property landmarks: ndarray: The 68 point facial landmarks aligned to the extracted face box.

property matrix: ndarray: The 3x2 transformation matrix for extracting and aligning the core face area out of the original frame, with no padding or sizing applied. The returned matrix is offset for the given centering.

property normalized_landmarks: ndarray: The 68 point facial landmarks normalized to 0.0 - 1.0 as aligned by Umeyama.

property original_roi: ndarray: The location of the extracted face box within the original frame.

property padding: int: The amount of padding (in pixels) that is applied to each side of the extracted face image for the selected extract type.

property pose: PoseEstimate: The estimated pose in 3D space.

property relative_eye_mouth_position: float: Value representing the relative position of the lowest eye/eye-brow point to the highest mouth point. Positive values indicate that eyes/eyebrows are aligned above the mouth, negative values indicate that eyes/eyebrows are misaligned below the mouth.

property size: int: The size (in pixels) of one side of the square extracted face image.

split_mask() → ndarray

Remove the mask from the alpha channel of face and return the mask

Return type:: The mask that was stored in the face’s alpha channel
Raises:: AssertionError – If face does not contain a mask in the alpha channel

transform_points(points: ndarray, invert: bool = False) → ndarray

Perform transformation on a series of (x, y) co-ordinates in world space into aligned face space.

Parameters:

points (ndarray) – The points to transform
invert (bool) – True to reverse the transformation (i.e. transform the points into world space from aligned face space). Default: False

Return type:

The transformed points

property y_offset: float: Additional offset applied to the face along the y-axis in -1. to 1. range