utils module

Utilities available across all scripts

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

Bases: object

A simple tool to help debug timings.

Parameters:

  • min (bool, Optional) – Display minimum time taken in summary stats. Default: True

  • mean (bool, Optional) – Display mean time taken in summary stats. Default: True

  • max (bool, Optional) – Display maximum time taken in summary stats. Default: True

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, optional) – 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

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, optional) – 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

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, optional) – The number of decimal places to display the summary elapsed times to. Default: 6

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

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

Bases: Exception

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)

Bases: object

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'
Type:

str or list[str]

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

Returns:

A list of the individual parts of the camelCase string.

Return type:

list[str]

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) → int

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

Parameters:

*args (int) – 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, optional) – Any additional information to display with the deprecation message. Default: 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

Returns:

The full path split into a separate item for each part

Return type:

list

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', 'directml', 'rocm']

Get the backend that Faceswap is currently configured to use.

Returns:

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

Return type:

str

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 or 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, optional) – 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 or None

Example

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

>>> get_folder('/tmp/myfolder', 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) – The file extension to search for. If not provided, all image file types will be searched for

Returns:

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

Return type:

list[str]

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_tf_version() → tuple[int, int]

Obtain the major. minor version of currently installed Tensorflow.

Returns:

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

Return type:

tuple[int, int]

Example

>>> from lib.utils import get_tf_version
>>> get_tf_version()
(2, 10)
lib.utils.handle_deprecated_cliopts(arguments: Namespace) → 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 (argpares.Namespace) – The passed in faceswap cli arguments

Returns:

The cli arguments with deprecated values mapped to the correct entry

Return type:

argpares.Namespace

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, optional) – True if this function is being called as the result of raised error. Default: False

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 (["cpu", "directml", "nvidia", "rocm", "apple_silicon"]) – The backend to set faceswap to

Example

>>> from lib.utils import set_backend
>>> set_backend("nvidia")
lib.utils.set_system_verbosity(log_level: str)

Set the verbosity level of tensorflow and suppresses future and deprecation warnings from any modules.

This function sets the TF_CPP_MIN_LOG_LEVEL environment variable to control the verbosity of TensorFlow output, as well as filters certain warning types to be ignored. The log level is determined based on the input string log_level.

Parameters:

log_level (str) – The requested Faceswap log level.

References

https://stackoverflow.com/questions/35911252/disable-tensorflow-debugging-information

Example

>>> from lib.utils import set_system_verbosity
>>> set_system_verbosity('warning')