lib.utils Module

Utilities available across all scripts

class lib.utils.DebugTimes(show_min: bool = True, show_mean: bool = True, show_max: bool = True)

A simple tool to help debug timings.

Parameters:

  • min – Display minimum time taken in summary stats. Default: True

  • mean – Display mean time taken in summary stats. Default: True

  • max – Display maximum time taken in summary stats. Default: True

  • show_min (bool)

  • show_mean (bool)

  • show_max (bool)

Example

>>> from lib.utils import DebugTimes
>>> debug_times = DebugTimes()
>>> debug_times.step_start("step 1")
>>> # do something here
>>> debug_times.step_end("step 1")
>>> debug_times.summary()
----------------------------------
Step             Count   Min
----------------------------------
step 1           1       0.000000
step_end(name: str, record: bool = True) → None

Stop the timer and record elapsed time for the given step name.

Parameters:

  • name (str) – The name of the step to end the timer for

  • record (bool) – True to record the step time, False to not record it. Used for when you have conditional code to time, but do not want to insert if/else statements in the code. Default: True

Return type:

None

Example

>>> from lib.util import DebugTimes
>>> debug_times = DebugTimes()
>>> debug_times.step_start("Example Step")
>>> # do something here
>>> debug_times.step_end("Example Step")
step_start(name: str, record: bool = True) → None

Start the timer for the given step name.

Parameters:

  • name (str) – The name of the step to start the timer for

  • record (bool) – True to record the step time, False to not record it. Used for when you have conditional code to time, but do not want to insert if/else statements in the code. Default: True

Return type:

None

Example

>>> from lib.util import DebugTimes
>>> debug_times = DebugTimes()
>>> debug_times.step_start("Example Step")
>>> # do something here
>>> debug_times.step_end("Example Step")
summary(decimal_places: int = 6, interval: int = 1) → None

Print a summary of step times.

Parameters:

  • decimal_places (int) – The number of decimal places to display the summary elapsed times to. Default: 6

  • interval (int) – How many times summary must be called before printing to console. Default: 1

Return type:

None

Example

>>> from lib.utils import DebugTimes
>>> debug = DebugTimes()
>>> debug.step_start("test")
>>> time.sleep(0.5)
>>> debug.step_end("test")
>>> debug.summary()
----------------------------------
Step             Count   Min
----------------------------------
test             1       0.500000
exception lib.utils.FaceswapError

Faceswap Error for handling specific errors with useful information.

Raises:

FaceswapError – on a captured error

Example

>>> from lib.utils import FaceswapError
>>> try:
...     # Some code that may raise an error
... except SomeError:
...     raise FaceswapError("There was an error while running the code")
FaceswapError: There was an error while running the code
class lib.utils.GetModel(model_filename: str | list[str], git_model_id: int)

Check for models in the cache path.

If available, return the path, if not available, get, unzip and install model

Parameters:

Notes

Models must have a certain naming convention: <model_name>_v<version_number>.<extension> (eg: s3fd_v1.pb).

Multiple models can exist within the model_filename. They should be passed as a list and follow the same naming convention as above. Any differences in filename should occur AFTER the version number: <model_name>_v<version_number><differentiating_information>.<extension> (eg: [“mtcnn_det_v1.1.py”, “mtcnn_det_v1.2.py”, “mtcnn_det_v1.3.py”], [“resnet_ssd_v1.caffemodel” ,”resnet_ssd_v1.prototext”]

Example

>>> from lib.utils import GetModel
>>> model_downloader = GetModel("s3fd_keras_v2.h5", 11)
property model_path: str | list[str]

The model path(s) in the cache folder.

Example

>>> from lib.utils import GetModel
>>> model_downloader = GetModel("s3fd_keras_v2.h5", 11)
>>> model_downloader.model_path
'/path/to/s3fd_keras_v2.h5'
lib.utils.camel_case_split(identifier: str) → list[str]

Split a camelCase string into a list of its individual parts

Parameters:

identifier (str) – The camelCase text to be split

Return type:

A list of the individual parts of the camelCase string.

References

https://stackoverflow.com/questions/29916065

Example

>>> from lib.utils import camel_case_split
>>> camel_case_split('camelCaseExample')
['camel', 'Case', 'Example']
lib.utils.convert_to_secs(*args: int | str) → int

Convert time in hours, minutes, and seconds to seconds.

Parameters:

*args (int | str) – 1, 2 or 3 ints. If 2 ints are supplied, then (minutes, seconds) is implied. If 3 ints are supplied then (hours, minutes, seconds) is implied.

Returns:

The given time converted to seconds

Return type:

int

Example

>>> from lib.utils import convert_to_secs
>>> convert_to_secs(1, 30, 0)
5400
>>> convert_to_secs(0, 15, 30)
930
>>> convert_to_secs(0, 0, 45)
45
lib.utils.deprecation_warning(function: str, additional_info: str | None = None) → None

Log a deprecation warning message.

This function logs a warning message to indicate that the specified function has been deprecated and will be removed in future. An optional additional message can also be included.

Parameters:

  • function (str) – The name of the function that will be deprecated.

  • additional_info (str | None) – Any additional information to display with the deprecation message. Default: None

Return type:

None

Example

>>> from lib.utils import deprecation_warning
>>> deprecation_warning('old_function', 'Use new_function instead.')
lib.utils.full_path_split(path: str) → list[str]

Split a file path into all of its parts.

Parameters:

path (str) – The full path to be split

Return type:

The full path split into a separate item for each part

Example

>>> from lib.utils import full_path_split
>>> full_path_split("/usr/local/bin/python")
['usr', 'local', 'bin', 'python']
>>> full_path_split("relative/path/to/file.txt")
['relative', 'path', 'to', 'file.txt']]
lib.utils.get_backend() → Literal['nvidia', 'cpu', 'apple_silicon', 'rocm']

Get the backend that Faceswap is currently configured to use.

Returns:

  • The backend configuration in use by Faceswap. One of [“cpu”, “nvidia”, “rocm”,

  • ”apple_silicon”]

Return type:

Literal[‘nvidia’, ‘cpu’, ‘apple_silicon’, ‘rocm’]

Example

>>> from lib.utils import get_backend
>>> get_backend()
'nvidia'
lib.utils.get_dpi() → float | None

Gets the DPI (dots per inch) of the display screen.

Returns:

  • The DPI of the display screen or ``None`` if the dpi couldn’t be obtained (ie (if the function)

  • is called on a headless system)

Return type:

float | None

Example

>>> from lib.utils import get_dpi
>>> get_dpi()
96.0
lib.utils.get_folder(path: str, make_folder: bool = True) → str

Return a path to a folder, creating it if it doesn’t exist

Parameters:

  • path (str) – The path to the folder to obtain

  • make_folder (bool) – True if the folder should be created if it does not already exist, False if the folder should not be created

Returns:

  • The path to the requested folder. If make_folder is set to False and the requested path

  • does not exist, then None is returned

Return type:

str

Example

>>> from lib.utils import get_folder
>>> get_folder('/tmp/my_folder')
'/tmp/my_folder'

>>> get_folder('/tmp/my_folder', make_folder=False)
''
lib.utils.get_image_paths(directory: str, extension: str | None = None) → list[str]

Gets the image paths from a given directory.

The function searches for files with the specified extension(s) in the given directory, and returns a list of their paths. If no extension is provided, the function will search for files with any of the following extensions: ‘.bmp’, ‘.jpeg’, ‘.jpg’, ‘.png’, ‘.tif’, ‘.tiff’

Parameters:

  • directory (str) – The directory to search in

  • extension (str | None) – The file extension to search for. If not provided, all image file types will be searched for

Return type:

The list of full paths to the images contained within the given folder

Example

>>> from lib.utils import get_image_paths
>>> get_image_paths('/path/to/directory')
['/path/to/directory/image1.jpg', '/path/to/directory/image2.png']
>>> get_image_paths('/path/to/directory', '.jpg')
['/path/to/directory/image1.jpg']
lib.utils.get_keras_version() → tuple[int, int]

Obtain the major. minor version of currently installed Keras.

Return type:

A tuple of the form (major, minor) representing the version of Keras that is installed

Example

>>> from lib.utils import get_torch_version
>>> get_torch_version()
(2, 2)
lib.utils.get_module_objects(module: str) → list[str]

Return a list of all public objects within the given module

Parameters:

module (str) – The module to parse for public objects

Return type:

A list of object names that exist within the given module

Example

>>> __all__ = get_module_objects(__name__)
["foo", "bar", "baz"]
lib.utils.get_torch_version() → tuple[int, int]

Obtain the major. minor version of currently installed PyTorch.

Return type:

A tuple of the form (major, minor) representing the version of PyTorch that is installed

Example

>>> from lib.utils import get_torch_version
>>> get_torch_version()
(2, 2)
lib.utils.handle_deprecated_cli_opts(arguments: Namespace, additional: dict[str, tuple[str | bool | T.Any, ...]] | None = None) → Namespace

Handle deprecated command line arguments and update to correct argument.

Deprecated cli opts will be provided in the following format: “depr_<option_key>_<deprecated_opt>_<new_opt>”

Parameters:

  • arguments (Namespace) – The passed in faceswap cli arguments

  • additional (dict[str, tuple[str | bool | T.Any, ...]] | None) – Additional information in format {deprecated_argument: (additional_text, should_update, [new_value])} where deprecated_argument is the command line argument, additional_text is any additional text to display, should_update is whether the deprecated argument should be replaced with the new argument and new_value is an optional value that can be passed in that the new argument should be set to. Default: None (no additional information)

Return type:

The cli arguments with deprecated values mapped to the correct entry

lib.utils.safe_shutdown(got_error: bool = False) → None

Safely shut down the system.

This function terminates the queue manager and exits the program in a clean and orderly manner. An optional boolean parameter can be used to indicate whether an error occurred during the program’s execution.

Parameters:

got_error (bool) – True if this function is being called as the result of raised error. Default: False

Return type:

None

Example

>>> from lib.utils import safe_shutdown
>>> safe_shutdown()
>>> safe_shutdown(True)
lib.utils.set_backend(backend: str) → None

Override the configured backend with the given backend.

Parameters:

backend (str) – The backend to set faceswap to

Return type:

None

Example

>>> from lib.utils import set_backend
>>> set_backend("nvidia")

Functions

camel_case_split(identifier)

Split a camelCase string into a list of its individual parts

convert_to_secs(*args)

Convert time in hours, minutes, and seconds to seconds.

deprecation_warning(function[, additional_info])

Log a deprecation warning message.

full_path_split(path)

Split a file path into all of its parts.

get_backend()

Get the backend that Faceswap is currently configured to use.

get_dpi()

Gets the DPI (dots per inch) of the display screen.

get_folder(path[, make_folder])

Return a path to a folder, creating it if it doesn't exist

get_image_paths(directory[, extension])

Gets the image paths from a given directory.

get_keras_version()

Obtain the major.

get_module_objects(module)

Return a list of all public objects within the given module

get_torch_version()

Obtain the major.

handle_deprecated_cli_opts(arguments[, ...])

Handle deprecated command line arguments and update to correct argument.

safe_shutdown([got_error])

Safely shut down the system.

set_backend(backend)

Override the configured backend with the given backend.

Classes

DebugTimes([show_min, show_mean, show_max])

A simple tool to help debug timings.

FaceswapError

Faceswap Error for handling specific errors with useful information.

GetModel(model_filename, git_model_id)

Check for models in the cache path.