align package

The align Package handles detected faces, their alignments and masks.

aligned_face module

Handles aligned faces and corresponding pose estimates

Module Summary

AlignedFace Class to align a face.
get_matrix_scaling Given a matrix, return the cv2 Interpolation method and inverse interpolation method for applying the matrix on an image.
PoseEstimate Estimates pose from a generic 3D head model for the given 2D face landmarks.
transform_image Perform transformation on an image, applying the given size and padding to the matrix.

Module

Aligner for faceswap.py

class lib.align.aligned_face.AlignedFace(landmarks, image=None, centering='face', size=64, coverage_ratio=1.0, dtype=None, is_aligned=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 (numpy.ndarray) – The original 68 point landmarks that pertain to the given image for this face
  • image (numpy.ndarray, optional) – 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 (["legacy", "face", "head"], optional) – 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, optional) – The size in pixels, of each edge of the final aligned face. Default: 64
  • coverage_ratio (float, optional) – 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.
  • dtype (str, optional) – 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 (bool, optional) – Indicates that the image is an aligned face rather than a frame. Default: False
adjusted_matrix

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

Type:numpy.ndarray
average_distance

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

Type:float
extract_face(image)

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

Parameters:image (numpy.ndarray or 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:numpy.ndarray or None
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.

Type:numpy.ndarray
get_cropped_roi(centering)

Obtain the region of interest within an aligned face set to centered coverage for an alternative centering

Parameters:centering (["legacy", "face"]) – The type of centering to obtain the region of interest for. “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.
Returns:The (left, top, right, bottom location of the region of interest within an aligned face centered on the head for the given centering
Return type:numpy.ndarray
interpolators

(interpolator and reverse interpolator) for the adjusted matrix.

Type:tuple
landmarks

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

Type:numpy.ndarray
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.

Type:numpy.ndarray
normalized_landmarks

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

Type:numpy.ndarray
original_roi

The location of the extracted face box within the original frame.

Type:numpy.ndarray
padding

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

Type:int
pose

The estimated pose in 3D space.

Type:lib.align.PoseEstimate
size

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

Type:int
transform_points(points, invert=False)

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

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

The transformed points

Return type:

numpy.ndarray

class lib.align.aligned_face.PoseEstimate(landmarks)

Bases: object

Estimates pose from a generic 3D head model for the given 2D face landmarks.

Parameters:landmarks (numpy.ndarry) – The original 68 point landmarks aligned to 0.0 - 1.0 range

References

Head Pose Estimation using OpenCV and Dlib - https://www.learnopencv.com/tag/solvepnp/ 3D Model points - http://aifi.isr.uc.pt/Downloads/OpenGL/glAnthropometric3DModel.cpp

offset

The amount to offset a standard 0.0 - 1.0 umeyama transformation matrix for a from the center of the face (between the eyes) or center of the head (middle of skull) rather than the nose area.

Type:dict
pitch

The pitch of the aligned face in eular angles

Type:float
xyz_2d

numpy.ndarray projected (x, y) coordinates for each x, y, z point at a constant distance from adjusted center of the skull (0.5, 0.5) in the 2D space.

yaw

The yaw of the aligned face in eular angles

Type:float
lib.align.aligned_face.get_centered_size(source_centering, target_centering, size)

Obtain the size of a cropped face from an aligned image.

Given an image of a certain dimensions, returns the dimensions of the sub-crop within that image for the requested centering.

Notes

“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” places the center in the middle of the skull in 3D space.

The ROI in relation to the source image is calculated by rounding the padding of one side to the nearest integer then applying this padding to the center of the crop, to ensure that any dimensions always have an even number of pixels.

Parameters:
  • source_centering (["head", "face", "legacy"]) – The centering that the original image is aligned at
  • target_centering (["head", "face", "legacy"]) – The centering that the sub-crop size should be obtained for
  • size (int) – The size of the source image to obtain the cropped size for
Returns:

The pixel size of a sub-crop image from a full head aligned image

Return type:

int

lib.align.aligned_face.get_matrix_scaling(matrix)

Given a matrix, return the cv2 Interpolation method and inverse interpolation method for applying the matrix on an image.

Parameters:matrix (numpy.ndarray) – The transform matrix to return the interpolator for
Returns:The interpolator and inverse interpolator for the given matrix. This will be (Cubic, Area) for an upscale matrix and (Area, Cubic) for a downscale matrix
Return type:tuple
lib.align.aligned_face.transform_image(image, matrix, size, padding=0)

Perform transformation on an image, applying the given size and padding to the matrix.

Parameters:
  • image (numpy.ndarray) – The image to transform
  • matrix (numpy.ndarray) – The transformation matrix to apply to the image
  • size (int) – The final size of the transformed image
  • padding (int, optional) – The amount of padding to apply to the final image. Default: 0
Returns:

The transformed image

Return type:

numpy.ndarray

alignments module

Handles alignments stored in a serialized alignments.fsa file

Module Summary

Alignments The alignments file is a custom serialized .fsa file that holds information for each frame for a video or series of images.
Thumbnails Thumbnail images stored in the alignments file.

Module

Alignments file functions for reading, writing and manipulating the data stored in a serialized alignments file.

class lib.align.alignments.Alignments(folder, filename='alignments')

Bases: object

The alignments file is a custom serialized .fsa file that holds information for each frame for a video or series of images.

Specifically, it holds a list of faces that appear in each frame. Each face contains information detailing their detected bounding box location within the frame, the 68 point facial landmarks and any masks that have been extracted.

Additionally it can also hold video meta information (timestamp and whether a frame is a key frame.)

Parameters:
  • folder (str) – The folder that contains the alignments .fsa file
  • filename (str, optional) – The filename of the .fsa alignments file. If not provided then the given folder will be checked for a default alignments file filename. Default: “alignments”
add_face(frame_name, face)

Add a new face for the given frame_name in data and return it’s index.

Parameters:
  • frame_name (str) – The frame name to add the face to. This should be the base name of the frame, not the full path
  • face (dict) – The face information to add to the given frame_name, correctly formatted for storing in data
Returns:

The index of the newly added face within data for the given frame_name

Return type:

int

backup()

Create a backup copy of the alignments file.

Creates a copy of the serialized alignments file appending a timestamp onto the end of the file name and storing in the same folder as the original file.

data

The loaded alignments file in dictionary form.

Type:dict
delete_face_at_index(frame_name, face_index)

Delete the face for the given frame_name at the given face index from data.

Parameters:
  • frame_name (str) – The frame name to remove the face from. This should be the base name of the frame, not the full path
  • face_index (int) – The index number of the face within the given frame_name to remove
Returns:

True if a face was successfully deleted otherwise False

Return type:

bool

faces_count

The total number of faces that appear in the alignments data.

Type:int
file

The full path to the currently loaded alignments file.

Type:str
filter_faces(filter_dict, filter_out=False)

Remove faces from data based on a given filter list.

Parameters:
  • filter_dict (dict) – Dictionary of source filenames as key with a list of face indices to filter as value.
  • filter_out (bool, optional) – True if faces should be removed from data when there is a corresponding match in the given filter_dict. False if faces should be kept in data when there is a corresponding match in the given filter_dict, but removed if there is no match. Default: False
frame_exists(frame_name)

Check whether a given frame_name exists within the alignments data.

Parameters:frame_name (str) – The frame name to check. This should be the base name of the frame, not the full path
Returns:True if the given frame_name exists within the alignments data otherwise False
Return type:bool
frame_has_faces(frame_name)

Check whether a given frame_name exists within the alignments data and contains at least 1 face.

Parameters:frame_name (str) – The frame name to check. This should be the base name of the frame, not the full path
Returns:True if the given frame_name exists within the alignments data and has at least 1 face associated with it, otherwise False
Return type:bool
frame_has_multiple_faces(frame_name)

Check whether a given frame_name exists within the alignments data and contains more than 1 face.

Parameters:frame_name (str) – The frame_name name to check. This should be the base name of the frame, not the full path
Returns:True if the given frame_name exists within the alignments data and has more than 1 face associated with it, otherwise False
Return type:bool
frames_count

The number of frames that appear in the alignments data.

Type:int
get_faces_in_frame(frame_name)

Obtain the faces from data associated with a given frame_name.

Parameters:frame_name (str) – The frame name to return faces for. This should be the base name of the frame, not the full path
Returns:The list of face dictionaries that appear within the requested frame_name
Return type:list
hashes_to_alignment

The SHA1 hash of the face mapped to the alignment for the face that the hash corresponds to. The structure of the dictionary is:

Notes

This method is depractated and exists purely for updating legacy hash based alignments to new png header storage in lib.align.update_legacy_png_header.

The first time this property is referenced, the dictionary will be created and cached. Subsequent references will be made to this cached dictionary.

Type:dict
hashes_to_frame

The SHA1 hash of the face mapped to the frame(s) and face index within the frame that the hash corresponds to. The structure of the dictionary is:

{SHA1_hash (str): {filename (str): face_index (int)}}.

Notes

This method is depractated and exists purely for updating legacy hash based alignments to new png header storage in lib.align.update_legacy_png_header.

The first time this property is referenced, the dictionary will be created and cached. Subsequent references will be made to this cached dictionary.

Type:dict
have_alignments_file

True if an alignments file exists at location file otherwise False.

Type:bool
mask_is_valid(mask_type)

Ensure the given mask_type is valid for the alignments data.

Every face in the alignments data must have the given mask type to successfully pass the test.

Parameters:mask_type (str) – The mask type to check against the current alignments data
Returns:True if all faces in the current alignments possess the given mask_type otherwise False
Return type:bool
mask_summary

The mask type names stored in the alignments data as key with the number of faces which possess the mask type as value.

Type:dict
save()

Write the contents of data and _meta to a serialized .fsa file at the location file.

save_video_meta_data(pts_time, keyframes)

Save video meta data to the alignments file.

If the alignments file does not have an entry for every frame (e.g. if Extract Every N was used) then the frame is added to the alignments file with no faces, so that they video meta data can be stored.

Parameters:
  • pts_time (list) – A list of presentation timestamps (float) in frame index order for every frame in the input video
  • keyframes (list) – A list of frame indices corresponding to the key frames in the input video
thumbnails

The low resolution thumbnail images that exist within the alignments file

Type:Thumbnails
update_face(frame_name, face_index, face)

Update the face for the given frame_name at the given face index in data.

Parameters:
  • frame_name (str) – The frame name to update the face for. This should be the base name of the frame, not the full path
  • face_index (int) – The index number of the face within the given frame_name to update
  • face (dict) – The face information to update to the given frame_name at the given face_index, correctly formatted for storing in data
version

The alignments file version number.

Type:float
video_meta_data

The frame meta data stored in the alignments file. If data does not exist in the alignments file then None is returned for each Key

Type:dict
yield_faces()

Generator to obtain all faces with meta information from data. The results are yielded by frame.

Notes

The yielded order is non-deterministic.

Yields:
  • frame_name (str) – The frame name that the face belongs to. This is the base name of the frame, as it appears in data, not the full path
  • faces (list) – The list of face dict objects that exist for this frame
  • face_count (int) – The number of faces that exist within data for this frame
  • frame_fullname (str) – The full path (folder and filename) for the yielded frame
class lib.align.alignments.Thumbnails(alignments)

Bases: object

Thumbnail images stored in the alignments file.

The thumbnails are stored as low resolution (64px), low quality jpg in the alignments file and are used for the Manual Alignments tool.

Parameters:alignments (:class:'~lib.align.Alignments`) – The parent alignments class that these thumbs belong to
add_thumbnail(frame, face_index, thumb)

Add a thumbnail for the given face index for the given frame.

Parameters:
  • frame (str) – The name of the frame to add the thumbnail for
  • face_index (int) – The face index within the given frame to add the thumbnail for
  • thumb (numpy.ndarray) – The encoded jpg thumbnail at 64px to add to the alignments file
get_thumbnail_by_index(frame_index, face_index)

Obtain a jpg thumbnail from the given frame index for the given face index

Parameters:
  • frame_index (int) – The frame index that contains the thumbnail
  • face_index (int) – The face index within the frame to retrieve the thumbnail for
Returns:

The encoded jpg thumbnail

Return type:

numpy.ndarray

has_thumbnails

True if all faces in the alignments file contain thumbnail images otherwise False.

Type:bool

detected_face module

Handles detected face objects and their associated masks.

Module Summary

BlurMask Factory class to return the correct blur object for requested blur type.
DetectedFace Detected face and landmark information
Mask Face Mask information and convenience methods
update_legacy_png_header Update a legacy extracted face from pre v2.1 alignments by placing the alignment data for the face in the png exif header for the given filename with the given alignment data.

Module

Face and landmarks detection for faceswap.py

class lib.align.detected_face.BlurMask(blur_type, mask, kernel, is_ratio=False, passes=1)

Bases: object

Factory class to return the correct blur object for requested blur type.

Works for square images only. Currently supports Gaussian and Normalized Box Filters.

Parameters:
  • blur_type (["gaussian", "normalized"]) – The type of blur to use
  • mask (numpy.ndarray) – The mask to apply the blur to
  • kernel (int or float) – Either the kernel size (in pixels) or the size of the kernel as a ratio of mask size
  • is_ratio (bool, optional) – Whether the given kernel parameter is a ratio or not. If True then the actual kernel size will be calculated from the given ratio and the mask size. If False then the kernel size will be set directly from the kernel parameter. Default: False
  • passes (int, optional) – The number of passes to perform when blurring. Default: 1

Example

>>> print(mask.shape)
(128, 128, 1)
>>> new_mask = BlurMask("gaussian", mask, 3, is_ratio=False, passes=1).blurred
>>> print(new_mask.shape)
(128, 128, 1)
blurred

The final mask with blurring applied.

Type:numpy.ndarray
class lib.align.detected_face.DetectedFace(image=None, x=None, w=None, y=None, h=None, landmarks_xy=None, mask=None, filename=None)

Bases: object

Detected face and landmark information

Holds information about a detected face, it’s location in a source image and the face’s 68 point landmarks.

Methods for aligning a face are also callable from here.

Parameters:
  • image (numpy.ndarray, optional) – Original frame that holds this face. Optional (not required if just storing coordinates)
  • x (int) – The left most point (in pixels) of the face’s bounding box as discovered in plugins.extract.detect
  • w (int) – The width (in pixels) of the face’s bounding box as discovered in plugins.extract.detect
  • y (int) – The top most point (in pixels) of the face’s bounding box as discovered in plugins.extract.detect
  • h (int) – The height (in pixels) of the face’s bounding box as discovered in plugins.extract.detect
  • landmarks_xy (list) – The 68 point landmarks as discovered in plugins.extract.align. Should be a list of 68 (x, y) tuples with each of the landmark co-ordinates.
  • mask (dict) – The generated mask(s) for the face as generated in plugins.extract.mask. Must be a dict of {name (str): Mask}.
image

This is a generic image placeholder that should not be relied on to be holding a particular image. It may hold the source frame that holds the face, a cropped face or a scaled image depending on the method using this object.

Type:numpy.ndarray, optional
x

The left most point (in pixels) of the face’s bounding box as discovered in plugins.extract.detect

Type:int
w

The width (in pixels) of the face’s bounding box as discovered in plugins.extract.detect

Type:int
y

The top most point (in pixels) of the face’s bounding box as discovered in plugins.extract.detect

Type:int
h

The height (in pixels) of the face’s bounding box as discovered in plugins.extract.detect

Type:int
landmarks_xy

The 68 point landmarks as discovered in plugins.extract.align.

Type:list
mask

The generated mask(s) for the face as generated in plugins.extract.mask. Is a dict of {name (str): Mask}.

Type:dict
add_mask(name, mask, affine_matrix, interpolator, storage_size=128, storage_centering='face')

Add a Mask to this detected face

The mask should be the original output from plugins.extract.mask If a mask with this name already exists it will be overwritten by the given mask.

Parameters:
  • name (str) – The name of the mask as defined by the plugins.extract.mask._base.name parameter.
  • mask (numpy.ndarray) – The mask that is to be added as output from plugins.extract.mask It should be in the range 0.0 - 1.0 ideally with a dtype of float32
  • affine_matrix (numpy.ndarray) – The transformation matrix required to transform the mask to the original frame.
  • int (interpolator,) – The CV2 interpolator required to transform this mask to it’s original frame.
  • int (optional) (storage_size,) – The size the mask is to be stored at. Default: 128
  • str (optional) (storage_centering,) – The centering to store the mask at. One of “legacy”, “face”, “head”. Default: “face”
bottom

Bottom point (in pixels) of face detection bounding box within the parent image

Type:int
from_alignment(alignment, image=None, with_thumb=False)

Set the attributes of this class from an alignments file and optionally load the face into the image attribute.

Parameters:
  • alignment (dict) – A dictionary entry for a face from an alignments file containing the keys x, w, y, h, landmarks_xy. Optionally the key thumb will be provided. This is for use in the manual tool and contains the compressed jpg thumbnail of the face to be allocated to thumbnail. Optionally the key ``mask` will be provided, but legacy alignments will not have this key.
  • image (numpy.ndarray, optional) – If an image is passed in, then the image attribute will be set to the cropped face based on the passed in bounding box co-ordinates
  • with_thumb (bool, optional) – Whether to load the jpg thumbnail into the detected face object, if provided. Default: False
from_png_meta(alignment)

Set the attributes of this class from alignments stored in a png exif header.

Parameters:alignment (dict) – A dictionary entry for a face from alignments stored in a png exif header containing the keys x, w, y, h, landmarks_xy and mask
get_landmark_mask(size, area, aligned=True, centering='face', dilation=0, blur_kernel=0, as_zip=False)

Obtain a single channel mask based on the face’s landmark points.

Parameters:
  • size (int or tuple) – The size of the aligned mask to retrieve. Should be an int if an aligned face is being requested, or a (‘height’, ‘width’) shape tuple if a full frame is being requested
  • area (["mouth", "eyes"]) – The type of mask to obtain. face is a full face mask the others are masks for those specific areas
  • aligned (bool, optional) – True if the returned mask should be for an aligned face. False if a full frame mask should be returned. Default True
  • centering (["legacy", "face", "head"], optional) – Only used if aligned`=``True`. The centering for the landmarks based mask. Should be the same as the centering used for the extracted face that this mask will be applied to. “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”
  • dilation (int, optional) – The amount of dilation to apply to the mask. 0 for none. Default: 0
  • blur_kernel (int, optional) – The kernel size for applying gaussian blur to apply to the mask. 0 for none. Default: 0
  • as_zip (bool, optional) – True if the mask should be returned zipped otherwise False
Returns:

The mask as a single channel image of the given size dimension. If as_zip is True then the numpy.ndarray will be contained within a zipped container

Return type:

numpy.ndarray or zipped array

left

Left point (in pixels) of face detection bounding box within the parent image

Type:int
load_aligned(image, size=256, dtype=None, centering='head', force=False)

Align a face from a given image.

Aligning a face is a relatively expensive task and is not required for all uses of the DetectedFace object, so call this function explicitly to load an aligned face.

This method plugs into lib.align.AlignedFace to perform face alignment based on this face’s landmarks_xy. If the face has already been aligned, then this function will return having performed no action.

Parameters:
  • image (numpy.ndarray) – The image that contains the face to be aligned
  • size (int) – The size of the output face in pixels
  • dtype (str, optional) – Optionally set a dtype for the final face to be formatted in. Default: None
  • centering (["legacy", "face", "head"], optional) – 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: “head”
  • force (bool, optional) – Force an update of the aligned face, even if it is already loaded. Default: False

Notes

This method must be executed to get access to the following an AlignedFace object

right

Right point (in pixels) of face detection bounding box within the parent image

Type:int
to_alignment()

Return the detected face formatted for an alignments file

Returns:alignment – The alignment dict will be returned with the keys x, w, y, h, landmarks_xy, mask. The additional key thumb will be provided if the detected face object contains a thumbnail.
Return type:dict
to_png_meta()

Return the detected face formatted for insertion into a png itxt header.

returns: dict
The alignments dict will be returned with the keys x, w, y, h, landmarks_xy and mask
top

Top point (in pixels) of face detection bounding box within the parent image

Type:int
class lib.align.detected_face.Mask(storage_size=128, storage_centering='face')

Bases: object

Face Mask information and convenience methods

Holds a Faceswap mask as generated from plugins.extract.mask and the information required to transform it to its original frame.

Holds convenience methods to handle the warping, storing and retrieval of the mask.

Parameters:
  • storage_size (int, optional) – The size (in pixels) that the mask should be stored at. Default: 128.
  • str (optional) (storage_centering,) – The centering to store the mask at. One of “legacy”, “face”, “head”. Default: “face”
stored_size

The size, in pixels, of the stored mask across its height and width.

Type:int
stored_centering

The centering that the mask is stored at. One of “legacy”, “face”, “head”

Type:str
add(mask, affine_matrix, interpolator)

Add a Faceswap mask to this Mask.

The mask should be the original output from plugins.extract.mask

Parameters:
  • mask (numpy.ndarray) – The mask that is to be added as output from plugins.extract.mask It should be in the range 0.0 - 1.0 ideally with a dtype of float32
  • affine_matrix (numpy.ndarray) – The transformation matrix required to transform the mask to the original frame.
  • int (interpolator,) – The CV2 interpolator required to transform this mask to it’s original frame
affine_matrix

numpy.ndarray: The affine matrix to transpose the mask to a full frame.

Type:class
from_dict(mask_dict)

Populates the Mask from a dictionary loaded from an alignments file.

Parameters:mask_dict (dict) – A dictionary stored in an alignments file containing the keys mask, affine_matrix, interpolator, stored_size, stored_centering
get_full_frame_mask(width, height)

Return the stored mask in a full size frame of the given dimensions

Parameters:
  • width (int) – The width of the original frame that the mask was extracted from
  • height (int) – The height of the original frame that the mask was extracted from
Returns:

numpy.ndarray

Return type:

The mask affined to the original full frame of the given dimensions

interpolator

The cv2 interpolator required to transpose the mask to a full frame.

Type:int
mask

The mask at the size of stored_size with any requested blurring, threshold amount and centering applied.

Type:numpy.ndarray
original_roi

numpy.ndarray: The original region of interest of the mask in the source frame.

Type:class
replace_mask(mask)

Replace the existing _mask with the given mask.

Parameters:mask (numpy.ndarray) – The mask that is to be added as output from plugins.extract.mask. It should be in the range 0.0 - 1.0 ideally with a dtype of float32
set_blur_and_threshold(blur_kernel=0, blur_type='gaussian', blur_passes=1, threshold=0)

Set the internal blur kernel and threshold amount for returned masks

Parameters:
  • blur_kernel (int, optional) – 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 (["gaussian", "normalized"], optional) – The blur type to use. gaussian or normalized box filter. Default: gaussian
  • blur_passes (int, optional) – The number of passed to perform when blurring. Default: 1
  • threshold (int, optional) – The threshold amount to minimize/maximize mask values to 0 and 100. Percentage value. Default: 0
set_sub_crop(offset, centering)

Set the internal crop area of the mask to be returned.

This impacts the returned mask from mask if the requested mask is required for different face centering than what has been stored.

Parameters:
  • offset (numpy.ndarray) – The (x, y) offset from the center point to return the mask for
  • centering (str) – The centering to set the sub crop area for. One of “legacy”, “face”. “head”
stored_mask

The mask at the size of stored_size as it is stored (i.e. with no blurring/centering applied).

Type:numpy.ndarray
to_dict()

Convert the mask to a dictionary for saving to an alignments file

Returns:The Mask for saving to an alignments file. Contains the keys mask, affine_matrix, interpolator, stored_size, stored_centering
Return type:dict
to_png_meta()

Convert the mask to a dictionary supported by png itxt headers.

Returns:The Mask for saving to an alignments file. Contains the keys mask, affine_matrix, interpolator, stored_size, stored_centering
Return type:dict
lib.align.detected_face.update_legacy_png_header(filename, alignments)

Update a legacy extracted face from pre v2.1 alignments by placing the alignment data for the face in the png exif header for the given filename with the given alignment data.

If the given file is not a .png then a png is created and the original file is removed

Parameters:
  • filename (str) – The image file to update
  • alignments (lib.align.alignments.Alignments) – The alignments data the contains the information to store in the image header. This must be a v2.0 or less alignments file as later versions no longer store the face hash (not required)
Returns:

The metadata that has been applied to the given image

Return type:

dict