alignments package

alignments module 

The Alignments Module is the main entry point into the Alignments Tool.

Tools for manipulating the alignments serialized file

class tools.alignments.alignments.Alignments(arguments: Namespace)

Bases: object

The main entry point for Faceswap’s Alignments Tool. This tool is part of the Faceswap Tools suite and should be called from the python tools.py alignments command.

The tool allows for manipulation, and working with Faceswap alignments files.

This parent class handles creating the individual job arguments when running in batch-mode or triggers the job when not running in batch mode

Parameters:: arguments (argparse.Namespace) – The argparse arguments as passed in from tools.py

process()

The entry point for the Alignments tool from lib.tools.alignments.cli.

Launches the selected alignments job.

jobs_faces module 

Tools for manipulating the alignments using extracted Faces as a source

class tools.alignments.jobs_faces.FaceToFile(alignments: AlignmentData, face_data: list[PNGHeaderDict])

Bases: object

Updates any optional/missing keys in the alignments file with any data that has been populated in a PNGHeader. Includes masks and identity fields.

Parameters:

alignments (tools.alignments.media.AlignmentsData) – The loaded alignments containing faces to be removed
face_data (list) – List of PNGHeaderDict objects

class tools.alignments.jobs_faces.FromFaces(alignments: None, arguments: Namespace)

Bases: object

Scan a folder of Faceswap Extracted Faces and re-create the associated alignments file(s)

Parameters:

alignments (NoneType) – Parameter included for standard job naming convention, but not used for this process.
arguments (argparse.Namespace) – The argparse arguments as passed in from tools.py

process() → None: Run the job to read faces from a folder to create alignments file(s).

class tools.alignments.jobs_faces.RemoveFaces(alignments: AlignmentData, arguments: Namespace)

Bases: object

Remove items from alignments file.

Parameters:

alignments (tools.alignments.media.AlignmentsData) – The loaded alignments containing faces to be removed
arguments (argparse.Namespace) – The command line arguments that have called this job

process() → None: Run the job to remove faces from an alignments file that do not exist within a faces folder.

class tools.alignments.jobs_faces.Rename(alignments: AlignmentData, arguments: Namespace | None, faces: Faces | None = None)

Bases: object

Rename faces in a folder to match their filename as stored in an alignments file.

Parameters:

alignments (tools.lib_alignments.media.AlignmentData) – The alignments data loaded from an alignments file for this rename job
arguments (argparse.Namespace) – The argparse arguments as passed in from tools.py
faces (tools.lib_alignments.media.Faces, Optional) – An optional faces object, if the rename task is being called by another job. Default: None

process() → None: Process the face renaming

jobs_frames module 

Tools for manipulating the alignments using Frames as a source

class tools.alignments.jobs_frames.Draw(alignments: AlignmentData, arguments: Namespace)

Bases: object

Draws annotations onto original frames and saves into a sub-folder next to the original frames.

Parameters:

alignments (tools.alignments.media.AlignmentsData) – The loaded alignments corresponding to the frames to be annotated
arguments (argparse.Namespace) – The command line arguments that have called this job

process() → None: Runs the process to draw face annotations onto original source frames.

class tools.alignments.jobs_frames.Extract(alignments: AlignmentData, arguments: Namespace)

Bases: object

Re-extract faces from source frames based on Alignment data

Parameters:

alignments (tools.lib_alignments.media.AlignmentData) – The alignments data loaded from an alignments file for this rename job
arguments (argparse.Namespace) – The argparse arguments as passed in from tools.py

process() → None: Run the re-extraction from Alignments file process

jobs module 

Tools for manipulating the alignments serialized file

class tools.alignments.jobs.Check(alignments: AlignmentData, arguments: Namespace)

Bases: object

Frames and faces checking tasks.

Parameters:

alignments (tools.alignments.media.AlignmentsData) – The loaded alignments corresponding to the frames to be annotated
arguments (argparse.Namespace) – The command line arguments that have called this job

output_file(output_message: str, items_discovered: int) → None

Save the output to a text file in the frames directory

Parameters:

output_message (str) – The message to write out to file
items_discovered (int) – The number of items which matched the criteria

process() → None: Process the frames check against the alignments file

class tools.alignments.jobs.Export(alignments: AlignmentData, arguments: Namespace)

Bases: object

Export alignments from a Faceswap .fsa file to a json formatted file.

Parameters

arguments: argparse.Namespace: The argparse arguments as passed in from tools.py. Unused

process() → None: Parse the imported alignments file and output relevant information to a json file

class tools.alignments.jobs.Sort(alignments: AlignmentData, arguments: Namespace)

Bases: object

Sort alignments’ index by the order they appear in an image in left to right order.

Parameters:

alignments (tools.lib_alignments.media.AlignmentData) – The alignments data loaded from an alignments file for this rename job
arguments (argparse.Namespace) – The argparse arguments as passed in from tools.py. Unused

process() → None: Execute the sort process

reindex_faces() → int: Re-Index the faces

class tools.alignments.jobs.Spatial(alignments: AlignmentData, arguments: Namespace)

Bases: object

Apply spatial temporal filtering to landmarks

Parameters:

alignments (tools.lib_alignments.media.AlignmentData) – The alignments data loaded from an alignments file for this rename job
arguments (argparse.Namespace) – The argparse arguments as passed in from tools.py
Reference –
--------- –
https (//www.kaggle.com/selfishgene/animating-and-smoothing-3d-facial-keypoints/notebook) –

process() → None: Perform spatial filtering

media module 

Media items (Alignments, Faces, Frames) for alignments tool

class tools.alignments.media.AlignmentData(alignments_file: str)

Bases: Alignments

Class to hold the alignment data

Parameters:: alignments_file (str) – Full path to an alignments file

static check_file_exists(alignments_file: str) → tuple[str, str]

Check if the alignments file exists, and returns a tuple of the folder and filename.

Parameters:

alignments_file (str) – Full path to an alignments file

Returns:

folder (str) – The full path to the folder containing the alignments file
filename (str) – The filename of the alignments file

save() → None: Backup copy of old alignments and save new alignments

class tools.alignments.media.ExtractedFaces(frames: Frames, alignments: AlignmentData, size: int = 512)

Bases: object

Holds the extracted faces and matrix for alignments

Parameters:

frames (Frames) – The frames object to extract faces from
alignments (AlignmentData) – The alignment data corresponding to the frames
size (int, optional) – The extract face size. Default: 512

extract_one_face(alignment: AlignmentFileDict, image: np.ndarray) → DetectedFace

Extract one face from image

Parameters:

alignment (dict) – The alignment for a single face
image (numpy.ndarray) – The image to extract the face from

Returns:

The detected face object for the given alignment with the aligned face loaded

Return type:

DetectedFace

get_faces(frame: str, image: np.ndarray | None = None) → None

Obtain faces and transformed landmarks for each face in a given frame with its alignments

Parameters:

frame (str) – The frame name to obtain faces for
image (numpy.ndarray, optional) – The image to extract the face from, if we already have it, otherwise None to load the image. Default: None

get_faces_in_frame(frame: str, update: bool = False, image: np.ndarray | None = None) → list[DetectedFace]

Return the faces for the selected frame

Parameters:

frame (str) – The frame name to get the faces for
update (bool, optional) – True if the faces should be refreshed regardless of current frame. False to not force a refresh. Default False
image (numpy.ndarray, optional) – Image to load faces from if it exists, otherwise None to load the image. Default: None

Returns:

List of DetectedFace objects for the frame, with the aligned face loaded

Return type:

list

get_roi_size_for_frame(frame: str) → list[int]

Return the size of the original extract box for the selected frame.

Parameters:: frame (str) – The frame to obtain the original sized bounding boxes for
Returns:: List of original pixel sizes of faces held within the frame
Return type:: list

class tools.alignments.media.Faces(folder: str, alignments: Alignments | None = None)

Bases: MediaLoader

Object to load Extracted Faces from a folder.

Parameters:

folder (str) – The folder to load faces from
alignments (lib.align.Alignments, optional) – The alignments object that contains the faces. This can be used for 2 purposes: - To update legacy hash based faces for <v2.1 alignments to png header based version. - When the remove-faces job is being run, when the process will only load faces that exist in the alignments file. Default: None

load_items() → dict[str, list[int]]

Load the face names into dictionary.

Returns:: The source filename as key with list of face indices for the frame as value
Return type:: dict

process_folder() → Generator[tuple[str, PNGHeaderDict], None, None]

Iterate through the faces folder pulling out various information for each face.

Yields:: dict – A dictionary for each face found containing the keys returned from lib.image.read_image_meta_batch

sorted_items() → list[tuple[str, PNGHeaderDict]]

Return the items sorted by the saved file name.

Returns:: List of dict objects for each face found, sorted by the face’s current filename
Return type:: list

class tools.alignments.media.Frames(folder: str, count: int | None = None)

Bases: MediaLoader

Object to hold the frames that are to be checked against

load_items() → dict[str, tuple[str, str]]

Load the frame info into dictionary

Returns:: Fullname as key, tuple of frame name and extension as value
Return type:: dict

process_folder() → Generator[dict[str, str], None, None]

Iterate through the frames folder pulling the base filename

Yields:: dict – The full framename, the filename and the file extension of the frame

process_frames() → Generator[dict[str, str], None, None]

Process exported Frames

Yields:: dict – The full framename, the filename and the file extension of the frame

process_video() → Generator[dict[str, str], None, None]

Dummy in frames for video

Yields:: dict – The full framename, the filename and the file extension of the frame

sorted_items() → list[dict[str, str]]

Return the items sorted by filename

Returns:: The sorted list of frame information
Return type:: list

class tools.alignments.media.MediaLoader(folder: str, count: int | None = None)

Bases: object

Class to load images.

Parameters:

folder (str) – The folder of images or video file to load images from
count (int or None, optional) – If the total frame count is known it can be passed in here which will skip analyzing a video file. If the count is not passed in, it will be calculated. Default: None

check_input_folder() → VideoCapture | None

Ensure that the frames or faces folder exists and is valid.: If frames folder contains a video file return imageio reader object

Returns:: Object for reading a video stream
Return type:: cv2.VideoCapture

property count: int

Number of faces or frames

Type:: int

property is_video: bool

Return whether source is a video or not

Type:: bool

load_image(filename: str) → np.ndarray

Load an image

Parameters:: filename (str) – The filename of the image to load
Returns:: The loaded image
Return type:: numpy.ndarray

load_items() → dict[str, list[int]] | dict[str, tuple[str, str]]: Override for specific item loading

load_video_frame(filename: str) → np.ndarray

Load a requested frame from video

Parameters:: filename (str) – The frame name to load
Returns:: The loaded image
Return type:: numpy.ndarray

process_folder() → Generator[dict[str, str], None, None] | Generator[tuple[str, PNGHeaderDict], None, None]: Override for specific folder processing

static save_image(output_folder: str, filename: str, image: np.ndarray, metadata: PNGHeaderDict | None = None) → None: Save an image

sorted_items() → list[dict[str, str]] | list[tuple[str, PNGHeaderDict]]: Override for specific folder processing

stream(skip_list: list[int] | None = None) → Generator[tuple[str, np.ndarray], None, None]

Load the images in folder in the order they are received from lib.image.ImagesLoader in a background thread.

Parameters:

skip_list (list, optional) – A list of frame indices that should not be loaded. Pass None if all images should be loaded. Default: None

Yields:

str – The filename of the image that is being returned
numpy.ndarray – The image that has been loaded from disk

static valid_extension(filename) → bool: bool: Check whether passed in file has a valid extension

alignments package

alignments module

jobs_faces module

jobs_frames module

jobs module

media module

alignments module 

jobs_faces module 

jobs_frames module 

jobs module 

media module 