sort package

tools.sort.cli Module

Command Line Arguments for tools

class tools.sort.cli.SortArgs(subparser: _SubParsersAction | None, command: str, description: str = 'default')

Class to parse the command line arguments for sort tool

Parameters:

• subparser (_SubParsersAction | None)

• command (str)

• description (str)

static get_argument_list()

Put the arguments in a list so that they are accessible from both argparse and gui

static get_info()

Return command information

Classes

SortArgs(subparser, command[, description])

Class to parse the command line arguments for sort tool

Class Inheritance Diagram

tools.sort.info_loader Module

Loads images with metadata from disk for the sort tool

class tools.sort.info_loader.InfoLoader(input_dir: str, info_type: Literal['face', 'meta', 'all'])

Loads aligned faces and/or face metadata

Parameters:

• input_dir (str) – Full path to containing folder of faces to be supported

• loader_type – Dictates the type of iterator that will be used. “face” just loads the image with the filename, “meta” just loads the image alignment data with the filename. “all” loads the image and the alignment data with the filename

• info_type (T.Literal['face', 'meta', 'all'])

__call__() → ImgMetaType

Return the selected iterator

The resulting generator:

Yields:

• filename – The filename that has been read

• image – The aligned face image loaded from disk for ‘face’ and ‘all’ info_types otherwise None

• alignments – The alignments dict for ‘all’ and ‘meta’ info_types otherwise None

Return type:

ImgMetaType

cached_source_data: dict[str, PNGSource]

The source data read from the PNG header for each processed face

property filelist_count: int

The number of files to be processed

update_png_header(filename: str, alignments: PNGAlignments) → None

Update the PNG header of the given file with the given alignments.

NB: Header information can only be updated if the face is already on at least alignment version 2.2. If below this version, then the header is not updated

Parameters:

• filename (str) – Full path to the PNG file to update

• alignments (dict) – The alignments to update into the PNG header

Return type:

None

Classes

InfoLoader(input_dir, info_type)

Loads aligned faces and/or face metadata

Class Inheritance Diagram

tools.sort.sort Module

A tool that allows for sorting and grouping images in different ways.

class tools.sort.sort.Sort(arguments: Namespace)

Sorts folders of faces based on input criteria

Wrapper for the sort process to run in either batch mode or single use mode

Parameters:

arguments (Namespace) – The arguments to be passed to the extraction process as generated from Faceswap’s command line arguments

process() → None

The entry point for triggering the Sort Process.

Should only be called from lib.cli.launcher.ScriptExecutor

Return type:

None

Classes

Sort(arguments)

Sorts folders of faces based on input criteria

tools.sort.sort_methods Module

Sorting methods for the sorting tool.

All sorting methods inherit from SortMethod and control functions for sorting one item, sorting a full list of scores and binning based on those sorted scores.

class tools.sort.sort_methods.SortBlur(arguments: Namespace, is_group: bool = False)

Sort images by blur or blur-fft amount

Parameters:

• arguments (Namespace) – The command line arguments passed to the sort process

• is_group (bool) – Set to True if this class is going to be called exclusively for binning. Default: False

binning() → list[list[str]]

Create bins to split linearly from the lowest to the highest sample value

Return type:

List of bins of filenames

estimate_blur(image: ndarray, alignments=None) → float

Estimate the amount of blur an image has with the variance of the Laplacian. Normalize by pixel number to offset the effect of image size on pixel gradients & variance.

Parameters:

• image (ndarray) – The face image to calculate blur for

• alignments – The metadata for the face image or None if no metadata is available. If metadata is provided the face will be masked by the “components” mask prior to calculating blur. Default:None

Return type:

The estimated blur score for the face

estimate_blur_fft(image: np.ndarray, alignments: PNGAlignments | None = None) → float

Estimate the amount of blur a fft filtered image has.

Parameters:

• image (np.ndarray) – Use Fourier Transform to analyze the frequency characteristics of the masked face using 2D Discrete Fourier Transform (DFT) filter to find the frequency domain. A mean value is assigned to the magnitude spectrum and returns a blur score. Adapted from https://www.pyimagesearch.com/2020/06/15/ opencv-fast-fourier-transform-fft-for-blur-detection-in-images-and-video-streams/

• alignments (PNGAlignments | None) – The metadata for the face image or None if no metadata is available. If metadata is provided the face will be masked by the “components” mask prior to calculating blur. Default:None

Return type:

The estimated fft blur score for the face

score_image(filename: str, image: np.ndarray | None, alignments: PNGAlignments | None) → None

Score a single image for blur or blur-fft and add the result to _result

Parameters:

• filename (str) – The filename of the currently processing image

• image (np.ndarray | None) – A face image loaded from disk

• alignments (PNGAlignments | None) – The alignments dictionary for the aligned face or None

Return type:

None

sort() → None

Sort by metric score. Order in reverse for distance sort.

Return type:

None

class tools.sort.sort_methods.SortColor(arguments: Namespace, is_group: bool = False)

Score by channel average intensity or black pixels.

Parameters:

• arguments (Namespace) – The command line arguments passed to the sort process

• is_group (bool) – Set to True if this class is going to be called exclusively for binning. Default: False

binning() → list[list[str]]

Group into bins by percentage of black pixels

Return type:

list[list[str]]

score_image(filename: str, image: np.ndarray | None, alignments: PNGAlignments | None) → None

Score a single image for color

Parameters:

• filename (str) – The filename of the currently processing image

• image (np.ndarray | None) – A face image loaded from disk

• alignments (PNGAlignments | None) – The alignments dictionary for the aligned face or None

Return type:

None

sort() → None

Sort by metric score. Order in reverse for distance sort.

Return type:

None

class tools.sort.sort_methods.SortFace(arguments: Namespace, is_group: bool = False)

Sort by identity similarity using an Identity plugin

Parameters:

• arguments (Namespace) – The command line arguments passed to the sort process

• is_group (bool) – Set to True if this class is going to be called exclusively for binning. Default: False

binning() → list[list[str]]

Group into bins by their sorted score

The bin ID has been output in the 2nd column of _result so use that for binning

Return type:

List of bins of filenames

score_image(filename: str, image: np.ndarray | None, alignments: PNGAlignments | None) → None

Score a single image for sort method and add the result to _result. Attempts to pull identity information from the PNG metadata. If not available, pulls the information from the Identity plugin and stores in the PNG header for future use

Parameters:

• filename (str) – The filename of the currently processing image

• image (np.ndarray | None) – A face image loaded from disk or None

• alignments (PNGAlignments | None) – The alignments dictionary for the aligned face or None

Return type:

None

sort() → None

Sort by dendrogram.

Parameters:

matched_list – The list of tuples with filename in first position and face encoding in the 2nd

Return type:

The original list, sorted for this metric

class tools.sort.sort_methods.SortHistogram(arguments: Namespace, is_group: bool = False)

Sort by image histogram similarity or dissimilarity

Parameters:

• arguments (Namespace) – The command line arguments passed to the sort process

• is_group (bool) – Set to True if this class is going to be called exclusively for binning. Default: False

binning() → list[list[str]]

Group into bins by histogram

Return type:

list[list[str]]

score_image(filename: str, image: np.ndarray | None, alignments: PNGAlignments | None) → None

Collect the histogram for the given face

Parameters:

• filename (str) – The filename of the currently processing image

• image (np.ndarray | None) – A face image loaded from disk

• alignments (PNGAlignments | None) – The alignments dictionary for the aligned face or None

Return type:

None

sort() → None

Sort by histogram.

Return type:

None

class tools.sort.sort_methods.SortMethod(arguments: Namespace, loader_type: T.Literal['face', 'meta', 'all'] = 'meta', is_group: bool = False)

Parent class for sort methods. All sort methods should inherit from this class

Parameters:

• arguments (Namespace) – The command line arguments passed to the sort process

• loader_type (T.Literal['face', 'meta', 'all']) – The type of image loader to use. “face” just loads the image with the filename, “meta” just loads the image alignment data with the filename. “all” loads the image and the alignment data with the filename

• is_group (bool) – Set to True if this class is going to be called exclusively for binning. Default: False

property bin_names: list[str]

The name of each created bin, if they exist, otherwise an empty list

property binned: list[list[str]]

List of bins (list) containing the filenames belonging to the bin. The binning process is called when this property is first accessed

binning() → list[list[str]]

Group into bins by their sorted score. Override for method specific binning techniques.

Binning takes the results from _result compiled during _sort_filelist() and organizes into bins for output.

Returns:

List of bins of filenames

Return type:

list

property loader_type: Literal['face', 'meta', 'all']

The loader that this sorter uses

Type:

[“face”, “meta”, “all”]

score_image(filename: str, image: np.ndarray | None, alignments: PNGAlignments | None) → None

Override for sort method’s specific logic. This method should be executed to get a single score from a single image and add the result to _result

Parameters:

• filename (str) – The filename of the currently processing image

• image (np.ndarray | None) – A face image loaded from disk or None

• alignments (PNGAlignments | None) – The alignments dictionary for the aligned face or None

Return type:

None

sort() → None

Override for method specific logic for sorting the loaded statistics.

The scored list _result should be sorted in place

Return type:

None

property sorted_filelist: list[str]

List of sorted filenames for given sorter in a single list. The sort process is called when this property is first accessed

class tools.sort.sort_methods.SortMultiMethod(arguments: Namespace, sort_method: SortMethod, group_method: SortMethod)

A Parent sort method that runs 2 different underlying methods (one for sorting one for binning) in instances where grouping has been requested, but the sort method is different from the group method

Parameters:

• arguments (Namespace) – The command line arguments passed to the sort process

• sort_method (SortMethod) – A sort method object for sorting the images

• group_method (SortMethod) – A sort method object used for sorting and binning the images

binning() → list[list[str]]

Override standard binning, to bin by the group-by method and sort by the sorting method.

Go through the grouped binned results, and reorder each bin contents based on the sorted list

Return type:

List of bins of filenames

score_image(filename: str, image: np.ndarray | None, alignments: PNGAlignments | None) → None

Score a single image for sort method and add the result to _result

Parameters:

• filename (str) – The filename of the currently processing image

• image (np.ndarray | None) – A face image loaded from disk or None

• alignments (PNGAlignments | None) – The alignments dictionary for the aligned face or None

Return type:

None

sort() → None

Sort the sorter and grouper methods

Return type:

None

Classes

SortBlur(arguments[, is_group])	Sort images by blur or blur-fft amount
SortColor(arguments[, is_group])	Score by channel average intensity or black pixels.
SortFace(arguments[, is_group])	Sort by identity similarity using an Identity plugin
SortHistogram(arguments[, is_group])	Sort by image histogram similarity or dissimilarity
SortMethod(arguments[, loader_type, is_group])	Parent class for sort methods.
SortMultiMethod(arguments, sort_method, ...)	A Parent sort method that runs 2 different underlying methods (one for sorting one for binning) in instances where grouping has been requested, but the sort method is different from the group method

Class Inheritance Diagram

tools.sort.sort_methods_aligned Module

Sorting methods that use the properties of a lib.align.AlignedFace object to obtain their sorting metrics.

class tools.sort.sort_methods_aligned.SortAlignedMetric(arguments: Namespace, loader_type: T.Literal['face', 'meta', 'all'] = 'meta', is_group: bool = False)

Sort by comparison of metrics stored in an Aligned Face objects. This is a parent class for sort by aligned metrics methods. Individual methods should inherit from this class

Parameters:

• arguments (argparse.Namespace) – The command line arguments passed to the sort process

• sort_reverse (bool, optional) – True if the sorted results should be in reverse order. Default: True

• is_group (bool, optional) – Set to True if this class is going to be called exclusively for binning. Default: False

• loader_type (T.Literal['face', 'meta', 'all'])

score_image(filename: str, image: np.ndarray | None, alignments: PNGAlignments | None) → None

Score a single image for sort method: “distance”, “yaw”, “pitch” or “size” and add the result to _result

Parameters:

• filename (str) – The filename of the currently processing image

• image (np.ndarray or None) – A face image loaded from disk or None

• alignments (dict or None) – The alignments dictionary for the aligned face or None

Return type:

None

sort() → None

Sort by metric score. Order in reverse for distance sort.

Return type:

None

class tools.sort.sort_methods_aligned.SortDistance(arguments: Namespace, loader_type: T.Literal['face', 'meta', 'all'] = 'meta', is_group: bool = False)

Sorting mechanism for sorting faces from small to large

Parameters:

• arguments (Namespace)

• loader_type (T.Literal['face', 'meta', 'all'])

• is_group (bool)

binning() → list[list[str]]

Create bins to split linearly from the lowest to the highest sample value

Returns:

List of bins of filenames

Return type:

list

sort() → None

Override default sort to sort in ascending order.

Return type:

None

class tools.sort.sort_methods_aligned.SortFaceCNN(arguments: Namespace, is_group: bool = False)

Sort by landmark similarity or dissimilarity

Parameters:

• arguments (argparse.Namespace) – The command line arguments passed to the sort process

• is_group (bool, optional) – Set to True if this class is going to be called exclusively for binning. Default: False

binning() → list[list[str]]

Group into bins by CNN face similarity

Returns:

List of bins of filenames

Return type:

list

sort() → None

Sort by landmarks.

Return type:

None

class tools.sort.sort_methods_aligned.SortPitch(arguments: Namespace, loader_type: T.Literal['face', 'meta', 'all'] = 'meta', is_group: bool = False)

Sorting mechanism for sorting a face by pitch (down to up)

Parameters:

• arguments (Namespace)

• loader_type (T.Literal['face', 'meta', 'all'])

• is_group (bool)

binning() → list[list[str]]

Create bins from 0 degrees to 180 degrees based on number of bins

Allocate item to bin when it is in range of one of the pre-allocated bins

Returns:

List of bins of filenames

Return type:

list

class tools.sort.sort_methods_aligned.SortRoll(arguments: Namespace, loader_type: T.Literal['face', 'meta', 'all'] = 'meta', is_group: bool = False)

Sorting mechanism for sorting a face by roll (rotation). Same logic as sort pitch, but with different metric

Parameters:

• arguments (Namespace)

• loader_type (T.Literal['face', 'meta', 'all'])

• is_group (bool)

class tools.sort.sort_methods_aligned.SortSize(arguments: Namespace, loader_type: T.Literal['face', 'meta', 'all'] = 'meta', is_group: bool = False)

Sorting mechanism for sorting faces from small to large

Parameters:

• arguments (Namespace)

• loader_type (T.Literal['face', 'meta', 'all'])

• is_group (bool)

binning() → list[list[str]]

Create bins to split linearly from the lowest to the highest sample value

Allocate item to bin when it is in range of one of the pre-allocated bins

Returns:

List of bins of filenames

Return type:

list

class tools.sort.sort_methods_aligned.SortYaw(arguments: Namespace, loader_type: T.Literal['face', 'meta', 'all'] = 'meta', is_group: bool = False)

Sorting mechanism for sorting a face by yaw (left to right). Same logic as sort pitch, but with different metric

Parameters:

• arguments (Namespace)

• loader_type (T.Literal['face', 'meta', 'all'])

• is_group (bool)

Classes

SortAlignedMetric(arguments[, loader_type, ...])	Sort by comparison of metrics stored in an Aligned Face objects.
SortDistance(arguments[, loader_type, is_group])	Sorting mechanism for sorting faces from small to large
SortFaceCNN(arguments[, is_group])	Sort by landmark similarity or dissimilarity
SortPitch(arguments[, loader_type, is_group])	Sorting mechanism for sorting a face by pitch (down to up)
SortRoll(arguments[, loader_type, is_group])	Sorting mechanism for sorting a face by roll (rotation).
SortSize(arguments[, loader_type, is_group])	Sorting mechanism for sorting faces from small to large
SortYaw(arguments[, loader_type, is_group])	Sorting mechanism for sorting a face by yaw (left to right).

Class Inheritance Diagram