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
) – Theargparse
arguments as passed in fromtools.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 removedface_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
) – Theargparse
arguments as passed in fromtools.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 removedarguments (
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 jobarguments (
argparse.Namespace
) – Theargparse
arguments as passed in fromtools.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 annotatedarguments (
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 jobarguments (
argparse.Namespace
) – Theargparse
arguments as passed in fromtools.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 annotatedarguments (
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 fromtools.py
. Unused
- process() None
Parse the imported alignments file and output relevant information to a json file
- arguments:
- 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 jobarguments (
argparse.Namespace
) – Theargparse
arguments as passed in fromtools.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 jobarguments (
argparse.Namespace
) – Theargparse
arguments as passed in fromtools.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 fromalignments (
AlignmentData
) – The alignment data corresponding to the framessize (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, otherwiseNone
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. DefaultFalse
image (
numpy.ndarray
, optional) – Image to load faces from if it exists, otherwiseNone
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 fromlib.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