sort package

sort module

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

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

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

Bases: object

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 (argparse.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

sort_methods module

Sorting methods for the sorting tool.

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

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

Bases: object

Loads aligned faces and/or face metadata

Parameters:

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

  • loader_type (["face", "meta", "all"]) – 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

property filelist_count: int

The number of files to be processed

Type:

int

update_png_header(filename: str, alignments: PNGHeaderAlignmentsDict) → 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

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

Bases: SortMethod

Sort images by blur or blur-fft amount

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]]

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

Returns:

List of bins of filenames

Return type:

list

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 (numpy.ndarray) – The face image to calculate blur for

  • alignments (dict, optional) – 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

Returns:

The estimated blur score for the face

Return type:

float

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

Estimate the amount of blur a fft filtered image has.

Parameters:

  • image (numpy.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 (dict, optional) – 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

Returns:

The estimated fft blur score for the face

Return type:

float

score_image(filename: str, image: np.ndarray | None, alignments: PNGHeaderAlignmentsDict | 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) – A face image loaded from disk

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

sort() → None

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

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

Bases: SortMethod

Score by channel average intensity or black pixels.

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 percentage of black pixels

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

Score a single image for color

Parameters:

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

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

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

sort() → None

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

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

Bases: SortMethod

Sort by identity similarity using VGG Face 2

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 their sorted score

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

Returns:

List of bins of filenames

Return type:

list

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

Processing logic for sort by face method.

Reads header information from the PNG file to look for VGGFace2 embedding. If it does not exist, the embedding is obtained and added back into the PNG Header.

Parameters:

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

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

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

sort() → None

Sort by dendogram.

Parameters:

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

Returns:

The original list, sorted for this metric

Return type:

list

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

Bases: SortMethod

Sort by image histogram 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 histogram

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

Collect the histogram for the given face

Parameters:

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

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

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

sort() → None

Sort by histogram.

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

Bases: object

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

Parameters:

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

  • loader_type (["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, optional) – 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

Type:

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

Type:

list

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: PNGHeaderAlignmentsDict | None) → None

Override for sort method’s specificic 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 or None) – A face image loaded from disk or None

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

sort() → None

Override for method specific logic for sorting the loaded statistics

The scored list _result should be sorted in place

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

Type:

list

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

Bases: 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 (argparse.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

Returns:

List of bins of filenames

Return type:

list

score_image(filename: str, image: np.ndarray | None, alignments: PNGHeaderAlignmentsDict | 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

sort() → None

Sort the sorter and grouper methods

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)

Bases: SortMethod

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

score_image(filename: str, image: np.ndarray | None, alignments: PNGHeaderAlignmentsDict | 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

sort() → None

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

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

Bases: SortAlignedMetric

Sorting mechanism for sorting faces from small to large

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.

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

Bases: SortAlignedMetric

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.

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

Bases: SortAlignedMetric

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

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)

Bases: SortPitch

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

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

Bases: SortAlignedMetric

Sorting mechanism for sorting faces from small to large

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)

Bases: SortPitch

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