dgenerate submodules

dgenerate.arguments module

Argument parsing for the dgenerate command line tool.

exception dgenerate.arguments.DgenerateHelpException

Bases: Exception

Raised by parse_args() and parse_known_args() when --help is encountered and help_raises=True

exception dgenerate.arguments.DgenerateUsageError

Bases: Exception

Raised by parse_args() and parse_known_args() on argument usage errors.

class dgenerate.arguments.DgenerateArguments

Bases: RenderLoopConfig

Represents dgenerates parsed command line arguments, can be used as a configuration object for dgenerate.renderloop.RenderLoop.

__init__()

adapter_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.ADAPTER_CACHE_MEMORY_CONSTRAINTS

cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.CACHE_MEMORY_CONSTRAINTS

controlnet_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.CONTROLNET_CACHE_MEMORY_CONSTRAINTS

guidance_scales: _types.Floats

List of floating point guidance scales, this corresponds to the --guidance-scales argument of the dgenerate command line tool.

image_encoder_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.IMAGE_ENCODER_CACHE_MEMORY_CONSTRAINTS

image_processor_cuda_memory_constraints: Sequence[str] | None = None

See: dgenerate.imageprocessors.IMAGE_PROCESSOR_CUDA_MEMORY_CONSTRAINTS

image_processor_memory_constraints: Sequence[str] | None = None

See: dgenerate.imageprocessors.IMAGE_PROCESSOR_MEMORY_CONSTRAINTS

inference_steps: _types.Integers

List of inference steps values, this corresponds to the --inference-steps argument of the dgenerate command line tool.

pipeline_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.PIPELINE_CACHE_MEMORY_CONSTRAINTS

plugin_module_paths: Sequence[str]

Plugin module paths --plugin-modules

prompts: _types.Prompts

List of prompt objects, this corresponds to the --prompts argument of the dgenerate command line tool.

seeds: _types.Integers

List of integer seeds, this corresponds to the --seeds argument of the dgenerate command line tool.

text_encoder_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.TEXT_ENCODER_CACHE_MEMORY_CONSTRAINTS

transformer_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.TRANSFORMER_CACHE_MEMORY_CONSTRAINTS

unet_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.UNET_CACHE_MEMORY_CONSTRAINTS

vae_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.VAE_CACHE_MEMORY_CONSTRAINTS

verbose: bool = False

Enable debug output? -v/--verbose

dgenerate.arguments.config_attribute_name_to_option(name)

Convert an attribute name of DgenerateArguments into its command line option name.

Parameters:

name – the attribute name

Returns:

the command line argument name as a string

dgenerate.arguments.is_valid_option(option: str)

Check if an option string is a valid option name in the parser.

Parameters:

option – The option name, short or long opt.

Returns:

True or False

dgenerate.arguments.parse_args(args: Sequence[str] | None = None, throw: bool = True, log_error: bool = True, help_raises: bool = False) → DgenerateArguments | None

Parse dgenerates command line arguments and return a configuration object.

Parameters:

• args – arguments list, as in args taken from sys.argv, or in that format

• throw – throw DgenerateUsageError on error? defaults to True

• log_error – Write ERROR diagnostics with dgenerate.messages?

• help_raises – --help raises dgenerate.arguments.DgenerateHelpException ? When True, this will occur even if throw=False

Raises:

• DgenerateUsageError –

• DgenerateHelpException –

Returns:

DgenerateArguments. If throw=False then None will be returned on errors.

dgenerate.arguments.parse_device(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[str | None, list[str]]

Retrieve the -d/--device argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Raises:

DgenerateUsageError – If no argument value was provided.

Returns:

(value | None, unknown_args_list)

dgenerate.arguments.parse_directives_help(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[list[str] | None, list[str]]

Retrieve the --directives-help argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Returns:

(values | None, unknown_args_list)

dgenerate.arguments.parse_functions_help(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[list[str] | None, list[str]]

Retrieve the --functions-help argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Returns:

(values | None, unknown_args_list)

dgenerate.arguments.parse_image_processor_help(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[list[str] | None, list[str]]

Retrieve the --image-processor-help argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Returns:

(values | None, unknown_args_list)

dgenerate.arguments.parse_known_args(args: Sequence[str] | None = None, throw: bool = True, log_error: bool = True, no_model: bool = True, no_help: bool = True, help_raises: bool = False) → tuple[DgenerateArguments, list[str]] | None

Parse only known arguments off the command line.

Ignores dgenerates only required argument model_path by default.

No logical validation is performed, DgenerateArguments.check() is not called by this function, only argument parsing and simple type validation is performed by this function.

Parameters:

• args – arguments list, as in args taken from sys.argv, or in that format

• throw – throw DgenerateUsageError on error? defaults to True

• log_error – Write ERROR diagnostics with dgenerate.messages?

• no_model – Remove the model_path argument from the parser.

• no_help – Remove the --help argument from the parser.

• help_raises – --help raises dgenerate.arguments.DgenerateHelpException ? When True, this will occur even if throw=False

Raises:

• DgenerateUsageError – on argument error (simple type validation only)

• DgenerateHelpException –

Returns:

(DgenerateArguments, unknown_args_list). If throw=False then None will be returned on errors.

dgenerate.arguments.parse_plugin_modules(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[list[str] | None, list[str]]

Retrieve the --plugin-modules argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Raises:

DgenerateUsageError – If no argument values were provided.

Returns:

(values | None, unknown_args_list)

dgenerate.arguments.parse_prompt_weighter_help(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[list[str] | None, list[str]]

Retrieve the --prompt-weighter-help argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Returns:

(values | None, unknown_args_list)

dgenerate.arguments.parse_sub_command(args: Sequence[str] | None = None) → tuple[str | None, list[str]]

Retrieve the --sub-command argument value

Parameters:

args – command line arguments

Raises:

DgenerateUsageError – If no argument value was provided.

Returns:

(value | None, unknown_args_list)

dgenerate.arguments.parse_sub_command_help(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[list[str] | None, list[str]]

Retrieve the --sub-command-help argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Returns:

(values | None, unknown_args_list)

dgenerate.arguments.parse_templates_help(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[list[str] | None, list[str]]

Retrieve the --templates-help argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Returns:

(values | None, unknown_args_list)

dgenerate.arguments.parse_verbose(args: Sequence[str] | None = None, throw_unknown: bool = False, log_error: bool = False) → tuple[bool, list[str]]

Retrieve the -v/--verbose argument value

Parameters:

• args – command line arguments

• throw_unknown – Raise DgenerateUsageError if any other specified argument is not a valid dgenerate argument? This treats the primary model argument as optional, and only goes into effect if the specific argument is detected.

• log_error – Write ERROR diagnostics with dgenerate.messages?

Returns:

(value, unknown_args_list)

dgenerate.batchprocess module

Batch processing / dgenerate config scripts.

exception dgenerate.batchprocess.BatchProcessError

Bases: Exception

Thrown by BatchProcessor.run_file() and BatchProcessor.run_string() when an error in a batch processing script is encountered.

exception dgenerate.batchprocess.ConfigRunnerPluginArgumentError

Bases: PluginArgumentError

Thrown when a dgenerate.batchprocess.ConfigRunnerPlugin plugin is not instantiated with correct arguments.

exception dgenerate.batchprocess.ConfigRunnerPluginNotFoundError

Bases: PluginNotFoundError

Thrown when ConfigRunnerPluginLoader cannot find any dgenerate.batchprocess.ConfigRunnerPlugin implementation for a specified name.

class dgenerate.batchprocess.BatchProcessor(invoker: Callable[[Sequence[str]], int], name: str, version: tuple[int, int, int] | str, template_variables: dict[str, Any] | None = None, reserved_template_variables: set[str] | None = None, template_functions: dict[str, Callable[[Any], Any]] | None = None, directives: dict[str, Callable[[list], None]] | None = None, builtins: dict[str, Callable[[Any], Any]] | None = None, injected_args: Sequence[str] | None = None)

Bases: object

Implements dgenerates batch processing scripts in a generified manner.

This is the bare-bones implementation of the shell with nothing implemented for you except for:

• \env

• \set

• \sete

• \setp

• \unset

• \unset_env

• \print

• \echo

If you wish to create this object to run a dgenerate configuration, use dgenerate.batchprocess.ConfigRunner

__init__(invoker: Callable[[Sequence[str]], int], name: str, version: tuple[int, int, int] | str, template_variables: dict[str, Any] | None = None, reserved_template_variables: set[str] | None = None, template_functions: dict[str, Callable[[Any], Any]] | None = None, directives: dict[str, Callable[[list], None]] | None = None, builtins: dict[str, Callable[[Any], Any]] | None = None, injected_args: Sequence[str] | None = None)

Parameters:

• invoker – A function for invoking lines recognized as shell commands, should return a return code.

• name – The name of this batch processor, currently used in the version check directive and messages

• version – Version for version check hash bang directive.

• template_variables – Live template variables, the initial environment, this dictionary will be modified during runtime.

• reserved_template_variables – These template variable names cannot be set with the \set or \setp directive, or un-defined with the \unset directive.

• template_functions – Functions available to Jinja2

• directives – batch processing directive handlers, for: \directives. This is a dictionary of names to functions which accept a single parameter, a list of directive arguments, and return a return code.

• builtins – builtin functions available as template functions and \setp functions. A safe default collection of functions is used if this is not specified. Builtins may be overridden by functions defined in template_functions

• injected_args – Arguments to be injected at the end of user specified arguments for every shell invocation. If -v/--verbose is present in injected_args debugging output will be enabled globally while the config runs, and not just for invocations. Passing -v/--verbose also disables handling of unhandled non SystemExit exceptions raised by config directive implementations, a stack trace will be printed when these exceptions are encountered.

static default_builtins() → dict[str, Callable[[Any], Any]]

Return the default builtins available as template functions.

render_template(string: str, stream: bool = False) → str | Iterator[str]

Render a template from a string

Parameters:

• string – the string containing the Jinja2 template.

• stream – Stream the results of generating this template line by line?

Returns:

rendered string

run_file(stream: Iterator[str])

Process a batch processing script from a file stream.

Technically, from an iterator over lines of text.

Raises:

BatchProcessError –

Parameters:

stream – A filestream in text read mode

run_string(string: str)

Process a batch processing script from a string

Raises:

BatchProcessError –

Parameters:

string – a string containing the script

user_define(name: str, value)

Define a template variable as if you were the user.

Raises:

BatchProcessError – if the specified variable name cannot be defined by the user due to not being a valid identifier string, being the name of a template function, being the name of a reserved template variable, or being the name of a builtin function.

Parameters:

• name – Variable name

• value – Assigned value

user_define_check(name: str)

Check if a template variable can be defined by the user, raise if not.

Raises:

BatchProcessError – if the specified variable name cannot be defined by the user due to not being a valid identifier string, being the name of a template function, being the name of a reserved template variable, or being the name of a builtin function.

Parameters:

name – Variable name

user_undefine(name: str)

Undefine a template variable as if you were the user.

Raises:

BatchProcessError – if the specified variable name cannot be undefined by the user due to not being a valid identifier string, being the name of a template function, being the name of a reserved template variable, being the name of a builtin function, or a non existing template variable.

Parameters:

name – Variable name

user_undefine_check(name: str)

Check if a template variable can be undefined by the user, raise if not.

Raises:

BatchProcessError – if the specified variable name cannot be undefined by the user due to not being a valid identifier string, being the name of a template function, being the name of a reserved template variable, being the name of a builtin function, or a non existing template variable.

Parameters:

name – Variable name

builtins: dict[str, Callable[[Any], Any]]

Safe python builtins that are always available as template functions and also usable with \setp

They may be overridden by functions defined in dgenerate.batchprocess.BatchProcessor.template_functions

property current_line: int

The current line number in the file being processed.

directives: dict[str, Callable[[Sequence[str]], int]] | None

Batch process directives, shell commands starting with a backslash.

Dictionary of callable(list) -> int.

The function should return a return code, 0 for success, anything else for failure.

property directives_builtins_help: dict[str, str]

Returns a dictionary of help strings for directives that are built into the BatchProcessor base class.

property executing_text: None | str

The text / command line that is currently being executed, or that was last executed.

expand_vars: Callable[[str], str]

A function for expanding environmental variables, defaults to dgenerate.textprocessing.shell_expandvars()

injected_args: Sequence[str]

Shell arguments to inject at the end of every invocation.

invoker: Callable[[Sequence[str]], int]

Invoker function, responsible for executing lines recognized as shell commands.

name: str

Name of this batch processor, currently used in the hash bang version check directive and messages.

reserved_template_variables: set[str]

These template variables cannot be set with the \set, \sete, or \setp directive, or un-defined with the \unset directive.

template_functions: dict[str, Callable[[Any], Any]]

Functions available when templating is occurring.

template_variables: dict[str, Any]

Live template variables.

version: tuple[int, int, int]

Version tuple for the version check hash bang directive.

class dgenerate.batchprocess.CivitAILinksDirective(**kwargs)

Bases: ConfigRunnerPlugin

__init__(**kwargs)

Parameters:

kwargs – plugin base class arguments

class dgenerate.batchprocess.ConfigRunner(injected_args: Sequence[str] | None = None, render_loop: RenderLoop | None = None, plugin_loader: ConfigRunnerPluginLoader = None, version: tuple[int, int, int] | str = '4.1.2', throw: bool = False)

Bases: BatchProcessor

A BatchProcessor that can run dgenerate batch processing configs from a string or file.

__init__(injected_args: Sequence[str] | None = None, render_loop: RenderLoop | None = None, plugin_loader: ConfigRunnerPluginLoader = None, version: tuple[int, int, int] | str = '4.1.2', throw: bool = False)

Raises:

dgenerate.plugin.ModuleFileNotFoundError – If a module path parsed from --plugin-modules in injected_args could not be found on disk.

Parameters:

• injected_args – dgenerate command line arguments in the form of a list, see: shlex module, or sys.argv. These arguments will be injected at the end of every dgenerate invocation in the config. --plugin-modules are parsed from injected_args and added to plugin_loader. If -v/--verbose is present in injected_args debugging output will be enabled globally while the config runs, and not just for invocations.

• render_loop – RenderLoop instance, if None is provided one will be created.

• plugin_loader – Batch processor plugin loader, if one is not provided one will be created.

• version – Config version for #! dgenerate x.x.x version checks, defaults to dgenerate.__version__

• throw – Whether to throw exceptions from dgenerate.invoker.invoke_dgenerate() or handle them. If you set this to True exceptions will propagate out of dgenerate invocations instead of a dgenerate.batchprocess.BatchProcessError being raised by the created dgenerate.batchprocess.BatchProcessor. A line number where the error occurred can be obtained using dgenerate.batchprocess.BatchProcessor.current_line.

generate_directives_help(directive_names: Collection[str] | None = None)

Generate the help string for --directives-help

Parameters:

directive_names – Display help for specific directives, if None or [] is specified, display all.

Raises:

ValueError – if given directive names could not be found

Returns:

help string

generate_functions_help(function_names: Collection[str] | None = None)

Generate the help string for --functions-help

Parameters:

function_names – Display help for specific functions, if None or [] is specified, display all.

Raises:

ValueError – if given directive names could not be found

Returns:

help string

generate_template_variables_help(variable_names: Collection[str] | None = None, show_values: bool = True)

Generate a help string describing available template variables, their types, and values for use in batch processing.

This is used for --templates-help

Parameters:

• variable_names – Display help for specific variables, if None or [] is specified, display all.

• show_values – Show the value of the template variable or just the name?

Raises:

ValueError – if given variable names could not be found

Returns:

a human-readable description of all template variables

property plugin_module_paths: frozenset[str]

Set of plugin module paths if they were injected into the config runner by --plugin-modules or used in a \import_plugins statement in a config.

Returns:

a set of paths, may be empty but not None

class dgenerate.batchprocess.ConfigRunnerPlugin(loaded_by_name: str, config_runner: ConfigRunner | None = None, render_loop: RenderLoop | None = None, **kwargs)

Bases: Plugin

Abstract base class for config runner plugin implementations.

__init__(loaded_by_name: str, config_runner: ConfigRunner | None = None, render_loop: RenderLoop | None = None, **kwargs)

Parameters:

• loaded_by_name – The name the plugin was loaded by, will be passed by the loader.

• argument_error_type – This exception type will be raised upon argument errors (invalid arguments) when loading a plugin using a PluginLoader implementation. It should match the argument_error_type given to the PluginLoader implementation being used to load the inheritor of this class.

• kwargs – Additional arguments that may arise when using an ARGS static signature definition with multiple NAMES in your implementation.

register_directive(name, implementation: Callable[[Sequence[str]], int])

Register a config directive implementation on the dgenerate.batchprocess.ConfigRunner instance.

Your directive should return a return code, 0 for success and anything else for failure.

Returning non zero will cause BatchProcessError to be raised from the runner, halting execution of the config.

Any non-exiting exception will be eaten and rethrown as BatchProcessError, also halting execution of the config.

Raises:

RuntimeError – if a config directive with the same name already exists

Parameters:

• name – directive name

• implementation – implementation callable

register_template_function(name, implementation: Callable)

Register a config template function implementation on the dgenerate.batchprocess.ConfigRunner instance.

Raises:

RuntimeError – if a template function with the same name already exists

Parameters:

• name – function name

• implementation – implementation callable

set_template_variable(name, value)

Set a template variable on the dgenerate.batchprocess.ConfigRunner instance.

Parameters:

• name – variable name

• value – variable value

update_template_variables(values)

Update multiple template variable values on the dgenerate.batchprocess.ConfigRunner instance.

Parameters:

values – variable values, dictionary of names to values

property config_runner: ConfigRunner | None

Provides access to the currently instantiated dgenerate.batchprocess.ConfigRunner object running the config file that this directive is being invoked in.

property injected_args: Sequence[str]

Return any arguments injected into the config from the command line.

If none were injected an empty sequence will be returned.

Returns:

command line arguments

property plugin_module_paths: frozenset[str]

Set of plugin module paths if they were injected into the config runner by --plugin-modules or used in a \import_plugins statement in a config.

Returns:

a set of paths, may be empty but not None

property render_loop: RenderLoop | None

Provides access to the currently instantiated dgenerate.renderloop.RenderLoop object.

This object will have been used for any previous invocation of dgenerate in a config file.

class dgenerate.batchprocess.ConfigRunnerPluginLoader

Bases: PluginLoader

Loads dgenerate.batchprocess.ConfigRunnerPlugin plugins.

__init__()

load(uri: str, **kwargs) → ConfigRunnerPlugin

Load an plugin using a URI string containing its name and arguments.

Parameters:

• uri – The URI string

• kwargs – default argument values, will be override by arguments specified in the URI

Raises:

• ValueError – If uri is None

• RuntimeError – If a plugin is discovered to be using a reserved argument name upon loading it.

• dgenerate.plugin.PluginArgumentError – If there is an error in the loading arguments for the plugin.

• dgenerate.plugin.PluginNotFoundError – If the plugin name mentioned in the URI could not be found.

Returns:

plugin instance

class dgenerate.batchprocess.ImageProcessDirective(**kwargs)

Bases: ConfigRunnerPlugin

__init__(**kwargs)

Parameters:

kwargs – plugin base class arguments

dgenerate.filecache module

On disk file cache implementation and primitives.

class dgenerate.filecache.CachedFile(data_dict)

Bases: object

Represents the path of a file in a FileCache

__init__(data_dict)

Parameters:

data_dict – file data dict parsed from the cache database.

metadata: dict[str, str]

Optional metadata for the file stored in the database.

path: str

The path to the file on disk.

class dgenerate.filecache.FileCache(db_path: str, cache_dir: str)

Bases: object

A cache system that stores files and their metadata.

__init__(db_path: str, cache_dir: str)

Initializes the FileCache object with a key-value store located at db_path and a cache directory at cache_dir. If the cache directory doesn’t exist, it creates it.

Parameters:

• db_path – The path to the key-value store database.

• cache_dir – The directory where the cache files are stored.

add(key: str, file_data: bytes | Iterable[bytes], metadata: Dict[str, str] = None, ext: str | None = None) → CachedFile | None

Adds a file to the cache. If a file with the same key already exists, it overwrites the existing file. Otherwise, it creates a new file with a unique filename.

Parameters:

• key – The key associated with the file.

• file_data – The data of the file in bytes, or an iterable of binary chunks.

• metadata – The metadata of the file.

• ext – The extension of the file.

Returns:

A CachedFile object representing the added file.

delete_older_than(timedelta: timedelta) → Iterator[CachedFile]

Deletes items from the key-value store that are older than the specified timedelta, yielding each key and its corresponding CachedFile object.

get(key) → CachedFile | None

Retrieves the CachedFile object for the specified key from the key-value store, or returns None if the key does not exist.

Parameters:

key – The key associated with the file.

Returns:

A CachedFile object representing the file, or None if the key does not exist.

items() → Iterator[CachedFile]

Yields all items in the key-value store as CachedFile objects.

keys() → Iterator[str]

Yields all keys in the key-value store.

class dgenerate.filecache.KeyValueStore(db_path: str)

Bases: object

A key-value store using SQLite3 for storage.

__init__(db_path: str)

Initialize the key-value store.

Parameters:

db_path – The path to the SQLite3 database file.

delete_older_than(timedelta: timedelta) → list[tuple[str, str]]

Delete all keys and their associated values that were created more than a certain time ago.

Parameters:

timedelta – The age of the keys to delete.

Returns:

The keys and values that were deleted.

get(key: str, default=None)

Get the value associated with a key.

Parameters:

• key – The key to get the value for.

• default – The default value to return if the key is not found.

Returns:

The value associated with the key, or the default value if the key is not found.

items() → Iterator[str]

Get all values in the store.

Returns:

An iterator over the values in the store.

keys() → Iterator[str]

Get all keys in the store.

Returns:

An iterator over the keys in the store.

class dgenerate.filecache.WebFileCache(db_path: str, cache_dir: str, expiry_delta: timedelta = datetime.timedelta(seconds=43200))

Bases: FileCache

A cache system that stores files and their metadata downloaded from the web.

__init__(db_path: str, cache_dir: str, expiry_delta: timedelta = datetime.timedelta(seconds=43200))

Initializes the WebFileCache object with a key-value store located at db_path, a cache directory at cache_dir, and an expiry delta. If the cache directory doesn’t exist, it creates it. It also attempts to clear old files.

Parameters:

• db_path – The path to the key-value store database.

• cache_dir – The directory where the cache files are stored.

• expiry_delta – The time delta for file expiry.

download(url, mime_acceptable_desc: str | None = None, mimetype_is_supported: ~typing.Callable[[str], bool] | None = None, unknown_mimetype_exception=<class 'ValueError'>, overwrite: bool = False, tqdm_pbar=<class 'tqdm.std.tqdm'>)

Downloads a file and/or returns a file path from the cache. If the mimetype of the file is not supported, it raises an exception.

Raises:

requests.RequestException – Can raise any exception raised by requests.get for request related errors.

Parameters:

• url – The URL of the file.

• mime_acceptable_desc – A description of acceptable mimetypes for use in exceptions.

• mimetype_is_supported – A function that determines if a mimetype is supported for downloading.

• unknown_mimetype_exception – The exception type to raise when an unknown mimetype is encountered.

• overwrite – Always overwrite any previously cached file?

• tqdm_pbar – tqdm progress bar type, if set to None no progress bar will be used. Defaults to tqdm.tqdm

Returns:

The path to the downloaded file.

static is_downloadable_url(string) → bool

Does a string represent a URL that can be downloaded by this web cache implementation?

Parameters:

string – the string

Returns:

True or False

request_mimetype(url) → str

Requests the mimetype of a file at a URL. If the file exists in the cache, a known mimetype is returned without connecting to the internet. Otherwise, it connects to the internet to retrieve the mimetype. This action does not update the cache.

Raises:

HTTPError – On http status errors.

Parameters:

url – The URL of the file.

Returns:

The mimetype of the file.

dgenerate.filelock module

Thread / Multiprocess safe file locking utilities.

dgenerate.filelock.suffix_path_maker(filenames: str | Iterable[str], suffix: str) → Callable[[str | None, int | None], str | Iterable[str]]

To be used with touch_avoid_duplicate(), a pathmaker implementation that appends a suffix and a number to a filename or list of files when a duplicate is detected for any of them in the directory.

Parameters:

• filenames – Original filename, or a list of filenames

• suffix – Suffix to append if needed, a trailing number will be appended

Returns:

dgenerate.filelock.temp_file_lock(path)

Multiprocess synchronization utility.

Get a lock on an empty file as a context manager, delete the lock file if possible when done.

Parameters:

path – Path where the lock file will be created.

Returns:

Lock as a context manager

dgenerate.filelock.touch_avoid_duplicate(directory: str, path_maker: Callable[[str | None, int | None], str | Iterable[str]], lock_name: str = '.lock', return_list=False)

Generate a filename in a directory and avoid duplicates using a file lock in that directory with a known name. Use to ensure duplicate checking in a directory is multiprocess safe, at least for processes using this function to write to the same directory.

Parameters:

• return_list – Always return a list even if generated paths is only of length 1, defaults to False, which means that a single string will be returned if only one path was generated by the pathmaker

• directory – The directory to create the lockfile in

• path_maker – Callback that generates paths until a non-existent path is found, first argument is the base filename and the second is attempt number. On the first attempt to create the files both arguments will be none, in which case the callback should return a single filename or iterable of filenames to touch with duplicate avoidance. Calls to the callback thereafter will have non None values for both arguments and the callback should take the passed base filename and apply a suffix using the attempt number.

• lock_name – Name of the lock file to be used as a mutex

Returns:

Unique path that has been touched (created but empty), or a tuple of paths if the path maker requested duplicate checks on multiple files

dgenerate.files module

Utilities for file like objects.

class dgenerate.files.GCFile(file)

Bases: object

File object wrapper, close file on garbage collection

__init__(file)

class dgenerate.files.PeekReader(iterator: Iterator[str])

Bases: object

Read from a file like iterator object while peeking at the next line.

This is an iterable reader wrapper that yields the tuple (current_line, next_line)

next_line will be None if the next line is the end of iterator / file.

__init__(iterator: Iterator[str])

Parameters:

iterator – The typing.Iterator capable reader to wrap.

class dgenerate.files.TerminalLineReader(file: BinaryIO | Callable[[], IO])

Bases: object

Reads lines from a binary stream, typically stdout or stderr of a subprocess.

Breaks on newlines and carriage return, preserves newlines and carriage return in the output as is.

__init__(file: BinaryIO | Callable[[], IO])

Parameters:

file – Binary IO object, or a function that returns one.

readline()

property file: BinaryIO

The current file object being read.

pushback_byte: bytes | None

Byte on the stack which will be prepended to the next line if needed.

Should be set to None if file was provided a callable and the underlying reader has changed to a new instance.

class dgenerate.files.Unbuffered(stream)

Bases: object

File wrapper which auto flushes a stream on write

__init__(stream)

write(data)

writelines(datas)

dgenerate.files.stdin_is_tty()

Safely checks if stdin is a tty

Returns:

True or False

dgenerate.image module

Image operations commonly used by dgenerate.

dgenerate.image.align_by(iterable: Iterable[int], align: int) → tuple

Align all elements by a value and return a tuple

Parameters:

• iterable – Elements to align

• align – The alignment value, None indicates no alignment.

Returns:

tuple(…)

dgenerate.image.copy_img(img: Image)

Copy a PIL.Image.Image while preserving its filename attribute.

Parameters:

img – the image

Returns:

a copy of the image

dgenerate.image.get_filename(img: Image)

Get the PIL.Image.Image.filename attribute or “NO_FILENAME” if it does not exist.

Parameters:

img – PIL.Image.Image

Returns:

filename string or “NO_FILENAME”

dgenerate.image.is_aligned(iterable: Iterable[int], align: int) → bool

Check if all elements are aligned by a specific value.

Parameters:

• iterable – Elements to test

• align – The alignment value, None indicates no alignment.

Returns:

bool

dgenerate.image.is_power_of_two(iterable: Iterable[int]) → bool

Check if all elements are a power of 2.

Parameters:

iterable – Elements to test

Returns:

bool

dgenerate.image.letterbox_image(img, box_size: tuple[int, int], box_is_padding: bool = False, box_color: str | int | float | tuple[int, int, int] | tuple[float, float, float] | None = None, inner_size: tuple[int, int] = None, aspect_correct: bool = True)

Letterbox an image on to a colored background.

Parameters:

• img – The image to letterbox

• box_size – Size of the outer letterbox

• box_is_padding – The letterbox_size argument should be interpreted as padding?

• box_color – What color to use for the letter box background, the default is black. This should be specified as a HEX color code, or as a 3 tuple of integer or floating point RGB values, or as a single integer or float representing all color channels.

• inner_size – The size of the inner image

• aspect_correct – Should the size of the inner image be aspect correct?

Returns:

The letterboxed image

dgenerate.image.nearest_power_of_two(iterable: Iterable[int]) → tuple

Round all elements to the nearest power of two and return a tuple.

Parameters:

iterable – Elements to round

Returns:

tuple(…)

dgenerate.image.resize_image(img: Image, size: tuple[int, int] | None, aspect_correct: bool = True, align: int | None = 8, algo: Resampling = Resampling.LANCZOS)

Resize a PIL.Image.Image and return a copy.

This function always returns a copy even if the images size did not change.

The new image dimension will always be forcefully aligned by align, specifying None or 1 indicates no alignment.

The filename attribute is preserved.

Parameters:

• img – the image to resize

• size – requested new size for the image, may be None.

• aspect_correct – preserve aspect ratio?

• align – Force alignment by this amount of pixels.

• algo – Resampling algorithm

Returns:

the resized image

dgenerate.image.resize_image_calc(old_size: tuple[int, int], new_size: tuple[int, int] | None, aspect_correct: bool = True, align: int | None = 8)

Calculate the new dimensions for a requested resize of an image..

Parameters:

• old_size – The old image size

• new_size – The new image size

• aspect_correct – preserve aspect ratio?

• align – Ensure returned size is aligned to this value.

Returns:

calculated new size

dgenerate.image.to_rgb(img: Image)

Convert a PIL.Image.Image to RGB format while preserving its filename attribute.

Parameters:

img – the image

Returns:

a converted copy of the image

dgenerate.image_process module

Implements the behaviors of dgenerates image-process sub-command and \image_process config directive.

exception dgenerate.image_process.ImageProcessHelpException

Bases: Exception

Raised by parse_args() when --help is encountered and help_raises=True

exception dgenerate.image_process.ImageProcessRenderLoopConfigError

Bases: Exception

Raised by ImageProcessRenderLoopConfig.check() on validation errors.

exception dgenerate.image_process.ImageProcessUsageError

Bases: Exception

Thrown by parse_args() on usage errors.

class dgenerate.image_process.AnimationETAEvent(origin, frame_index: int, total_frames: int, eta: timedelta)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when there is an update about the estimated finish time of an animation being generated.

__init__(origin, frame_index: int, total_frames: int, eta: timedelta)

eta: timedelta

Current estimated time to complete the animation.

frame_index: int

Frame index at which the ETA was calculated.

total_frames: int

Total frames needed for the animation to complete.

class dgenerate.image_process.AnimationFileFinishedEvent(origin: ImageProcessRenderLoop, path: str, starting_event: StartingAnimationFileEvent)

Bases: Event

Generated in the event stream of ImageProcessRenderLoop.events()

Occurs when an animation (video or animated image) has finished being written to disk.

__init__(origin: ImageProcessRenderLoop, path: str, starting_event: StartingAnimationFileEvent)

path: str

Path on disk where the video/animated image was saved.

starting_event: StartingAnimationFileEvent

Animation StartingAnimationFileEvent related to this file finished event.

class dgenerate.image_process.AnimationFinishedEvent(origin, starting_event: StartingAnimationEvent)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a sequence of images that belong to an animation are done generating.

This occurs whether an animation was written to disk or not.

__init__(origin, starting_event: StartingAnimationEvent)

starting_event: StartingAnimationEvent

Animation StartingAnimationEvent related to this file finished event.

class dgenerate.image_process.ImageFileSavedEvent(origin: ImageProcessRenderLoop, generated_event, path)

Bases: Event

Generated in the event stream of ImageProcessRenderLoop.events()

Occurs when an image file is written to disk.

__init__(origin: ImageProcessRenderLoop, generated_event, path)

generated_event: ImageGeneratedEvent

The ImageGeneratedEvent for the image that was saved.

path: str

Path to the saved image.

class dgenerate.image_process.ImageGeneratedEvent(origin: ImageProcessRenderLoop, image: Image, generation_step: int, suggested_directory: str, suggested_filename: str, is_animation_frame=False, frame_index: int | None = None)

Bases: Event

Generated in the event stream of ImageProcessRenderLoop.events()

Occurs when an image is generated (but not saved yet).

__init__(origin: ImageProcessRenderLoop, image: Image, generation_step: int, suggested_directory: str, suggested_filename: str, is_animation_frame=False, frame_index: int | None = None)

frame_index: int | None

The frame index if this is an animation frame.

generation_step: int

The current generation step. (zero indexed)

image: Image

The generated image.

is_animation_frame: bool

Is this image a frame in an animation?

suggested_directory: str

A suggested directory path for saving this image in.

A value of '.' may be present, this indicates the current working directory.

suggested_filename: str

A suggested filename for saving this image as. This filename will be unique to the render loop run / configuration. This is just the filename, it will not contain a directory name.

class dgenerate.image_process.ImageProcessArgs

Bases: ImageProcessRenderLoopConfig

Configuration object for ImageProcessRenderLoop

__init__()

plugin_module_paths: Sequence[str]

class dgenerate.image_process.ImageProcessRenderLoop(config: ImageProcessRenderLoopConfig = None, image_processor_loader: ImageProcessorLoader | None = None)

Bases: object

Implements the behavior of the image-process sub-command as well as \image_process directive.

__init__(config: ImageProcessRenderLoopConfig = None, image_processor_loader: ImageProcessorLoader | None = None)

events() → Generator[ImageGeneratedEvent | StartingAnimationEvent | StartingAnimationFileEvent | AnimationFileFinishedEvent | ImageFileSavedEvent | AnimationFinishedEvent | StartingGenerationStepEvent | AnimationETAEvent, None, None]

Run the render loop, and iterate over a stream of event objects produced by the render loop.

Event objects are of the union type RenderLoopEvent

The exceptions mentioned here are those you may encounter upon iterating, they will not occur upon simple acquisition of the event stream iterator.

Raises:

• dgenerate.OutOfMemoryError – if the execution device runs out of memory

• ImageProcessRenderLoopConfigError – on config errors

Returns:

RenderLoopEventStream

run()

Run the render loop, this calls ImageProcessRenderLoopConfig.check() prior to running.

Raises:

• dgenerate.OutOfMemoryError – if the execution device runs out of memory

• ImageProcessRenderLoopConfigError – on config errors

disable_writes: bool = False

Disable or enable all writes to disk, if you intend to only ever use the event stream of the render loop when using dgenerate as a library, this is a useful option.

RenderLoop.last_images and last_animations will not be available if writes to disk are disabled.

image_processor_loader: ImageProcessorLoader

The loader responsible for loading user specified image processors

message_header: str = 'image-process'

Used as the header for messages written via dgenerate.messages

property written_animations: Iterable[str]

Iterable over animation filenames written by the last run

property written_images: Iterable[str]

Iterable over image filenames written by the last run

class dgenerate.image_process.ImageProcessRenderLoopConfig

Bases: SetFromMixin

__init__()

check(attribute_namer: Callable[[str], str] = None)

Preforms logical validation on the configuration.

align: int = 8

Forced image alignment, corresponds to -al/--align

device: str = 'cuda'

Rendering device, corresponds to -d/--device

frame_end: int | None = None

Optional zero indexed inclusive frame slice end, corresponds to -fe/--frame-end

frame_format: str = 'png'

Animation frame format, corresponds to -ff/-frame-format

frame_start: int = 0

Zero indexed inclusive frame slice start, corresponds to -fs/--frame-start

input: Sequence[str]

Input file paths.

no_animation_file: bool = False

Disable animated file output when rendering an animation? mutually exclusive with no_frames. Corresponds to -naf/--no-animation-file

no_aspect: bool = False

Disable aspect correction? corresponds to -na/--no-aspect

no_frames: bool = False

Disable frame output when rendering an animation? mutually exclusive with no_animation. Corresponds to -nf/--no-frames

output: Sequence[str] | None = None

Output file paths, corresponds to -o/--output

output_overwrite: bool = False

Should existing files be overwritten? corresponds to -ox/--output-overwrite

processors: Sequence[str] | None = None

Image processor URIs, corresponds to -p/--processors

resize: tuple[int, int] | None = None

Naive resizing value (LANCZOS), corresponds to -r/--resize

class dgenerate.image_process.StartingAnimationEvent(origin, total_frames: int, fps: float, frame_duration: float)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a sequence of images that belong to an animation are about to start being generated.

This occurs whether an animation is going to be written to disk or not.

__init__(origin, total_frames: int, fps: float, frame_duration: float)

fps: float

FPS of the generated file.

frame_duration: float

Frame duration of the generated file, (the time a frame is visible in milliseconds)

total_frames: int

Number of frames written.

class dgenerate.image_process.StartingAnimationFileEvent(origin, path: str, total_frames: int, fps: float, frame_duration: float)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a sequence of images that belong to an animation are about to start being written to a file.

__init__(origin, path: str, total_frames: int, fps: float, frame_duration: float)

fps: float

FPS of the generated file.

frame_duration: float

Frame duration of the generated file, (the time a frame is visible in milliseconds)

path: str

File path where the animation will reside.

total_frames: int

Number of frames written.

class dgenerate.image_process.StartingGenerationStepEvent(origin, generation_step: int, total_steps: int)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a generation step is starting, a generation step may produce multiple images and or an animation.

__init__(origin, generation_step: int, total_steps: int)

generation_step: int

The generation step number.

total_steps: int

The total number of steps that are needed to complete the render loop.

dgenerate.image_process.invoke_image_process(args: Sequence[str], render_loop: ImageProcessRenderLoop | None = None, throw: bool = False, log_error: bool = True, help_raises: bool = False, help_name: str = 'image-process', help_desc: str | None = None) → int

Invoke image-process using its command line arguments and return a return code.

image-process is invoked in the current process, this method does not spawn a subprocess.

Parameters:

• args – image-process command line arguments in the form of a list, see: shlex module, or sys.argv

• render_loop – ImageProcessRenderLoop instance, if None is provided one will be created.

• throw – Whether to throw known exceptions or handle them.

• log_error – Write ERROR diagnostics with dgenerate.messages?

• help_raises – --help raises ImageProcessHelpException ? When True, this will occur even if throw=False

• help_name – name used in the --help output

• help_desc – description used in the --help output, if None is provided a default value will be used.

Raises:

• ImageProcessUsageError –

• ImageProcessHelpException –

• dgenerate.ImageProcessorArgumentError –

• dgenerate.ImageProcessorNotFoundError –

• dgenerate.FrameStartOutOfBounds –

• dgenerate.MediaIdentificationError –

• dgenerate.OutOfMemoryError –

• EnvironmentError –

Returns:

integer return-code, anything other than 0 is failure

dgenerate.image_process.invoke_image_process_events(args: Sequence[str], render_loop: ImageProcessRenderLoop | None = None, throw: bool = False, log_error: bool = True, help_raises: bool = False, help_name: str = 'image-process', help_desc: str | None = None) → Generator[ImageProcessExitEvent | ImageGeneratedEvent | StartingAnimationEvent | StartingAnimationFileEvent | AnimationFileFinishedEvent | ImageFileSavedEvent | AnimationFinishedEvent | StartingGenerationStepEvent | AnimationETAEvent, None, None]

Invoke image-process using its command line arguments and return a stream of events.

image-process is invoked in the current process, this method does not spawn a subprocess.

The exceptions mentioned here are those you may encounter upon iterating, they will not occur upon simple acquisition of the event stream iterator.

Parameters:

• args – image-process command line arguments in the form of a list, see: shlex module, or sys.argv

• render_loop – ImageProcessRenderLoop instance, if None is provided one will be created.

• throw – Whether to throw known exceptions or handle them.

• log_error – Write ERROR diagnostics with dgenerate.messages?

• help_raises – --help raises ImageProcessHelpException ? When True, this will occur even if throw=False

• help_name – name used in the --help output

• help_desc – description used in the --help output, if None is provided a default value will be used.

Raises:

• ImageProcessUsageError –

• ImageProcessHelpException –

• dgenerate.ImageProcessorArgumentError –

• dgenerate.ImageProcessorNotFoundError –

• dgenerate.FrameStartOutOfBounds –

• dgenerate.MediaIdentificationError –

• dgenerate.OutOfMemoryError –

• EnvironmentError –

Returns:

InvokeImageProcessEventStream

dgenerate.image_process.parse_args(args: Sequence[str] | None = None, help_name='image-process', help_desc=None, throw: bool = True, log_error: bool = True, help_raises: bool = False) → ImageProcessArgs | None

Parse and validate the arguments used for image-process, which is a dgenerate sub-command as well as config directive.

Parameters:

• args – command line arguments

• help_name – program name displayed in --help output.

• help_desc – program description displayed in --help output.

• throw – throw ImageProcessUsageError on error? defaults to True

• log_error – Write ERROR diagnostics with dgenerate.messages?

• help_raises – --help raises ImageProcessHelpException ? When True, this will occur even if throw=False

Raises:

• ImageProcessUsageError –

• ImageProcessHelpException –

Returns:

parsed arguments object

dgenerate.imageprocessors module

Image processors implemented by dgenerate.

This includes many image processing tasks useful for creating diffusion input images, or for postprocessing.

exception dgenerate.imageprocessors.ImageProcessorArgumentError

Bases: PluginArgumentError, ImageProcessorError

Raised when an image processor receives invalid arguments.

exception dgenerate.imageprocessors.ImageProcessorError

Bases: Exception

Generic image processor error base exception.

exception dgenerate.imageprocessors.ImageProcessorImageModeError

Bases: ImageProcessorError

Raised when an image processor cannot support a PIL images reported mode.

A mode being a mode string such as RGB, BGR, etc.

exception dgenerate.imageprocessors.ImageProcessorNotFoundError

Bases: PluginNotFoundError, ImageProcessorError

Raised when a reference to an unknown image processor name is made.

class dgenerate.imageprocessors.AnylineProcessor(gaussian_sigma: float = 2.0, intensity_threshold: int = 2, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

anyline, MistoLine Control Every Line image preprocessor, see: https://huggingface.co/TheMistoAI/MistoLine

This is an edge detector based on TEED.

The “gaussian-sigma” argument is the gaussian filter sigma value.

The “intensity-threshold” argument is the pixel value intensity threshold.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect_resolution” before detection runs is aspect correct, this defaults to true.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(gaussian_sigma: float = 2.0, intensity_threshold: int = 2, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• gaussian_sigma – gaussian filter sigma value

• intensity_threshold – pixel value intensity threshold

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly an anyline detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly an anyline detected image, or the input image

NAMES = ['anyline']

class dgenerate.imageprocessors.CannyEdgeDetectProcessor(lower: int = 50, upper: int = 100, aperture_size: int = 3, L2_gradient: bool = False, blur: bool = False, gray: bool = False, threshold_algo: str | None = None, sigma: float = 0.33, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Process the input image with the Canny edge detection algorithm.

The “lower” argument indicates the lower threshold value for the algorithm, and the “upper” argument indicates the upper threshold. “aperture-size” is the size of Sobel kernel used for find image gradients, it must be an odd integer from 3 to 7. “L2-gradient” specifies the equation for finding gradient magnitude, if True a more accurate equation is used. See: https://docs.opencv.org/3.4/da/d22/tutorial_py_canny.html.

If “blur” is true, apply a 3x3 gaussian blur before processing. If “gray” is true, convert the image to the cv2 “GRAY” format before processing, which does not happen automatically unless you are using a “threshold_algo” value, OpenCV is capable of edge detection on colored images, however you may find better results by converting to its internal grayscale format before processing, or you may not, it depends.

If “threshold_algo” is one of (“otsu”, “triangle”, “median”) try to calculate the lower and upper threshold automatically using cv2.threshold or cv2.median in the case of “median”. “sigma” scales the range of the automatic threshold calculation done when a value for “threshold_algo” is selected. “pre-resize” is a boolean value determining if the processing should take place before or after the image is resized by dgenerate.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(lower: int = 50, upper: int = 100, aperture_size: int = 3, L2_gradient: bool = False, blur: bool = False, gray: bool = False, threshold_algo: str | None = None, sigma: float = 0.33, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• lower – lower threshold for canny edge detection

• upper – upper threshold for canny edge detection

• aperture_size – aperture size, an odd integer from 3 to 7

• L2_gradient – Use L2_gradient? https://docs.opencv.org/3.4/da/d22/tutorial_py_canny.html

• blur – apply a 3x3 gaussian blur before processing?

• gray – convert to cv2.GRAY format before processing?

• threshold_algo – optional auto thresholding algorithm. One of “otsu”, “triangle”, or “median”. the lower, and upper threshold values are determined automagically from the image content if this argument is supplied a value.

• sigma – scales the range of the automatic threshold calculation

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize, canny edge detection may or may not occur here depending on the boolean value of the processor argument “pre-resize”

Parameters:

image – image to process

Returns:

possibly a canny edge detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize, canny edge detection may or may not occur here depending on the boolean value of the processor argument “pre-resize”

Parameters:

• image – image to process

• resize_resolution – purely informational, is unused by this processor

Returns:

possibly a canny edge detected image, or the input image

to(device) → CannyEdgeDetectProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['canny']

class dgenerate.imageprocessors.HEDProcessor(scribble: bool = False, safe: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

HED detection (holistically-nested edge detection), this is an edge detection algorithm that can produced something akin to thick lineart.

The “scribble” argument determines whether scribble mode is enabled, this produces thicker lines.

The “safe” argument enables or disables numerically safe / more precise stepping.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect_resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect_resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(scribble: bool = False, safe: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• scribble – determines whether or not scribble mode is enabled, this produces thicker lines

• safe – enables numerically safe / more precise stepping

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly an HED depth detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly an HED depth detected image, or the input image

NAMES = ['hed']

class dgenerate.imageprocessors.ImageProcessor(loaded_by_name: str, device: str | None = None, output_file: str | None = None, output_overwrite: bool = False, model_offload: bool = False, **kwargs)

Bases: Plugin

Abstract base class for image processor implementations.

__init__(loaded_by_name: str, device: str | None = None, output_file: str | None = None, output_overwrite: bool = False, model_offload: bool = False, **kwargs)

Parameters:

• loaded_by_name – The name the processor was loaded by

• device – the device the processor will run on, for example: cpu, cuda, cuda:1. Specifying None causes the device to default to cpu.

• output_file – output a debug image to this path

• output_overwrite – can the debug image output path be overwritten?

• model_offload – if True, any torch modules that the processor has registered are offloaded to the CPU immediately after processing an image

• kwargs – child class forwarded arguments

get_alignment() → int | None

Get required input image alignment, which will be forcefully applied.

If this function returns None, specific alignment is not required and will never be forced.

Returns:

integer or None

impl_post_resize(image: Image)

Implementation of post_resize that does nothing. Inheritor must implement.

This method should not be invoked directly, use the class method ImageProcessor.call_post_resize() to invoke it.

Parameters:

image – image to process

Returns:

the processed image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Implementation of pre_resize that does nothing. Inheritor must implement.

This method should not be invoked directly, use the class method ImageProcessor.call_pre_resize() to invoke it.

Parameters:

• image – image to process

• resize_resolution – image will be resized to this resolution after this process is complete. If None is passed no resize is going to occur. It is not the duty of the inheritor to resize the image, in fact it should NEVER be resized.

Returns:

the processed image

classmethod inheritable_help(subclass, loaded_by_name)

post_resize(image: Image) → Image

Invoke a processors ImageProcessor.impl_post_resize() method.

Implements important behaviors depending on if the image was modified.

This is the only appropriate way to invoke a processor manually.

The original image will be closed if the implementation returns a new image instead of modifying it in place, you should not count on the original image being open and usable once this function completes though it is safe to use the input image in a with context, if you need to retain a copy, pass a copy.

Raises:

• dgenerate.OutOfMemoryError – if the execution device runs out of memory

• dgenerate.ImageProcessorImageModeError – if a passed image has an invalid format

Parameters:

• self – ImageProcessor implementation instance

• image – the image to pass

Returns:

processed image, may be the same image or a copy.

pre_resize(image: Image, resize_resolution: tuple[int, int] | None = None) → Image

Invoke a processors ImageProcessor.impl_pre_resize() method.

Implements important behaviors depending on if the image was modified.

This is the only appropriate way to invoke a processor manually.

The original image will be closed if the implementation returns a new image instead of modifying it in place, you should not count on the original image being open and usable once this function completes though it is safe to use the input image in a with context, if you need to retain a copy, pass a copy.

Raises:

• dgenerate.OutOfMemoryError – if the execution device runs out of memory

• dgenerate.ImageProcessorImageModeError – if a passed image has an invalid format

Parameters:

• self – ImageProcessor implementation instance

• image – the image to pass

• resize_resolution – the size that the image is going to be resized to after this step, or None if it is not being resized.

Returns:

processed image, may be the same image or a copy.

process(image: Image, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8)

Preform image processing on an image, including the requested resizing step.

Invokes the image processor pre and post resizing with appropriate arguments and correct resource management.

The original image will be closed if the implementation returns a new image instead of modifying it in place, you should not count on the original image being open and usable once this function completes though it is safe to use the input image in a with context, if you need to retain a copy, pass a copy.

Raises:

• dgenerate.OutOfMemoryError – if the execution device runs out of memory

• dgenerate.ImageProcessorImageModeError – if a passed image has an invalid format

Parameters:

• image – image to process

• resize_resolution – image will be resized to this dimension by this method.

• aspect_correct – Should the resize operation be aspect correct?

• align – Align by this amount of pixels, if the input image is not aligned to this amount of pixels, it will be aligned by resizing. Passing None or 1 disables alignment.

Returns:

the processed image

register_module(module)

Register torch.nn.Module objects.

These will be brought on to the cpu during finalization.

All of these modules can be cast to a specific device with ImageProcessor.to

Parameters:

module – the module

set_size_estimate(size_bytes: int)

Set the estimated size of this model in bytes for memory management heuristics, this is intended to be used by implementors of the ImageProcessor plugin class.

For the best memory optimization, this value should be set very shortly before the model even enters CPU side ram, IE: before it is loaded at all.

Raises:

ValueError – if size_bytes is less than zero.

Parameters:

size_bytes – the size in bytes

to(device: device | str) → ImageProcessor

Move all torch.nn.Module modules registered to this image processor to a specific device.

Raises:

dgenerate.OutOfMemoryError – if there is not enough memory on the specified device

Parameters:

device – The device string, or torch device object

Returns:

the image processor itself

property device: str

The rendering device requested for this processor.

Torch modules associated with the processor will not be on this device until the processor is used.

Returns:

device string, for example “cuda”, “cuda:N”, or “cpu”

property image_modes: list[str]

Returns a list of PIL image modes that this processor can handle.

This may be overridden by implementers

Returns:

['RGB']

property modules_device: device

The rendering device that this processors modules currently exist on.

This will change with calls to ImageProcessor.to() and possibly when the processor is used.

Returns:

torch.device, using str() on this object will yield a device string such as “cuda”, “cuda:N”, or “cpu”

property size_estimate: int

Get the estimated size of this model in bytes.

Returns:

size bytes

class dgenerate.imageprocessors.ImageProcessorChain(image_processors: Iterable[ImageProcessor] | None = None)

Bases: ImageProcessor

Implements chainable image processors.

Chains processing steps together in a sequence.

__init__(image_processors: Iterable[ImageProcessor] | None = None)

Parameters:

image_processors – optional initial image processors to fill the chain, accepts an iterable

add_processor(image_processor: ImageProcessor)

Add a imageprocessor implementation to the chain.

Parameters:

image_processor – dgenerate.imageprocessors.imageprocessor.ImageProcessor

impl_post_resize(image: Image)

Invoke post_resize on all image processors in this image processor chain in turn.

Every subsequent invocation receives the last processed image as its argument.

This method should not be invoked directly, use the class method dgenerate.imageprocessors.imageprocessor.ImageProcessor.post_resize() to invoke it.

Parameters:

image – initial image to process

Returns:

the processed image, possibly affected by every imageprocessor in the chain

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Invoke pre_resize on all image processors in this imageprocessor chain in turn.

Every subsequent invocation receives the last processed image as its argument.

This method should not be invoked directly, use the class method dgenerate.imageprocessors.imageprocessor.ImageProcessor.pre_resize() to invoke it.

Parameters:

• image – initial image to process

• resize_resolution – the size which the image will be resized to after this step, this is only information for the image processors and the image will not be resized by this method. Image processors should never resize images as it is the responsibility of dgenerate to do that for the user.

Returns:

the processed image, possibly affected by every image processor in the chain

to(device: device | str) → ImageProcessorChain

Move all torch.nn.Module modules registered to this image processor to a specific device.

Raises:

dgenerate.OutOfMemoryError – if there is not enough memory on the specified device

Parameters:

device – The device string, or torch device object

Returns:

the image processor itself

HIDDEN = True

class dgenerate.imageprocessors.ImageProcessorLoader

Bases: PluginLoader

Loads dgenerate.imageprocessor.ImageProcessor plugins.

__init__()

load(uri: str | Iterable[str], device: str = 'cpu', **kwargs) → ImageProcessor | ImageProcessorChain | None

Load an image processor or multiple image processors. They are loaded by URI, which is their name and any module arguments, for example: canny;lower=50;upper=100

Specifying multiple processors with a list will create an image processor chain object.

Raises:

• RuntimeError – if more than one class was found using the provided name mentioned in the URI.

• ImageProcessorNotFoundError – if the name mentioned in the URI could not be found.

• ImageProcessorArgumentError – if the URI contained invalid arguments.

Parameters:

• uri – Processor URI or list of URIs

• device – Request a specific rendering device, default is CPU

• kwargs – Default argument values, will be overriden by arguments specified in the URI

Returns:

dgenerate.imageprocessors.ImageProcessor or dgenerate.imageprocessors.ImageProcessorChain

class dgenerate.imageprocessors.ImageProcessorMixin(image_processor: ImageProcessor | None = None, *args, **kwargs)

Bases: object

Mixin functionality for objects that can do image processing such as implementors of dgenerate.mediainput.AnimationReader

This object can also be instantiated and used alone.

This object implements resizing functionality identical to an image processor in the absense or disabled state of the image processor.

Which is used for among other things, frame slicing with an image processor involved.

__init__(image_processor: ImageProcessor | None = None, *args, **kwargs)

Parameters:

• processor – the processor implementation that will be doing the image processing.

• args – mixin forwarded args

• kwargs – mixin forwarded kwargs

process_image(image: Image, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8)

Preform image processing on an image, including the requested resizing step.

Invokes the assigned image processor on an image.

If no processor is assigned or the processor is disabled, only necessary resizing will be preformed based on the given arguments.

The original image will be closed if the processor returns a new image instead of modifying it in place, you should not count on the original image being open and usable once this function completes with a processor assigned and the processor enabled, though it is safe to use the input image in a with context, if you need to retain a copy, pass a copy.

Parameters:

• image – image to process

• resize_resolution – image will be resized to this dimension by this method.

• aspect_correct – Should the resize operation be aspect correct?

• align – Align by this amount of pixels, if the input image is not aligned to this amount of pixels, it will be aligned by resizing. Passing None or 1 disables alignment.

Returns:

the processed image, processed by the processor assigned in the constructor.

image_processor: ImageProcessor | None = None

Current image processor.

Images will still be resized as needed/requested if this is not assigned.

image_processor_enabled: bool

Enable or disable image processing.

Images will still be resized as needed/requested with this disabled.

class dgenerate.imageprocessors.LeresDepthProcessor(threshold_near: int = 0, threshold_far: int = 0, boost: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

LeReS depth detector.

The “threshold-near” argument is the near threshold, think the low threshold of canny.

The “threshold-far” argument is the far threshold, think the high threshold of canny.

The “boost” argument determines if monocular depth boost is used.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(threshold_near: int = 0, threshold_far: int = 0, boost: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Parameters:

• threshold_near – argument is the near threshold, think the low threshold of canny

• threshold_far – argument is the far threshold, think the high threshold of canny

• boost – argument determines if monocular depth boost is used

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

get_alignment()

Get required input image alignment, which will be forcefully applied.

If this function returns None, specific alignment is not required and will never be forced.

Returns:

integer or None

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a LeReS depth detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a LeReS depth detected image, or the input image

NAMES = ['leres']

class dgenerate.imageprocessors.LetterboxProcessor(box_size: str, box_is_padding: bool = False, box_color: str | None = None, inner_size: str | None = None, aspect_correct: bool = True, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Letterbox an image.

The “box-size” argument is the size of the outer letterbox

The “box-is-padding” argument can be used to indicate that “box-size” should be interpreted as padding.

The “box-color” argument specifies the color to use for the letter box background, the default is black. This should be specified as a HEX color code.

The “inner-size” argument specifies the size of the inner image.

The “aspect-correct” argument can be used to determine if the aspect ratio of the inner image is maintained or not.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(box_size: str, box_is_padding: bool = False, box_color: str | None = None, inner_size: str | None = None, aspect_correct: bool = True, pre_resize: bool = False, **kwargs)

Parameters:

• box_size – Size of the outer letterbox

• box_is_padding – The letterbox_size argument should be interpreted as padding?

• box_color – What color to use for the letter box background, the default is black. This should be specified in as a HEX color code.

• inner_size – The size of the inner image

• aspect_correct – Should the size of the inner image be aspect correct?

impl_post_resize(image: Image)

Letterbox operation is preformed by this method if pre_resize constructor argument was False.

Parameters:

image – image to process

Returns:

the letterboxed image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Letterbox operation is preformed by this method if pre_resize constructor argument was True.

Parameters:

• image – image to process

• resize_resolution – purely informational, is unused by this imageprocessor

Returns:

the letterboxed image

to(device) → LetterboxProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['letterbox']

class dgenerate.imageprocessors.LineArtAnimeProcessor(detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Anime line art generator, generate anime line art from an image.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a lineart image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a lineart image, or the input image

NAMES = ['lineart-anime']

class dgenerate.imageprocessors.LineArtProcessor(course: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Line art generator, generate line art from an image.

The “course” argument determines whether to use the course model or the normal model.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(course: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• course – determines whether to use the course model or the normal model

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a lineart image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a lineart image, or the input image

NAMES = ['lineart']

class dgenerate.imageprocessors.LineArtStandardProcessor(gaussian_sigma: float = 6.0, intensity_threshold: int = 8, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Standard lineart detector, generate lineart from an image.

The “gaussian-sigma” argument is the gaussian filter sigma value.

The “intensity-threshold” argument is the pixel value intensity threshold.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(gaussian_sigma: float = 6.0, intensity_threshold: int = 8, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• gaussian_sigma – gaussian filter sigma value

• intensity_threshold – pixel value intensity threshold

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a lineart image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a lineart image, or the input image

to(device) → LineArtStandardProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['lineart-standard']

class dgenerate.imageprocessors.MLSDProcessor(threshold_score: float = 0.1, threshold_distance: float = 0.1, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Machine Learning Model for Detecting Wireframes. Wireframe edge detector, this processor overlays lines on to the edges of objects in an image.

The “threshold-score” argument is the score threshold.

The “threshold-distance” argument is the distance threshold.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(threshold_score: float = 0.1, threshold_distance: float = 0.1, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• threshold_score – score threshold

• threshold_distance – distance threshold

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a wireframe detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a wireframe detected image, or the input image

NAMES = ['mlsd']

class dgenerate.imageprocessors.MidasDepthProcessor(normals: bool = False, alpha: float = 6.283185307179586, background_threshold: float = 0.1, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

MiDaS depth detector and normal map generation.

The “normals” argument determines if this processor produces a normal map or a depth image.

The “alpha” argument is related to normal map generation.

The “background_threshold” argument is related to normal map generation.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect_resolution” before detection runs is aspect correct, this defaults to true.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(normals: bool = False, alpha: float = 6.283185307179586, background_threshold: float = 0.1, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Parameters:

• normals – Return a generated normals image instead of a depth image?

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

get_alignment()

Get required input image alignment, which will be forcefully applied.

If this function returns None, specific alignment is not required and will never be forced.

Returns:

integer or None

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a MiDaS depth detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a MiDaS depth detected image, or the input image

NAMES = ['midas']

class dgenerate.imageprocessors.MirrorFlipProcessor(pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Implements the “mirror” and “flip” PIL.ImageOps operations as an image imageprocessor

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(pre_resize: bool = False, **kwargs)

Parameters:

kwargs – forwarded to base class

static help(loaded_by_name)

impl_post_resize(image: Image)

Mirrors or flips the image depending on what name was used to invoke this imageprocessor implementation.

Executes if pre_resize constructor argument was False.

Parameters:

image – image to process

Returns:

the mirrored or flipped image.

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Mirrors or flips the image depending on what name was used to invoke this imageprocessor implementation.

Executes if pre_resize constructor argument was True.

Parameters:

• image – image to process

• resize_resolution – purely informational, is unused by this imageprocessor

Returns:

the mirrored or flipped image.

to(device) → MirrorFlipProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['mirror', 'flip']

class dgenerate.imageprocessors.NormalBaeProcessor(detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Normal Bae Detector, generate a normal map from an image.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Parameters:

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a normal map image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a normal map image, or the input image

NAMES = ['normal-bae']

class dgenerate.imageprocessors.OpenPoseProcessor(include_body: bool = True, include_hand: bool = False, include_face: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Generate an OpenPose rigging from the input image (of a human/humanoid) for use with a ControlNet.

“include-body” is a boolean value indicating if a body rigging should be generated.

“include-hand” is a boolean value indicating if a detailed hand/finger rigging should be generated.

“include-face” is a boolean value indicating if a detailed face rigging should be generated.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(include_body: bool = True, include_hand: bool = False, include_face: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• include_body – generate a body rig?

• include_hand – include detailed hand rigging?

• include_face – include detailed face rigging?

• pre_resize – process the image before it is resized, or after? default is after (False)

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize, OpenPose rig generation may or may not occur here depending on the boolean value of the processor argument “pre-resize”

Parameters:

image – image to process

Returns:

possibly an OpenPose rig image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize, OpenPose rig generation may or may not occur here depending on the boolean value of the processor argument “pre-resize”

Parameters:

• image – image to process

• resize_resolution – purely informational, is unused by this processor

Returns:

possibly an OpenPose rig image, or the input image

NAMES = ['openpose']

class dgenerate.imageprocessors.PidiNetProcessor(apply_filter: bool = False, safe: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

PidiNet (Pixel Difference Networks for Efficient Edge Detection) edge detector.

The “apply-filter” argument enables possibly crisper edges / less noise.

The “safe” argument enables or disables numerically safe / more precise stepping.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(apply_filter: bool = False, safe: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• apply_filter – enables possibly crisper edges / less noise

• safe – enables numerically safe / more precise stepping

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly an edge detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly an edge detected image, or the input image

NAMES = ['pidi']

class dgenerate.imageprocessors.PosterizeProcessor(bits: int, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Posterize the input image with PIL.ImageOps.posterize.

Accepts the argument ‘bits’, an integer value from 1 to 8.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(bits: int, pre_resize: bool = False, **kwargs)

Parameters:

• bits – required argument, integer value from 1 to 8

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Posterize operation is preformed by this method if pre_resize constructor argument was False.

Parameters:

image – image to process

Returns:

the posterized image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Posterize operation is preformed by this method if pre_resize constructor argument was True.

Parameters:

• image – image to process

• resize_resolution – purely informational, is unused by this imageprocessor

Returns:

the posterized image

to(device) → PosterizeProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['posterize']

class dgenerate.imageprocessors.ResizeProcessor(size: str | None = None, align: int | None = None, aspect_correct: bool = True, algo: str = 'lanczos', **kwargs)

Bases: ImageProcessor

Resize an image using basic resampling algorithms.

The “size” argument is the new image size.

The “align” argument is the new image alignment.

The “aspect-correct” argument is a boolean argument that determines if the resize is aspect correct.

The “algo” argument is the resize filtering algorithm, which can be one of: “nearest”, “box”, “bilinear”, “hamming”, “bicubic”, “lanczos”

__init__(size: str | None = None, align: int | None = None, aspect_correct: bool = True, algo: str = 'lanczos', **kwargs)

Parameters:

• loaded_by_name – The name the processor was loaded by

• device – the device the processor will run on, for example: cpu, cuda, cuda:1. Specifying None causes the device to default to cpu.

• output_file – output a debug image to this path

• output_overwrite – can the debug image output path be overwritten?

• model_offload – if True, any torch modules that the processor has registered are offloaded to the CPU immediately after processing an image

• kwargs – child class forwarded arguments

impl_post_resize(image: Image)

Preform the resize operation.

Parameters:

image – The image after being resized by dgenerate.

Returns:

The resized image.

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Does nothing, no-op.

Parameters:

• image – the image.

• resize_resolution – dimension dgenerate will resize to.

Returns:

The same image.

to(device) → ResizeProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['resize']

class dgenerate.imageprocessors.SegmentAnythingProcessor(detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Segment Anything Model, this processor attempts to creates cutouts for every distinct objects in an image.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect-resolution” before detection runs is aspect correct, this defaults to true.

The “detect-align” argument determines the pixel alignment of the image resize requested by “detect-resolution”, it defaults to 1 indicating no requested alignment.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(detect_resolution: str | None = None, detect_aspect: bool = True, detect_align: int = 1, pre_resize: bool = False, **kwargs)

Parameters:

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• detect_align – the input image is forcefully aligned to this amount of pixels before being processed.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a segment-anything image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a segment-anything image, or the input image

NAMES = ['sam']

class dgenerate.imageprocessors.SimpleColorProcessor(pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Implements the “grayscale” and “invert” PIL.ImageOps operations as an image imageprocessor.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(pre_resize: bool = False, **kwargs)

Parameters:

kwargs – forwarded to base class

static help(loaded_by_name)

impl_post_resize(image: Image)

Invert or grayscale the image depending on which name was used to invoke this imageprocessor.

Executes if pre_resize constructor argument was False.

Parameters:

image – image to process

Returns:

the inverted or grayscale image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Invert or grayscale the image depending on which name was used to invoke this imageprocessor.

Executes if pre_resize constructor argument was True.

Parameters:

• image – image to process

• resize_resolution – purely informational, is unused by this imageprocessor

Returns:

the inverted or grayscale image

to(device) → SimpleColorProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['grayscale', 'invert']

class dgenerate.imageprocessors.SolarizeProcessor(threshold: int = 128, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Solarize the input image with PIL.ImageOps.solarize.

Accepts the argument “threshold” which is an integer value from 0 to 255.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(threshold: int = 128, pre_resize: bool = False, **kwargs)

Parameters:

• threshold – integer value from 0 to 255, default is 128

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Solarize operation is preformed by this method if pre_resize constructor argument was False.

Parameters:

image – image to process

Returns:

the solarized image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Solarize operation is preformed by this method if pre_resize constructor argument was True.

Parameters:

• image – image to process

• resize_resolution – purely informational, is unused by this imageprocessor

Returns:

the solarized image

to(device) → SolarizeProcessor

Does nothing for this processor. :param device: the device :return: this processor

HIDE_ARGS = ['device', 'model-offload']

NAMES = ['solarize']

class dgenerate.imageprocessors.TEEDProcessor(safe: bool = True, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

teed, a (tiny efficient edge detector).

The “safe” argument enables or disables numerically safe / more precise stepping.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect_resolution” before detection runs is aspect correct, this defaults to true.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(safe: bool = True, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Parameters:

• safe – enables or disables numerically safe / more precise stepping

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a teed edge detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a teed edge detected image, or the input image

NAMES = ['teed']

class dgenerate.imageprocessors.UpscalerProcessor(model: str, tile: int | str = 512, overlap: int = 32, force_tiling: bool = False, dtype: str = 'float32', pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

Implements tiled upscaling with chaiNNer compatible upscaler models.

The “model” argument should be a path to a chaiNNer compatible upscaler model on disk, such as a model downloaded from https://openmodeldb.info/, or an HTTP/HTTPS URL that points to a raw model file.

For example: “upscaler;model=https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-x4v3.pth”

Downloaded models are cached in the dgenerate web cache on disk until the cache expiry time for the file is met.

The “tile” argument can be used to specify the tile size for tiled upscaling, it must be divisible by 2, and defaults to 512. Specifying ‘auto’ indicates that this value should be calculated based off available GPU memory if applicable. Specifying 0 disables tiling entirely.

The “overlap” argument can be used to specify the overlap amount of each tile in pixels, it must be greater than or equal to 0, and defaults to 32.

The “force-tiling” argument can be used to force external image tiling for upscaler model architectures which discourage the use of external tiling (SCUNEt and MixDehazeNet currently), this may mean that the model needs information about the whole image to achieve a good result. External tiling breaks up the image into tiles before feeding it to the model and reassembles the images output by the model, this is not the default behavior when a model specifies that tiling is discouraged, tiling is only on by default for models where external tiling is fully supported. Only use this if you run into memory issues with models that discourage external tiling, in the case that the model discourages its use, using it may result in substandard image output.

The “dtype” argument can be used to specify the datatype to use to for the model in memory, it can be either “float32” or “float16”. Using “float16” will result in a smaller memory footprint if supported.

The “pre-resize” argument is a boolean value determining if the processing should take place before or after the image is resized by dgenerate.

Example: “upscaler;model=my-model.pth;tile=256;overlap=16”

__init__(model: str, tile: int | str = 512, overlap: int = 32, force_tiling: bool = False, dtype: str = 'float32', pre_resize: bool = False, **kwargs)

Parameters:

• model – chaiNNer compatible upscaler model on disk, or at a URL

• tile – specifies the tile size for tiled upscaling, it must be divisible by 2, and defaults to 512. Specifying ‘auto’ indicates that this value should be calculated based off available GPU memory if applicable. Specifying 0 disable tiling entirely.

• overlap – the overlap amount of each tile in pixels, it must be greater than or equal to 0, and defaults to 32.

• dtype – the datatype to use to for the model in memory, it may be either “float32” or “float16”. using float16 will result in a smaller memory footprint if supported.

• force_tiling – Force external image tiling for model architectures that discourage it.

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Implementation of post_resize that does nothing. Inheritor must implement.

This method should not be invoked directly, use the class method ImageProcessor.call_post_resize() to invoke it.

Parameters:

image – image to process

Returns:

the processed image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None) → Image

Implementation of pre_resize that does nothing. Inheritor must implement.

This method should not be invoked directly, use the class method ImageProcessor.call_pre_resize() to invoke it.

Parameters:

• image – image to process

• resize_resolution – image will be resized to this resolution after this process is complete. If None is passed no resize is going to occur. It is not the duty of the inheritor to resize the image, in fact it should NEVER be resized.

Returns:

the processed image

NAMES = ['upscaler']

class dgenerate.imageprocessors.ZoeDepthProcessor(gamma_corrected: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Bases: ImageProcessor

zoe depth detector, a SOTA depth estimation model which produces high-quality depth maps.

The “gamma-corrected” argument determines if gamma correction is preformed on the produced depth math.

The “detect-resolution” argument is the resolution the image is resized to internal to the processor before detection is run on it. It should be a single dimension for example: “detect-resolution=512” or the X/Y dimensions seperated by an “x” character, like so: “detect-resolution=1024x512”. If you do not specify this argument, the detector runs on the input image at its full resolution. After processing the image will be resized to whatever you have requested dgenerate resize it to via –output-size or –resize/–align in the case of the image-process sub-command, if you have not requested any resizing the output will be resized back to the original size of the input image.

The “detect-aspect” argument determines if the image resize requested by “detect_resolution” before detection runs is aspect correct, this defaults to true.

The “pre-resize” argument determines if the processing occurs before or after dgenerate resizes the image. This defaults to False, meaning the image is processed after dgenerate is done resizing it.

__init__(gamma_corrected: bool = False, detect_resolution: str | None = None, detect_aspect: bool = True, pre_resize: bool = False, **kwargs)

Parameters:

• gamma_corrected – perform gamma correction on the depth map?

• detect_resolution – the input image is resized to this dimension before being processed, providing None indicates it is not to be resized. If there is no resize requested during the processing action via resize_resolution it will be resized back to its original size.

• detect_aspect – if the input image is resized by detect_resolution or detect_align before processing, will it be an aspect correct resize?

• pre_resize – process the image before it is resized, or after? default is False (after).

• kwargs – forwarded to base class

impl_post_resize(image: Image)

Post resize.

Parameters:

image – image

Returns:

possibly a zoe depth detected image, or the input image

impl_pre_resize(image: Image, resize_resolution: tuple[int, int] | None)

Pre resize.

Parameters:

• image – image to process

• resize_resolution – resize resolution

Returns:

possibly a zoe depth detected image, or the input image

NAMES = ['zoe']

dgenerate.imageprocessors.image_processor_help(names: Sequence[str], plugin_module_paths: Sequence[str] | None = None, throw=False, log_error=True)

Implements --image-processor-help command line option

Parameters:

• names – arguments (processor names, or empty list)

• plugin_module_paths – extra plugin module paths to search

• throw – throw on error? or simply print to stderr and return a return code.

• log_error – log errors to stderr?

Raises:

• ImageProcessorNotFoundError –

• dgenerate.ModuleFileNotFoundError –

Returns:

return-code, anything other than 0 is failure

dgenerate.imageprocessors.IMAGE_PROCESSOR_CUDA_MEMORY_CONSTRAINTS = ['processor_size > (available * 0.70)']

Cache constraint expressions for when to attempt to fully clear cuda VRAM before moving an image processor on to a cuda device, syntax provided via dgenerate.memory.cuda_memory_constraints()

If any of these constraints are met, an effort is made to clear modules off the GPU which are cached for fast repeat usage but are okay to flush, prior to moving an image processor to the GPU.

The only available extra variable is: pipeline_size (the estimated size of the image processor module that needs to enter VRAM, in bytes)

dgenerate.imageprocessors.IMAGE_PROCESSOR_MEMORY_CONSTRAINTS = ['processor_size > (available * 0.70)']

Cache constraint expressions for when to attempt to fully clear CPU side ram before the initial loading of an image processor module into ram, syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, an effort is made to clear modules out of cpu side ram which are cached for fast repeat usage but are okay to flush, prior to loading an image processor model.

The only available extra variable is: pipeline_size (the estimated size of the image processor module that needs to enter ram, in bytes)

dgenerate.invoker module

Functions to invoke dgenerate inside the current process using its command line arguments.

class dgenerate.invoker.DgenerateExitEvent(origin, return_code: int)

Bases: Event

Generated in the event stream created by invoke_dgenerate_events()

Exit with return code event for invoke_dgenerate_events()

__init__(origin, return_code: int)

return_code: int

dgenerate.invoker.invoke_dgenerate(args: Sequence[str], render_loop: RenderLoop | None = None, throw: bool = False, log_error: bool = True, help_raises: bool = False) → int

Invoke dgenerate using its command line arguments and return a return code.

dgenerate is invoked in the current process, this method does not spawn a subprocess.

Meta arguments such as --file, --shell, --no-stdin, and --console are not supported

Parameters:

• args – dgenerate command line arguments in the form of a list, see: shlex module, or sys.argv

• render_loop – dgenerate.renderloop.RenderLoop instance, if None is provided one will be created.

• throw – Whether to throw known exceptions or handle them.

• log_error – Write ERROR diagnostics with dgenerate.messages?

• help_raises – --help raises dgenerate.arguments.DgenerateHelpException ? When True, this will occur even if throw=False

Raises:

• dgenerate.DgenerateUsageError –

• dgenerate.DgenerateHelpException –

• dgenerate.ImageSeedError –

• dgenerate.UnknownMimetypeError –

• dgenerate.MediaIdentificationError –

• dgenerate.FrameStartOutOfBounds –

• dgenerate.InvalidModelFileError –

• dgenerate.InvalidModelUriError –

• dgenerate.ModelUriLoadError –

• dgenerate.InvalidSchedulerNameError –

• dgenerate.OutOfMemoryError –

• dgenerate.ModelNotFoundError –

• dgenerate.NonHFModelDownloadError –

• dgenerate.UnsupportedPipelineConfigError –

• dgenerate.PromptWeightingUnsupported –

• dgenerate.PluginNotFoundError –

• dgenerate.PluginArgumentError –

• dgenerate.ModuleFileNotFoundError –

• OSError –

Returns:

integer return-code, anything other than 0 is failure

dgenerate.invoker.invoke_dgenerate_events(args: Sequence[str], render_loop: RenderLoop | None = None, throw: bool = False, log_error: bool = True, help_raises: bool = False) → Generator[ImageGeneratedEvent | StartingAnimationEvent | StartingAnimationFileEvent | AnimationFileFinishedEvent | ImageFileSavedEvent | AnimationFinishedEvent | StartingGenerationStepEvent | AnimationETAEvent | DgenerateExitEvent, None, None]

Invoke dgenerate using its command line arguments and return a stream of events, you must iterate over this stream of events to progress through the execution of dgenerate.

dgenerate is invoked in the current process, this method does not spawn a subprocess.

Meta arguments such as --file, --shell, --no-stdin, and --console are not supported

The exceptions mentioned here are those you may encounter upon iterating, they will not occur upon simple acquisition of the event stream iterator.

Parameters:

• args – dgenerate command line arguments in the form of a list, see: shlex module, or sys.argv

• render_loop – dgenerate.renderloop.RenderLoop instance, if None is provided one will be created.

• throw – Whether to throw known exceptions or handle them.

• log_error – Write ERROR diagnostics with dgenerate.messages?

• help_raises – --help raises dgenerate.arguments.DgenerateHelpException ? When True, this will occur even if throw=False

Raises:

• dgenerate.DgenerateUsageError –

• dgenerate.DgenerateHelpException –

• dgenerate.ImageSeedError –

• dgenerate.UnknownMimetypeError –

• dgenerate.MediaIdentificationError –

• dgenerate.FrameStartOutOfBounds –

• dgenerate.InvalidModelFileError –

• dgenerate.InvalidModelUriError –

• dgenerate.ModelUriLoadError –

• dgenerate.InvalidSchedulerNameError –

• dgenerate.OutOfMemoryError –

• dgenerate.ModelNotFoundError –

• dgenerate.NonHFModelDownloadError –

• dgenerate.UnsupportedPipelineConfigError –

• dgenerate.PromptWeightingUnsupported –

• dgenerate.PluginNotFoundError –

• dgenerate.PluginArgumentError –

• dgenerate.ModuleFileNotFoundError –

• OSError –

Returns:

InvokeDgenerateEventStream

dgenerate.invoker.InvokeDgenerateEventStream

Event stream produced by invoke_dgenerate_events()

alias of Generator[Union[ImageGeneratedEvent, StartingAnimationEvent, StartingAnimationFileEvent, AnimationFileFinishedEvent, ImageFileSavedEvent, AnimationFinishedEvent, StartingGenerationStepEvent, AnimationETAEvent, DgenerateExitEvent], None, None]

dgenerate.invoker.InvokeDgenerateEvents

Events yield-able by invoke_dgenerate_events()

alias of Union[ImageGeneratedEvent, StartingAnimationEvent, StartingAnimationFileEvent, AnimationFileFinishedEvent, ImageFileSavedEvent, AnimationFinishedEvent, StartingGenerationStepEvent, AnimationETAEvent, DgenerateExitEvent]

dgenerate.mediainput module

Media input, handles reading videos/animations and static images, and creating readers from image seed URIs.

Also provides media download capabilities and temporary caching of web based files.

Provides information about supported input formats.

exception dgenerate.mediainput.FrameStartOutOfBounds

Bases: ValueError

Raised by MultiMediaReader when the provided frame_start frame slicing value is calculated to be out of bounds.

exception dgenerate.mediainput.ImageSeedArgumentError

Bases: ImageSeedError

Raised when image seed URI keyword arguments receive invalid values.

exception dgenerate.mediainput.ImageSeedError

Bases: Exception

Raised on image seed parsing and loading errors.

exception dgenerate.mediainput.ImageSeedFileNotFoundError

Bases: ImageSeedError

Raised when a file on disk in an image seed could not be found.

exception dgenerate.mediainput.ImageSeedParseError

Bases: ImageSeedError

Raised on image seed syntactic parsing error.

exception dgenerate.mediainput.ImageSeedSizeMismatchError

Bases: ImageSeedError

Raised when the constituent image sources of an image seed specification are mismatched in dimension.

exception dgenerate.mediainput.MediaIdentificationError

Bases: Exception

Raised when a media file is being loaded and it fails to load due to containing invalid or unexpected data.

exception dgenerate.mediainput.UnknownMimetypeError

Bases: Exception

Raised when an unsupported mimetype is encountered

class dgenerate.mediainput.AnimatedImageReader(file: str | BinaryIO, file_source: str, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_processor: ImageProcessor = None)

Bases: ImageProcessorMixin, AnimationReader

Implementation of AnimationReader that reads animated image formats using Pillow.

All frames from this animation reader will be aligned by 8 pixels by default.

__init__(file: str | BinaryIO, file_source: str, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_processor: ImageProcessor = None)

Parameters:

• file – a file path or binary file stream

• file_source – the source filename for the animated image, should be the filename. this is for informational purpose when reading from a stream or a cached file and should be provided in every case even if it is a symbolic value only. It should possess a file extension. PIL.Image.Image objects produced by the reader will have this value set to their filename attribute.

• resize_resolution – Progressively resize each frame to this resolution while reading. The provided resolution will be aligned by align if it is not None.

• aspect_correct – Should resize operations be aspect correct?

• align – Align by this amount of pixels, if the input file is not aligned to this amount of pixels, it will be aligned by resizing. Passing None or 1 disables alignment.

• image_processor – optionally process every frame with this image processor

Raises:

MediaIdentificationError – If the animated image data is an unknown format or corrupt.

class dgenerate.mediainput.AnimationReader(width: int, height: int, fps: float, frame_duration: float, total_frames: int, **kwargs)

Bases: object

Abstract base class for animation readers.

__init__(width: int, height: int, fps: float, frame_duration: float, total_frames: int, **kwargs)

Parameters:

• width – width of the animation, X dimension

• height – height of the animation, Y dimension

• fps – frames per second

• frame_duration – frame duration in milliseconds

• total_frames – total frames in the animation

• kwargs – for mixins

property fps: float

Frames per second.

property frame_duration: float

Duration of each frame in milliseconds.

property height: int

Height dimension, (Y dimension).

property size: tuple[int, int]

returns (width, height) as a tuple.

property total_frames: int

Total number of frames that can be read.

property width: int

Width dimension, (X dimension).

class dgenerate.mediainput.IPAdapterImageUri(path, resize, aspect, align)

Bases: object

__init__(path, resize, aspect, align)

align: int

Pixel alignment, defaults to 1.

aspect: bool

Aspect correct resizing?

path: str

File path or URL to an image.

resize: str | None

Image resize dimension in the form WIDTHxHEIGHT or WIDTH

scale: float

IP Adapter image scale value.

class dgenerate.mediainput.ImageSeed(images: Image | None = None, mask_images: Image | None = None, control_images: Sequence[Image] | None = None, floyd_image: Image | None = None, adapter_images: list[Sequence[Image]] | None = None)

Bases: object

An ImageSeed with attached image data

__init__(images: Image | None = None, mask_images: Image | None = None, control_images: Sequence[Image] | None = None, floyd_image: Image | None = None, adapter_images: list[Sequence[Image]] | None = None)

adapter_images: Sequence[Sequence[Image]] | None

IP Adapter images, or None.

control_images: Sequence[Image] | None

Control guidance images, or None.

floyd_image: Image | None

An optional image from a Deep Floyd IF stage, used for disambiguation in the case of using Deep Floyd for img2img and inpainting, where the un-varied input image is needed as a parameter for both stages. This image is used to define the image that was generated by Deep Floyd in a previous stage and to be used in the next stage, where ImageSeed.image defines the img2img image that you want a variation of.

This image will never be assigned a value when ImageSeed.control_images has a a value. As that is considered incorrect –image-seeds

fps: float | None = None

Frames per second in the case that ImageSeed.is_animation_frame is True

frame_duration: float | None = None

Duration of a frame in milliseconds in the case that ImageSeed.is_animation_frame is True

frame_index: int | None = None

Frame index in the case that ImageSeed.is_animation_frame is True

images: Sequence[Image] | None

An optional images used for img2img mode, or inpainting mode in combination with ImageSeed.mask_images.

May be None when using IP Adapter only images, IE: the adapter: ... uri syntax.

is_animation_frame: bool

Is this part of an animation?

mask_images: Sequence[Image] | None

An optional inpaint mask images, may be None.

total_frames: int | None = None

Total frame count in the case that ImageSeed.is_animation_frame is True

uri: str

The original URI string that this image seed originates from.

class dgenerate.mediainput.ImageSeedInfo(is_animation: bool, total_frames: int | None, fps: float | None, frame_duration: float | None)

Bases: object

Information acquired about an --image-seeds uri

__init__(is_animation: bool, total_frames: int | None, fps: float | None, frame_duration: float | None)

fps: float | None

Animation frames per second in the case that ImageSeedInfo.is_animation is True

frame_duration: float | None

Animation frame duration in milliseconds in the case that ImageSeedInfo.is_animation is True

is_animation: bool

Does this image seed specification result in an animation?

total_frames: int | None

Animation frame count in the case that ImageSeedInfo.is_animation is True

class dgenerate.mediainput.ImageSeedParseResult

Bases: object

The result of parsing an --image-seeds uri

get_control_image_paths() → Sequence[str] | None

Return ImageSeedParseResult.seed_path if ImageSeedParseResult.is_single_spec is True.

If the image seed is not a single specification, return ImageSeedParseResult.control_path.

If ImageSeedParseResult.control_path is not set and the image seed is not a single specification, return None.

Returns:

list of resource paths, or None

adapter_images: Sequence[Sequence[IPAdapterImageUri]] | None = None

IP Adapter image URIs.

In parses such as:

• --image-seeds "adapter: adapter-image1.png + adapter-image2.png"

• --image-seeds "adapter: adapter-image1.png + adapter-image2.png;control=control.png"

• --image-seeds "img2img.png;adapter=adapter-image1.png + adapter-image2.png"

• --image-seeds "img2img.png;adapter=adapter-image1.png + adapter-image2.png;control=control.png"

• --image-seeds "img2img.png;adapter=adapter-image1.png + adapter-image2.png;mask=inpaint-mask.png;control=control.png"

aspect_correct: bool | None = None

Aspect correct resize setting override from the aspect image seed keyword argument, if this is None it was not specified. This value if defined should override any globally defined aspect correct resize setting.

control_images: Sequence[str] | None = None

Optional controlnet guidance path, or a sequence of controlnet guidance paths. This field is only used when the secondary syntax of --image-seeds is encountered.

IE: This parameter is only filled if the keyword argument control is used.

In parses such as:

• --image-seeds "img2img.png;control=control.png"

• --image-seeds "img2img.png;control=control1.png, control2.png"

• --image-seeds "img2img.png;mask=mask.png;control=control.png"

• --image-seeds "img2img.png;mask=mask.png;control=control1.png, control2.png"

floyd_image: str | None = None

Optional path to a result from a Deep Floyd IF stage, used only for img2img and inpainting mode with Deep Floyd. This is the only way to specify the image that was output by a stage in that case.

the arguments floyd and control are mutually exclusive.

In parses such as:

• --image-seeds "img2img.png;floyd=stage1-output.png"

• --image-seeds "img2img.png;mask=mask.png;floyd=stage1-output.png"

There can only ever be one floyd stage image provided.

frame_end: int | None = None

Optional end frame specification for per-image seed slicing.

frame_start: int | None = None

Optional start frame specification for per-image seed slicing.

property has_ip_adapter_images: bool

images: Sequence[str] | None

Optional image paths that will be used for img2img operations or the base image in inpaint operations.

Or controlnet guidance paths, in the case that images: ... syntax is not being used (multi_image_mode==False) and there are multiple provided images, and is_single_spec is True.

A path being a file path, or an HTTP/HTTPS URL.

property is_single_spec: bool

Is this --image-seeds uri a single resource or resource group specification existing within the seed_path attribute of this object?

For instance could it be a img2img definition / sequence of img2img images using the images: ... syntax, or a sequence of controlnet guidance images?

This requires that mask_images, control_images, floyd_image, adapter_images are all undefined.

Possible parses which trigger this condition are:

• --image-seeds "img2img.png"

• --image-seeds "control-image.png"

• --image-seeds "control-image1.png, control-image2.png"

• --image-seeds "images: img2img-1.png, img2img-2.png"

Since this is an ambiguous parse, it must be resolved later with the help of other specified arguments. Such as by the specification of --control-nets, which makes the intention unambiguous.

Returns:

bool

mask_images: Sequence[str] | None = None

Optional inpaint mask paths, may be HTTP/HTTPS URLs or file paths.

This may be multiple masks when there are multiple img2img image paths, for example: --image-seeds "images: image1.png, image2.png; mask1.png, mask2.png"

There will always be an equal number of images and mask images.

If a single mask is supplied for multiple images, the mask path is duplicated to match the amount of images.

multi_image_mode: bool

Are there multiple img2img images associated with this image seed?

This indicates that --image-seeds "images: image1.png, image2.png" syntax was used, in order to differentiate from a control image sequence specification.

resize_resolution: tuple[int, int] | None = None

Per image user specified resize resolution for image, mask, and control image components of the --image-seed specification.

This field available in parses such as:

• --image-seeds "img2img.png;512x512"

• --image-seeds "img2img.png;mask.png;512x512"

• --image-seeds "img2img.png;control=control.png;resize=512x512"

• --image-seeds "img2img.png;control=control1.png, control2.png;resize=512x512"

• --image-seeds "img2img.png;mask=mask.png;control=control.png;resize=512x512"

• --image-seeds "img2img.png;mask=mask.png;control=control1.png, control2.png;resize=512x512"

This should override any globally defined resize value.

uri: str

The original URI string the image seed was parsed from.

class dgenerate.mediainput.MediaReader(path: str, image_processor: ~dgenerate.imageprocessors.imageprocessor.ImageProcessor | None = None, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, frame_start: int = 0, frame_end: int | None = None, path_opener: ~typing.Callable[[str], ~typing.BinaryIO] = <function fetch_media_data_stream>)

Bases: AnimationReader

Thin wrapper around MultiMediaReader which simply reads from a single file instead of multiple files simultaneously.

The interface provided by this object is that of AnimationReader

This object can read any media supported by dgenerate for input and supports frame slicing animated media formats and image processors.

Static images are treated as an animation with a single frame.

With the default path opener, URLs will be downloaded, dgenerates temporary web cache will be utilized.

All images produced from this reader will be aligned to 8 pixels by default.

__init__(path: str, image_processor: ~dgenerate.imageprocessors.imageprocessor.ImageProcessor | None = None, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, frame_start: int = 0, frame_end: int | None = None, path_opener: ~typing.Callable[[str], ~typing.BinaryIO] = <function fetch_media_data_stream>)

Raises:

• ValueError – if frame_start > frame_end

• FrameStartOutOfBounds – if frame_start > total_frames - 1

Parameters:

• path – File path or URL

• resize_resolution – Resize resolution

• aspect_correct – Aspect correct resize enabled?

• align – Images which are read are aligned to this amount of pixels, None or 1 will disable alignment.

• image_processor – Optional image image processor associated with the file

• frame_start – inclusive frame slice start frame

• frame_end – inclusive frame slice end frame

• path_opener – opens a binary file stream from paths.

property frame_end: int

Frame slice end value (inclusive)

property frame_index: int

Current frame index while reading.

property frame_start: int

Frame slice start value (inclusive)

class dgenerate.mediainput.MediaReaderSpec(path: str, image_processor: ImageProcessor | None = None, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8)

Bases: object

Used by MultiMediaReader to define resource paths.

__init__(path: str, image_processor: ImageProcessor | None = None, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8)

Parameters:

• path – File path or URL

• resize_resolution – Resize resolution

• aspect_correct – Aspect correct resize enabled?

• align – Images which are read are aligned to this amount of pixels, None or 1 will disable alignment.

• image_processor – Optional image image processor associated with the file

align: int | None = 8

Images which are read are aligned to this amount of pixels, None or 1 will disable alignment.

aspect_correct: bool = True

Aspect correct resize enabled?

image_processor: ImageProcessor | None = None

Optional image image processor associated with the file

path: str

File path (or HTTP/HTTPS URL with default path_opener)

resize_resolution: tuple[int, int] | None = None

Optional resize resolution.

class dgenerate.mediainput.MockImageAnimationReader(img: Image, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_repetitions: int = 1, image_processor: ImageProcessor = None)

Bases: ImageProcessorMixin, AnimationReader

Implementation of AnimationReader that repeats a single PIL image as many times as desired in order to mock/emulate an animation.

All frame images from this animation reader will be aligned by 8 pixels by default.

__init__(img: Image, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_repetitions: int = 1, image_processor: ImageProcessor = None)

Parameters:

• img – source image to copy for each frame, the image is immediately copied once upon construction of the mock reader, and then once per frame thereafter. Your copy of the image can be disposed of after the construction of this object.

• resize_resolution – the source image will be resized to this dimension with a maintained aspect ratio. This occurs once upon construction, a copy is then yielded for each frame that is read. The provided resolution will be aligned by align if it is not None.

• aspect_correct – Should resize operations be aspect correct?

• align – Align by this amount of pixels, if the input file is not aligned to this amount of pixels, it will be aligned by resizing. Passing None or 1 disables alignment.

• image_repetitions – number of frames that this mock reader provides using a copy of the source image.

• image_processor – optionally process the initial image with this image processor, this occurs once.

property total_frames: int

Settable total_frames property.

Returns:

frame count

class dgenerate.mediainput.MultiMediaReader(specs: list[~dgenerate.mediainput.MediaReaderSpec], frame_start: int = 0, frame_end: int | None = None, path_opener: ~typing.Callable[[str], ~typing.BinaryIO] = <function fetch_media_data_stream>)

Bases: object

Zips together multiple automatically created AnimationReader implementations and allows enumeration over their reads, which are collected into a list of a defined order.

Images when zipped together with animated files will be repeated over the total amount of frames.

The animation with the lowest amount of frames determines the total amount of frames that can be read when animations are involved.

If all paths point to images, then MultiMediaReader.total_frames will be 1.

There is no guarantee that images read from the individual readers are the same size and you must handle that condition.

__init__(specs: list[~dgenerate.mediainput.MediaReaderSpec], frame_start: int = 0, frame_end: int | None = None, path_opener: ~typing.Callable[[str], ~typing.BinaryIO] = <function fetch_media_data_stream>)

Raises:

• ValueError – if frame_start > frame_end

• FrameStartOutOfBounds – if frame_start > total_frames - 1

Parameters:

• specs – list of MediaReaderSpec

• frame_start – inclusive frame slice start frame

• frame_end – inclusive frame slice end frame

• path_opener – opens a binary file stream from paths mentioned by MediaReaderSpec

height(idx) → int

Height dimension, (Y dimension) of a specific reader index.

Returns:

height

size(idx) → tuple[int, int]

returns (width, height) as a tuple of a specific reader index.

Returns:

(width, height)

width(idx) → int

Width dimension, (X dimension) of a specific reader index.

Returns:

width

property fps: float | None

Frames per second, this will be None if there is only a single frame

property frame_duration: float | None

Duration of a frame in milliseconds, this will be None if there is only a single frame

property frame_end: int

Frame slice end value (inclusive)

property frame_index: int

Current frame index while reading.

property frame_start: int

Frame slice start value (inclusive)

property total_frames: int

Total number of frames readable from this reader.

class dgenerate.mediainput.VideoReader(file: str | BinaryIO, file_source: str, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_processor: ImageProcessor = None)

Bases: ImageProcessorMixin, AnimationReader

Implementation AnimationReader that reads Video files with PyAV.

All frame images from this animation reader will be aligned by 8 pixels by default.

__init__(file: str | BinaryIO, file_source: str, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_processor: ImageProcessor = None)

Parameters:

• file – a file path or binary file stream

• file_source – the source filename for the video data, should be the filename. this is for informational purpose when reading from a stream or a cached file and should be provided in every case even if it is a symbolic value only. It should possess a file extension as it is used to determine file format when reading from a byte stream. PIL.Image.Image objects produced by the reader will have this value set to their filename attribute.

• resize_resolution – Progressively resize each frame to this resolution while reading. The provided resolution will be aligned by align if it is not None.

• aspect_correct – Should resize operations be aspect correct?

• align – Align by this amount of pixels, if the input file is not aligned to this amount of pixels, it will be aligned by resizing. Passing None or 1 disables alignment.

• image_processor – optionally process every frame with this image processor

Raises:

• ValueError – if file_source lacks a file extension, it is needed to determine the video file format.

• MediaIdentificationError – If the video data is an unknown format or corrupt.

dgenerate.mediainput.create_animation_reader(mimetype: str, file_source: str, file: BinaryIO, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_processor: ImageProcessor | None = None) → AnimationReader

Create an animation reader object from mimetype specification and binary file stream.

Images will return a MockImageAnimationReader with a total_frames value of 1, which can then be adjusted by you.

VideoReader or AnimatedImageReader will be returned for Video files and Animated Images respectively.

Raises:

• UnknownMimetypeError – on unknown mimetype value

• MediaIdentificationError – If the file data is an unknown format or corrupt.

Parameters:

• mimetype – one of get_supported_mimetypes()

• file – the binary file stream

• file_source – the source filename for videos/animated images, should be the filename. this is for informational purpose and should be provided in every case even if it is a symbolic value only. It should possess a file extension. PIL.Image.Image objects produced by the reader will have this value set to their filename attribute.

• resize_resolution – Progressively resize each frame to this resolution while reading. The provided resolution will be aligned by align pixels.

• align – Align by this amount of pixels, if the input file is not aligned to this amount of pixels, it will be aligned by resizing. Passing None or 1 disables alignment.

• aspect_correct – Should resize operations be aspect correct?

• image_processor – optionally process every frame with this image processor

Returns:

AnimationReader

dgenerate.mediainput.create_image(path_or_file: BinaryIO | str, file_source: str, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8) → Image

Create an RGB format PIL image from a file path or binary file stream. The image is oriented according to any EXIF directives. Image is aligned to align in every case, specifying None or 1 for align disables alignment.

Raises:

MediaIdentificationError – If the image data is an unknown format or corrupt.

Parameters:

• path_or_file – file path or binary IO object

• file_source – PIL.Image.Image.filename is set to this value

• resize_resolution – Optional resize resolution

• aspect_correct – preserve aspect ratio when resize_resolution is specified?

• align – Align the image by this amount of pixels, None or 1 indicates no alignment.

Returns:

PIL.Image.Image

dgenerate.mediainput.create_web_cache_file(url, mime_acceptable_desc: str | None = None, mimetype_is_supported: ~typing.Callable[[str], bool] | None = <function mimetype_is_supported>) → tuple[str, str]

Download a file from a url and add it to dgenerates temporary web cache that is available to all concurrent dgenerate processes.

If the file exists in the cache already, return information for the existing file.

Parameters:

• url – The url

• mime_acceptable_desc – a string describing what mimetype values are acceptable which is used when UnknownMimetypeError is raised. If None is provided, this string will be generated using get_supported_mimetypes()

• mimetype_is_supported – a function that test if a mimetype string is supported, if you supply the value None all mimetypes are considered supported.

Raises:

• UnknownMimetypeError – if a mimetype is considered not supported

• requests.RequestException – Can raise any exception raised by requests.get for request related errors.

Returns:

tuple(mimetype_str, filepath)

dgenerate.mediainput.fetch_media_data_stream(uri: str) → tuple[str, BinaryIO]

Get an open stream to a local file, or file at an HTTP or HTTPS URL, with caching for web files.

Caching for downloaded files is multiprocess safe, multiple processes using this module can share the cache simultaneously, the last process alive clears the cache when it exits.

Parameters:

uri – Local file path or URL

Raises:

UnknownMimetypeError – If a remote file serves an unsupported mimetype value

Returns:

(mime-type string, BinaryIO)

dgenerate.mediainput.frame_slice_count(total_frames: int, frame_start: int, frame_end: int | None = None) → int

Calculate the number of frames resulting from frame slicing.

Parameters:

• total_frames – Total frames being sliced from

• frame_start – The start frame

• frame_end – The end frame

Returns:

int

dgenerate.mediainput.get_control_image_info(uri: str | ImageSeedParseResult, frame_start: int = 0, frame_end: int | None = None) → ImageSeedInfo

Get an informational object from a dgenerate --image-seeds uri that is known to be a control image/video specification.

This can consist of a single resource path or a list of comma separated image and video resource paths, which may be files on disk or remote files (http / https).

This method is to be used when it is known that there is only a control image/video specification in the path, and it handles this specification syntax:

• --image-seeds "control1.png"

• --image-seeds "control1.png, control2.png"

Parameters:

• uri – The path string or ImageSeedParseResult

• frame_start – slice start

• frame_end – slice end

Returns:

ImageSeedInfo

dgenerate.mediainput.get_image_seed_info(uri: str | ImageSeedParseResult, frame_start: int = 0, frame_end: int | None = None) → ImageSeedInfo

Get an informational object from a dgenerate --image-seeds uri.

Parameters:

• uri – The uri string or ImageSeedParseResult

• frame_start – slice start

• frame_end – slice end

Returns:

ImageSeedInfo

dgenerate.mediainput.get_supported_animated_image_mimetypes() → list[str]

Get a list of mimetypes that are considered to be supported animated image mimetypes.

Returns:

list of mimetype strings.

dgenerate.mediainput.get_supported_animation_reader_formats()

Supported animation reader formats, file extensions with no period.

Returns:

list of file extensions.

dgenerate.mediainput.get_supported_image_formats()

What file extensions does PIL/Pillow support for reading?

File extensions are returned without a period.

Returns:

list of file extensions

dgenerate.mediainput.get_supported_image_mimetypes() → list[str]

Get all supported --image-seeds image mimetypes, including animated image mimetypes

Returns:

list of strings

dgenerate.mediainput.get_supported_mimetypes() → list[str]

Get all supported --image-seeds mimetypes, video mimetype may contain a wildcard.

Returns:

list of strings

dgenerate.mediainput.get_supported_static_image_mimetypes() → list[str]

Get a list of mimetypes that are considered to be supported static image mimetypes.

Returns:

list of mimetype strings.

dgenerate.mediainput.get_supported_video_mimetypes() → list[str]

Get all supported --image-seeds video mimetypes, may contain a wildcard

Returns:

list of strings

dgenerate.mediainput.get_web_cache_directory() → str

Get the default web cache directory or the value of the environmental variable DGENERATE_WEB_CACHE

Returns:

string (directory path)

dgenerate.mediainput.guess_mimetype(filename) → str | None

Guess the mimetype of a filename.

The filename does not need to exist on disk.

Parameters:

filename – the file name

Returns:

mimetype string or None

dgenerate.mediainput.is_downloadable_url(string) → bool

Does a string represent a URL that can be downloaded from by dgenerate.mediainput?

Parameters:

string – the string

Returns:

True or False

dgenerate.mediainput.iterate_control_image(uri: str | ImageSeedParseResult, frame_start: int = 0, frame_end: int | None = None, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, image_processor: ImageProcessor | Sequence[ImageProcessor] | None = None) → Iterator[ImageSeed]

Parse and load a control image/video in an --image-seeds uri and return an iterator that produces ImageSeed objects while progressively reading that file.

One or more ImageSeed objects may be yielded depending on whether an animation is being read.

This can consist of a single resource path or a list of comma separated image and video resource paths, which may be files on disk or remote files (http / https).

This method is to be used when it is known that there is only a controlnet guidance resource specification in the path, and it handles this specification syntax:

• --image-seeds "control1.png"

• --image-seeds "control1.png, control2.png"

• --image-seeds "control1.png, control2.png;512x512"

• --image-seeds "control1.png, control2.png;resize=512x512"

• --image-seeds "control1.png, control2.png;frame-start=2"

• --image-seeds "control1.png, control2.png;frame-start=2;frame-end=10"

• --image-seeds "control1.png, control2.png;resize=512x512;frame-start=2;frame-end=10"

The image or images read will be available from the ImageSeed.control_images attribute.

Parameters:

• uri – --image-seeds uri or ImageSeedParseResult

• frame_start – starting frame, inclusive value

• frame_end – optional end frame, inclusive value

• resize_resolution – optional global resize resolution. The URI syntax of image seeds allows for overriding this value.

• aspect_correct – should the global resize operation be aspect correct by default? The URI syntax for image seeds allows for overriding this value with the aspect keyword argument.

• align – Images which are read are aligned to this amount of pixels, None or 1 will disable alignment.

• image_processor – optional dgenerate.imageprocessors.ImageProcessor or list of them. A list is used to specify processors for individual images in a multi guidance image specification such as uri = “img1.png, img2.png”. In the case that a multi guidance image specification is used and only one processor is given, that processor will be used on only the first image / video in the specification. Images in a guidance specification with no corresponding processor value will have their processor set to None, specifying extra processors as compared to control guidance image sources will cause ValueError to be raised.

Raises:

ValueError – if there are more image_processor values than there are control guidance image sources in the URI.

Returns:

an iterator over ImageSeed objects

dgenerate.mediainput.iterate_image_seed(uri: str | ImageSeedParseResult, frame_start: int = 0, frame_end: int | None = None, resize_resolution: tuple[int, int] | None = None, aspect_correct: bool = True, align: int | None = 8, seed_image_processor: ImageProcessor | Sequence[ImageProcessor] | None = None, mask_image_processor: ImageProcessor | Sequence[ImageProcessor] | None = None, control_image_processor: ImageProcessor | Sequence[ImageProcessor] | None = None, check_dimensions_match: bool = True) → Iterator[ImageSeed]

Parse and load images/videos in an --image-seeds uri and return an iterator that produces ImageSeed objects while progressively reading those files.

This method is used to iterate over an --image-seeds uri in the case that the image source mentioned is to be used for img2img / inpaint operations, and handles this syntax:

• --image-seeds "img2img.png"

• --image-seeds "img2img.png;mask.png"

• --image-seeds "img2img.png;mask.png;512x512"

• --image-seeds "images: img2img-1.png, img2img-2.png"

• --image-seeds "images: img2img-1.png, img2img-2.png; mask1.png, mask2.png"

• --image-seeds "images: img2img-1.png, img2img-2.png; mask1.png, mask2.png;512"

Additionally, controlnet guidance resources are handled with keyword arguments:

• --image-seeds "img2img.png;control=control1.png, control2.png"

• --image-seeds "img2img.png;control=control1.png, control2.png;resize=512x512"

• --image-seeds "img2img.png;mask=mask.png;control=control1.png, control2.png"

• --image-seeds "img2img.png;mask=mask.png;control=control1.png, control2.png;resize=512x512"

• --image-seeds "img2img.png;mask=mask.png;control=control1.png;frame-start=2"

• --image-seeds "img2img.png;mask=mask.png;control=control1.png;frame-start=2;frame-end=5"

• --image-seeds "images: img2img-1.png, img2img-2.png;control=control1.png, control2.png"

• --image-seeds "images: img2img-1.png, img2img-2.png;mask=mask1.png, mask2.png;control=control1.png, control2.png"

IP Adapter Images can be specified in these ways:

• --image-seeds "adapter: image.png"

• --image-seeds "adapter: adapter1-image.png, adapter2-image.png"

• --image-seeds "adapter: image1.png + image2.png"

• --image-seeds "adapter: adapter1-image1.png + adapter1-image2.png, adapter2-image1.png + adapter2-image2.png"

• --image-seeds "img2img.png;adapter=image.png"

• --image-seeds "img2img.png;adapter=adapter1-image.png, adapter2-image.png"

• --image-seeds "img2img.png;adapter=image1.png + image2.png"

• --image-seeds "img2img.png;adapter=adapter1-image1.png + adapter1-image2.png, adapter2-image1.png + adapter2-image2.png"

• --image-seeds "images: img2img-1.png, img2img-2.png;adapter=image.png"

The control argument is supported for any IP Adapter image specification.

The mask argument is also supported for img2img with additional IP Adapter images.

Deep Floyd img2img and inpainting mode can be specified in these ways:

• --image-seeds "img2img.png;floyd=stage1-image.png"

• --image-seeds "img2img.png;mask=mask.png;floyd=stage2-image.png"

Note that all keyword arguments mentioned above can be used together, except for “control” and “floyd”, or “adapter” and “floyd”, which are mutually exclusive arguments.

One or more ImageSeed objects may be yielded depending on whether an animation is being read.

Parameters:

• uri – --image-seeds uri or ImageSeedParseResult

• frame_start – starting frame, inclusive value

• frame_end – optional end frame, inclusive value

• resize_resolution – optional global resize resolution. The URI syntax of image seeds allows for overriding this value.

• aspect_correct – should the global resize operation be aspect correct by default? The URI syntax for image seeds allows for overriding this value with the aspect keyword argument.

• align – Images which are read are aligned to this amount of pixels, None or 1 will disable alignment.

• seed_image_processor – optional dgenerate.imageprocessors.ImageProcessor or list of them. A list is used to specify processors for individual images in a multi img2img image specification such as uri = “images: img2img-1.png, img2img-2.png”. In the case that a multi img2img image specification is used and only one processor is given, that processor will be used on only the first image / video in the specification. Images in a multi img2img specification with no corresponding processor value will have their processor set to None, specifying extra processors as compared to img2img sources will cause ValueError to be raised.

• mask_image_processor – optional dgenerate.imageprocessors.ImageProcessor or list of them. A list is used to specify processors for individual mask images in a multi inpaint mask specification such as uri = “images: img2img-1.png, img2img-2.png;mask=mask-1.png, mask-2.png”. In the case that a multi inpaint mask specification is used and only one processor is given, that processor will be used on only the first image / video in the specification. Images in an inpaint mask specification with no corresponding processor value will have their processor set to None, specifying extra processors as compared to inpaint mask image sources will cause ValueError to be raised.

• control_image_processor – optional dgenerate.imageprocessors.ImageProcessor or list of them. A list is used to specify processors for individual images in a multi guidance image specification such as uri = “img2img.png;control=img1.png, img2.png”. In the case that a multi guidance image specification is used and only one processor is given, that processor will be used on only the first image / video in the specification. Images in a guidance specification with no corresponding processor value will have their processor set to None, specifying extra processors as compared to control guidance image sources will cause ValueError to be raised.

• check_dimensions_match – Check the dimensions of input images, mask images, and control images to confirm that they match? For pipelines like stable cascade, this does not matter, input images can be any dimension as they are used as a style reference and not a noise base similar to IP Adapters.

Raises:

ValueError – if there are more control_image_processor values than there are control guidance image sources in the URI.

Returns:

an iterator over ImageSeed objects

dgenerate.mediainput.mimetype_is_animated_image(mimetype: str) → bool

Check if a mimetype is one that dgenerate considers an animated image

Parameters:

mimetype – The mimetype string

Returns:

bool

dgenerate.mediainput.mimetype_is_static_image(mimetype: str) → bool

Check if a mimetype is one that dgenerate considers a static image

Parameters:

mimetype – The mimetype string

Returns:

bool

dgenerate.mediainput.mimetype_is_supported(mimetype: str) → bool

Check if dgenerate supports a given input mimetype

Parameters:

mimetype – The mimetype string

Returns:

bool

dgenerate.mediainput.mimetype_is_video(mimetype: str) → bool

Check if a mimetype is a video mimetype supported by dgenerate

Parameters:

mimetype – The mimetype string

Returns:

bool

dgenerate.mediainput.parse_image_seed_uri(uri: str, align: int | None = 8) → ImageSeedParseResult

Parse an --image-seeds uri into its constituents

All URI related errors raised by this function derive from ImageSeedError.

Raises:

• ValueError – if align < 1

• ImageSeedParseError – on syntactical parsing errors

• ImageSeedArgumentError – on image seed URI argument errors

• ImageSeedFileNotFoundError – when a file mentioned in an image seed does not exist on disk

Parameters:

• uri – --image-seeds uri

• align – do not allow per image seed resize resolutions that are not aligned to this value, setting this value to 1 or None disables alignment checks.

Returns:

ImageSeedParseResult

dgenerate.mediainput.request_mimetype(url) → str

Request the mimetype of a file at a URL, if the file exists in the cache, a known mimetype is returned without connecting to the internet. Otherwise, connect to the internet to retrieve the mimetype, this action does not update the cache.

Parameters:

url – The url

Returns:

mimetype string

dgenerate.mediainput.url_aware_basename(path)

Get the os.path.basename of a file path or URL.

Parameters:

path – the path

Returns:

basename

dgenerate.mediainput.url_aware_normpath(path)

Only os.path.normpath a file path if it is not a URL.

Parameters:

path – the path

Returns:

normalized file path or unmodified URL

dgenerate.mediainput.url_aware_splitext(path)

Get the os.path.splitext result for a file path or URL.

Parameters:

path – the path

Returns:

base, ext

dgenerate.mediaoutput module

Media output, handles writing videos and animations.

Provides information about supported output formats.

exception dgenerate.mediaoutput.UnknownAnimationFormatError

Bases: Exception

Raised by create_animation_writer() when an unknown animation format is provided.

class dgenerate.mediaoutput.AnimatedImageWriter(filename: str, duration: float)

Bases: AnimationWriter

Animation writer for animated images such as GIFs and webp

__init__(filename: str, duration: float)

Parameters:

• filename – Filename to write to.

• duration – Frame duration, (duration of a single frame) in milliseconds.

end(new_file: str = None)

write(img: Image)

class dgenerate.mediaoutput.AnimationWriter

Bases: object

Interface for animation writers

__init__()

end(new_file: str = None)

write(pil_img_rgb: Image)

class dgenerate.mediaoutput.MultiAnimationWriter(animation_format: str, filename: str, fps: float, allow_overwrites=False)

Bases: AnimationWriter

Splits writes between N files with generated filename suffixes if necessary depending on how many images were written on the first write.

__init__(animation_format: str, filename: str, fps: float, allow_overwrites=False)

Parameters:

• animation_format – One of supported_animation_writer_formats()

• filename – The desired filename, if multiple images are written a suffix _animation_N will be appended for each file

• fps – Frames per second

• allow_overwrites – Allow overwrites of existing files? or append _duplicate_N, The overwrite dis-allowance is multiprocess safe between instances of this library.

end(new_file=None)

write(img: Image | Iterable[Image])

class dgenerate.mediaoutput.VideoWriter(filename, fps: float)

Bases: AnimationWriter

Animation writer for MP4 h264 format video

__init__(filename, fps: float)

Parameters:

• filename – Filename to write to.

• fps – Frame rate, in frames per second.

end(new_file=None)

write(img: Image)

dgenerate.mediaoutput.create_animation_writer(animation_format: str, out_filename: str, fps: float)

Create an animation writer of a given format.

Raises:

UnknownAnimationFormatError – if the provided animation_format is unknown.

Parameters:

• animation_format – The animation format, see supported_animation_writer_formats()

• out_filename – the output file name

• fps – FPS

Returns:

AnimationWriter

dgenerate.mediaoutput.get_supported_animation_writer_formats()

Supported animation writer formats, file extensions with no period.

Returns:

list of file extensions.

dgenerate.mediaoutput.get_supported_static_image_formats()

What file extensions does PIL/Pillow support for output of at least one frame?

File extensions are returned without a period.

Returns:

list of file extensions

dgenerate.memoize module

Function memoization wrapper and associated hashing tools.

dgenerate.memoize.args_cache_key(args_dict: dict[str, Any], custom_hashes: dict[str, Callable[[Any], str]] = None)

Generate a cache key for a functions arguments to use for memoization.

Parameters:

• args_dict – The args dictionary of the function

• custom_hashes – Custom hash functions for specific argument names if needed

Returns:

string

dgenerate.memoize.memoize(cache: dict[str, ~typing.Any], exceptions: set[str] = None, hasher: ~typing.Callable[[dict[str, ~typing.Any]], str] = <function args_cache_key>, on_hit: ~typing.Callable[[str, ~typing.Any], None] = None, on_create: ~typing.Callable[[str, ~typing.Any], None] = None)

Decorator used to Memoize a function using a dictionary as a value cache.

Parameters:

• cache – The dictionary to serve as a cache

• exceptions – Function arguments to ignore

• hasher – Responsible for hashing arguments and argument values

• on_hit – Called on cache hit for the wrapped function

• on_create – Called on cache miss for the wrapped function

Returns:

decorator

dgenerate.memoize.simple_cache_hit_debug(title: str, cache_key: str, cache_hit: Any)

Basic cache hit debug message for memoize() decorator on_hit parameter.

Messages are printed using dgenerate.messages.debug_log()

Example:

on_hit=lambda key, hit: simple_cache_hit_debug("My Object", key, hit)

Debug Prints:

Cache Hit, Loaded My Object: (fully qualified name of hit object), Cache Key: (key)

Parameters:

• title – Object Title

• cache_key – cache key

• cache_hit – cached object

dgenerate.memoize.simple_cache_miss_debug(title: str, cache_key: str, new: Any)

Basic cache hit debug message for memoize() decorator on_create parameter.

Messages are printed using dgenerate.messages.debug_log()

Example:

on_create=lambda key, hit: simple_cache_miss_debug("My Object", key, hit)

Debug Prints:

Cache Miss, Created My Object: (fully qualified name of new object), Cache Key: (key)

Parameters:

• title – Object Title

• cache_key – cache key

• new – newly created object

dgenerate.memoize.struct_hasher(obj: Any, custom_hashes: dict[str, Callable[[Any], str]] = None, exclude: set[str] | None = None) → str

Create a hash string from a simple objects public attributes.

Parameters:

• obj – the object

• custom_hashes – Custom hash functions for specific attribute names if needed

• exclude – Exclude attributes by name

Returns:

string

dgenerate.memory module

System memory information and memory constraint expressions.

exception dgenerate.memory.MemoryConstraintSyntaxError

Bases: Exception

Thrown by memory_constraints() on syntax errors or if an expression returns a non-boolean value

dgenerate.memory.bytes_best_human_unit(byte_count: int, delimiter='') → str

Return a string for humans from a byte count using an appropriate unit: IE 1KB, 1MB, 1GB etc.

Parameters:

• delimiter – add this string between the value and the unit

• byte_count – the byte count

Returns:

formatted string

dgenerate.memory.calculate_chunk_size(file_size)

Calculate the chunk size for downloading / copying a file based on the file size and available memory.

Parameters:

file_size – The size of the file to be downloaded / copied.

Returns:

The calculated chunk size.

dgenerate.memory.cuda_memory_constraints(expressions: ~collections.abc.Iterable[str], extra_vars: dict[str, int | float] | None = None, mode=<built-in function any>, device: str | ~torch.device = 'cuda:0') → bool

Evaluate a user boolean expression involving the CUDA device’s memory in bytes, used memory percent, and available CUDA memory in bytes.

If you pass a non cuda device identifier to this method, it will always return False

Available functions are:

• kb(bytes to kilobytes)

• mb(bytes to megabytes)

• gb(bytes to gigabytes)

• kib(bytes to kibibytes)

• mib(bytes to mebibytes)

• gib(bytes to gibibytes)

Available values are:

• used / u (memory currently used by the CUDA device in bytes)

• used_total_percent / utp (memory used by the CUDA device, as percent of total CUDA memory, example: 25.4)

• available / a (available memory remaining on the CUDA device in bytes that can be used)

• total / t (total memory on the CUDA device in bytes)

Example expressions:

• used > gb(1) (when the device has used more than 1GB of memory)

• used_total_percent > 25 (when the device has used more than 25 percent of CUDA memory)

• available < gb(2) (when the available memory on the device is less than 2GB)

Expressions may not be longer than 128 characters. However, multiple expressions may be provided.

Raises:

• ValueError – if extra_vars overwrites a reserved variable name, or if device is not a str or torch.device object.

• MemoryConstraintSyntaxError – on syntax errors or if the return value of an expression is not a boolean value.

Parameters:

• expressions – a list of expressions, if expressions is None or empty this function will return False.

• extra_vars – extra integer or float variables

• mode – the standard library function ‘any’ (equating to OR all expressions) or the standard library function ‘all’ (equating to AND all expressions). The default is ‘any’ which ORs all expressions.

• device – CUDA device string or torch.device object, defaults to ‘cuda:0’.

Returns:

Boolean result of the expression

dgenerate.memory.get_available_memory(unit='b')

Get the available memory remaining on the system in a selectable unit.

Parameters:

unit – one of (case insensitive): b (bytes), kb (kilobytes), mb (megabytes), gb (gigabytes), kib (kibibytes), mib (mebibytes), gib (gibibytes)

Returns:

Requested value.

dgenerate.memory.get_total_memory(unit='b')

Get the total physical memory on the system.

Parameters:

unit – one of (case insensitive): b (bytes), kb (kilobytes), mb (megabytes), gb (gigabytes), kib (kibibytes), mib (mebibytes), gib (gibibytes)

Returns:

Requested value.

dgenerate.memory.get_used_memory(unit='b', pid: int | None = None) → int

Get the memory used by a process in a selectable unit.

Parameters:

• unit – one of (case insensitive): b (bytes), kb (kilobytes), mb (megabytes), gb (gigabytes), kib (kibibytes), mib (mebibytes), gib (gibibytes)

• pid – The process PID to retrieve this information from, defaults to the current process.

Returns:

Requested value.

dgenerate.memory.get_used_memory_percent(pid: int | None = None) → float

Get the percentage of memory used by a process as a percentage of already used memory plus available virtual memory.

Parameters:

pid – PID of the process, defaults to the current process.

Returns:

A whole percentage, for example: 25.4

dgenerate.memory.get_used_total_memory_percent(pid: int | None = None) → float

Get the percentage of memory used by a process as a percentage of total system memory.

Parameters:

pid – PID of the process, defaults to the current process.

Returns:

A whole percentage, for example: 25.4

dgenerate.memory.memory_constraint_syntax_check(expression: str)

Syntax check an expression given to memory_constraints()

Parameters:

expression – the expression string

Raises:

MemoryConstraintSyntaxError – on syntax errors.

dgenerate.memory.memory_constraints(expressions: ~collections.abc.Iterable[str], extra_vars: dict[str, int | float] | None = None, mode=<built-in function any>, pid: int | None = None) → bool

Evaluate a user boolean expression involving the processes used memory in bytes, used memory percent, and available system memory in bytes.

Available functions are:

• kb(bytes to kilobytes)

• mb(bytes to megabytes)

• gb(bytes to gigabytes)

• kib(bytes to kibibytes)

• mib(bytes to mebibytes)

• gib(bytes to gibibytes)

Available values are:

• used / u (memory currently used by the process in bytes)

• used_total_percent / utp (memory used by the process, as percent of total system memory, example: 25.4)

• used_percent / up (memory used by the process, as a percent of used + available memory, example 75.4)

• available / a (available memory remaining on the system in bytes that can be used without going to the swap)

• total / t (total memory on the system in bytes)

Example expressions:

• used > gb(1) (when the process has used more than 1GB of memory)

• used_total_percent > 25 (when the process has used more than 25 percent of system memory)

• used_percent > 25 (when the process has used more than 25 percent of virtual memory available to it)

• available < gb(2) (when the available memory on the system is less than 2GB)

Expressions may not be longer than 128 characters. However, multiple expressions may be provided.

Raises:

• ValueError – if extra_vars overwrites a reserved variable name

• MemoryConstraintSyntaxError – on syntax errors or if the return value of an expression is not a boolean value.

Parameters:

• expressions – a list of expressions, if expressions is None or empty this function will return False.

• extra_vars – extra integer or float variables

• mode – the standard library function ‘any’ (equating to OR all expressions) or the standard library function ‘all’ (equating to AND all expressions). The default is ‘any’ which ORs all expressions.

• pid – PID of the process from which to acquire the ‘used’ and ‘used_percent’ variable values from, defaults to the current process.

Returns:

Boolean result of the expression

dgenerate.memory.memory_use_debug_string(pid=None)

Return a debug string using describing the memory consumption of a process and also available system memory.

Example:

“Used Memory: 465.25MB, Available Memory: 50.94GB, Used Percent: 0.91%, Total Memory: 68.64GB, Used Total Percent: 0.68%”

Where:

• Used Memory = get_used_memory()

• Available Memory = get_available_memory()

• Used Percent = get_used_memory_percent()

• Total Memory = get_total_memory()

• Used Percent Total = get_used_total_memory_percent()

Parameters:

pid – PID of the process to describe, defaults to the current process.

Returns:

formatted string

dgenerate.messages module

Library logging / informational output.

dgenerate.messages.add_logging_handler(callback: Callable[[ParamSpecArgs, int, bool, str], None])

Add your own logging handler callback.

Parameters:

callback – Callback accepting (*args, LEVEL, underline (bool), underline_char)

dgenerate.messages.debug_log(*func_or_str: Callable[[], Any] | Any, underline=False, underline_char='=')

Conditionally log strings or possibly expensive functions if LEVEL is set to DEBUG.

Parameters:

• func_or_str – objects to be stringified and printed or callables that return said objects

• underline – Underline this message?

• underline_char – Underline character.

dgenerate.messages.errors_to_null()

Force dgenerates error output to a null file.

dgenerate.messages.get_error_file()

Get the file stream or file like object for dgenerates error output.

dgenerate.messages.get_message_file()

Get the file stream or file like object for dgenerates normal (non error) output.

dgenerate.messages.log(*args: Any, level=1, underline=False, underline_char='=')

Write a message to dgenerates log

Parameters:

• args – args, objects that will be stringified and joined with a space

• level – Log level, one of: INFO, WARNING, ERROR, DEBUG

• underline – Underline this message?

• underline_char – Underline character

Returns:

dgenerate.messages.messages_to_null()

Force dgenerates normal output to a null file.

dgenerate.messages.pop_level()

Pop LEVEL value last saved by push_level() and assign it to LEVEL.

If no previous level was saved, no-op.

dgenerate.messages.push_level(level)

Set LEVEL and save the previous value to a stack.

Parameters:

level – one of INFO, WARNING, ERROR, , DEBUG

dgenerate.messages.remove_logging_handler(callback: Callable[[ParamSpecArgs, int, bool, str], None])

Remove a logging handler callback by reference.

Parameters:

callback – The previously registered callback

dgenerate.messages.set_error_file(file: TextIO)

Set a file stream or file like object for dgenerates error output.

Parameters:

file – The file stream

dgenerate.messages.set_message_file(file: TextIO)

Set a file stream or file like object for dgenerates normal (non error) output.

Parameters:

file – The file stream

dgenerate.messages.AUTO_FLUSH_MESSAGES = True

Whether to auto flush the output stream when printing to stdout or the output file assigned with set_message_file().

Errors are printed to stderr which is unbuffered by default.

dgenerate.messages.DEBUG = 8

Log Level DEBUG

dgenerate.messages.ERROR = 4

Log Level ERROR

dgenerate.messages.INFO = 1

Log level INFO

dgenerate.messages.LEVEL = 1

Current Log Level (set-able)

Setting to INFO means print all messages except DEBUG messages.

Setting to ERROR means only print ERROR messages.

Setting to WARNING means only print WARNING messages.

Setting to DEBUG means print every message.

Levels are a bitfield, so you can set: LEVEL = WARNING | ERROR etc.

dgenerate.messages.WARNING = 2

Log Level WARNING

dgenerate.pipelinewrapper module

huggingface diffusers pipeline wrapper / driver interface.

All functionality needed from the diffusers library is behind this interface.

exception dgenerate.pipelinewrapper.ArgumentHelpException

Bases: Exception

Not an error, runtime argument help was requested by passing “help” or a special value to an argument of DiffusionPipelineWrapper.__init__() which supports a help query.

exception dgenerate.pipelinewrapper.ControlNetUriLoadError

Bases: ModelUriLoadError

Error while loading model file in --control-nets uri

exception dgenerate.pipelinewrapper.InvalidControlNetUriError

Bases: InvalidModelUriError

Error in --control-nets uri

exception dgenerate.pipelinewrapper.InvalidDeviceOrdinalException

Bases: Exception

GPU in device specification (cuda:N) does not exist

exception dgenerate.pipelinewrapper.InvalidLoRAUriError

Bases: InvalidModelUriError

Error in --loras uri

exception dgenerate.pipelinewrapper.InvalidModelFileError

Bases: Exception

Raised when a file is loaded from disk that is an invalid diffusers model format.

This indicates that was a problem loading the primary diffusion model, This could also refer to an SDXL refiner model or Stable Cascade decoder model which are considered primary models.

exception dgenerate.pipelinewrapper.InvalidModelUriError

Bases: Exception

Thrown on model path syntax or logical usage error

exception dgenerate.pipelinewrapper.InvalidSCascadeDecoderUriError

Bases: InvalidModelUriError

Error in --s-cascade-decoder uri

exception dgenerate.pipelinewrapper.InvalidSDXLRefinerUriError

Bases: InvalidModelUriError

Error in --sdxl-refiner uri

exception dgenerate.pipelinewrapper.InvalidSchedulerNameError

Bases: Exception

Unknown scheduler name used

exception dgenerate.pipelinewrapper.InvalidT2IAdapterUriError

Bases: InvalidModelUriError

Error in --t2i-adapters uri

exception dgenerate.pipelinewrapper.InvalidTextEncoderUriError

Bases: InvalidModelUriError

Error in --text-encoder* uri

exception dgenerate.pipelinewrapper.InvalidTextualInversionUriError

Bases: InvalidModelUriError

Error in --textual-inversions uri

exception dgenerate.pipelinewrapper.InvalidUNetUriError

Bases: InvalidModelUriError

Error in --unet uri

exception dgenerate.pipelinewrapper.InvalidVaeUriError

Bases: InvalidModelUriError

Error in --vae uri

exception dgenerate.pipelinewrapper.LoRAUriLoadError

Bases: ModelUriLoadError

Error while loading model file in --loras uri

exception dgenerate.pipelinewrapper.ModelNotFoundError

Bases: Exception

Raised when a specified model can not be located either locally or remotely

exception dgenerate.pipelinewrapper.ModelUriLoadError

Bases: Exception

Thrown when model fails to load from a URI for a reason other than not being found, such as being unsupported.

This exception refers to loadable sub models such as VAEs, LoRAs, ControlNets, Textual Inversions etc.

exception dgenerate.pipelinewrapper.NonHFModelDownloadError

Bases: Exception

exception dgenerate.pipelinewrapper.SchedulerHelpException

Bases: ArgumentHelpException

Not an error, runtime scheduler help was requested by passing “help” to a scheduler name argument of DiffusionPipelineWrapper.__init__() such as scheduler or sdxl_refiner_scheduler. Upon calling DiffusionPipelineWrapper.__call__() info was printed using dgenerate.messages.log(), then this exception raised to get out of the call stack.

exception dgenerate.pipelinewrapper.T2IAdapterUriLoadError

Bases: ModelUriLoadError

Error while loading model file in --t2i-adapters uri

exception dgenerate.pipelinewrapper.TextEncoderUriLoadError

Bases: InvalidModelUriError

Error loading --text-encoder* uri

exception dgenerate.pipelinewrapper.TextEncodersHelpException

Bases: ArgumentHelpException

Not an error, runtime text encoder help was requested by passing “help” to a text encoder URI argument of DiffusionPipelineWrapper.__init__() such as text_encoder_uris or second_text_encoder_uris. Upon calling DiffusionPipelineWrapper.__call__() info was printed using dgenerate.messages.log(), then this exception raised to get out of the call stack.

exception dgenerate.pipelinewrapper.TextualInversionUriLoadError

Bases: ModelUriLoadError

Error while loading model file in --textual-inversions uri

exception dgenerate.pipelinewrapper.UNetUriLoadError

Bases: ModelUriLoadError

Error while loading model file in --unet / --unet2 uri

exception dgenerate.pipelinewrapper.UnsupportedPipelineConfigError

Bases: Exception

Occurs when a diffusers pipeline is requested to be configured in a way that is unsupported by that pipeline.

exception dgenerate.pipelinewrapper.VAEUriLoadError

Bases: ModelUriLoadError

Error while loading model file in --vae uri

class dgenerate.pipelinewrapper.ControlNetUri(model: str, revision: str | None, variant: str | None, subfolder: str | None, dtype: DataType | str | None = None, scale: float = 1.0, start: float = 0.0, end: float = 1.0)

Bases: object

Representation of --control-nets uri when --model-type torch*

__init__(model: str, revision: str | None, variant: str | None, subfolder: str | None, dtype: DataType | str | None = None, scale: float = 1.0, start: float = 0.0, end: float = 1.0)

Parameters:

• model – model path

• revision – model revision (branch name)

• variant – model variant, for example fp16

• subfolder – model subfolder

• dtype – model data type (precision)

• scale – control net scale

• start – control net guidance start value

• end – control net guidance end value

Raises:

InvalidControlNetUriError – If dtype is passed an invalid data type string.

load(dtype_fallback: ~dgenerate.pipelinewrapper.enums.DataType = DataType.AUTO, use_auth_token: str | None = None, local_files_only: bool = False, sequential_cpu_offload_member: bool = False, model_cpu_offload_member: bool = False, model_class: type[~diffusers.models.controlnet.ControlNetModel] | type[~diffusers.models.controlnet_sd3.SD3ControlNetModel] = <class 'diffusers.models.controlnet.ControlNetModel'>) → ControlNetModel | SD3ControlNetModel

Load a diffusers.ControlNetModel from this URI.

Parameters:

• dtype_fallback – Fallback datatype if dtype was not specified in the URI.

• use_auth_token – Optional huggingface API auth token, used for downloading restricted repos that your account has access to.

• local_files_only – Avoid connecting to huggingface to download models and only use cached models?

• sequential_cpu_offload_member – This model will be attached to a pipeline which will have sequential cpu offload enabled?

• model_cpu_offload_member – This model will be attached to a pipeline which will have model cpu offload enabled?

• model_class – What class of control net model should be loaded? diffusers.ControlNetModel or diffusers.SD3ControlNetModel. The first class is for Stable Diffusion 1 & 2, and the second class is used for Stable Diffusion 3.

Raises:

ModelNotFoundError – If the model could not be found.

Returns:

diffusers.ControlNetModel or diffusers.SD3ControlNetModel

static parse(uri: str) → ControlNetUri

Parse a --model-type torch* --control-nets uri specification and return an object representing its constituents

Parameters:

uri – string with --control-nets uri syntax

Raises:

InvalidControlNetUriError –

Returns:

TorchControlNetUri

property dtype: DataType | None

Model dtype (precision)

property end: float

ControlNet guidance end point, fraction of inference / timesteps.

property model: str

Model path, huggingface slug

property revision: str | None

Model repo revision

property scale: float

ControlNet guidance scale

property start: float

ControlNet guidance start point, fraction of inference / timesteps.

property subfolder: str | None

Model repo subfolder

property variant: str | None

Model repo revision

class dgenerate.pipelinewrapper.DataType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Represents model precision

AUTO = 0

Auto selection.

BFLOAT16 = 3

16 bit brain floating point.

FLOAT16 = 1

16 bit floating point.

FLOAT32 = 2

32 bit floating point.

class dgenerate.pipelinewrapper.DiffusionArguments

Bases: SetFromMixin

Represents all possible arguments for a DiffusionPipelineWrapper call.

describe_pipeline_wrapper_args() → str

Describe the pipeline wrapper arguments in a pretty, human-readable way, with word wrapping depending on console size or a maximum length depending on what stdout currently is.

Returns:

description string.

determine_pipeline_type()

Determine the dgenerate.pipelinewrapper.PipelineType needed to utilize these arguments.

Returns:

dgenerate.pipelinewrapper.PipelineType

get_pipeline_wrapper_kwargs()

Get the arguments dictionary needed to call DiffusionPipelineWrapper

Returns:

dictionary of argument names with values

batch_size: int | None = None

Number of images to produce in a single generation step on the same GPU.

clip_skip: int | None = None

Number of layers to be skipped from CLIP while computing the prompt embeddings. A value of 1 means that the output of the pre-final layer will be used for computing the prompt embeddings. Only supported for model_type values torch and torch-sdxl, including with controlnet_uris defined.

control_images: Sequence[Image] | None = None

ControlNet guidance images to use if controlnet_uris were given to the constructor of DiffusionPipelineWrapper.

All input images involved in a generation must match in dimension and be aligned by 8 pixels.

floyd_image: Image | None = None

The output image of the last stage when preforming img2img or inpainting generation with Deep Floyd. When preforming txt2img generation DiffusionArguments.image is used.

flux_max_sequence_length: int | None = None

Max number of prompt tokens that the T5EncoderModel (text encoder 2) of Flux can handle.

This defaults to 512 when not specified, and the maximum value is 512 and the minimum value is 1.

High values result in more resource usage and processing time.

flux_second_prompt: Prompt | None = None

Secondary prompt for the Flux pipeline. Usually the prompt attribute of this object is used, unless you override it by giving this attribute a value.

guidance_rescale: float | None = None

This value is only supported for certain dgenerate.pipelinewrapper.DiffusionPipelineWrapper configurations, an error will be produced when it is unsupported.

Guidance rescale factor proposed by [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://arxiv.org/pdf/2305.08891.pdf) guidance_scale is defined as φ in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://arxiv.org/pdf/2305.08891.pdf). Guidance rescale factor should fix overexposure when using zero terminal SNR.

guidance_scale: float | None = None

A higher guidance scale value encourages the model to generate images closely linked to the text DiffusionArguments.prompt at the expense of lower image quality. Guidance scale is enabled when DiffusionArguments.guidance_scale > 1

height: int | None = None

Output image height.

Ignored when img2img, inpainting, or controlnet guidance images are involved.

Width will be the width of the input image in those cases.

Output image width, must be aligned by 8

image_guidance_scale: float | None = None

This value is only relevant for pix2pix dgenerate.pipelinewrapper.ModelType.

Image guidance scale is to push the generated image towards the initial image DiffusionArguments.image. Image guidance scale is enabled by setting DiffusionArguments.image_guidance_scale > 1. Higher image guidance scale encourages to generate images that are closely linked to the source image DiffusionArguments.image, usually at the expense of lower image quality.

image_seed_strength: float | None = None

Image seed strength, which relates to how much an img2img source (image attribute) is used during generation. Between 0.001 (close to zero but not 0) and 1.0, the closer to 1.0 the less the image is used for generation, IE. the more creative freedom the AI has.

images: Sequence[Image] | None = None

Images for img2img operations, or the base for inpainting operations.

All input images involved in a generation except for adapter_images must match in dimension and be aligned by 8 pixels, except in the case of Stable Cascade, which can accept multiple images of any dimension for the purpose of image based prompting similar to IP Adapters.

All other pipelines interpret multiple image inputs as a batching request.

inference_steps: int | None = None

The number of denoising steps. More denoising steps usually lead to a higher quality image at the expense of slower inference.

ip_adapter_images: Sequence[Sequence[Image]] | None = None

IP Adapter images to use if ip_adapter_uris were given to the constructor of DiffusionPipelineWrapper.

This should be a list of Sequence[PIL.Image]

Each list entry corresponds to an IP adapter URI.

Multiple IP Adapter URIs can be provided, each IP Adapter can get its own set of images.

mask_images: Sequence[Image] | None = None

Mask images for inpainting operations.

The amount of img2img images must be equal to the amount of mask_images supplied.

All input images involved in a generation except for adapter_images must match in dimension and be aligned by 8 pixels, except in the case of Stable Cascade, which can accept multiple images of any dimension for the purpose of image based prompting similar to IP Adapters. Stable Cascade cannot perform inpainting, so mask_images is irrelevant in this case. All other pipelines interpret multiple image inputs as a batching request.

prompt: Prompt | None = None

Primary prompt

s_cascade_decoder_guidance_scale: float | None = None

Guidance scale value for the Stable Cascade decoder, this corresponds to the --s-cascade-decoder-guidance-scales argument of the dgenerate command line tool.

s_cascade_decoder_inference_steps: int | None = None

Inference steps value for the Stable Cascade decoder, this corresponds to the --s-cascade-decoder-inference-steps argument of the dgenerate command line tool.

s_cascade_decoder_prompt: Prompt | None = None

Primary prompt for the Stable Cascade decoder when a decoder URI is specified in the constructor of DiffusionPipelineWrapper. Usually the prompt attribute of this object is used, unless you override it by giving this attribute a value.

sd3_max_sequence_length: int | None = None

Max number of prompt tokens that the T5EncoderModel (text encoder 3) of Stable Diffusion 3 can handle.

This defaults to 256 when not specified, and the maximum value is 512 and the minimum value is 1.

High values result in more resource usage and processing time.

sd3_second_prompt: Prompt | None = None

Secondary prompt for the SD3 main pipeline. Usually the prompt attribute of this object is used, unless you override it by giving this attribute a value.

sd3_third_prompt: Prompt | None = None

Tertiary (T5) prompt for the SD3 main pipeline. Usually the prompt attribute of this object is used, unless you override it by giving this attribute a value.

sdxl_aesthetic_score: float | None = None

Optional, defaults to 6.0. This argument is used for img2img and inpainting operations only Used to simulate an aesthetic score of the generated image by influencing the positive text condition. Part of SDXL’s micro-conditioning as explained in section 2.2 of [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

sdxl_crops_coords_top_left: tuple[int, int] | None = None

Optional SDXL conditioning parameter. DiffusionArguments.sdxl_crops_coords_top_left can be used to generate an image that appears to be “cropped” from the position DiffusionArguments.sdxl_crops_coords_top_left downwards. Favorable, well-centered images are usually achieved by setting DiffusionArguments.sdxl_crops_coords_top_left to (0, 0). Part of SDXL’s micro-conditioning as explained in section 2.2 of [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

sdxl_high_noise_fraction: float | None = None

SDXL high noise fraction. This proportion of timesteps/inference steps are handled by the primary model, while the inverse proportion is handled by the refiner model when an SDXL model_type value.

When the refiner is operating in edit mode the number of total inference steps for the refiner will be calculated in a different manner, currently the refiner operates in edit mode during generations involving ControlNets as well as inpainting.

In edit mode, the refiner uses img2img with an image seed strength to add details to the image instead of cooperative denoising, this image seed strength is calculated as (1.0 - DiffusionArguments.sdxl_high_noise_fraction), and the number of inference steps for the refiner is then calculated as (image_seed_strength * inference_steps).

sdxl_negative_aesthetic_score: float | None = None

Negative influence version of DiffusionArguments.sdxl_aesthetic_score

sdxl_negative_crops_coords_top_left: tuple[int, int] | None = None

Negative influence version of DiffusionArguments.sdxl_crops_coords_top_left

sdxl_negative_original_size: tuple[int, int] | None = None

This value is only supported for certain dgenerate.pipelinewrapper.DiffusionPipelineWrapper configurations, an error will be produced when it is unsupported. It is not known to be supported by pix2pix.

Optional SDXL conditioning parameter. To negatively condition the generation process based on a specific image resolution. Part of SDXL’s micro-conditioning as explained in section 2.2 of [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). For more information, refer to this issue thread: https://github.com/huggingface/diffusers/issues/4208.

sdxl_negative_target_size: tuple[int, int] | None = None

This value is only supported for certain dgenerate.pipelinewrapper.DiffusionPipelineWrapper configurations, an error will be produced when it is unsupported. It is not known to be supported by pix2pix.

Optional SDXL conditioning parameter. To negatively condition the generation process based on a target image resolution. It should be as same as the DiffusionArguments.target_size for most cases. Part of SDXL’s micro-conditioning as explained in section 2.2 of [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952). For more information, refer to this issue thread: https://github.com/huggingface/diffusers/issues/4208.

sdxl_original_size: tuple[int, int] | None = None

Optional SDXL conditioning parameter. If DiffusionArguments.sdxl_original_size is not the same as DiffusionArguments.sdxl_target_size the image will appear to be down- or up-sampled. DiffusionArguments.sdxl_original_size defaults to (width, height) if not specified or the size of any input images provided. Part of SDXL’s micro-conditioning as explained in section 2.2 of [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

sdxl_refiner_aesthetic_score: float | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_aesthetic_score

sdxl_refiner_clip_skip: int | None = None

Clip skip override value for the SDXL refiner, which normally defaults to that of DiffusionArguments.clip_skip when it is defined.

sdxl_refiner_crops_coords_top_left: tuple[int, int] | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_crops_coords_top_left

sdxl_refiner_edit: bool | None = None

Force the SDXL refiner to operate in edit mode instead of cooperative denoising mode.

sdxl_refiner_guidance_rescale: float | None = None

Override the guidance rescale value used by the SDXL refiner, which is normally set to the value of DiffusionArguments.guidance_rescale.

sdxl_refiner_guidance_scale: float | None = None

Override the guidance scale used by the SDXL refiner, which is normally set to the value of DiffusionArguments.guidance_scale.

sdxl_refiner_inference_steps: int | None = None

Override the default amount of inference steps preformed by the SDXL refiner. Which is normally set to the value for the primary model.

The attribute DiffusionArguments.sdxl_high_noise_fraction still factors in to the actual amount of inference steps preformed.

sdxl_refiner_negative_aesthetic_score: float | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_negative_aesthetic_score

sdxl_refiner_negative_crops_coords_top_left: tuple[int, int] | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_negative_crops_coords_top_left

sdxl_refiner_negative_original_size: tuple[int, int] | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_negative_original_size

sdxl_refiner_negative_target_size: tuple[int, int] | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_negative_target_size

sdxl_refiner_original_size: tuple[int, int] | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_original_size

sdxl_refiner_prompt: Prompt | None = None

Primary prompt for the SDXL refiner when a refiner URI is specified in the constructor of DiffusionPipelineWrapper. Usually the prompt attribute of this object is used, unless you override it by giving this attribute a value.

sdxl_refiner_second_prompt: Prompt | None = None

Secondary prompt for the SDXL refiner when a refiner URI is specified in the constructor of DiffusionPipelineWrapper. Usually the sdxl_refiner_prompt attribute of this object is used, unless you override it by giving this attribute a value.

sdxl_refiner_target_size: tuple[int, int] | None = None

Override the refiner value usually taken from DiffusionArguments.sdxl_target_size

sdxl_second_prompt: Prompt | None = None

Secondary prompt for the SDXL main pipeline when a refiner URI is specified in the constructor of DiffusionPipelineWrapper. Usually the prompt attribute of this object is used, unless you override it by giving this attribute a value.

sdxl_t2i_adapter_factor: float | None = None

SDXL specific T2I adapter factor, this controls the amount of time-steps for which a T2I adapter applies guidance to an image, this is a value between 0.0 and 1.0. A value of 0.5 for example indicates that the T2I adapter is only active for half the amount of time-steps it takes to completely render an image.

sdxl_target_size: tuple[int, int] | None = None

Optional SDXL conditioning parameter. For most cases, DiffusionArguments.sdxl_target_size should be set to the desired height and width of the generated image. If not specified it will default to (width, height) or the size of any input images provided. Part of SDXL’s micro-conditioning as explained in section 2.2 of [https://huggingface.co/papers/2307.01952](https://huggingface.co/papers/2307.01952).

seed: int | None = None

An integer to serve as an RNG seed.

upscaler_noise_level: int | None = None

Upscaler noise level for the dgenerate.pipelinewrapper.ModelType.TORCH_UPSCALER_X4 model type only.

width: int | None = None

Output image width.

Ignored when img2img, inpainting, or controlnet guidance images are involved.

Width will be the width of the input image in those cases.

Output image width, must be aligned by 8

class dgenerate.pipelinewrapper.DiffusionPipelineWrapper(model_path: str, model_type: ModelType | str = ModelType.TORCH, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str = DataType.AUTO, unet_uri: str | None = None, second_unet_uri: str | None = None, transformer_uri: str | None = None, vae_uri: str | None = None, vae_tiling: bool = False, vae_slicing: bool = False, lora_uris: Sequence[str] | None = None, lora_fuse_scale: float | None = None, image_encoder_uri: str | None = None, ip_adapter_uris: Sequence[str] | None = None, textual_inversion_uris: Sequence[str] | None = None, text_encoder_uris: Sequence[str] | None = None, second_text_encoder_uris: Sequence[str] | None = None, controlnet_uris: Sequence[str] | None = None, t2i_adapter_uris: Sequence[str] | None = None, scheduler: str | None = None, sdxl_refiner_uri: str | None = None, sdxl_refiner_scheduler: str | None = None, s_cascade_decoder_uri: str | None = None, s_cascade_decoder_scheduler: str | None = None, device: str = 'cuda', safety_checker: bool = False, auth_token: str | None = None, local_files_only: bool = False, model_extra_modules: dict[str, Any] = None, second_model_extra_modules: dict[str, Any] = None, model_cpu_offload: bool = False, model_sequential_offload: bool = False, sdxl_refiner_cpu_offload: bool = False, sdxl_refiner_sequential_offload: bool = False, s_cascade_decoder_cpu_offload: bool = False, s_cascade_decoder_sequential_offload: bool = False, prompt_weighter_uri: str | None = None, prompt_weighter_loader: PromptWeighterLoader | None = None)

Bases: object

Monolithic diffusion pipelines wrapper.

__call__(args: DiffusionArguments | None = None, **kwargs) → PipelineWrapperResult

Call the pipeline and generate a result.

Parameters:

• args – Optional DiffusionArguments

• kwargs – See DiffusionArguments.get_pipeline_wrapper_kwargs(), any keyword arguments given here will override values derived from the DiffusionArguments object given to the args parameter.

Raises:

• InvalidModelFileError –

• UnsupportedPipelineConfigError –

• InvalidModelUriError –

• InvalidSchedulerNameError –

• dgenerate.OutOfMemoryError –

Returns:

PipelineWrapperResult

__init__(model_path: str, model_type: ModelType | str = ModelType.TORCH, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str = DataType.AUTO, unet_uri: str | None = None, second_unet_uri: str | None = None, transformer_uri: str | None = None, vae_uri: str | None = None, vae_tiling: bool = False, vae_slicing: bool = False, lora_uris: Sequence[str] | None = None, lora_fuse_scale: float | None = None, image_encoder_uri: str | None = None, ip_adapter_uris: Sequence[str] | None = None, textual_inversion_uris: Sequence[str] | None = None, text_encoder_uris: Sequence[str] | None = None, second_text_encoder_uris: Sequence[str] | None = None, controlnet_uris: Sequence[str] | None = None, t2i_adapter_uris: Sequence[str] | None = None, scheduler: str | None = None, sdxl_refiner_uri: str | None = None, sdxl_refiner_scheduler: str | None = None, s_cascade_decoder_uri: str | None = None, s_cascade_decoder_scheduler: str | None = None, device: str = 'cuda', safety_checker: bool = False, auth_token: str | None = None, local_files_only: bool = False, model_extra_modules: dict[str, Any] = None, second_model_extra_modules: dict[str, Any] = None, model_cpu_offload: bool = False, model_sequential_offload: bool = False, sdxl_refiner_cpu_offload: bool = False, sdxl_refiner_sequential_offload: bool = False, s_cascade_decoder_cpu_offload: bool = False, s_cascade_decoder_sequential_offload: bool = False, prompt_weighter_uri: str | None = None, prompt_weighter_loader: PromptWeighterLoader | None = None)

This is a monolithic wrapper around all supported diffusion pipelines which handles txt2img, img2img, and inpainting on demand. It spins up the correct pipelines as needed in order to handle provided pipeline arguments using lazy initialization.

Pipelines and user specified sub models are memoized and their lifetimes are managed via heuristics based on system memory and available resources.

All arguments to this constructor should be provided as keyword arguments, using this constructor in any other fashion could result in breakage inbetween semver compatible versions.

Parameters:

• model_path – main model path

• model_type – main model type

• revision – main model revision

• variant – main model variant

• subfolder – main model subfolder (huggingface or disk)

• dtype – main model dtype

• unet_uri – main model UNet URI string

• second_unet_uri – secondary model unet uri (SDXL Refiner, Stable Cascade decoder)

• transformer_uri – Optional transformer URI string for specifying a specific Transformer, currently this is only supported for Stable Diffusion 3 models.

• vae_uri – main model VAE URI string

• vae_tiling – use VAE tiling?

• vae_slicing – use VAE slicing?

• lora_uris – One or more LoRA URI strings

• lora_fuse_scale – Optional global LoRA fuse scale value. Once all LoRAs are merged with their individual scales, the merged weights will be fused into the pipeline at this scale. The default value is 1.0.

• image_encoder_uri – One or more Image Encoder URI strings, Image Encoders are used with IP Adapters and Stable Cascade

• ip_adapter_uris – One or more IP Adapter URI strings

• textual_inversion_uris – One or more Textual Inversion URI strings

• text_encoder_uris – One or more Text Encoder URIs (“+”, or None for default. Or “null” indicating do not load) for the main model

• second_text_encoder_uris – One or more Text Encoder URIs (“+”, or None for default. Or “null” indicating do not load) for the secondary model (SDXL Refiner or Stable Cascade decoder)

• controlnet_uris – One or more ControlNet URI strings

• t2i_adapter_uris – One or more T2IAdapter URI strings

• scheduler – Scheduler URI string for the main model

• sdxl_refiner_uri – SDXL Refiner model URI string

• sdxl_refiner_scheduler – Scheduler URI string for the SDXL Refiner

• s_cascade_decoder_uri – Stable Cascade decoder URI string

• s_cascade_decoder_scheduler – Scheduler URI string for the Stable Cascade decoder

• device – Rendering device string, example: cuda:0 or cuda

• safety_checker – Use safety checker model if available? (antiquated, for SD 1/2, Deep Floyd etc.)

• auth_token – huggingface authentication token.

• local_files_only – Do not attempt to download files from huggingface?

• model_extra_modules – Raw extra diffusers modules for the main pipeline

• second_model_extra_modules – Raw extra diffusers modules for the secondary pipeline (SDXL Refiner, Stable Cascade decoder)

• model_cpu_offload – Use model CPU offloading for the main pipeline via the accelerate module?

• model_sequential_offload – Use sequential CPU offloading for the main pipeline via the accelerate module?

• sdxl_refiner_cpu_offload – Use CPU offloading for the SDXL Refiner via the accelerate module?

• sdxl_refiner_sequential_offload – Use sequential CPU offloading for the SDXL Refiner via the accelerate module?

• s_cascade_decoder_cpu_offload – Use CPU offloading for the Stable Cascade decoder via the accelerate module?

• s_cascade_decoder_sequential_offload – Use sequential CPU offloading for the Stable Cascade decoder via the accelerate module?

• prompt_weighter_uri – Prompt weighter implementation URI, to be loaded from prompt_weighter_loader

• prompt_weighter_loader – Plugin loader for prompt weighter implementations, if you pass None a default instance will be created.

gen_dgenerate_command(args: DiffusionArguments | None = None, extra_opts: Sequence[tuple[str] | tuple[str, Any]] | None = None, omit_device=False, **kwargs)

Generate a valid dgenerate command line invocation that reproduces the arguments associated with DiffusionArguments.

This does not reproduce --image-seeds, you must include that value in extra_opts, this is because there is not enough information in DiffusionArguments to accurately reproduce it.

Parameters:

• args – DiffusionArguments object to take values from

• extra_opts – Extra option pairs to be added to the end of reconstructed options of the dgenerate invocation, this should be a sequence of tuples of length 1 (switch only) or length 2 (switch with args)

• omit_device – Omit the --device option? For a shareable configuration it might not make sense to include the device specification. And instead simply fallback to whatever the default device is, which is generally cuda

• kwargs – pipeline wrapper keyword arguments, these will override values derived from any DiffusionArguments object given to the args argument. See: DiffusionArguments.get_pipeline_wrapper_kwargs

Returns:

A string containing the dgenerate command line needed to reproduce this result.

gen_dgenerate_config(args: DiffusionArguments | None = None, extra_opts: Sequence[tuple[str] | tuple[str, Any]] | None = None, extra_comments: Iterable[str] | None = None, omit_device: bool = False, **kwargs)

Generate a valid dgenerate config file with a single invocation that reproduces the arguments associated with DiffusionArguments.

This does not reproduce --image-seeds, you must include that value in extra_opts, this is because there is not enough information in DiffusionArguments to accurately reproduce it.

Parameters:

• args – DiffusionArguments object to take values from

• extra_opts – Extra option pairs to be added to the end of reconstructed options of the dgenerate invocation, this should be a sequence of tuples of length 1 (switch only) or length 2 (switch with args)

• extra_comments – Extra strings to use as comments after the initial version check directive

• omit_device – Omit the --device option? For a shareable configuration it might not make sense to include the device specification. And instead simply fallback to whatever the default device is, which is generally cuda

• kwargs – pipeline wrapper keyword arguments, these will override values derived from any DiffusionArguments object given to the args argument. See: DiffusionArguments.get_pipeline_wrapper_kwargs

Returns:

The configuration as a string

recall_main_pipeline() → PipelineCreationResult

Fetch the last used main pipeline creation result, possibly the pipeline will be recreated if no longer in the in memory cache. If there is no pipeline currently created, which will be the case if an image was never generated yet, RuntimeError will be raised.

Raises:

RuntimeError –

Returns:

dgenerate.pipelinewrapper.PipelineCreationResult

recall_refiner_pipeline() → PipelineCreationResult

Fetch the last used refiner pipeline creation result, possibly the pipeline will be recreated if no longer in the in memory cache. If there is no refiner pipeline currently created, which will be the case if an image was never generated yet or a refiner model was not specified, RuntimeError will be raised.

Raises:

RuntimeError –

Returns:

dgenerate.pipelinewrapper.PipelineCreationResult

reconstruct_dgenerate_opts(args: DiffusionArguments | None = None, extra_opts: Sequence[tuple[str] | tuple[str, Any]] | None = None, omit_device=False, shell_quote=True, **kwargs) → list[tuple[str] | tuple[str, Any]]

Reconstruct dgenerates command line arguments from a particular set of pipeline wrapper call arguments.

This does not reproduce --image-seeds, you must include that value in extra_opts, this is because there is not enough information in DiffusionArguments to accurately reproduce it.

Parameters:

• args – DiffusionArguments object to take values from

• extra_opts – Extra option pairs to be added to the end of reconstructed options, this should be a sequence of tuples of length 1 (switch only) or length 2 (switch with args)

• omit_device – Omit the --device option? For a shareable configuration it might not make sense to include the device specification. And instead simply fallback to whatever the default device is, which is generally cuda

• shell_quote – Shell quote and format the argument values? or return them raw.

• kwargs – pipeline wrapper keyword arguments, these will override values derived from any DiffusionArguments object given to the args argument. See: DiffusionArguments.get_pipeline_wrapper_kwargs

Returns:

List of tuples of length 1 or 2 representing the option

property auth_token: str | None

Current --auth-token value or None

property controlnet_uris: Sequence[str] | None

List of supplied --control-nets uri strings or an empty list

property device: str

Currently set --device string

property dtype: DataType

Currently set --dtype enum value for the main model

property dtype_string: str

Currently set --dtype string value for the main model

property image_encoder_uri: str | None

Selected --image-encoder uri for the main model or None

property ip_adapter_uris: Sequence[str] | None

List of supplied --ip-adapters uri strings or an empty list

property local_files_only: bool

Currently set value for local_files_only

property lora_fuse_scale: float

Supplied --lora-fuse-scale value

property lora_uris: Sequence[str] | None

List of supplied --loras uri strings or an empty list

property model_cpu_offload: bool

Current --model-cpu-offload value

property model_path: str

Model path for the main model

property model_sequential_offload: bool

Current --model-sequential-offload value

property model_type: ModelType

Currently set --model-type enum value

property model_type_string: str

Currently set --model-type string value

property prompt_weighter_loader: PromptWeighterLoader

Current prompt weighter loader

property prompt_weighter_uri: str | None

Current prompt weighter implementation uri

property revision: str | None

Currently set --revision for the main model or None

property s_cascade_decoder_cpu_offload: bool

Current --s-cascade-decoder-cpu-offload value

property s_cascade_decoder_scheduler: str | None

Selected scheduler URI for the Stable Cascade decoder or None

property s_cascade_decoder_sequential_offload: bool

Current --s-cascade-decoder-sequential-offload value

property s_cascade_decoder_uri: str | None

Model URI for the Stable Cascade decoder or None

property safety_checker: bool

Safety checker enabled status

property scheduler: str | None

Selected scheduler URI for the main model or None

property sdxl_refiner_cpu_offload: bool

Current --sdxl-refiner-cpu-offload value

property sdxl_refiner_scheduler: str | None

Selected scheduler URI for the SDXL refiner or None

property sdxl_refiner_sequential_offload: bool

Current --sdxl-refiner-sequential-offload value

property sdxl_refiner_uri: str | None

Model URI for the SDXL refiner or None

property second_text_encoder_uris: Sequence[str] | None

List of supplied --text-encoders2 uri strings or an empty list

property second_unet_uri: str | None

Selected --unet2 uri for the SDXL refiner or Stable Cascade decoder model or None

property subfolder: str | None

Selected model --subfolder for the main model, (remote repo subfolder or local) or None

property t2i_adapter_uris: Sequence[str] | None

List of supplied --t2i-adapters uri strings or an empty list

property text_encoder_uris: Sequence[str] | None

List of supplied --text-encoders uri strings or an empty list

property textual_inversion_uris: Sequence[str] | None

List of supplied --textual-inversions uri strings or an empty list

property transformer_uri: str | None

Model URI for the SD3 Transformer or None

property unet_uri: str | None

Selected --unet uri for the main model or None

property vae_slicing: bool

Current --vae-slicing status

property vae_tiling: bool

Current --vae-tiling status

property vae_uri: str | None

Selected --vae uri for the main model or None

property variant: str | None

Currently set --variant for the main model or None

class dgenerate.pipelinewrapper.IPAdapterUri(model: str, revision: str | None = None, subfolder: str | None = None, weight_name: str | None = None, scale: float = 1.0)

Bases: object

Representation of a --ip-adapters uri

__init__(model: str, revision: str | None = None, subfolder: str | None = None, weight_name: str | None = None, scale: float = 1.0)

static load_on_pipeline(pipeline: DiffusionPipeline, uris: Iterable[IPAdapterUri | str], use_auth_token: str | None = None, local_files_only: bool = False)

Load IP Adapter weights on to a pipeline using this URI

Parameters:

• pipeline – diffusers.DiffusionPipeline

• uris – IP Adapter URIs to load on to the pipeline

• use_auth_token – optional huggingface auth token.

• local_files_only – avoid downloading files and only look for cached files when the model path is a huggingface slug

Raises:

• ModelNotFoundError – If the model could not be found.

• dgenerate.pipelinewrapper.uris.exceptions.InvalidIPAdapterUriError – On URI parsing errors.

• dgenerate.pipelinewrapper.uris.exceptions.IPAdapterUriLoadError – On loading errors.

static parse(uri: str) → IPAdapterUri

Parse a --ip-adapters uri and return an object representing its constituents

Parameters:

uri – string with --ip-adapters uri syntax

Raises:

InvalidIPAdapterUriError –

Returns:

IPAdapterUri

property model: str

Model path, huggingface slug, file path

property revision: str | None

Model repo revision

property scale: float

IP Adapter scale

property subfolder: str | None

Model repo subfolder

property weight_name: str | None

Model weight-name

class dgenerate.pipelinewrapper.LoRAUri(model: str, revision: str | None = None, subfolder: str | None = None, weight_name: str | None = None, scale: float = 1.0)

Bases: object

Representation of a --loras uri

__init__(model: str, revision: str | None = None, subfolder: str | None = None, weight_name: str | None = None, scale: float = 1.0)

static load_on_pipeline(pipeline: DiffusionPipeline, uris: Iterable[LoRAUri | str], fuse_scale: float = 1.0, use_auth_token: str | None = None, local_files_only: bool = False)

Load LoRA weights on to a pipeline using this URI

Parameters:

• pipeline – diffusers.DiffusionPipeline

• uris – Iterable of LoRAUri or str LoRA URIs to load

• fuse_scale – Global scale for the fused LoRAs, all LoRAs are fused together using their individual scale value, and then fused into the main model using this scale.

• use_auth_token – optional huggingface auth token.

• local_files_only – avoid downloading files and only look for cached files when the model path is a huggingface slug

Raises:

• dgenerate.ModelNotFoundError – If the model could not be found.

• dgenerate.pipelinewrapper.uris.exceptions.InvalidLoRAUriError – On URI parsing errors.

• dgenerate.pipelinewrapper.uris.exceptions.LoRAUriLoadError – On loading errors.

static parse(uri: str) → LoRAUri

Parse a --loras uri and return an object representing its constituents

Parameters:

uri – string with --loras uri syntax

Raises:

InvalidLoRAUriError –

Returns:

LoRAUri

property model: str

Model path, huggingface slug, file path

property revision: str | None

Model repo revision

property scale: float

LoRA scale

property subfolder: str | None

Model repo subfolder

property weight_name: str | None

Model weight-name

class dgenerate.pipelinewrapper.ModelType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum representation of --model-type

TORCH = 0

Stable Diffusion, such as SD 1.0 - 2.x

TORCH_FLUX = 12

Flux pipeline

TORCH_IF = 3

Deep Floyd IF stage 1

TORCH_IFS = 4

Deep Floyd IF superscaler (stage 2)

TORCH_IFS_IMG2IMG = 5

Deep Floyd IF superscaler (stage 2) image to image / variation mode.

TORCH_PIX2PIX = 1

Stable Diffusion pix2pix prompt guided editing.

TORCH_SD3 = 11

Stable Diffusion 3

TORCH_SDXL = 2

Stable Diffusion XL

TORCH_SDXL_PIX2PIX = 6

Stable Diffusion XL pix2pix prompt guided editing.

TORCH_S_CASCADE = 9

Stable Cascade prior

TORCH_S_CASCADE_DECODER = 10

Stable Cascade decoder

TORCH_UPSCALER_X2 = 7

Stable Diffusion X2 upscaler

TORCH_UPSCALER_X4 = 8

Stable Diffusion X4 upscaler

class dgenerate.pipelinewrapper.PipelineCreationResult(pipeline)

Bases: object

__init__(pipeline)

get_pipeline_modules(names=collections.abc.Iterable[str])

Get associated pipeline module such as vae etc, in a dictionary mapped from name to module value.

Possible Module Names:

• unet

• vae

• transformer

• text_encoder

• text_encoder_2

• text_encoder_3

• tokenizer

• tokenizer_2

• tokenizer_3

• safety_checker

• feature_extractor

• image_encoder

• adapter

• controlnet

• scheduler

If the module is not present or a recognized name, a ValueError will be thrown describing the module that is not part of the pipeline.

Raises:

ValueError –

Parameters:

names – module names, such as vae, text_encoder

Returns:

dictionary

property pipeline

class dgenerate.pipelinewrapper.PipelineType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Represents possible diffusers pipeline types.

IMG2IMG = 2

Image to image mode. Generation seeded / controlled with an image in some fashion.

INPAINT = 3

Inpainting mode. Generation seeded / controlled with an image and a mask in some fashion.

TXT2IMG = 1

Text to image mode. Prompt only generation.

class dgenerate.pipelinewrapper.PipelineWrapperResult(images: Sequence[Image] | None)

Bases: object

The result of calling DiffusionPipelineWrapper

__init__(images: Sequence[Image] | None)

image_grid(cols_rows: tuple[int, int])

Render an image grid from the images in this result.

Raises:

ValueError – if no images are present on this object. This is impossible if this object was produced by DiffusionPipelineWrapper.

Parameters:

cols_rows – columns and rows (WxH) desired as a tuple

Returns:

PIL.Image.Image

property image

The first image in the batch of requested batch size.

Returns:

PIL.Image.Image

property image_count

The number of images produced.

Returns:

int

images: MutableSequence[Image] | None

class dgenerate.pipelinewrapper.SCascadeDecoderUri(model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Bases: object

Representation of --s-cascade-decoder uri

__init__(model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Parameters:

• model – model path

• revision – model revision (branch name)

• variant – model variant, for example fp16

• subfolder – model subfolder

• dtype – model data type (precision)

static parse(uri: str) → SCascadeDecoderUri

Parse an --s-cascade-decoder uri and return an object representing its constituents

Parameters:

uri – string with --s-cascade-decoder uri syntax

Returns:

SCascadeDecoderUri

property dtype: DataType | None

Model dtype (precision)

property model: str

Model path, huggingface slug

property revision: str | None

Model repo revision

property subfolder: str | None

Model repo subfolder

property variant: str | None

Model repo revision

class dgenerate.pipelinewrapper.SDXLRefinerUri(model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Bases: object

Representation of --sdxl-refiner uri

__init__(model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Parameters:

• model – model path

• revision – model revision (branch name)

• variant – model variant, for example fp16

• subfolder – model subfolder

• dtype – model data type (precision)

Raises:

InvalidSDXLRefinerUriError – If dtype is passed an invalid data type string.

static parse(uri: str) → SDXLRefinerUri

Parse an --sdxl-refiner uri and return an object representing its constituents

Parameters:

uri – string with --sdxl-refiner uri syntax

Raises:

InvalidSDXLRefinerUriError –

Returns:

SDXLRefinerUri

property dtype: DataType | None

Model dtype (precision)

property model: str

Model path, huggingface slug

property revision: str | None

Model repo revision

property subfolder: str | None

Model repo subfolder

property variant: str | None

Model repo revision

class dgenerate.pipelinewrapper.T2IAdapterUri(model: str, revision: str | None, variant: str | None, subfolder: str | None, dtype: DataType | str | None = None, scale: float = 1.0)

Bases: object

Representation of --t2i-adapters uri when --model-type torch*

__init__(model: str, revision: str | None, variant: str | None, subfolder: str | None, dtype: DataType | str | None = None, scale: float = 1.0)

Parameters:

• model – model path

• revision – model revision (branch name)

• variant – model variant, for example fp16

• subfolder – model subfolder

• dtype – model data type (precision)

• scale – t2i adapter scale

Raises:

InvalidT2IAdapterUriError – If dtype is passed an invalid data type string.

load(dtype_fallback: DataType = DataType.AUTO, use_auth_token: str | None = None, local_files_only: bool = False, sequential_cpu_offload_member: bool = False, model_cpu_offload_member: bool = False) → T2IAdapter

Load a diffusers.T2IAdapter from this URI.

Parameters:

• dtype_fallback – Fallback datatype if dtype was not specified in the URI.

• use_auth_token – Optional huggingface API auth token, used for downloading restricted repos that your account has access to.

• local_files_only – Avoid connecting to huggingface to download models and only use cached models?

• sequential_cpu_offload_member – This model will be attached to a pipeline which will have sequential cpu offload enabled?

• model_cpu_offload_member – This model will be attached to a pipeline which will have model cpu offload enabled?

Raises:

ModelNotFoundError – If the model could not be found.

Returns:

diffusers.T2IAdapter

static parse(uri: str) → T2IAdapterUri

Parse a --model-type torch* --t2i-adapters uri specification and return an object representing its constituents

Parameters:

uri – string with --t2i-adapters uri syntax

Raises:

InvalidT2IAdapterUriError –

Returns:

T2IAdapterUri

property dtype: DataType | None

Model dtype (precision)

property model: str

Model path, huggingface slug

property revision: str | None

Model repo revision

property scale: float

T2IAdapter scale

property subfolder: str | None

Model repo subfolder

property variant: str | None

Model repo revision

class dgenerate.pipelinewrapper.TextEncoderUri(encoder: str, model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None, quantize: str | None = None)

Bases: object

Representation of --text-encoders* uri when --model-type torch*

__init__(encoder: str, model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None, quantize: str | None = None)

Parameters:

• encoder – encoder class name, for example CLIPTextModel

• model – model path

• revision – model revision (branch name)

• variant – model variant, for example fp16

• subfolder – model subfolder

• dtype – model data type (precision)

• quantize – Quantize to a specific data type optimum-quanto, must be a supported dtype name that exists in optimum.quanto.qtypes, such as qint8 or qfloat8

Raises:

InvalidTextEncoderUriError – If dtype is passed an invalid data type string, or if model points to a single file and the specified encoder class name does not support loading from a single file.

load(variant_fallback: str | None = None, dtype_fallback: DataType = DataType.AUTO, use_auth_token: str | None = None, local_files_only: bool = False, sequential_cpu_offload_member: bool = False, model_cpu_offload_member: bool = False) → CLIPTextModel | CLIPTextModelWithProjection | T5EncoderModel

Load a torch Text Encoder of type transformers.models.clip.CLIPTextModel, transformers.models.clip.CLIPTextModelWithProjection, or transformers.models.t5.T5EncoderModel from this URI

Parameters:

• variant_fallback – If the URI does not specify a variant, use this variant.

• dtype_fallback – If the URI does not specify a dtype, use this dtype.

• use_auth_token – optional huggingface auth token.

• local_files_only – avoid downloading files and only look for cached files when the model path is a huggingface slug or blob link

• sequential_cpu_offload_member – This model will be attached to a pipeline which will have sequential cpu offload enabled?

• model_cpu_offload_member – This model will be attached to a pipeline which will have model cpu offload enabled?

Raises:

ModelNotFoundError – If the model could not be found.

Returns:

transformers.models.clip.CLIPTextModel, transformers.models.clip.CLIPTextModelWithProjection, or transformers.models.t5.T5EncoderModel

static parse(uri: str) → TextEncoderUri

Parse a --model-type torch* --text-encoders* uri and return an object representing its constituents

Parameters:

uri – string with --text-encoders* uri syntax

Raises:

InvalidTextEncoderUriError –

Returns:

TorchTextEncoderUri

static supported_encoder_names() → list[str]

property dtype: DataType | None

Model dtype (precision)

property encoder: str

Encoder class name such as “CLIPTextModel”

property model: str

Model path, huggingface slug

property quantize: str | None

optimum.quanto Quantization dtype

property revision: str | None

Model repo revision

property subfolder: str | None

Model repo subfolder

property variant: str | None

Model repo revision

class dgenerate.pipelinewrapper.TextualInversionUri(model: str, token: str | None = None, revision: str | None = None, subfolder: str | None = None, weight_name: str | None = None)

Bases: object

Representation of --textual-inversions uri

__init__(model: str, token: str | None = None, revision: str | None = None, subfolder: str | None = None, weight_name: str | None = None)

static load_on_pipeline(pipeline: DiffusionPipeline, uris: Iterable[TextualInversionUri | str], use_auth_token: str | None = None, local_files_only: bool = False)

Load Textual Inversion weights on to a pipeline using on or more URIs

Parameters:

• pipeline – diffusers.DiffusionPipeline

• uris – Iterable of TextualInversionUri or str Textual Inversion URIs to load

• use_auth_token – optional huggingface auth token.

• local_files_only – avoid downloading files and only look for cached files when the model path is a huggingface slug

Raises:

• ModelNotFoundError – If the model could not be found.

• dgenerate.pipelinewrapper.uris.exceptions.InvalidTextualInversionUriError – On URI parsing errors.

• dgenerate.pipelinewrapper.uris.exceptions.TextualInversionUriLoadError – On loading errors.

static parse(uri: str) → TextualInversionUri

Parse a --textual-inversions uri and return an object representing its constituents

Parameters:

uri – string with --textual-inversions uri syntax

Raises:

InvalidTextualInversionUriError –

Returns:

TextualInversionPath

property model: str

Model path, huggingface slug, file path

property revision: str | None

Model repo revision

property subfolder: str | None

Model repo subfolder

property token: str | None

Prompt keyword

property weight_name: str | None

Model weight-name

class dgenerate.pipelinewrapper.TorchPipelineCreationResult(pipeline: DiffusionPipeline, parsed_unet_uri: UNetUri | None, parsed_transformer_uri: TransformerUri | None, parsed_vae_uri: VAEUri | None, parsed_image_encoder_uri: ImageEncoderUri | None, parsed_lora_uris: Sequence[LoRAUri], parsed_ip_adapter_uris: Sequence[IPAdapterUri], parsed_textual_inversion_uris: Sequence[TextualInversionUri], parsed_controlnet_uris: Sequence[ControlNetUri], parsed_t2i_adapter_uris: Sequence[T2IAdapterUri])

Bases: PipelineCreationResult

__init__(pipeline: DiffusionPipeline, parsed_unet_uri: UNetUri | None, parsed_transformer_uri: TransformerUri | None, parsed_vae_uri: VAEUri | None, parsed_image_encoder_uri: ImageEncoderUri | None, parsed_lora_uris: Sequence[LoRAUri], parsed_ip_adapter_uris: Sequence[IPAdapterUri], parsed_textual_inversion_uris: Sequence[TextualInversionUri], parsed_controlnet_uris: Sequence[ControlNetUri], parsed_t2i_adapter_uris: Sequence[T2IAdapterUri])

call(device: str | None = 'cuda', prompt_weighter: PromptWeighter | None = None, **kwargs) → BaseOutput

Call pipeline, see: call_pipeline()

Parameters:

• device – move the pipeline to this device before calling

• prompt_weighter – Optional prompt weighter for weighted prompt syntaxes

• kwargs – forward kwargs to pipeline

Returns:

A subclass of diffusers.utils.BaseOutput

parsed_controlnet_uris: Sequence[ControlNetUri]

Parsed ControlNet URIs if any were present

parsed_image_encoder_uri: ImageEncoderUri | None

Parsed ImageEncoder URI if one was present

parsed_ip_adapter_uris: Sequence[IPAdapterUri]

Parsed IP Adapter URIs if any were present

parsed_lora_uris: Sequence[LoRAUri]

Parsed LoRA URIs if any were present

parsed_t2i_adapter_uris: Sequence[T2IAdapterUri]

Parsed T2IAdapter URIs if any were present

parsed_textual_inversion_uris: Sequence[TextualInversionUri]

Parsed Textual Inversion URIs if any were present

parsed_transformer_uri: TransformerUri | None

Parsed Transformer URI if one was present

parsed_unet_uri: UNetUri | None

Parsed UNet URI if one was present

parsed_vae_uri: VAEUri | None

Parsed VAE URI if one was present

property pipeline: DiffusionPipeline

A created subclass of diffusers.DiffusionPipeline

class dgenerate.pipelinewrapper.TorchPipelineFactory(model_path: str, model_type: ModelType = ModelType.TORCH, pipeline_type: PipelineType = PipelineType.TXT2IMG, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType = DataType.AUTO, unet_uri: str | None = None, transformer_uri: str | None = None, vae_uri: str | None = None, lora_uris: Sequence[str] | None = None, lora_fuse_scale: float | None = None, image_encoder_uri: str | None = None, ip_adapter_uris: Sequence[str] | None = None, textual_inversion_uris: Sequence[str] | None = None, controlnet_uris: Sequence[str] | None = None, t2i_adapter_uris: Sequence[str] | None = None, text_encoder_uris: Sequence[str] | None = None, scheduler: str | None = None, safety_checker: bool = False, auth_token: str | None = None, device: str = 'cuda', extra_modules: dict[str, Any] | None = None, model_cpu_offload: bool = False, sequential_cpu_offload: bool = False, local_files_only: bool = False, vae_tiling=False, vae_slicing=False)

Bases: object

Combines create_torch_diffusion_pipeline() and set_vae_slicing_tiling() into a factory that can recreate the same Torch pipeline over again, possibly from cache.

__call__() → TorchPipelineCreationResult

Raises:

• InvalidModelFileError –

• ModelNotFoundError –

• InvalidModelUriError –

• InvalidSchedulerNameError –

• UnsupportedPipelineConfigError –

Returns:

TorchPipelineCreationResult

__init__(model_path: str, model_type: ModelType = ModelType.TORCH, pipeline_type: PipelineType = PipelineType.TXT2IMG, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType = DataType.AUTO, unet_uri: str | None = None, transformer_uri: str | None = None, vae_uri: str | None = None, lora_uris: Sequence[str] | None = None, lora_fuse_scale: float | None = None, image_encoder_uri: str | None = None, ip_adapter_uris: Sequence[str] | None = None, textual_inversion_uris: Sequence[str] | None = None, controlnet_uris: Sequence[str] | None = None, t2i_adapter_uris: Sequence[str] | None = None, text_encoder_uris: Sequence[str] | None = None, scheduler: str | None = None, safety_checker: bool = False, auth_token: str | None = None, device: str = 'cuda', extra_modules: dict[str, Any] | None = None, model_cpu_offload: bool = False, sequential_cpu_offload: bool = False, local_files_only: bool = False, vae_tiling=False, vae_slicing=False)

class dgenerate.pipelinewrapper.UNetUri(model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Bases: object

Representation of --unet uri when --model-type torch*

__init__(model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Parameters:

• model – model path

• revision – model revision (branch name)

• variant – model variant, for example fp16

• subfolder – model subfolder

• dtype – model data type (precision)

Raises:

InvalidUNetUriError – If model points to a single file, single file loads are not supported. Or if dtype is passed an invalid data type string.

load(variant_fallback: str | None = None, dtype_fallback: ~dgenerate.pipelinewrapper.enums.DataType = DataType.AUTO, use_auth_token: str | None = None, local_files_only: bool = False, sequential_cpu_offload_member: bool = False, model_cpu_offload_member: bool = False, unet_class=<class 'diffusers.models.unets.unet_2d_condition.UNet2DConditionModel'>)

Load a UNet of type diffusers.UNet2DConditionModel

Parameters:

• variant_fallback – If the URI does not specify a variant, use this variant.

• dtype_fallback – If the URI does not specify a dtype, use this dtype.

• use_auth_token – optional huggingface auth token.

• local_files_only – avoid downloading files and only look for cached files when the model path is a huggingface slug or blob link

• sequential_cpu_offload_member – This model will be attached to a pipeline which will have sequential cpu offload enabled?

• model_cpu_offload_member – This model will be attached to a pipeline which will have model cpu offload enabled?

• unet_class – UNet class

Raises:

ModelNotFoundError – If the model could not be found.

Returns:

diffusers.UNet2DConditionModel

static parse(uri: str) → UNetUri

Parse a --model-type torch* --unet uri and return an object representing its constituents

Parameters:

uri – string with --unet uri syntax

Raises:

InvalidUNetUriError –

Returns:

TorchUNetPath

property dtype: DataType | None

Model dtype (precision)

property model: str

Model path, huggingface slug, file path, or blob link

property revision: str | None

Model repo revision

property subfolder: str | None

Model repo subfolder

property variant: str | None

Model repo revision

class dgenerate.pipelinewrapper.VAEUri(encoder: str, model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Bases: object

Representation of --vae uri when --model-type torch*

__init__(encoder: str, model: str, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType | str | None = None)

Parameters:

• encoder – encoder class name, for example AutoencoderKL

• model – model path

• revision – model revision (branch name)

• variant – model variant, for example fp16

• subfolder – model subfolder

• dtype – model data type (precision)

Raises:

InvalidVaeUriError – If dtype is passed an invalid data type string, or if model points to a single file and the specified encoder class name does not support loading from a single file.

load(dtype_fallback: DataType = DataType.AUTO, use_auth_token: str | None = None, local_files_only: bool = False, sequential_cpu_offload_member: bool = False, model_cpu_offload_member: bool = False) → AutoencoderKL | AsymmetricAutoencoderKL | AutoencoderTiny | ConsistencyDecoderVAE

Load a VAE of type diffusers.AutoencoderKL, diffusers.AsymmetricAutoencoderKL, diffusers.AutoencoderKLTemporalDecoder, or diffusers.AutoencoderTiny from this URI

Parameters:

• dtype_fallback – If the URI does not specify a dtype, use this dtype.

• use_auth_token – optional huggingface auth token.

• local_files_only – avoid downloading files and only look for cached files when the model path is a huggingface slug or blob link

• sequential_cpu_offload_member – This model will be attached to a pipeline which will have sequential cpu offload enabled?

• model_cpu_offload_member – This model will be attached to a pipeline which will have model cpu offload enabled?

Raises:

ModelNotFoundError – If the model could not be found.

Returns:

diffusers.AutoencoderKL, diffusers.AsymmetricAutoencoderKL, diffusers.AutoencoderKLTemporalDecoder, or diffusers.AutoencoderTiny

static parse(uri: str) → VAEUri

Parse a --model-type torch* --vae uri and return an object representing its constituents

Parameters:

uri – string with --vae uri syntax

Raises:

InvalidVaeUriError –

Returns:

TorchVAEPath

static supported_encoder_names() → list[str]

property dtype: DataType | None

Model dtype (precision)

property encoder: str

Encoder class name such as “AutoencoderKL”

property model: str

Model path, huggingface slug

property revision: str | None

Model repo revision

property subfolder: str | None

Model repo subfolder

property variant: str | None

Model repo revision

dgenerate.pipelinewrapper.adapter_cache_size() → int

Return the estimated memory usage in bytes of all user specified T2IAdapter models currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.adapter_create_update_cache_info(adapter, estimated_size: int)

Add additional information about the size of a newly created T2IAdapter model to the cache.

Tag the object with an internal tag.

Parameters:

• adapter – the T2IAdapter object

• estimated_size – size bytes

dgenerate.pipelinewrapper.adapter_off_cpu_update_cache_info(adapter: T2IAdapter | MultiAdapter)

Update CPU side cache size information when a T2IAdapter module is moved to a device that is not the CPU

Parameters:

adapter – the adapter, or multi adapter

dgenerate.pipelinewrapper.adapter_to_cpu_update_cache_info(adapter: T2IAdapter | MultiAdapter)

Update CPU side cache size information when a T2IAdapter module is moved to the CPU

Parameters:

adapter – the adapter, or multi adapter

dgenerate.pipelinewrapper.call_pipeline(pipeline: DiffusionPipeline, device: device | str | None = 'cuda', prompt_weighter: PromptWeighter = None, **kwargs)

Call a diffusers pipeline, offload the last called pipeline to CPU before doing so if the last pipeline is not being called in succession

Parameters:

• pipeline – The pipeline

• device – The device to move the pipeline to before calling, it will be moved to this device if it is not already on the device. If the pipeline does not support moving to specific device, such as with sequentially offloaded pipelines which cannot move at all, or cpu offloaded pipelines which can only move to CPU, this argument is ignored.

• kwargs – diffusers pipeline keyword arguments

• prompt_weighter – Optional prompt weighter for weighted prompt syntaxes

Raises:

• dgenerate.OutOfMemoryError – if there is not enough memory on the specified device

• UnsupportedPipelineConfiguration – If the pipeline is missing certain required modules, such as text encoders.

Returns:

the result of calling the diffusers pipeline

dgenerate.pipelinewrapper.clear_adapter_cache(collect=True)

Clear T2IAdapter cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_controlnet_cache(collect=True)

Clear ControlNet cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_image_encoder_cache(collect=True)

Clear Image Encoder cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_model_cache(collect=True)

Clear all in-memory model caches and garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_pipeline_cache(collect=True)

Clear DiffusionPipeline cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_text_encoder_cache(collect=True)

Clear Text Encoder cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_transformer_cache(collect=True)

Clear transformer model cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_unet_cache(collect=True)

Clear UNet cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.clear_vae_cache(collect=True)

Clear VAE cache and then garbage collect.

Parameters:

collect – Call gc.collect() ?

dgenerate.pipelinewrapper.controlnet_cache_size() → int

Return the estimated memory usage in bytes of all user specified ControlNet models currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.controlnet_create_update_cache_info(controlnet, estimated_size: int)

Add additional information about the size of a newly created ControlNet model to the cache.

Tag the object with an internal tag.

Parameters:

• controlnet – the ControlNet object

• estimated_size – size bytes

dgenerate.pipelinewrapper.controlnet_off_cpu_update_cache_info(controlnet: ControlNetModel | MultiControlNetModel | SD3ControlNetModel | SD3MultiControlNetModel)

Update CPU side cache size information when a ControlNet module is moved to a device that is not the CPU

Parameters:

controlnet – the control net, or multi control net

dgenerate.pipelinewrapper.controlnet_to_cpu_update_cache_info(controlnet: ControlNetModel | MultiControlNetModel | SD3ControlNetModel | SD3MultiControlNetModel)

Update CPU side cache size information when a ControlNet module is moved to the CPU

Parameters:

controlnet – the control net, or multi control net

dgenerate.pipelinewrapper.create_torch_diffusion_pipeline(model_path: str, model_type: ModelType = ModelType.TORCH, pipeline_type: PipelineType = PipelineType.TXT2IMG, revision: str | None = None, variant: str | None = None, subfolder: str | None = None, dtype: DataType = DataType.AUTO, unet_uri: str | None = None, transformer_uri: str | None = None, vae_uri: str | None = None, lora_uris: Sequence[str] | None = None, lora_fuse_scale: float | None = None, image_encoder_uri: str | None = None, ip_adapter_uris: Sequence[str] | None = None, textual_inversion_uris: Sequence[str] | None = None, text_encoder_uris: Sequence[str] | None = None, controlnet_uris: Sequence[str] | None = None, t2i_adapter_uris: Sequence[str] | None = None, scheduler: str | None = None, safety_checker: bool = False, auth_token: str | None = None, device: str = 'cuda', extra_modules: dict[str, Any] | None = None, model_cpu_offload: bool = False, sequential_cpu_offload: bool = False, local_files_only: bool = False) → TorchPipelineCreationResult

Create a diffusers.DiffusionPipeline in dgenerates in memory cacheing system.

Parameters:

• model_type – dgenerate.pipelinewrapper.ModelType enum value

• model_path – huggingface slug, huggingface blob link, path to folder on disk, path to file on disk

• pipeline_type – dgenerate.pipelinewrapper.PipelineType enum value

• revision – huggingface repo revision (branch)

• variant – model weights name variant, for example ‘fp16’

• subfolder – huggingface repo subfolder if applicable

• dtype – Optional dgenerate.pipelinewrapper.DataType enum value

• unet_uri – Optional --unet URI string for specifying a specific UNet

• transformer_uri – Optional --transformer URI string for specifying a specific Transformer, currently this is only supported for Stable Diffusion 3 and Flux models.

• vae_uri – Optional --vae URI string for specifying a specific VAE

• lora_uris – Optional --loras URI strings for specifying LoRA weights

• lora_fuse_scale – Optional --lora-fuse-scale global LoRA fuse scale value. Once all LoRAs are merged with their individual scales, the merged weights will be fused into the pipeline at this scale. The default value is 1.0.

• image_encoder_uri – Optional --image-encoder URI for use with IP Adapter weights or Stable Cascade

• ip_adapter_uris – Optional --ip-adapters URI strings for specifying IP Adapter weights

• textual_inversion_uris – Optional --textual-inversions URI strings for specifying Textual Inversion weights

• text_encoder_uris – Optional user specified --text-encoders URIs that will be loaded on to the pipeline in order. A uri value of + or None indicates use default, a string value of null indicates to explicitly not load any encoder all

• controlnet_uris – Optional --control-nets URI strings for specifying ControlNet models

• t2i_adapter_uris – Optional --t2i-adapters URI strings for specifying T2IAdapter models

• scheduler – Optional scheduler (sampler) class name, unqualified, or “help” / “helpargs” to print supported values to STDOUT and raise dgenerate.pipelinewrapper.SchedulerHelpException. Dgenerate URI syntax is supported for overriding the schedulers constructor parameter defaults.

• safety_checker – Safety checker enabled? default is False

• auth_token – Optional huggingface API token for accessing repositories that are restricted to your account

• device – Optional --device string, defaults to “cuda”

• extra_modules – Extra module arguments to pass directly into diffusers.DiffusionPipeline.from_single_file() or diffusers.DiffusionPipeline.from_pretrained()

• model_cpu_offload – This pipeline has model_cpu_offloading enabled?

• sequential_cpu_offload – This pipeline has sequential_cpu_offloading enabled?

• local_files_only – Only look in the huggingface cache and do not connect to download models?

Raises:

• InvalidModelFileError –

• ModelNotFoundError –

• InvalidModelUriError –

• InvalidSchedulerNameError –

• UnsupportedPipelineConfigError –

Returns:

TorchPipelineCreationResult

dgenerate.pipelinewrapper.destroy_last_called_pipeline(collect=True)

Move to CPU and dereference the globally cached pipeline last called with call_pipeline().

This is a no-op if a pipeline has never been called with call_pipeline()

Parameters:

collect – call gc.collect and torch.cuda.empty_cache if there is a pipeline to dereference?

dgenerate.pipelinewrapper.enable_model_cpu_offload(pipeline: DiffusionPipeline, device: device | str = 'cuda')

Enable sequential model cpu offload on a torch pipeline, in a way dgenerate can keep track of.

Parameters:

• pipeline – the pipeline

• device – the device

dgenerate.pipelinewrapper.enable_sequential_cpu_offload(pipeline: DiffusionPipeline, device: device | str = 'cuda')

Enable sequential offloading on a torch pipeline, in a way dgenerate can keep track of.

Parameters:

• pipeline – the pipeline

• device – the device

dgenerate.pipelinewrapper.enforce_adapter_cache_constraints(new_adapter_size, collect=True)

Enforce dgenerate.pipelinewrapper.ADAPTER_CACHE_MEMORY_CONSTRAINTS and clear the ControlNet cache if needed.

Parameters:

• new_adapter_size – estimated size in bytes of any new t2i adapter that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_cache_constraints(collect=True)

Enforce dgenerate.pipelinewrapper.CACHE_MEMORY_CONSTRAINTS and clear caches accordingly

Parameters:

collect – Call gc.collect() after a cache clear ?

Returns:

Whether any caches were cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_controlnet_cache_constraints(new_controlnet_size, collect=True)

Enforce dgenerate.pipelinewrapper.CONTROLNET_CACHE_MEMORY_CONSTRAINTS and clear the ControlNet cache if needed.

Parameters:

• new_controlnet_size – estimated size in bytes of any new control net that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_image_encoder_cache_constraints(new_image_encoder_size, collect=True)

Enforce dgenerate.pipelinewrapper.IMAGE_ENCODER_CACHE_MEMORY_CONSTRAINTS and clear the Image Encoder cache if needed.

Parameters:

• new_image_encoder_size – estimated size in bytes of any new image encoder that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_pipeline_cache_constraints(new_pipeline_size, collect=True)

Enforce dgenerate.pipelinewrapper.PIPELINE_CACHE_MEMORY_CONSTRAINTS and clear the diffusers.DiffusionPipeline cache if needed.

Parameters:

• new_pipeline_size – estimated size in bytes of any new pipeline that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_text_encoder_cache_constraints(new_text_encoder_size, collect=True)

Enforce dgenerate.pipelinewrapper.TEXT_ENCODER_CACHE_MEMORY_CONSTRAINTS and clear the Text Encoder cache if needed.

Parameters:

• new_text_encoder_size – estimated size in bytes of any new text encoder that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_transformer_cache_constraints(new_transformer_size, collect=True)

Enforce dgenerate.pipelinewrapper.TRANSFORMER_CACHE_MEMORY_CONSTRAINTS and clear the transformer model cache if needed.

Parameters:

• new_transformer_size – estimated size in bytes of any new transformer model that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_unet_cache_constraints(new_unet_size, collect=True)

Enforce dgenerate.pipelinewrapper.UNET_CACHE_MEMORY_CONSTRAINTS and clear the UNet cache if needed.

Parameters:

• new_unet_size – estimated size in bytes of any new unet that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.enforce_vae_cache_constraints(new_vae_size, collect=True)

Enforce dgenerate.pipelinewrapper.VAE_CACHE_MEMORY_CONSTRAINTS and clear the VAE cache if needed.

Parameters:

• new_vae_size – estimated size in bytes of any new vae that is about to enter memory

• collect – Call gc.collect() after a cache clear ?

Returns:

Whether the cache was cleared due to constraint expressions.

dgenerate.pipelinewrapper.estimate_pipeline_memory_use(model_path: str, model_type: ModelType, pipeline_type: PipelineType = PipelineType.TXT2IMG, revision: str = 'main', variant: str | None = None, subfolder: str | None = None, unet_uri: str | None = None, transformer_uri: str | None = None, vae_uri: str | None = None, lora_uris: Sequence[str] | None = None, image_encoder_uri: str | None = None, ip_adapter_uris: Sequence[str] | None = None, textual_inversion_uris: Sequence[str] | None = None, text_encoder_uris: Sequence[str] | None = None, safety_checker: bool = False, auth_token: str | None = None, extra_args: dict[str, Any] | None = None, local_files_only: bool = False)

Estimate the CPU side memory use of a pipeline.

Parameters:

• model_path – huggingface slug, blob link, path to folder on disk, path to model file.

• model_type – dgenerate.pipelinewrapper.ModelType

• pipeline_type – dgenerate.pipelinewrapper.PipelineType

• revision – huggingface repo revision if using a huggingface slug

• variant – model file variant desired, for example “fp16”

• subfolder – huggingface repo subfolder if using a huggingface slug

• unet_uri – optional user specified --unet URI that will be loaded on to the pipeline

• transformer_uri – optional user specified --transformer URI that will be loaded on to the pipeline, this is currently only supported for Stable Diffusion 3 and Flux models.

• vae_uri – optional user specified --vae URI that will be loaded on to the pipeline

• lora_uris – optional user specified --loras URIs that will be loaded on to the pipeline

• image_encoder_uri – optional user specified --image-encoder URI that will be loaded on to the pipeline

• ip_adapter_uris – optional user specified --ip-adapters URIs that will be loaded on to the pipeline

• textual_inversion_uris – optional user specified --textual-inversion URIs that will be loaded on to the pipeline

• text_encoder_uris – optional user specified --text-encoders URIs that will be loaded on to the pipeline

• safety_checker – consider the safety checker? dgenerate usually loads the safety checker and then retroactively disables it if needed, so it usually considers the size of the safety checker model.

• auth_token – optional huggingface auth token to access restricted repositories that your account has access to.

• extra_args – extra_args as to be passed to create_torch_diffusion_pipeline()

• local_files_only – Only ever attempt to look in the local huggingface cache? if False the huggingface API will be contacted when necessary.

Returns:

size estimate in bytes.

dgenerate.pipelinewrapper.get_data_type_enum(id_str: DataType | str | None) → DataType

Convert a --dtype string to its DataType enum value

Parameters:

id_str – --dtype string

Raises:

ValueError – if an invalid string value (name) is passed

Returns:

DataType

dgenerate.pipelinewrapper.get_data_type_string(data_type_enum: DataType) → str

Convert a DataType enum value to its --dtype string

Parameters:

data_type_enum – DataType value

Returns:

--dtype string

dgenerate.pipelinewrapper.get_last_called_pipeline() → DiffusionPipeline | None

Get a reference to the globally cached pipeline last called with call_pipeline().

This value may be None if a pipeline was never called.

Returns:

diffusion pipeline object

dgenerate.pipelinewrapper.get_model_type_enum(id_str: ModelType | str) → ModelType

Convert a --model-type string to its ModelType enum value

Parameters:

id_str – --model-type string

Raises:

ValueError – if an invalid string value (name) is passed

Returns:

ModelType

dgenerate.pipelinewrapper.get_model_type_string(model_type_enum: ModelType) → str

Convert a ModelType enum value to its --model-type string

Parameters:

model_type_enum – ModelType value

Returns:

--model-type string

dgenerate.pipelinewrapper.get_pipeline_type_enum(id_str: PipelineType | str | None) → PipelineType

Get a PipelineType enum value from a string.

Parameters:

id_str – one of: “txt2img”, “img2img”, or “inpaint”

Raises:

ValueError – if an invalid string value (name) is passed

Returns:

PipelineType

dgenerate.pipelinewrapper.get_pipeline_type_string(pipeline_type_enum: PipelineType)

Convert a PipelineType enum value to a string.

Parameters:

pipeline_type_enum – PipelineType value

Returns:

one of: “txt2img”, “img2img”, or “inpaint”

dgenerate.pipelinewrapper.get_torch_device(component: DiffusionPipeline | Module) → device

Get the device that a pipeline or pipeline component exists on.

Parameters:

component – pipeline or pipeline component.

Returns:

torch.device

dgenerate.pipelinewrapper.get_torch_device_string(component: DiffusionPipeline | Module) → str

Get the device string that a pipeline or pipeline component exists on.

Parameters:

component – pipeline or pipeline component.

Returns:

device string

dgenerate.pipelinewrapper.get_torch_dtype(dtype: DataType | dtype | str | None) → dtype | None

Return a torch.dtype datatype from a DataType value, or a string, or a torch.dtype datatype itself.

Passing None results in None being returned.

Passing ‘auto’ or DataType.AUTO results in None being returned.

Parameters:

dtype – DataType, string, torch.dtype, None

Raises:

ValueError – if an invalid string value (name) is passed

Returns:

torch.dtype

dgenerate.pipelinewrapper.get_torch_pipeline_modules(pipeline: DiffusionPipeline)

Get all component modules of a torch diffusers pipeline.

Parameters:

pipeline – the pipeline

Returns:

dictionary of modules by name

dgenerate.pipelinewrapper.image_encoder_cache_size() → int

Return the estimated memory usage in bytes of all user specified Image Encoders currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.image_encoder_create_update_cache_info(image_encoder, estimated_size: int)

Add additional information about the size of a newly created Image Encoder model to the cache.

Tag the object with an internal tag.

Parameters:

• image_encoder – the Image Encoder object

• estimated_size – size bytes

dgenerate.pipelinewrapper.image_encoder_off_cpu_update_cache_info(image_encoder)

Update CPU side cache size information when an Image Encoder module is moved to a device that is not the CPU

Parameters:

image_encoder – the Image Encoder

dgenerate.pipelinewrapper.image_encoder_to_cpu_update_cache_info(image_encoder)

Update CPU side cache size information when an Image Encoder module is moved to the CPU

Parameters:

image_encoder – the Image Encoder

dgenerate.pipelinewrapper.is_model_cpu_offload_enabled(module: DiffusionPipeline | Module)

Test if a pipeline or torch neural net module created by dgenerate has model cpu offload enabled.

Parameters:

module – the module object

Returns:

True or False

dgenerate.pipelinewrapper.is_quantized_and_frozen(model)

Return true if a model object has had dgenerate.pipelinewrapper.quanto.quantize_freeze called on it.

Parameters:

model – The model to test

Returns:

True or False

dgenerate.pipelinewrapper.is_sequential_cpu_offload_enabled(module: DiffusionPipeline | Module)

Test if a pipeline or torch neural net module created by dgenerate has sequential offload enabled.

Parameters:

module – the module object

Returns:

True or False

dgenerate.pipelinewrapper.is_valid_device_string(device, raise_ordinal=True)

Is a device string valid? including the device ordinal specified?

Other than cuda, “mps” (MacOS metal performance shaders) is experimentally supported.

Parameters:

• device – device string, such as cpu, or cuda, or cuda:N

• raise_ordinal – Raise InvalidDeviceOrdinalException if a specified CUDA device ordinal is found to not exist?

Raises:

InvalidDeviceOrdinalException – If raise_ordinal=True and a the device ordinal specified in a CUDA device string does not exist.

Returns:

True or False

dgenerate.pipelinewrapper.load_scheduler(pipeline: DiffusionPipeline, scheduler_name=None, model_path: str | None = None)

Load a specific compatible scheduler class name onto a huggingface diffusers pipeline object.

Raises:

SchedulerHelpException – if “help” is passed as a scheduler name.

Parameters:

• pipeline – pipeline object

• scheduler_name – compatible scheduler class name, pass “help” to receive a print out to STDOUT and raise SchedulerHelpException, this argument can accept a URI in typical dgenerate format, for overriding the schedulers constructor parameters.

• model_path – Optional model path to be used in the message to STDOUT produced by passing “help”

Returns:

dgenerate.pipelinewrapper.model_type_is_floyd(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an floyd “if” of “ifs” type model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_floyd_if(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an floyd “if” type model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_floyd_ifs(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an floyd “ifs” type model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_flux(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent a Flux model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_pix2pix(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an pix2pix type model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_s_cascade(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent a Stable Cascade related model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_sd3(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an SD3 model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_sdxl(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an SDXL model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_torch(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an Torch model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.model_type_is_upscaler(model_type: ModelType | str) → bool

Does a --model-type string or ModelType enum value represent an upscaler model?

Parameters:

model_type – --model-type string or ModelType enum value

Returns:

bool

dgenerate.pipelinewrapper.pipeline_cache_size() → int

Return the estimated memory usage in bytes of all diffusers pipelines currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.pipeline_create_update_cache_info(pipeline, estimated_size: int)

Add additional information about the size of a newly created diffusers.DiffusionPipeline to the cache.

Tag the object with an internal tag.

Parameters:

• pipeline – the diffusers.DiffusionPipeline object

• estimated_size – size bytes

dgenerate.pipelinewrapper.pipeline_off_cpu_update_cache_info(pipeline: DiffusionPipeline)

Update CPU side cache size information when a diffusers pipeline is moved to a device that is not the CPU

Parameters:

pipeline – the pipeline

dgenerate.pipelinewrapper.pipeline_to(pipeline, device: device | str | None)

Move a diffusers pipeline to a device if possible, in a way that dgenerate can keep track of.

This calls methods associated with updating the cache statistics such as dgenerate.pipelinewrapper.pipeline_off_cpu_update_cache_info() and dgenerate.pipelinewrapper.pipeline_to_cpu_update_cache_info() for you, as well as the associated cache update functions for the pipelines individual components as needed.

If device==None this is a no-op.

Modules which are meta tensors will not be moved (sequentially offloaded modules)

Modules which have model cpu offload enabled will not be moved unless they are moving to “cpu”

Raises:

dgenerate.OutOfMemoryError – if there is not enough memory on the specified device

Parameters:

• pipeline – the pipeline

• device – the device

Returns:

the moved pipeline

dgenerate.pipelinewrapper.pipeline_to_cpu_update_cache_info(pipeline: DiffusionPipeline)

Update CPU side cache size information when a diffusers pipeline is moved to the CPU

Parameters:

pipeline – the pipeline

dgenerate.pipelinewrapper.quantize_freeze(model: Module, weights: str | qtype | None = None, activations: str | qtype | None = None, optimizer: Optimizer | None = None, include: str | list[str] | None = None, exclude: str | list[str] | None = None)

Quantize and freeze a nn.Module with optimum.quanto.quantize.

Add an internal tag so it can be determined that this has happened.

Args:

model (torch.nn.Module): the model whose submodules will be quantized. weights (Optional[Union[str, qtype]]): the qtype for weights quantization. activations (Optional[Union[str, qtype]]): the qtype for activations quantization. include (Optional[Union[str, List[str]]]):

Patterns constituting the allowlist. If provided, module names must match at least one pattern from the allowlist.

exclude (Optional[Union[str, List[str]]]):

Patterns constituting the denylist. If provided, module names must not match any patterns from the denylist.

Parameters:

• model – The model

• weights – the qtype for weights quantization.

• activations – the qtype for activations quantization.

• optimizer –

• include – Patterns constituting the allowlist. If provided, module names must match at least one pattern from the allowlist.

• exclude – optimizer Patterns constituting the denylist. If provided, module names must not match any patterns from the denylist.

Returns:

The model

dgenerate.pipelinewrapper.scheduler_is_help(name: str | None)

This scheduler name is simply a request for help?, IE: “help”?

Parameters:

name – string to test

Returns:

True or False

dgenerate.pipelinewrapper.set_vae_slicing_tiling(pipeline: DiffusionPipeline, vae_tiling: bool, vae_slicing: bool)

Set the vae_slicing and vae_tiling status on a created huggingface diffusers pipeline.

Raises:

UnsupportedPipelineConfigError – if the pipeline does not support one or both of the provided values for vae_tiling and vae_slicing

Parameters:

• pipeline – pipeline object

• vae_tiling – tiling status

• vae_slicing – slicing status

dgenerate.pipelinewrapper.supported_data_type_enums() → list[DataType]

Return a list of supported DataType enum values

dgenerate.pipelinewrapper.supported_data_type_strings()

Return a list of supported --dtype strings

dgenerate.pipelinewrapper.supported_model_type_enums() → list[ModelType]

Return a list of supported ModelType enum values

dgenerate.pipelinewrapper.supported_model_type_strings()

Return a list of supported --model-type strings

dgenerate.pipelinewrapper.text_encoder_cache_size() → int

Return the estimated memory usage in bytes of all user specified Text Encoder models currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.text_encoder_create_update_cache_info(text_encoder, estimated_size: int)

Add additional information about the size of a newly created Text Encoder model to the cache.

Tag the object with an internal tag.

Parameters:

• text_encoder – the Text Encoder object

• estimated_size – size bytes

dgenerate.pipelinewrapper.text_encoder_is_help(text_encoder_uris: Sequence[str] | None)

Text encoder uris specification is simply a request for help?, IE: “help”?

Parameters:

text_encoder_uris – list of text encoder URIs to test

Returns:

True or False

dgenerate.pipelinewrapper.text_encoder_off_cpu_update_cache_info(text_encoder)

Update CPU side cache size information when a Text Encoder module is moved to a device that is not the CPU

Parameters:

text_encoder – the Text Encoder

dgenerate.pipelinewrapper.text_encoder_to_cpu_update_cache_info(text_encoder)

Update CPU side cache size information when a Text Encoder module is moved to the CPU

Parameters:

text_encoder – the Text Encoder

dgenerate.pipelinewrapper.transformer_cache_size() → int

Return the estimated memory usage in bytes of all transformer models currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.transformer_create_update_cache_info(transformer, estimated_size: int)

Add additional information about the size of a newly created transformer model to the cache.

Tag the object with an internal tag.

Parameters:

• transformer – the transformer object

• estimated_size – size bytes

dgenerate.pipelinewrapper.transformer_off_cpu_update_cache_info(transformer)

Update CPU side cache size information when a transformer module is moved to a device that is not the CPU

Parameters:

transformer – the transformer

dgenerate.pipelinewrapper.transformer_to_cpu_update_cache_info(transformer)

Update CPU side cache size information when a transformer module is moved to the CPU

Parameters:

transformer – the transformer

dgenerate.pipelinewrapper.unet_cache_size() → int

Return the estimated memory usage in bytes of all user specified UNets currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.unet_create_update_cache_info(unet, estimated_size: int)

Add additional information about the size of a newly created UNet model to the cache.

Tag the object with an internal tag.

Parameters:

• unet – the UNet object

• estimated_size – size bytes

dgenerate.pipelinewrapper.unet_off_cpu_update_cache_info(unet)

Update CPU side cache size information when a UNet module is moved to a device that is not the CPU

Parameters:

unet – the UNet

dgenerate.pipelinewrapper.unet_to_cpu_update_cache_info(unet)

Update CPU side cache size information when a UNet module is moved to the CPU

Parameters:

unet – the UNet

dgenerate.pipelinewrapper.uri_hash_with_parser(parser, exclude: set[str] | None = None)

Create a hash function from a particular URI parser function that hashes a URI string.

The URI is parsed and then the object that results from parsing is hashed with dgenerate.memoize.struct_hasher().

If the parser returns a string, it is regarded as the hash value instead of being passed to dgenerate.memoize.struct_hasher().

Parameters:

• parser – The URI parser function

• exclude – URI argument names to exclude from hashing

Returns:

a hash function compatible with dgenerate.memoize.memoize()

dgenerate.pipelinewrapper.uri_list_hash_with_parser(parser, exclude: set[str] | None = None)

Create a hash function from a particular URI parser function that hashes a list of URIs.

Parameters:

• parser – The URI parser function

• exclude – URI argument names to exclude from hashing

Returns:

a hash function compatible with dgenerate.memoize.memoize()

dgenerate.pipelinewrapper.vae_cache_size() → int

Return the estimated memory usage in bytes of all user specified VAEs currently cached in memory.

Returns:

memory usage in bytes.

dgenerate.pipelinewrapper.vae_create_update_cache_info(vae, estimated_size: int)

Add additional information about the size of a newly created VAE model to the cache.

Tag the object with an internal tag.

Parameters:

• vae – the VAE object

• estimated_size – size bytes

dgenerate.pipelinewrapper.vae_off_cpu_update_cache_info(vae)

Update CPU side cache size information when a VAE module is moved to a device that is not the CPU

Parameters:

vae – the VAE

dgenerate.pipelinewrapper.vae_to_cpu_update_cache_info(vae)

Update CPU side cache size information when a VAE module is moved to the CPU

Parameters:

vae – the VAE

dgenerate.pipelinewrapper.CACHE_MEMORY_CONSTRAINTS = ['used_percent > 70']

Cache constraint expressions for when to clear all model caches (DiffusionPipeline, VAE, ControlNet, and Text Encoder), syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, a call to enforce_cache_constraints() will call clear_model_cache() and force a garbage collection.

dgenerate.pipelinewrapper.PIPELINE_CACHE_MEMORY_CONSTRAINTS = ['pipeline_size > (available * 0.75)']

Cache constraint expressions for when to clear the DiffusionPipeline cache, syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, a call to enforce_pipeline_cache_constraints() will call clear_pipeline_cache() and force a garbage collection.

Extra variables include: cache_size (the current estimated cache size in bytes), and pipeline_size (the estimated size of the new pipeline before it is brought into memory, in bytes)

dgenerate.pipelinewrapper.UNET_CACHE_MEMORY_CONSTRAINTS = ['unet_size > (available * 0.75)']

Cache constraint expressions for when to clear UNet cache, syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, a call to enforce_unet_cache_constraints() will call clear_unet_cache() and force a garbage collection.

Extra variables include: cache_size (the current estimated cache size in bytes), and unet_size (the estimated size of the new UNet before it is brought into memory, in bytes)

dgenerate.pipelinewrapper.VAE_CACHE_MEMORY_CONSTRAINTS = ['vae_size > (available * 0.75)']

Cache constraint expressions for when to clear VAE cache, syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, a call to enforce_vae_cache_constraints() will call clear_vae_cache() and force a garbage collection.

Extra variables include: cache_size (the current estimated cache size in bytes), and vae_size (the estimated size of the new VAE before it is brought into memory, in bytes)

dgenerate.pipelinewrapper.CONTROLNET_CACHE_MEMORY_CONSTRAINTS = ['controlnet_size > (available * 0.75)']

Cache constraint expressions for when to clear the ControlNet cache, syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, a call to enforce_controlnet_cache_constraints() will call clear_controlnet_cache() and force a garbage collection.

Extra variables include: cache_size (the current estimated cache size in bytes), and controlnet_size (the estimated size of the new ControlNet before it is brought into memory, in bytes)

dgenerate.pipelinewrapper.ADAPTER_CACHE_MEMORY_CONSTRAINTS = ['adapter_size > (available * 0.75)']

Cache constraint expressions for when to clear the T2IAdapter cache, syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, a call to enforce_adapter_cache_constraints() will call clear_adapter_cache() and force a garbage collection.

Extra variables include: cache_size (the current estimated cache size in bytes), and adapter_size (the estimated size of the new T2IAdapter before it is brought into memory, in bytes)

dgenerate.pipelinewrapper.TEXT_ENCODER_CACHE_MEMORY_CONSTRAINTS = ['text_encoder_size > (available * 0.75)']

Cache constraint expressions for when to clear the Text Encoder cache, syntax provided via dgenerate.memory.memory_constraints()

If any of these constraints are met, a call to enforce_text_encoder_cache_constraints() will call clear_text_encoder_cache() and force a garbage collection.

Extra variables include: cache_size (the current estimated cache size in bytes), and text_encoder_size (the estimated size of the new Text Encoder before it is brought into memory, in bytes)

dgenerate.pipelinewrapper.DEFAULT_INFERENCE_STEPS = 30

Default value for inference steps.

dgenerate.pipelinewrapper.DEFAULT_GUIDANCE_SCALE = 5

Default value for guidance scale.

dgenerate.pipelinewrapper.DEFAULT_IMAGE_SEED_STRENGTH = 0.8

Default image seed strength for img2img.

dgenerate.pipelinewrapper.DEFAULT_IMAGE_GUIDANCE_SCALE = 1.5

Default image guidance scale for pix2pix.

dgenerate.pipelinewrapper.DEFAULT_SDXL_HIGH_NOISE_FRACTION = 0.8

Default SDXL high noise fraction.

dgenerate.pipelinewrapper.DEFAULT_X4_UPSCALER_NOISE_LEVEL = 20

Default x4 upscaler noise level.

dgenerate.pipelinewrapper.DEFAULT_FLOYD_SUPERRESOLUTION_NOISE_LEVEL = 250

Default noise level for floyd super resolution upscalers.

dgenerate.pipelinewrapper.DEFAULT_FLOYD_SUPERRESOLUTION_IMG2IMG_NOISE_LEVEL = 250

Default noise level for floyd super resolution upscalers when preforming img2img.

dgenerate.pipelinewrapper.DEFAULT_FLOYD_SUPERRESOLUTION_INPAINT_NOISE_LEVEL = 0

Default noise level for floyd super resolution upscalers when inpainting.

dgenerate.pipelinewrapper.DEFAULT_OUTPUT_WIDTH = 512

Default output width for txt2img.

dgenerate.pipelinewrapper.DEFAULT_OUTPUT_HEIGHT = 512

Default output height for txt2img.

dgenerate.pipelinewrapper.DEFAULT_SDXL_OUTPUT_WIDTH = 1024

Default output width for SDXL txt2img.

dgenerate.pipelinewrapper.DEFAULT_SDXL_OUTPUT_HEIGHT = 1024

Default output height for SDXL txt2img.

dgenerate.pipelinewrapper.DEFAULT_FLOYD_IF_OUTPUT_WIDTH = 64

Default output width for Deep Floyd IF txt2img first stage.

dgenerate.pipelinewrapper.DEFAULT_FLOYD_IF_OUTPUT_HEIGHT = 64

Default output height for Deep Floyd IF txt2img first stage.

dgenerate.pipelinewrapper.DEFAULT_SEED = 0

Default RNG seed.

dgenerate.pipelinewrapper.DEFAULT_S_CASCADE_DECODER_GUIDANCE_SCALE = 0

Default guidance scale for the Stable Cascade decoder.

dgenerate.pipelinewrapper.DEFAULT_S_CASCADE_DECODER_INFERENCE_STEPS = 10

Default inference steps for the Stable Cascade decoder.

dgenerate.pipelinewrapper.DEFAULT_S_CASCADE_OUTPUT_HEIGHT = 1024

Default output height for Stable Cascade.

dgenerate.pipelinewrapper.DEFAULT_S_CASCADE_OUTPUT_WIDTH = 1024

Default output width for Stable Cascade.

dgenerate.pipelinewrapper.DEFAULT_SD3_OUTPUT_HEIGHT = 1024

Default output height for Stable Diffusion 3.

dgenerate.pipelinewrapper.DEFAULT_SD3_OUTPUT_WIDTH = 1024

Default output width for Stable Diffusion 3.

dgenerate.pipelinewrapper.DEFAULT_FLUX_OUTPUT_HEIGHT = 1024

Default output height for Flux.

dgenerate.pipelinewrapper.DEFAULT_FLUX_OUTPUT_WIDTH = 1024

Default output width for Flux.

dgenerate.plugin module

URI based plugin loading system base implementations.

exception dgenerate.plugin.ModuleFileNotFoundError

Bases: FileNotFoundError

Raised by load_modules() if a module could not be found on disk.

exception dgenerate.plugin.PluginArgumentError

Bases: Exception

Raised when a plugin encounters an error in the arguments it is loaded by.

Or errors in arguments used for execution.

exception dgenerate.plugin.PluginNotFoundError

Bases: Exception

Raised when a plugin could not be located by a name.

class dgenerate.plugin.Plugin(loaded_by_name: str, argument_error_type: type[~dgenerate.plugin.PluginArgumentError] = <class 'dgenerate.plugin.PluginArgumentError'>, **kwargs)

Bases: object

__init__(loaded_by_name: str, argument_error_type: type[~dgenerate.plugin.PluginArgumentError] = <class 'dgenerate.plugin.PluginArgumentError'>, **kwargs)

Parameters:

• loaded_by_name – The name the plugin was loaded by, will be passed by the loader.

• argument_error_type – This exception type will be raised upon argument errors (invalid arguments) when loading a plugin using a PluginLoader implementation. It should match the argument_error_type given to the PluginLoader implementation being used to load the inheritor of this class.

• kwargs – Additional arguments that may arise when using an ARGS static signature definition with multiple NAMES in your implementation.

argument_error(msg: str)

Return an constructed exception that is suitable for raising as an argument error for this plugin.

Example: raise self.argument_error('oops!')

Parameters:

msg – exception message

Returns:

the exception object, you must raise it.

classmethod get_accepted_args(loaded_by_name: str, include_bases: bool = False)

Retrieve the argument signature of a plugin implementation.

Parameters:

• loaded_by_name – The name used to load the plugin. Argument signature may vary by name used to load.

• include_bases – Include all base classes except Plugin?

Returns:

List of argument descriptors, PluginArg

classmethod get_accepted_args_schema(loaded_by_name: str, include_bases: bool = False)

Reduce the accepted arguments to a schema dict.

Keyed by argument name, content keys include:

default contains any default value, this key may not exist if the argument has no default value.

types contains all accepted types for the argument in string form.

optional can the argument accept the value None?

Parameters:

• loaded_by_name – Plugin loaded by name

• include_bases – Include all base classes except Plugin?

Returns:

dict

classmethod get_bases() → list[Type[Plugin]]

Return a list of base classes, except for Plugin

Returns:

list of class type objects

classmethod get_default_args(loaded_by_name: str) → list[PluginArg]

Get the names and values of arguments for this plugin that possess default values.

Parameters:

loaded_by_name – The name used to load the plugin. Default arguments may vary by name used to load.

Returns:

list of arguments with default value: (name, value)

classmethod get_help(loaded_by_name: str, wrap_width: int | None = None, include_bases: bool = False) → str

Get formatted help information about the plugin.

This includes any implemented help strings and an auto formatted description of the plugins accepted arguments.

Parameters:

• loaded_by_name – The name used to load the plugin. Help may vary depending on how many names the plugin implementation handles and what loading it by a certain name does.

• wrap_width – wrap paragraphs to this width.

• include_bases – include argument names and inherited help from base classes?

Returns:

Formatted help string

classmethod get_hidden_args(loaded_by_name: str) → set[str]

Get argument names that have been explicitly hidden from use or disabled by the plugin for URI use.

These may be unsupported arguments inherited from a base class, or just arguments the plugin does not want you to use via a URI.

These arguments can still be passed manually from code in the interest of maintaining a generic interface, but they may be ignored by the plugin implementation.

Parameters:

loaded_by_name – The name used to load the plugin. Argument signature may vary by name used to load.

Returns:

hidden argument names

classmethod get_names() → list[str]

Get the names that this class can be loaded by.

Returns:

classmethod get_required_args(loaded_by_name: str) → list[PluginArg]

Get a list of required arguments for this plugin class.

Parameters:

loaded_by_name – The name used to load the plugin. Required arguments may vary by name used to load.

Returns:

list of argument names

property loaded_by_name: str

The name the plugin was loaded by.

Returns:

name

class dgenerate.plugin.PluginArg(name: str, type: type = typing.Any, **kwargs)

Bases: object

__init__(name: str, type: type = typing.Any, **kwargs)

name_dashdown() → PluginArg

name_dashup() → PluginArg

parse_by_type(value: str | Any)

type_string()

validate_non_parsed(value: Any)

property base_type

property hinted_optional_type

property is_hinted_optional

class dgenerate.plugin.PluginLoader(base_class=<class 'dgenerate.plugin.Plugin'>, description: str = 'plugin', reserved_args: list[~dgenerate.plugin.PluginArg] | None = None, argument_error_type: type[~dgenerate.plugin.PluginArgumentError] = <class 'dgenerate.plugin.PluginArgumentError'>, not_found_error_type: type[~dgenerate.plugin.PluginNotFoundError] = <class 'dgenerate.plugin.PluginNotFoundError'>)

Bases: object

__init__(base_class=<class 'dgenerate.plugin.Plugin'>, description: str = 'plugin', reserved_args: list[~dgenerate.plugin.PluginArg] | None = None, argument_error_type: type[~dgenerate.plugin.PluginArgumentError] = <class 'dgenerate.plugin.PluginArgumentError'>, not_found_error_type: type[~dgenerate.plugin.PluginNotFoundError] = <class 'dgenerate.plugin.PluginNotFoundError'>)

Parameters:

• base_class – Base class of plugins, will be used for searching modules.

• description – Short plugin description / name, used in exception messages.

• reserved_args – Constructor arguments that are used by the plugin class which cannot be redefined by implementors of the plugin class. This should be a list of plugin argument descriptors, PluginArg

• argument_error_type – This exception type will be raised when the plugin is loaded with invalid URI arguments.

• not_found_error_type – This exception type will be raised when a plugin could not be located by a name specified in a loading URI.

add_class(cls: type[Plugin])

Add an implementation class to this loader.

Raises:

RuntimeError – If the added class specifies a name that already exists in this loader.

Parameters:

cls – the class

add_search_module(module: module) → list[type[Plugin]]

Directly add a module object that will be searched for implementations.

Parameters:

module – the module object

Raises:

ValueError – If module is not a python module object.

Returns:

list of classes that were newly discovered

add_search_module_string(string: str) → list[type[Plugin]]

Add a module string (in sys.modules) that will be searched for implementations.

Parameters:

string – the module string

Returns:

list of classes that were newly discovered

get_accepted_args_schema(include_bases: bool = False) → dict[str, dict[str, Any]]

Get a Plugin.get_accepted_args_schema() for every plugin class, keyed by callable plugin name.

Parameters:

include_bases – Include base class arguments? This excludes the base Plugin

Returns:

dict

get_all_names() → Sequence[str]

Get all plugin names that this loader can see.

Returns:

list of names (strings)

get_available_classes() → list[type[Plugin]]

Get classes seen by this plugin loader.

Returns:

list of classes (types)

get_class_by_name(plugin_name: str) → type[Plugin]

Get a plugin class by one of its names.

IE: one of the names listed in its NAMES static attribute.

Parameters:

plugin_name – a name associated with a plugin class

Raises:

PluginNotFoundError – If the plugin name could not be found.

Returns:

class (type)

get_help(plugin_name: str, wrap_width: int | None = None, include_bases: bool = False) → str

Get a formatted help string for a plugin by one of its loadable names.

Parameters:

• plugin_name – a name associated with the plugin class

• wrap_width – wrap paragraphs to this width.

• include_bases – include argument names and inherited help from base classes?

Raises:

PluginNotFoundError – If the plugin name could not be found.

Returns:

formatted string

load(uri: str, **kwargs) → Plugin

Load an plugin using a URI string containing its name and arguments.

Parameters:

• uri – The URI string

• kwargs – default argument values, will be override by arguments specified in the URI

Raises:

• ValueError – If uri is None

• RuntimeError – If a plugin is discovered to be using a reserved argument name upon loading it.

• dgenerate.plugin.PluginArgumentError – If there is an error in the loading arguments for the plugin.

• dgenerate.plugin.PluginNotFoundError – If the plugin name mentioned in the URI could not be found.

Returns:

plugin instance

load_plugin_modules(paths: Iterable[str]) → list[type[Plugin]]

Modules that will be loaded from disk, or the python environment, and searched for implementations.

Either python files, or module directories containing __init__.py, or names of python modules installed in the environment.

It can be a mix of these.

Raises:

ModuleFileNotFoundError – If a module path could not be found on disk, or when a module could not be loaded from the python environment.

Parameters:

paths – list of folder/file paths, or references to python modules installed in the environment

Returns:

list of classes that were newly discovered

loader_help(names: Sequence[str], plugin_module_paths: Sequence[str] | None = None, title='plugin', title_plural='plugins', throw=False, log_error=True, include_bases: bool = False)

Implements --sub-command-help and --image-processor-help command line options for example.

Parameters:

• names – arguments (sub-command names, or empty list)

• plugin_module_paths – extra plugin module paths to search

• title – plugin title, used in messages

• title_plural – plural plugin title, used in messages

• throw – throw on error?

• log_error – log errors to stderr?

• include_bases – include argument names from base classes?

Raises:

• PluginNotFoundError – names contained an unknown plugin name

• ModuleFileNotFoundError – plugin_module_paths contained a missing module

Returns:

return-code, anything other than 0 is failure

property plugin_module_paths: frozenset[str]

Every module path ever seen by PluginLoader.load_plugin_modules().

Returns:

frozen set

dgenerate.plugin.import_plugins(paths: Iterable[str])

Set plugin paths that will be considered by all plugin loader instances.

Parameters:

paths – environment modules, python script paths, directory paths

dgenerate.plugin.load_modules(paths: Iterable[str]) → list[module]

Load python modules from a folder, directly from a .py file, or from a python module installed in the environment. Cache them so that repeat requests for loading return an already loaded module.

Raises:

ModuleFileNotFoundError – If a module path could not be found on disk, or when a module could not be loaded from the python environment.

Parameters:

paths – list of folder/file paths, or references to python modules installed in the environment

Returns:

list of types.ModuleType

dgenerate.plugin.LOADED_PLUGIN_MODULES: dict[str, module] = {}

Plugin module in memory cache

dgenerate.plugin.PLUGIN_PATHS = {}

Plugin paths that are considered by all PluginLoader instances.

This should be updated with import_plugins()

dgenerate.prompt module

Prompt representation object / prompt parsing.

class dgenerate.prompt.Prompt(positive: str | None = None, negative: str | None = None, delimiter: str = ';')

Bases: object

Represents a combined positive and optional negative prompt split by a delimiter character.

__init__(positive: str | None = None, negative: str | None = None, delimiter: str = ';')

Parameters:

• positive – positive prompt component

• negative – negative prompt component

• delimiter – delimiter for stringification

__str__()

Return str(self).

static parse(value: str, delimiter=';') → Prompt

Parse the positive and negative prompt from a string and return a prompt object.

Parameters:

• value – the string

• delimiter – The prompt delimiter character

Raises:

ValueError – if value is None

Returns:

Prompt (returns self)

dgenerate.promptweighters module

exception dgenerate.promptweighters.PromptWeighterArgumentError

Bases: PluginArgumentError

Thrown when a dgenerate.promptweighters.PromptWeighter implementation is loaded with an invalid argument.

exception dgenerate.promptweighters.PromptWeighterNotFoundError

Bases: PluginNotFoundError

Thrown when a dgenerate.promptweighters.PromptWeighter implementation could not be found for a given name.

exception dgenerate.promptweighters.PromptWeightingUnsupported

Bases: Exception

Thrown when a dgenerate.promptweighters.PromptWeighter implementation cannot handle a specific pipeline or combination of pipeline arguments.

class dgenerate.promptweighters.CompelPromptWeighter(syntax: str = 'compel', **kwargs)

Bases: PromptWeighter

Implements prompt weighting syntax for Stable Diffusion 1/2 and Stable Diffusion XL using compel. The default syntax is “compel” which is analogous to the syntax used by InvokeAI.

Specifying the syntax “sdwui” will translate your prompt from Stable Diffusion Web UI syntax into compel / InvokeAI syntax before generating the prompt embeddings.

If you wish to use prompt syntax for weighting tokens that is similar to ComfyUI, Automatic1111, or CivitAI for example, use: ‘compel;syntax=sdwui’

The underlying weighting behavior for tokens is not exactly the same as other software that uses the more common “sdwui” syntax, so your prompt may need adjusting if you are reusing a prompt from those other pieces of software.

You can read about compel here: https://github.com/damian0815/compel

And InvokeAI here: https://github.com/invoke-ai/InvokeAI

This prompt weighter supports the model types:

NOWRAP! –model-type torch –model-type torch-pix2pix –model-type torch-upscaler-x4 –model-type torch-sdxl –model-type torch-sdxl-pix2pix –model-type torch-s-cascade

The secondary prompt option for SDXL –sdxl-second-prompts is supported by this prompt weighter implementation. However, –sdxl-refiner-second-prompts is not supported and will be ignored with a warning message.

__init__(syntax: str = 'compel', **kwargs)

Parameters:

• loaded_by_name – The name the prompt weighter was loaded by

• model_type – Model type enum dgenerate.ModelType

• pipeline_type – Pipeline type enum dgenerate.PipelineType

• dtype – Data type enum dgenerate.DataType

• kwargs – child class forwarded arguments

cleanup()

Preform any cleanup required after translating the pipeline arguments to embeds

translate_to_embeds(pipeline, device: str, args: dict[str, any])

Translate the pipeline prompt arguments to prompt_embeds and pooled_prompt_embeds as needed.

Parameters:

• pipeline – The pipeline object

• device – The device the pipeline modules are on

• args – Call arguments to the pipeline

Returns:

args, supplemented with prompt embedding arguments

NAMES = ['compel']

class dgenerate.promptweighters.PromptWeighter(loaded_by_name: str, model_type: ModelType, pipeline_type: PipelineType, dtype: DataType, **kwargs)

Bases: Plugin

Abstract base class for prompt weighter implementations.

__init__(loaded_by_name: str, model_type: ModelType, pipeline_type: PipelineType, dtype: DataType, **kwargs)

Parameters:

• loaded_by_name – The name the prompt weighter was loaded by

• model_type – Model type enum dgenerate.ModelType

• pipeline_type – Pipeline type enum dgenerate.PipelineType

• dtype – Data type enum dgenerate.DataType

• kwargs – child class forwarded arguments

cleanup()

Preform any cleanup required after translating the pipeline arguments to embeds

translate_to_embeds(pipeline, device: str, args: dict[str, any])

Translate the pipeline prompt arguments to prompt_embeds and pooled_prompt_embeds as needed.

Parameters:

• pipeline – The pipeline object

• device – The device the pipeline modules are on

• args – Call arguments to the pipeline

Returns:

args, supplemented with prompt embedding arguments

HIDE_ARGS = ['model-type', 'pipeline-type', 'dtype']

property dtype: DataType

property model_type: ModelType

property pipeline_type: PipelineType

class dgenerate.promptweighters.PromptWeighterLoader

Bases: PluginLoader

Loads dgenerate.promptweighters.PromptWeighter plugins.

__init__()

load(uri: str, **kwargs) → PromptWeighter

Load an plugin using a URI string containing its name and arguments.

Parameters:

• uri – The URI string

• kwargs – default argument values, will be override by arguments specified in the URI

Raises:

• ValueError – If uri is None

• RuntimeError – If a plugin is discovered to be using a reserved argument name upon loading it.

• dgenerate.plugin.PluginArgumentError – If there is an error in the loading arguments for the plugin.

• dgenerate.plugin.PluginNotFoundError – If the plugin name mentioned in the URI could not be found.

Returns:

plugin instance

class dgenerate.promptweighters.SdEmbedPromptWeighter(**kwargs)

Bases: PromptWeighter

Implements prompt weighting syntax for Stable Diffusion 1/2, Stable Diffusion XL, and Stable Diffusion 3, and Flux using sd_embed.

sd_embed uses a Stable Diffusion Web UI compatible prompt syntax.

See: https://github.com/xhinker/sd_embed

NOWRAP! @misc{sd_embed_2024,

author = {Shudong Zhu(Andrew Zhu)}, title = {Long Prompt Weighted Stable Diffusion Embedding}, howpublished = {url{https://github.com/xhinker/sd_embed}}, year = {2024},

}

NOWRAP! –model-type torch –model-type torch-pix2pix –model-type torch-upscaler-x4 –model-type torch-sdxl –model-type torch-sdxl-pix2pix –model-type torch-s-cascade –model-type torch-sd3 –model-type torch-flux

The secondary prompt option for SDXL –sdxl-second-prompts is supported by this prompt weighter implementation. However, –sdxl-refiner-second-prompts is not supported and will be ignored with a warning message.

The secondary prompt option for SD3 –sd3-second-prompts is not supported by this prompt weighter implementation. Neither is –sd3-third-prompts. The prompts from these arguments will be ignored.

The secondary prompt option for Flux –flux-second-prompts is supported by this prompt weighter.

Flux does not support negative prompting in either prompt.

__init__(**kwargs)

Parameters:

• loaded_by_name – The name the prompt weighter was loaded by

• model_type – Model type enum dgenerate.ModelType

• pipeline_type – Pipeline type enum dgenerate.PipelineType

• dtype – Data type enum dgenerate.DataType

• kwargs – child class forwarded arguments

cleanup()

Preform any cleanup required after translating the pipeline arguments to embeds

translate_to_embeds(pipeline, device: str, args: dict[str, any])

Translate the pipeline prompt arguments to prompt_embeds and pooled_prompt_embeds as needed.

Parameters:

• pipeline – The pipeline object

• device – The device the pipeline modules are on

• args – Call arguments to the pipeline

Returns:

args, supplemented with prompt embedding arguments

NAMES = ['sd-embed']

dgenerate.promptweighters.create_prompt_weighter(uri, model_type: ModelType, pipeline_type: PipelineType, dtype: DataType) → PromptWeighter

Create a prompt weighter implementation using the default PromptWeighterLoader instance.

Parameters:

• uri – The prompt weighter URI

• model_type – Model type the prompt weighter is expected to handle

• pipeline_type – Pipeline type the prompt weighter is expected to handle

• dtype – The dtype of the pipeline

Returns:

A PromptWeighter implementation

dgenerate.promptweighters.prompt_weighter_exists(uri)

Check if a prompt weighter implementation exists for a given URI.

This uses the default PromptWeighterLoader instance.

Parameters:

uri – The prompt weighter URI

Returns:

True or False

dgenerate.promptweighters.prompt_weighter_help(names: Sequence[str], plugin_module_paths: Sequence[str] | None = None, throw=False, log_error=True)

Implements --prompt-weighter-help command line option

Parameters:

• names – arguments (prompt weighter names, or empty list)

• plugin_module_paths – extra plugin module paths to search

• throw – throw on error? or simply print to stderr and return a return code.

• log_error – log errors to stderr?

Raises:

• PromptWeighterNotFoundError –

• dgenerate.ModuleFileNotFoundError –

Returns:

return-code, anything other than 0 is failure

dgenerate.promptweighters.prompt_weighter_name_from_uri(uri)

Extract just the implementation name from a prompt weighter URI.

Parameters:

uri – the URI

Returns:

the implementation name.

dgenerate.promptweighters.prompt_weighter_names()

Implementation names for all prompt weighters implemented by dgenerate, which are visible to the default PromptWeighterLoader instance.

Returns:

a list of prompt weighter implementation names.

dgenerate.pygments module

This module provides a pygments lexer for the dgenerate config / shell language.

This can be used for syntax highlighting.

class dgenerate.pygments.DgenerateLexer(*args, **kwds)

Bases: RegexLexer

pygments lexer for dgenerate configuration / script

get_tokens_unprocessed(text, stack=('root',))

Split text into (tokentype, text) pairs.

stack is the initial stack (default: ['root'])

aliases = ['dgenerate']

A list of short, unique identifiers that can be used to look up the lexer from a list, e.g., using get_lexer_by_name().

filenames = ['*.dgen']

A list of fnmatch patterns that match filenames which contain content for this lexer. The patterns in this list should be unique among all lexers.

name = 'DgenerateLexer'

Full name of the lexer, in human-readable form

dgenerate.renderloop module

The main dgenerate render loop, which implements the primary functionality of dgenerate.

exception dgenerate.renderloop.RenderLoopConfigError

Bases: Exception

Raised by RenderLoopConfig.check() on configuration errors.

class dgenerate.renderloop.AnimationETAEvent(origin, frame_index: int, total_frames: int, eta: timedelta)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when there is an update about the estimated finish time of an animation being generated.

__init__(origin, frame_index: int, total_frames: int, eta: timedelta)

eta: timedelta

Current estimated time to complete the animation.

frame_index: int

Frame index at which the ETA was calculated.

total_frames: int

Total frames needed for the animation to complete.

class dgenerate.renderloop.AnimationFileFinishedEvent(origin: RenderLoop, path: str, config_filename: str, starting_event: StartingAnimationFileEvent)

Bases: Event

Generated in the event stream of RenderLoop.events()

Occurs when an animation (video or animated image) has finished being written to disk.

__init__(origin: RenderLoop, path: str, config_filename: str, starting_event: StartingAnimationFileEvent)

config_filename: str | None

Path to a dgenerate config file if output_configs is enabled.

path: str

Path on disk where the video/animated image was saved.

starting_event: StartingAnimationFileEvent

Animation StartingAnimationFileEvent related to this file finished event.

class dgenerate.renderloop.AnimationFinishedEvent(origin, starting_event: StartingAnimationEvent)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a sequence of images that belong to an animation are done generating.

This occurs whether an animation was written to disk or not.

__init__(origin, starting_event: StartingAnimationEvent)

starting_event: StartingAnimationEvent

Animation StartingAnimationEvent related to this file finished event.

class dgenerate.renderloop.ImageFileSavedEvent(origin: RenderLoop, generated_event: ImageGeneratedEvent, path: str, config_filename: str | None = None)

Bases: Event

Generated in the event stream of RenderLoop.events()

Occurs when an image file is written to disk.

__init__(origin: RenderLoop, generated_event: ImageGeneratedEvent, path: str, config_filename: str | None = None)

config_filename: str | None = None

Path to a dgenerate config file if output_configs is enabled.

generated_event: ImageGeneratedEvent

The ImageGeneratedEvent for the image that was saved.

path: str

Path to the saved image.

class dgenerate.renderloop.ImageGeneratedEvent(origin: RenderLoop, image: Image | None, generation_step: int, batch_index: int, suggested_directory: str, suggested_filename: str, diffusion_args: DiffusionArguments, image_seed: ImageSeed, command_string: str, config_string: str)

Bases: Event

Generated in the event stream of RenderLoop.events()

Occurs when an image is generated (but not saved yet).

__init__(origin: RenderLoop, image: Image | None, generation_step: int, batch_index: int, suggested_directory: str, suggested_filename: str, diffusion_args: DiffusionArguments, image_seed: ImageSeed, command_string: str, config_string: str)

batch_index: int

The index in the image batch for this image. Will only every be greater than zero if RenderLoopConfig.batch_size > 1 and RenderLoopConfig.batch_grid_size is None.

command_string: str

Reproduction of a command line that can be used to reproduce this image.

This does not include the --device argument.

config_string: str

Reproduction of a dgenerate config file that can be used to reproduce this image.

This does not include the --device argument.

diffusion_args: DiffusionArguments

Diffusion argument object, contains dgenerate.pipelinewrapper.DiffusionPipelineWrapper arguments used to produce this image.

property frame_index: int | None

The frame index if this is an animation frame. Also available through image_seed.frame_index, though here for convenience.

generation_step: int

The current generation step. (zero indexed)

image: Image

The generated image.

image_seed: ImageSeed | None

If an --image-seeds specification was used in the generation of this image, this object represents that image seed and contains the images that contributed to the generation of this image.

property is_animation_frame: bool

Is this image a frame in an animation?

suggested_directory: str

A suggested directory path for saving this image in.

A value of '.' may be present, this indicates the current working directory.

suggested_filename: str

A suggested filename for saving this image as. This filename will be unique to the render loop run / configuration. This filename will not contain RenderLoopConfig.output_path, it is the suggested filename by itself.

class dgenerate.renderloop.RenderLoop(config: RenderLoopConfig | None = None, image_processor_loader: ImageProcessorLoader | None = None, prompt_weighter_loader: PromptWeighterLoader | None = None)

Bases: object

Render loop which implements the bulk of dgenerates rendering capability.

This object handles the scatter gun iteration over requested diffusion parameters, the generation of animations, and writing images and media to disk or providing those to library users through callbacks.

__init__(config: RenderLoopConfig | None = None, image_processor_loader: ImageProcessorLoader | None = None, prompt_weighter_loader: PromptWeighterLoader | None = None)

Parameters:

• config – RenderLoopConfig or dgenerate.arguments.DgenerateArguments. If None is provided, a RenderLoopConfig instance will be created and assigned to RenderLoop.config.

• image_processor_loader – dgenerate.imageprocessors.ImageProcessorLoader. If None is provided, an instance will be created and assigned to RenderLoop.image_processor_loader.

• prompt_weighter_loader – dgenerate.promptweighters.PromptWeighterLoader. If None is provided, an instance will be created and assigned to RenderLoop.prompt_weighter_loader.

events() → Generator[ImageGeneratedEvent | StartingAnimationEvent | StartingAnimationFileEvent | AnimationFileFinishedEvent | ImageFileSavedEvent | AnimationFinishedEvent | StartingGenerationStepEvent | AnimationETAEvent, None, None]

Run the render loop, and iterate over a stream of event objects produced by the render loop.

Event objects are of the union type RenderLoopEvent

The exceptions mentioned here are those you may encounter upon iterating, they will not occur upon simple acquisition of the event stream iterator.

Raises:

• RenderLoopConfigError –

• dgenerate.ModelNotFoundError –

• dgenerate.OutOfMemoryError –

Returns:

RenderLoopEventStream

run()

Run the diffusion loop, this calls RenderLoopConfig.check() prior to running.

Raises:

• RenderLoopConfigError –

• dgenerate.ModelNotFoundError –

• dgenerate.OutOfMemoryError –

config: RenderLoopConfig

Render loop configuration.

disable_writes: bool = False

Disable or enable all writes to disk, if you intend to only ever use the event stream of the render loop when using dgenerate as a library, this is a useful option.

RenderLoop.written_images and RenderLoop.written_animations will not be available if writes to disk are disabled.

property generation_step

Returns the current generation step, (zero indexed)

image_processor_loader: ImageProcessorLoader

Responsible for loading any image processors referenced in the render loop configuration.

model_extra_modules: dict[str, Any] = None

Extra raw diffusers modules to use in the creation of the main model pipeline.

property pipeline_wrapper: DiffusionPipelineWrapper

Get the last used dgenerate.pipelinewrapper.DiffusionPipelineWrapper instance.

Will be None if RenderLoop.run() has never been called.

Returns:

dgenerate.pipelinewrapper.DiffusionPipelineWrapper or None

prompt_weighter_loader: PromptWeighterLoader

Responsible for loading any prompt weighters referenced in the render loop configuration.

second_model_extra_modules: dict[str, Any] = None

Extra raw diffusers modules to use in the creation of any refiner or stable cascade decoder model pipeline.

property written_animations: Iterable[str]

Iterable over animation filenames written by the last run

property written_images: Iterable[str]

Iterable over image filenames written by the last run

class dgenerate.renderloop.RenderLoopConfig

Bases: SetFromMixin

This object represents configuration for RenderLoop.

It nearly directly maps to dgenerates command line arguments.

See subclass dgenerate.arguments.DgenerateArguments

__init__()

calculate_generation_steps()

Calculate the number of generation steps that this configuration results in.

Returns:

int

check(attribute_namer: Callable[[str], str] = None)

Check the configuration for type and logical usage errors, set defaults for certain values when needed and not specified.

Raises:

RenderLoopConfigError – on errors

Parameters:

attribute_namer – Callable for naming attributes mentioned in exception messages

iterate_diffusion_args(**overrides) → Iterator[DiffusionArguments]

Iterate over dgenerate.pipelinewrapper.DiffusionArguments argument objects using every combination of argument values provided for that object by this configuration.

Parameters:

overrides – use key word arguments to override specific attributes of this object with a new list value.

Returns:

an iterator over dgenerate.pipelinewrapper.DiffusionArguments

animation_format: str = 'mp4'

Format for any rendered animations, see: dgenerate.mediaoutput.supported_animation_writer_formats(). This value may also be set to ‘frames’ to indicate that only individual frames should be output and no animation file coalesced. This corresponds to the --animation-format argument of the dgenerate command line tool.

auth_token: str | None = None

Optional huggingface API token which will allow the download of restricted repositories that your huggingface account has been granted access to. This corresponds to the --auth-token argument of the dgenerate command line tool.

batch_grid_size: tuple[int, int] | None = None

Optional image grid size specification for when batch_size is greater than one. This is the --batch-grid-size argument of the dgenerate command line tool.

batch_size: int | None = None

Image generation batch size, --batch-size argument of dgenerate command line tool.

clip_skips: Sequence[int] | None = None

List of clip skip values. Clip skip is the number of layers to be skipped from CLIP while computing the prompt embeddings. A value of 1 means that the output of the pre-final layer will be used for computing the prompt embeddings. Only supported for model_type values torch and torch-sdxl, including with controlnet_uris defined.

control_image_processors: Sequence[str] | None = None

Corresponds to the --control-image-processors argument of the dgenerate command line tool verbatim, including the grouping syntax using the “+” symbol, the plus symbol should be used as its own list element, IE: it is a token.

controlnet_uris: Sequence[str] | None = None

Optional user specified ControlNet URIs, this corresponds to the --control-nets argument of the dgenerate command line tool.

device: str = 'cuda'

Processing device specification, for example “cuda” or “cuda:N” where N is an alternate GPU id as reported by nvidia-smi if you want to specify a specific GPU. This corresponds to the --device argument of the dgenerate command line tool.

The default device on MacOS is “mps”.

dtype: DataType = 0

Primary model data type specification, IE: integer precision. Default is auto selection. Lower precision datatypes result in less GPU memory usage. This corresponds to the --dtype argument of the dgenerate command line tool.

flux_max_sequence_length: int | None = None

Max number of prompt tokens that the T5EncoderModel (text encoder 2) of Flux can handle.

This defaults to 512 when not specified, and the maximum value is 512 and the minimum value is 1.

High values result in more resource usage and processing time.

flux_second_prompts: Sequence[Prompt] | None = None

Optional list of Flux secondary prompts, this corresponds to the --flux-second-prompts argument of the dgenerate command line tool.

frame_end: int | None = None

Optional end frame inclusive frame slice for any rendered animations. This corresponds to the --frame-end argument of the dgenerate command line tool.

frame_start: int = 0

Start frame inclusive frame slice for any rendered animations. This corresponds to the --frame-start argument of the dgenerate command line tool.

guidance_rescales: Sequence[float] | None = None

List of floating point guidance rescale values which are supported by some pipelines, (there will be an error if it is unsupported upon running), this corresponds to the --guidance-rescales argument of the dgenerate command line tool.

guidance_scales: Sequence[float]

List of floating point guidance scales, this corresponds to the --guidance-scales argument of the dgenerate command line tool.

image_encoder_uri: str | None = None

Optional user specified Image Encoder URI when using IP Adapter models or Stable Cascade. This corresponds to the --image-encoder argument of the dgenerate command line tool.

If none of your specified --ip-adapters URIs point to a model which contains an Image Encoder model, you will need to specify one manually using this argument.

image_format: str = 'png'

Format for any images that are written including animation frames.

Anything other than “png” is not compatible with output_metadata=True and a RenderLoopConfigError will be raised upon running the render loop if output_metadata=True and this value is not “png”

image_guidance_scales: Sequence[float] | None = None

Optional list of floating point image guidance scales, used for pix2pix model types, this corresponds to the --image-guidance-scales argument of the dgenerate command line tool.

image_seed_strengths: Sequence[float] | None = None

Optional list of floating point image seed strengths, this corresponds to the --image-seed-strengths argument of the dgenerate command line tool.

image_seeds: Sequence[str] | None = None

List of --image-seeds URI strings.

inference_steps: Sequence[int]

List of inference steps values, this corresponds to the --inference-steps argument of the dgenerate command line tool.

ip_adapter_uris: Sequence[str] | None = None

Optional user specified IP Adapter URIs, this corresponds to the --ip-adapters argument of the dgenerate command line tool.

lora_fuse_scale: float | None = None

Optional global LoRA fuse scale, this corresponds to the --lora-fuse-scale argument of the dgenerate command line tool.

LoRA weights are merged into the main model at this scale.

When specifying multiple LoRA models, they are fused together into one set of weights using their individual scale values, after which they are fused into the main model at this scale value.

The default value when None is specified is 1.0.

lora_uris: Sequence[str] | None = None

Optional user specified LoRA URIs, this corresponds to the --loras argument of the dgenerate command line tool.

mask_image_processors: Sequence[str] | None = None

Corresponds to the --mask-image-processors argument of the dgenerate command line tool verbatim.

model_cpu_offload: bool = False

Force model cpu offloading for the main pipeline, this may reduce memory consumption and allow large models to run when they would otherwise not fit in your GPUs VRAM. Inference will be slower. Mutually exclusive with RenderLoopConfig.model_sequential_offload

model_path: str | None = None

Primary diffusion model path, model_path argument of dgenerate command line tool.

model_sequential_offload: bool = False

Force sequential model offloading for the main pipeline, this may drastically reduce memory consumption and allow large models to run when they would otherwise not fit in your GPUs VRAM. Inference will be much slower. Mutually exclusive with RenderLoopConfig.model_cpu_offload

model_type: ModelType = 0

Corresponds to the --model-type argument of the dgenerate command line tool.

no_aspect: bool = False

Should Seed, Mask, and Control guidance images specified in RenderLoopConfig.image_seeds definitions (--image-seeds) have their aspect ratio ignored when being resized to RenderLoopConfig.output_size (--output-size) ?

no_frames: bool = False

Should individual frames not be output when rendering an animation? defaults to False. This corresponds to the --no-frames argument of the dgenerate command line tool. Using this option when RenderLoopConfig.animation_format is equal to "frames" will cause a RenderLoopConfigError be raised.

offline_mode: bool = False

Avoid ever connecting to the huggingface API? this can be used if all your models are cached or if you are only ever using models that exist on disk. Corresponds to the --offline-mode argument of the dgenerate command line tool.

output_configs: bool = False

Output a config text file next to every generated image or animation? this file will contain configuration that is pipeable to dgenerate stdin, which will reproduce said file. This corresponds to the --output-configs argument of the dgenerate command line tool.

output_metadata: bool = False

Write config text to the metadata of all written images? this data is not written to animated files, only PNGs. This corresponds to the --output-metadata argument of the dgenerate command line tool.

output_overwrite: bool = False

Allow overwrites of files? or avoid this with a file suffix in a multiprocess safe manner? This corresponds to the --output-overwrite argument of the dgenerate command line tool.

output_path: str = 'output'

Render loop write folder, where images and animations will be written. This corresponds to the --output-path argument of the dgenerate command line tool.

output_prefix: str | None = None

Output filename prefix, add an optional prefix string to all written files. This corresponds to the --output-prefix argument of the dgenerate command line tool.

output_size: tuple[int, int] | None = None

Desired output size, sizes not aligned by 8 pixels will result in an error message. This corresponds to the --output-size argument of the dgenerate command line tool.

parsed_image_seeds: Sequence[ImageSeedParseResult] | None = None

The results of parsing URIs mentioned in RenderLoopConfig.image_seeds, will only be available if RenderLoopConfig.check() has been called.

post_processors: Sequence[str] | None = None

Corresponds to the --post-processors argument of the dgenerate command line tool verbatim.

prompt_weighter_uri: str | None = None

The URI of a prompt weighter implementation supported by dgenerate.

This corresponds to the --prompt-weighter argument of the dgenerate command line tool.

prompts: Sequence[Prompt]

List of prompt objects, this corresponds to the --prompts argument of the dgenerate command line tool.

revision: str = 'main'

Repo revision selector for the main model when loading from a huggingface repository. This corresponds to the --revision argument of the dgenerate command line tool.

s_cascade_decoder_cpu_offload: bool | None = None

Force model cpu offloading for the Stable Cascade decoder pipeline, this may reduce memory consumption and allow large models to run when they would otherwise not fit in your GPUs VRAM. Inference will be slower. Mutually exclusive with RenderLoopConfig.s_cascade_decoder_sequential_offload

s_cascade_decoder_guidance_scales: Sequence[float] | None = None

List of guidance scale values for the Stable Cascade decoder, this corresponds to the --s-cascade-decoder-guidance-scales argument of the dgenerate command line tool.

s_cascade_decoder_inference_steps: Sequence[int] | None = None

List of inference steps values for the Stable Cascade decoder, this corresponds to the --s-cascade-decoder-inference-steps argument of the dgenerate command line tool.

s_cascade_decoder_prompts: Sequence[Prompt] | None = None

Optional list of Stable Cascade decoder prompt overrides, this corresponds to the --s-cascade-decoder-prompts argument of the dgenerate command line tool.

s_cascade_decoder_scheduler: str | None = None

Optional Stable Cascade decoder model scheduler/sampler class name specification, this corresponds to the --s-cascade-decoder-scheduler argument of the dgenerate command line tool. Setting this to ‘help’ will yield a help message to stdout describing scheduler names compatible with the current configuration upon running. Passing ‘helpargs’ will yield a help message with a list of overridable arguments for each scheduler and their typical defaults.

s_cascade_decoder_sequential_offload: bool | None = None

Force sequential model offloading for the Stable Cascade decoder pipeline, this may drastically reduce memory consumption and allow large models to run when they would otherwise not fit in your GPUs VRAM. Inference will be much slower. Mutually exclusive with RenderLoopConfig.s_cascade_decoder_cpu_offload

s_cascade_decoder_uri: str | None = None

Stable Cascade model URI, --s-cascade-decoder argument of dgenerate command line tool.

safety_checker: bool = False

Enable safety checker? --safety-checker

scheduler: str | None = None

Optional primary model scheduler/sampler class name specification, this corresponds to the --scheduler argument of the dgenerate command line tool. Setting this to ‘help’ will yield a help message to stdout describing scheduler names compatible with the current configuration upon running. Passing ‘helpargs’ will yield a help message with a list of overridable arguments for each scheduler and their typical defaults.

sd3_max_sequence_length: int | None = None

Max number of prompt tokens that the T5EncoderModel (text encoder 3) of Stable Diffusion 3 can handle.

This defaults to 256 when not specified, and the maximum value is 512 and the minimum value is 1.

High values result in more resource usage and processing time.

sd3_second_prompts: Sequence[Prompt] | None = None

Optional list of SD3 secondary prompts, this corresponds to the --sd3-second-prompts argument of the dgenerate command line tool.

sd3_third_prompts: Sequence[Prompt] | None = None

Optional list of SD3 tertiary prompts, this corresponds to the --sd3-third-prompts argument of the dgenerate command line tool.

sdxl_aesthetic_scores: Sequence[float] | None = None

Optional list of SDXL aesthetic-score conditioning values, this corresponds to the --sdxl-aesthetic-scores argument of the dgenerate command line tool.

sdxl_crops_coords_top_left: Sequence[tuple[int, int]] | None = None

Optional list of SDXL top-left-crop-coords micro-conditioning parameters, this corresponds to the --sdxl-crops-coords-top-left argument of the dgenerate command line tool.

sdxl_high_noise_fractions: Sequence[float] | None = None

Optional list of SDXL refiner high noise fractions (floats), this value is the fraction of inference steps that the base model handles, the inverse proportion of the provided fraction is handled by the refiner model. This corresponds to the --sdxl-high-noise-fractions argument of the dgenerate command line tool.

sdxl_negative_aesthetic_scores: Sequence[float] | None = None

Optional list of negative influence SDXL aesthetic-score conditioning values, this corresponds to the --sdxl-negative-aesthetic-scores argument of the dgenerate command line tool.

sdxl_negative_crops_coords_top_left: Sequence[tuple[int, int]] | None = None

Optional list of negative influence SDXL top-left crop coords micro-conditioning parameters, this corresponds to the --sdxl-negative-crops-coords-top-left argument of the dgenerate command line tool.

sdxl_negative_original_sizes: Sequence[tuple[int, int]] | None = None

Optional list of negative influence SDXL original-size micro-conditioning parameters, this corresponds to the --sdxl-negative-original-sizes argument of the dgenerate command line tool.

sdxl_negative_target_sizes: Sequence[tuple[int, int]] | None = None

Optional list of negative influence SDXL target-size micro-conditioning parameters, this corresponds to the --sdxl-negative-target-sizes argument of the dgenerate command line tool.

sdxl_original_sizes: Sequence[tuple[int, int]] | None = None

Optional list of SDXL original-size micro-conditioning parameters, this corresponds to the --sdxl-original-sizes argument of the dgenerate command line tool.

sdxl_refiner_aesthetic_scores: Sequence[float] | None = None

Optional list of SDXL-refiner override aesthetic-score conditioning values, this corresponds to the --sdxl-refiner-aesthetic-scores argument of the dgenerate command line tool.

sdxl_refiner_clip_skips: Sequence[int] | None = None

Clip skip override values for the SDXL refiner, which normally defaults to the clip skip value for the main model when it is defined.

sdxl_refiner_cpu_offload: bool | None = None

Force model cpu offloading for the SDXL refiner pipeline, this may reduce memory consumption and allow large models to run when they would otherwise not fit in your GPUs VRAM. Inference will be slower. Mutually exclusive with RenderLoopConfig.sdxl_refiner_sequential_offload

sdxl_refiner_crops_coords_top_left: Sequence[tuple[int, int]] | None = None

Optional list of SDXL-refiner override top-left-crop-coords micro-conditioning parameters, this corresponds to the --sdxl-refiner-crops-coords-top-left argument of the dgenerate command line tool.

sdxl_refiner_edit: bool | None = None

Force the SDXL refiner to operate in edit mode instead of cooperative denoising mode.

sdxl_refiner_guidance_rescales: Sequence[float] | None = None

Optional list of guidance rescale value overrides for the SDXL refiner, this corresponds to the --sdxl-refiner-guidance-rescales argument of the dgenerate command line tool.

sdxl_refiner_guidance_scales: Sequence[float] | None = None

Optional list of guidance scale value overrides for the SDXL refiner, this corresponds to the --sdxl-refiner-guidance-scales argument of the dgenerate command line tool.

sdxl_refiner_inference_steps: Sequence[int] | None = None

Optional list of inference steps value overrides for the SDXL refiner, this corresponds to the --sdxl-refiner-inference-steps argument of the dgenerate command line tool.

sdxl_refiner_negative_aesthetic_scores: Sequence[float] | None = None

Optional list of negative influence SDXL-refiner override aesthetic-score conditioning values, this corresponds to the --sdxl-refiner-negative-aesthetic-scores argument of the dgenerate command line tool.

sdxl_refiner_negative_crops_coords_top_left: Sequence[tuple[int, int]] | None = None

Optional list of negative influence SDXL-refiner top-left crop coords micro-conditioning parameters, this corresponds to the --sdxl-refiner-negative-crops-coords-top-left argument of the dgenerate command line tool.

sdxl_refiner_negative_original_sizes: Sequence[tuple[int, int]] | None = None

Optional list of negative influence SDXL-refiner override original-size micro-conditioning parameters, this corresponds to the --sdxl-refiner-negative-original-sizes argument of the dgenerate command line tool.

sdxl_refiner_negative_target_sizes: Sequence[tuple[int, int]] | None = None

Optional list of negative influence SDXL-refiner override target-size micro-conditioning parameters, this corresponds to the --sdxl-refiner-negative-target-sizes argument of the dgenerate command line tool.

sdxl_refiner_original_sizes: Sequence[tuple[int, int]] | None = None

Optional list of SDXL-refiner override original-size micro-conditioning parameters, this corresponds to the --sdxl-refiner-original-sizes argument of the dgenerate command line tool.

sdxl_refiner_prompts: Sequence[Prompt] | None = None

Optional list of SDXL refiner prompt overrides, this corresponds to the --sdxl-refiner-prompts argument of the dgenerate command line tool.

sdxl_refiner_scheduler: str | None = None

Optional SDXL refiner model scheduler/sampler class name specification, this corresponds to the --sdxl-refiner-scheduler argument of the dgenerate command line tool. Setting this to ‘help’ will yield a help message to stdout describing scheduler names compatible with the current configuration upon running. Passing ‘helpargs’ will yield a help message with a list of overridable arguments for each scheduler and their typical defaults.

sdxl_refiner_second_prompts: Sequence[Prompt] | None = None

Optional list of SDXL refiner secondary prompt overrides, this corresponds to the --sdxl-refiner-second-prompts argument of the dgenerate command line tool.

sdxl_refiner_sequential_offload: bool | None = None

Force sequential model offloading for the SDXL refiner pipeline, this may drastically reduce memory consumption and allow large models to run when they would otherwise not fit in your GPUs VRAM. Inference will be much slower. Mutually exclusive with RenderLoopConfig.sdxl_refiner_cpu_offload

sdxl_refiner_target_sizes: Sequence[tuple[int, int]] | None = None

Optional list of SDXL-refiner override target-size micro-conditioning parameters, this corresponds to the --sdxl-refiner-target-sizes argument of the dgenerate command line tool.

sdxl_refiner_uri: str | None = None

SDXL Refiner model URI, --sdxl-refiner argument of dgenerate command line tool.

sdxl_second_prompts: Sequence[Prompt] | None = None

Optional list of SDXL secondary prompts, this corresponds to the --sdxl-second-prompts argument of the dgenerate command line tool.

sdxl_t2i_adapter_factors: Sequence[float] | None = None

Optional list of SDXL specific T2I adapter factors to try, this controls the amount of time-steps for which a T2I adapter applies guidance to an image, this is a value between 0.0 and 1.0. A value of 0.5 for example indicates that the T2I adapter is only active for half the amount of time-steps it takes to completely render an image.

sdxl_target_sizes: Sequence[tuple[int, int]] | None = None

Optional list of SDXL target-size micro-conditioning parameters, this corresponds to the --sdxl-target-sizes argument of the dgenerate command line tool.

second_text_encoder_uris: Sequence[str] | None = None

Optional user specified Text Encoder URIs, this corresponds to the --text-encoders2 argument of the dgenerate command line tool. This specifies text encoders for the SDXL refiner or Stable Cascade decoder.

second_unet_uri: str | None = None

Optional user specified second UNet URI, this corresponds to the --unet2 argument of the dgenerate command line tool. This UNet uri will be used for the SDXL refiner or Stable Cascade decoder model.

seed_image_processors: Sequence[str] | None = None

Corresponds to the --seed-image-processors argument of the dgenerate command line tool verbatim.

seeds: Sequence[int]

List of integer seeds, this corresponds to the --seeds argument of the dgenerate command line tool.

seeds_to_images: bool = False

Should RenderLoopConfig.seeds be interpreted as seeds for each image input instead of combinatorial? this includes control images.

subfolder: str | None = None

Primary model subfolder argument, --subfolder argument of dgenerate command line tool.

t2i_adapter_uris: Sequence[str] | None = None

Optional user specified T2IAdapter URIs, this corresponds to the --t2i-adapters argument of the dgenerate command line tool.

text_encoder_uris: Sequence[str] | None = None

Optional user specified Text Encoder URIs, this corresponds to the --text-encoders argument of the dgenerate command line tool.

textual_inversion_uris: Sequence[str] | None = None

Optional user specified Textual Inversion URIs, this corresponds to the --textual-inversions argument of the dgenerate command line tool.

transformer_uri: str | None = None

Optional user specified Transformer URI, this corresponds to the --transformer argument of the dgenerate command line tool.

This is currently only supported for Stable Diffusion 3 and Flux models.

unet_uri: str | None = None

Optional user specified UNet URI, this corresponds to the --unet argument of the dgenerate command line tool.

upscaler_noise_levels: Sequence[int] | None = None

Optional list of integer upscaler noise levels, this corresponds to the --upscaler-noise-levels argument of the dgenerate command line tool that is used for the dgenerate.pipelinewrapper.ModelType.TORCH_UPSCALER_X4 model type only.

vae_slicing: bool = False

Enable VAE slicing? --vae-slicing

vae_tiling: bool = False

Enable VAE tiling? --vae-tiling

vae_uri: str | None = None

Optional user specified VAE URI, this corresponds to the --vae argument of the dgenerate command line tool.

variant: str | None = None

Primary model weights variant string. This corresponds to the --variant argument of the dgenerate command line tool.

class dgenerate.renderloop.StartingAnimationEvent(origin, total_frames: int, fps: float, frame_duration: float)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a sequence of images that belong to an animation are about to start being generated.

This occurs whether an animation is going to be written to disk or not.

__init__(origin, total_frames: int, fps: float, frame_duration: float)

fps: float

FPS of the generated file.

frame_duration: float

Frame duration of the generated file, (the time a frame is visible in milliseconds)

total_frames: int

Number of frames written.

class dgenerate.renderloop.StartingAnimationFileEvent(origin, path: str, total_frames: int, fps: float, frame_duration: float)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a sequence of images that belong to an animation are about to start being written to a file.

__init__(origin, path: str, total_frames: int, fps: float, frame_duration: float)

fps: float

FPS of the generated file.

frame_duration: float

Frame duration of the generated file, (the time a frame is visible in milliseconds)

path: str

File path where the animation will reside.

total_frames: int

Number of frames written.

class dgenerate.renderloop.StartingGenerationStepEvent(origin, generation_step: int, total_steps: int)

Bases: Event

Common event stream object produced by the events() event stream of a render loop.

Occurs when a generation step is starting, a generation step may produce multiple images and or an animation.

__init__(origin, generation_step: int, total_steps: int)

generation_step: int

The generation step number.

total_steps: int

The total number of steps that are needed to complete the render loop.

dgenerate.renderloop.gen_seeds(n) → list[int]

Generate a list of N random seed integers

Parameters:

n – number of seeds to generate

Returns:

list of integer seeds

dgenerate.renderloop.RenderLoopEvent

Possible events from the event stream created by RenderLoop.events()

alias of Union[ImageGeneratedEvent, StartingAnimationEvent, StartingAnimationFileEvent, AnimationFileFinishedEvent, ImageFileSavedEvent, AnimationFinishedEvent, StartingGenerationStepEvent, AnimationETAEvent]

dgenerate.renderloop.RenderLoopEventStream

Event stream created by RenderLoop.events()

alias of Generator[Union[ImageGeneratedEvent, StartingAnimationEvent, StartingAnimationFileEvent, AnimationFileFinishedEvent, ImageFileSavedEvent, AnimationFinishedEvent, StartingGenerationStepEvent, AnimationETAEvent], None, None]

dgenerate.textprocessing module

Text processing, console text rendering, and parsing utilities. URI parser, and reusable tokenization.

exception dgenerate.textprocessing.ConceptUriParseError

Bases: Exception

Raised by ConceptUriParser.parse() on parsing errors.

exception dgenerate.textprocessing.ShellParseSyntaxError

Bases: Exception

Raised by shell_parse() on syntax errors.

exception dgenerate.textprocessing.TimeDeltaParseError

Bases: Exception

Raised by parse_timedelta() on parse errors.

exception dgenerate.textprocessing.TokenizedSplitSyntaxError

Bases: Exception

Raised by tokenized_split() on syntax errors.

exception dgenerate.textprocessing.UnquoteSyntaxError

Bases: Exception

Raised by unquote() on parsing errors.

class dgenerate.textprocessing.ArgparseParagraphFormatter(*args, **kwargs)

Bases: HelpFormatter

Argparse formatter which preserves paragraphs in help text.

This formatter also underlines option text for better visual segregation.

__init__(*args, **kwargs)

PARAGRAPH_SEPARATOR = '\n\n'

PARAGRAPH_SEPARATOR_RE = re.compile('\\n\\s*\\n', re.ASCII)

WHITESPACE_PATTERN = re.compile('\\s+')

class dgenerate.textprocessing.ConceptUri(concept: str, args: dict[str, str])

Bases: object

Represents a parsed concept URI.

__init__(concept: str, args: dict[str, str])

args: dict[str, str | list[str]]

Provided keyword arguments with their (string) values.

concept: str

The primary concept mentioned in the URI.

class dgenerate.textprocessing.ConceptUriParser(concept_name: str, known_args: Iterable[str], args_lists: bool | Iterable[str] | None = None, args_raw: bool | Iterable[str] | None = None, delimiter: str = ';')

Bases: object

Parser for dgenerate concept paths with arguments, IE: concept;arg1="a";arg2="b"

Used for --vae, --loras etc. as well as image processor plugin module arguments.

__init__(concept_name: str, known_args: Iterable[str], args_lists: bool | Iterable[str] | None = None, args_raw: bool | Iterable[str] | None = None, delimiter: str = ';')

Raises:

ValueError – if duplicate argument names are specified.

Parameters:

• concept_name – Concept name, used in error messages

• known_args – valid arguments for the parser, must be unique

parse(uri: str) → ConceptUri

Parse a string.

Parameters:

uri – the string

Raises:

• ConceptUriParseError – on parsing errors

• ValueError – if uri is None

Returns:

ConceptPath

args_lists: bool | set[str] | None

True indicates all arguments can accept a comma separated list.

None or False indicates no arguments can accept a comma separated list.

Assigning a set containing argument names indicates only the specified arguments can accept a comma separated list.

When an argument is parsed as a comma separated list, its value/type in ConceptUri.args will be that of a list.

args_raw: bool | set[str] | None

True indicates all argument values are returned without any unquoting or processing into lists.

None or False indicates no argument values skip extended processing.

Assigning a set containing argument names indicates only the specified arguments skip extended processing (unquoting or splitting).

concept_name: str

Name / title string for this concept. Used in parse error exceptions.

delimiter: str

URI argument delimiter, the default is semicolon.

known_args: set[str]

Unique recognized keyword arguments

dgenerate.textprocessing.contains_space(string: str) → bool

Check if a string contains any whitespace characters including newlines

Parameters:

string – the string

Returns:

bool

dgenerate.textprocessing.dashdown(string: str) → str

Replace ‘-’ with ‘_’

Parameters:

string – the string

Returns:

modified string

dgenerate.textprocessing.dashup(string: str) → str

Replace ‘_’ with ‘-’

Parameters:

string – the string

Returns:

modified string

dgenerate.textprocessing.debug_format_args(args_dict: dict[str, Any], value_transformer: Callable[[str, Any], str] | None = None, max_value_len: int = 256, as_kwargs: bool = False)

Format function arguments in a way that can be printed for debug messages.

Parameters:

• args_dict – argument dictionary

• value_transformer – transform values in the argument dictionary

• max_value_len – Max length of a formatted value before it is turned into a class and id string only

• as_kwargs – Format the string as python keyword arguments instead of a dictionary

Returns:

formatted string

dgenerate.textprocessing.format_dgenerate_config(lines: Iterator[str], indentation='    ') → Iterator[str]

A very rudimentary code formatter for dgenerate configuration / script.

Does not handle breaking jinja control blocks on to a new line if multiple start blocks exist on the same line.

Parameters:

• lines – iterator over lines

• indentation – level of indentation for top level jinja control blocks

Returns:

formatted code

dgenerate.textprocessing.format_image_seed_uri(seed_images: str | Iterable[str] | None = None, mask_images: str | Iterable[str] | None = None, control_images: str | Iterable[str] | None = None, adapter_images: Iterable[str] | None = None, floyd_image: str | None = None, resize: str | tuple[int | str, int | str] | None = None, aspect: bool = True, frame_start: int | None = None, frame_end: int | None = None) → str

Formats a --image-seeds URI to its shortest possible string form.

Raises:

ValueError – if inpaint_image is specified without seed_image. if keyword arguments are present without seed_image or control_images. if frame_start or frame_end are negative values. if frame_start is greater than frame_end. if adapter_images are used with floyd_image. if both control_images and floyd_image are specified. if too many mask images are provided. if too few mask images are provided. if no arguments are provided.

Parameters:

• seed_images – Seed image path(s)

• mask_images – Inpaint image path(s)

• control_images – Control image path(s)

• adapter_images – Adapter image paths

• floyd_image – Path to a Floyd image

• resize – Optional resize dimension (WxH string)

• aspect – Preserve aspect ratio?

• frame_start – Optional frame start index

• frame_end – Optional frame end index

Returns:

The generated --image-seeds URI string

dgenerate.textprocessing.format_size(size: Iterable[int])

Join together an iterable of integers with the character x

Parameters:

size – the iterable

Returns:

formatted string

dgenerate.textprocessing.indent_text(text, initial_indent: str | None = None, subsequent_indent: str | None = None)

Indent consecutive lines of text.

Parameters:

• text – Text to be indented

• initial_indent – String of characters to be used for the initial indentation

• subsequent_indent – String of characters to be used for the subsequent indentation

Returns:

Indented text

dgenerate.textprocessing.is_quoted(string: str) → bool

Return True if a string is quoted with an identical starting and end quote.

Parameters:

string – the string

Returns:

True or False

dgenerate.textprocessing.justify_left(string: str)

Justify text to the left.

Parameters:

string – string with text

Returns:

left justified text

dgenerate.textprocessing.long_text_wrap_width() → int

Return the current terminal width or the default value of 150 characters for text-wrapping purposes.

This can be affected by the environmental variable COLUMNS.

Raises:

ValueError – if the environmental variable COLUMNS is not an integer value or is less than 0.

Returns:

int

dgenerate.textprocessing.oxford_comma(elements: Collection[str], conjunction: str) → str

Join a sequence of strings with commas, end with an oxford comma and conjunction if needed.

Parameters:

• elements – strings

• conjunction – “and”, “or”

Returns:

a joined string

dgenerate.textprocessing.parse_dimensions(string)

Parse a dimensions tuple from a string, integers seperated by the character ‘x’

Parameters:

string – the string

Raises:

ValueError – On non integer dimension values.

Returns:

a tuple representing the dimensions

dgenerate.textprocessing.parse_image_size(string)

Parse an image size tuple from a string, 2 integers seperated by the character ‘x’, or a single integer specifying both dimensions.

Parameters:

string – the string

Raises:

ValueError – On non integer dimension values, or if more than 2 dimensions are provided, or if the product of the dimensions is 0.

Returns:

a tuple representing the dimensions

dgenerate.textprocessing.parse_timedelta(string: str | None) → timedelta

Parse a datetime.timedelta object from an arguments string.

Passing ‘forever’, an empty string, or None will result in this function returning datetime.timedelta.max

Accepts all named arguments of datetime.timedelta

parse_time_delta('days=1; seconds=30')

Raises:

TimeDeltaParseError – on parse errors

Parameters:

string – the arguments string

Returns:

datetime.timedelta

dgenerate.textprocessing.parse_version(string: str) → tuple[int, int, int]

Parse a SemVer version string into a tuple of 3 integers

Parameters:

string – the version string

Returns:

tuple of three ints

dgenerate.textprocessing.quote(string: str, char='"') → str

Wrap a string with a quote character.

Double quotes by default.

This is not equivalent to shell quoting.

Parameters:

• string – the string

• char – the quote character to use

Returns:

the quoted string

dgenerate.textprocessing.quote_spaces(value_or_struct: Any | Iterable[Any | list | tuple]) → list | tuple | Any

Quote any str type values containing spaces, or str type values containing spaces within a list, or list of lists/tuples.

The entire content of the data structure is stringified by this process.

This is not equivalent to shell quoting.

Parameters:

value_or_struct – value or (list of values, and or lists/tuples containing values)

Returns:

input data structure with strings quoted if needed

dgenerate.textprocessing.remove_tail_comments(string) → tuple[bool, str]

Remove trailing comments from a dgenerate config line

Will not remove a comment if it is the only thing on the line.

Considers strings and comment escape sequences.

Parameters:

string – the string

Returns:

(removed anything?, stripped string)

dgenerate.textprocessing.remove_terminal_escape_sequences(string)

Remove any terminal escape sequences from a string.

Parameters:

string – the string

Returns:

the clean string

dgenerate.textprocessing.shell_expandvars(string: str)

Expand shell variables of form $var, ${var}, %var% in a string.

Unknown variables expand to nothing.

Parameters:

string – input string

dgenerate.textprocessing.shell_parse(string, expand_home: bool = True, expand_vars: bool = True, expand_glob: bool = True, expand_vars_func: ~typing.Callable[[str], str] = <function shell_expandvars>) → list[str]

Shell command line parsing, implements basic home directory expansion, globbing, and environmental variable expansion.

Globbing and home directory expansion do not occur inside strings.

This can be used in place of shlex.split

# basic glob
shell_parse('command *.png')

# recursive glob
shell_parse('command dir/**/*.png')

# home directory
shell_parse('command ~')

# home directory of user test
shell_parse('command ~test')

# everything under home directory
shell_parse('command ~/*')

# append text to every glob result
shell_parse('command *".png"')

# append text to every glob result
shell_parse("command *'.png'")

# environmental variable syntax 1
shell_parse('command $ENVVAR')

# environmental variable syntax 2
shell_parse('command %ENVVAR%')

Parameters:

• string – String to parse

• expand_home – Expand ~ ?

• expand_vars – Expand unix style $ and windows style % environmental variables?

• expand_glob – Expand * glob expressions including recursive globs?

• expand_vars_func – This function is used to expand shell variables in a string, analogous to os.path.expandvars

Returns:

shell arguments

dgenerate.textprocessing.tokenized_split(string: str, separator: str | None, remove_quotes: bool = False, strict: bool = False, escapes_in_unquoted: bool = False, escapes_in_quoted: bool = False, single_quotes_raw: bool = False, double_quotes_raw: bool = False, string_expander: Callable[[str, str], str] = None, text_expander: Callable[[str], list[str]] = None, remove_stray_separators: bool = False, escapable_separator: bool = False, allow_unterminated_strings: bool = False, first_string_halts: bool = False) → list[str]

Split a string by a separator and discard whitespace around tokens, avoid splitting within single or double-quoted strings. Empty fields may be used.

Quotes can be always be escaped with a backslash to avoid the creation of a string type token. The backslash will remain in the output if escapes_in_unquoted or escapes_in_quoted are False and the escape occurs in the relevant context.

Raises:

TokenizedSplitSyntaxError – on syntax errors.

Parameters:

• string – the string

• separator – separator

• remove_quotes – remove quotes from quoted string tokens?

• strict – Text tokens cannot be intermixed with quoted strings? disallow IE: "text'string'text"

• escapes_in_unquoted – evaluate escape sequences in text tokens (unquoted strings)? The slash is retained by default when escaping quotes, this disables that, and also enables handling of the escapes n, r, t, b, f, and \. IE: given separator =";" parse \"token\"; "a b" -> ['"token"', 'a b'], instead of \"token\"; "a b"-> ['\"token\"', 'a b']

• escapes_in_quoted – evaluate escape sequences in quoted string tokens? The slash is retained by default when escaping quotes, this disables that, and also enables handling of the escapes n, r, t, b, f, and \. IE given separator = ";" parse token; "a \" b" -> ['token', 'a " b'], instead of token; "a \" b"-> ['token', 'a \" b']

• single_quotes_raw – Never evaluate escape sequences in single-quoted strings?

• double_quotes_raw – Never evaluate escape sequences in double-quoted strings?

• string_expander – User post process string expansion hook string_expander(quote_char, string) -> str

• text_expander – User post process text token expansion hook text_expander(text_token) -> list[str]. should return a list of new tokens.

• remove_stray_separators – Remove consecutive seperator characters with no inner content at the end of the string? In effect, do not create entrys for empty seperators at the end of a string.

• escapable_separator – The seperator character may be escaped with a backslash where it would otherwise cause a split?

• allow_unterminated_strings – Allows the lex to end on an unterminated string without a syntax error being produced. It is necessary to perform lookahead N to determine if a seperator is quoted by a string or not, this allows your input to end with an unterminated string and still split correctly, complete strings proceeding the unterminated string which contain the seperator character will not be split on the seperator because the seperator is considered quoted in a string token.

• first_string_halts – The first completed string token halts lexing immediately, this is mainly used by the lexer internally for recursion in cases where a lookahead for string termination is required, but may be useful for some external parsing tasks.

Returns:

parsed fields

dgenerate.textprocessing.underline(string: str, underline_char: str = '=') → str

Underline a string with the selected character.

Parameters:

• string – the string

• underline_char – the character to underline with

Returns:

the underlined string

dgenerate.textprocessing.unquote(string: str, escapes_in_quoted=True, escapes_in_unquoted=False) → str

Remove quotes from a string, including single quotes.

Unquoted strings will have leading an trailing whitespace stripped.

Quoted strings will have leading and trailing whitespace stripped up to where the quotes were.

Parameters:

• escapes_in_unquoted – Render escape sequences in strings that are unquoted?

• escapes_in_quoted – Render escape sequences in strings that are quoted?

• string – the string

Returns:

The un-quoted string

dgenerate.textprocessing.wrap(text: str, width: int, initial_indent='', subsequent_indent='', break_long_words=False, break_on_hyphens=False, **fill_args)

Wrap text.

Parameters:

• text – The prompt text

• width – The wrap width

• initial_indent – initial indent string

• subsequent_indent – subsequent indent string

• break_long_words – Break on long words?

• break_on_hyphens – Break on hyphens?

• fill_args – extra keyword arguments to textwrap.fill() if desired

Returns:

text wrapped string

dgenerate.textprocessing.wrap_paragraphs(text: str, width: int, break_long_words=False, break_on_hyphens=False, **fill_args)

Wrap text that may contain paragraphs without removing separating whitespace.

The directive NOWRAP! can be used to start a paragraph block with no word wrapping, which is useful for manually formatting small blocks of text. NOWRAP! should exist on its own line, immediately followed by the block of text which will have wrapping disabled. The NOWRAP! directive line will not exist in the output text.

Parameters:

• text – Text containing paragraphs

• width – Wrap with in characters

• break_long_words – break on long words? default False

• break_on_hyphens – break on hyphens? default False

• fill_args – extra keyword arguments to textwrap.fill() if desired

Returns:

text wrapped string

dgenerate.types module

Commonly used static type definitions and utilities for introspecting on objects, functions, types, etc.

class dgenerate.types.SetFromMixin

Bases: object

Allows an obj ot have its attributes set from a dictionary or attributes taken from another obj with an overlapping set of attribute names.

set_from(obj: Any | dict, missing_value_throws: bool = True)

Set the attributes in this configuration obj from a dictionary or another obj possessing keys / attributes of the same name.

Parameters:

• obj – The obj, or dictionary

• missing_value_throws – whether to throw ValueError if obj is missing an attribute that exist in this obj

Returns:

self

dgenerate.types.class_and_id_string(obj) → str

Return a string formatted with an objects class name next to its memory ID.

IE: <ClassName: id_integer>

Parameters:

obj – the obj

Returns:

formatted string

dgenerate.types.default(value, default_value)

Return value if value is not None, otherwise default

Parameters:

• value –

• default_value –

Returns:

value or default_value

dgenerate.types.format_function_signature(func: Callable, alternate_name: str | None = None, omit_params: Container | None = None) → str

Formats the signature of a given function to a string, including default values for arguments.

Parameters:

• func – The function

• alternate_name – Alternate function display name

• omit_params – Omit parameters by name, this should be a container filled with parameter names, such as a set or list.

dgenerate.types.fullname(obj)

Get the fully qualified name of an obj or function or type/class

Parameters:

obj – The obj

Returns:

Fully qualified name

dgenerate.types.get_accepted_args_with_defaults(func) → Iterator[tuple[str] | tuple[str, Any]]

Get the argument signature of a simple function with any default values present.

Parameters:

func – the function

Returns:

an iterator over tuples of length 1 or 2, length 2 indicates a default argument value is present. (name,) or (name, value)

dgenerate.types.get_all_base_classes(cls) → list[Type]

Get all base classes of a given class recursively.

Returns:

A list of all base classes.

dgenerate.types.get_default_args(func) → Iterator[tuple[str, Any]]

Get a list of default arguments from a simple function with their default values.

Parameters:

func – the function

Returns:

iterator over tuples of length 2 (name, value)

dgenerate.types.get_null_attr_name(e)

If an AttributeError occurred due to accessing an attribute of a NoneType value, get the exact name of the value (variable ID) that was None.

For the most accurate result, sources must be present. If sources are not present the line of code where the issue occurred is returned instead.

Parameters:

e – The exception

Returns:

Name or None if not found.

dgenerate.types.get_null_call_name(e)

If a TypeError occurred due to calling a NoneType value, get the exact name of the value (variable ID) that was None

For the most accurate result, sources must be present. If sources are not present the line of code where the issue occurred is returned instead.

Parameters:

e – The exception

Returns:

Name or None if not found.

dgenerate.types.get_public_attributes(obj) → dict[str, Any]

Get the public attributes (excluding functions) and their values from an obj.

Parameters:

obj – the obj

Returns:

dict of attribute names to values

dgenerate.types.get_public_members(obj) → dict[str, Any]

Get the public members (including functions) and their values from an obj.

Parameters:

obj – the obj

Returns:

dict of attribute names to values

dgenerate.types.get_type(hinted_type)

Get the basic type of hinted type

Parameters:

hinted_type – the type hint

Returns:

bool

dgenerate.types.get_type_of_optional(hinted_type: type, get_origin=True)

Get the first possible type for an typing.Optional[] type hint

Parameters:

• get_origin – Should the returned type be the origin type?

• hinted_type – The hinted type to extract from

Returns:

the type, or None

dgenerate.types.is_optional(hinted_type)

Check if a hinted type is typing.Optional[]

Parameters:

hinted_type – The hinted type

Returns:

bool

dgenerate.types.is_type(hinted_type, comparison_type)

Check if a hinted type is equal to a comparison type.

Parameters:

• hinted_type – The hinted type

• comparison_type – The type to check for

Returns:

bool

dgenerate.types.is_type_or_optional(hinted_type, comparison_type)

Check if a hinted type is equal to a comparison type, even if the type hint is typing.Optional[] (compare the inside if necessary).

Parameters:

• hinted_type – The hinted type

• comparison_type – The type to check for

Returns:

bool

dgenerate.types.is_typing_hint(obj)

Does a type hint object originate from the the builtin typing module?

Parameters:

obj – type hint

Returns:

True or False

dgenerate.types.iterate_attribute_combinations(attribute_defs: Iterable[tuple[str, Iterable]], return_type: type) → Iterator

Iterate over every combination of attributes in a given class using a list of tuples mapping attribute names to a list of possible values.

Parameters:

• attribute_defs – sequence of tuple (attribute_name, [sequence of values])

• return_type – Construct this type and assign attribute values to it

Returns:

an iterator over instances of the type mentioned in the my_class argument

dgenerate.types.module_all()

Return the name of all public non-module type global objects inside the current module.

Can be used for __all__

Returns:

list of names

dgenerate.types.parse_bool(string_or_bool: str | bool)

Parse a case insensitive boolean value from a string, for example “true” or “false”

Additionally, values that are already bool are passed through.

Raises:

ValueError – on parse failure.

Parameters:

string_or_bool – the string, or a bool value

Returns:

python boolean type equivalent

dgenerate.types.partial_deep_copy_container(container: list | dict | set)

Partially copy nested containers, handles lists, dicts, and sets.

Parameters:

container – top level container

Returns:

structure with all containers copied

dgenerate.types.type_check_struct(obj, attribute_namer: Callable[[str], str] | None = None)

Preform some basic type checks on a struct like objects attributes using their type hints.

Raises:

ValueError – on type checking failure

Parameters:

• obj – the object

• attribute_namer – function which names attributes an alternate name

dgenerate.webcache module

Single point of access to the global dgenerate web cache.

dgenerate.webcache.create_web_cache_file(url, mime_acceptable_desc: str | None = None, mimetype_is_supported: ~typing.Callable[[str], bool] | None = None, unknown_mimetype_exception=<class 'ValueError'>, overwrite: bool = False, tqdm_pbar=<class 'tqdm.std.tqdm'>) → tuple[str, str]

Download a file from a url and add it to dgenerates temporary web cache that is available to all concurrent dgenerate processes.

If the file exists in the cache already, return information for the existing file.

Raises:

requests.RequestException – Can raise any exception raised by requests.get for request related errors.

Parameters:

• url – The url

• mime_acceptable_desc – A description of acceptable mimetypes for use in exceptions.

• mimetype_is_supported – A function that determines if a mimetype is supported for downloading.

• unknown_mimetype_exception – The exception type to raise when an unknown mimetype is encountered.

• overwrite – Always overwrite any previously cached file?

• tqdm_pbar – tqdm progress bar type, if set to None no progress bar will be used. Defaults to tqdm.tqdm

Returns:

tuple(mimetype_str, filepath)

dgenerate.webcache.get_web_cache_directory() → str

Get the default web cache directory or the value of the environmental variable DGENERATE_WEB_CACHE

Returns:

string (directory path)

dgenerate.webcache.is_downloadable_url(string) → bool

Does a string represent a URL that can be downloaded into the web cache?

Parameters:

string – the string

Returns:

True or False

dgenerate.webcache.request_mimetype(url) → str

Request the mimetype of a file at a URL, if the file exists in the cache, a known mimetype is returned without connecting to the internet. Otherwise, connect to the internet to retrieve the mimetype, this action does not update the cache.

Parameters:

url – The url

Returns:

mimetype string