dgenerate module

exception dgenerate.BatchProcessError

Bases: Exception

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

exception dgenerate.DgenerateHelpException

Bases: Exception

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

exception dgenerate.DgenerateUsageError

Bases: Exception

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

exception dgenerate.FrameStartOutOfBounds

Bases: ValueError

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

exception dgenerate.ImageProcessorArgumentError

Bases: PluginArgumentError, ImageProcessorError

Raised when an image processor receives invalid arguments.

exception dgenerate.ImageProcessorError

Bases: Exception

Generic image processor error base exception.

exception dgenerate.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.ImageProcessorNotFoundError

Bases: PluginNotFoundError, ImageProcessorError

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

exception dgenerate.ImageSeedError

Bases: Exception

Raised on image seed parsing and loading errors.

exception dgenerate.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.InvalidModelUriError

Bases: Exception

Thrown on model path syntax or logical usage error

exception dgenerate.InvalidSchedulerNameError

Bases: Exception

Unknown scheduler name used

exception dgenerate.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.ModelNotFoundError

Bases: Exception

Raised when a specified model can not be located either locally or remotely

exception dgenerate.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.ModuleFileNotFoundError

Bases: FileNotFoundError

Raised by load_modules() if a module could not be found on disk.

exception dgenerate.NonHFModelDownloadError

Bases: Exception

exception dgenerate.OutOfMemoryError(message)

Bases: Exception

Raised when a GPU or processing device runs out of memory.

__init__(message)

exception dgenerate.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.PluginNotFoundError

Bases: Exception

Raised when a plugin could not be located by a name.

exception dgenerate.PromptWeightingUnsupported

Bases: Exception

Thrown when a dgenerate.promptweighters.PromptWeighter implementation cannot handle a specific pipeline or combination of pipeline arguments.

exception dgenerate.RenderLoopConfigError

Bases: Exception

Raised by RenderLoopConfig.check() on configuration errors.

exception dgenerate.UnknownMimetypeError

Bases: Exception

Raised when an unsupported mimetype is encountered

exception dgenerate.UnsupportedPipelineConfigError

Bases: Exception

Occurs when the a diffusers pipeline is requested to be configured in a way that is unsupported by that pipeline.

class dgenerate.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.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.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.ConfigRunner(injected_args: Sequence[str] | None = None, render_loop: RenderLoop | None = None, plugin_loader: ConfigRunnerPluginLoader = None, version: tuple[int, int, int] | str = '3.10.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 = '3.10.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.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.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.

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

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

Returns:

plugin instance

class dgenerate.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.DgenerateArguments

Bases: RenderLoopConfig

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

__init__()

cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.CACHE_MEMORY_CONSTRAINTS

control_net_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.CONTROL_NET_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

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

text_encoder_cache_memory_constraints: Sequence[str] | None = None

See: dgenerate.pipelinewrapper.TEXT_ENCODER_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

class dgenerate.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.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.ModelType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum representation of --model-type

FLAX = 9

Stable Diffusion, such as SD 1.0 - 2.x, with Flax / Jax parallelization.

TORCH = 0

Stable Diffusion, such as SD 1.0 - 2.x

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 = 12

Stable Diffusion 3

TORCH_SDXL = 2

Stable Diffusion XL

TORCH_SDXL_PIX2PIX = 6

Stable Diffusion XL pix2pix prompt guided editing.

TORCH_S_CASCADE = 10

Stable Cascade prior

TORCH_S_CASCADE_DECODER = 11

Stable Cascade decoder

TORCH_UPSCALER_X2 = 7

Stable Diffusion X2 upscaler

TORCH_UPSCALER_X4 = 8

Stable Diffusion X4 upscaler

class dgenerate.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.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

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)

class dgenerate.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.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 control_net_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.

control_net_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.

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.

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_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.

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 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_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.

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.

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.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.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.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.format_image_seed_uri(seed_image: str | None, inpaint_image: str | None = None, control_images: 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 dgenerate --image-seeds URI to its shortest possible string form.

A control image / images specifier can be specified alone.

An inpaint image must have an accompanying seed image.

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.

Parameters:

• seed_image – Seed image path

• inpaint_image – Inpaint image path

• control_images – Single control image path, or a paths string with multiple paths separated by the , character.

• 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.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.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 –

• EnvironmentError –

Returns:

integer return-code, anything other than 0 is failure

dgenerate.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 –

• EnvironmentError –

Returns:

InvokeDgenerateEventStream

dgenerate.main(args: Sequence[str] | None = None)

Entry point for the dgenerate command line tool.

Parameters:

args – program arguments, if None is provided they will be taken from sys.argv

dgenerate.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.