dgenerate module

exception dgenerate.BatchProcessError

Bases: Exception

Thrown on errors encountered within a batch processing script including non-zero return codes from the invoker.

exception dgenerate.DgenerateUsageError

Bases: Exception

exception dgenerate.ImagePreprocessorArgumentError

Bases: Exception

Raised when an image preprocessor receives invalid arguments.

exception dgenerate.ImagePreprocessorNotFoundError

Bases: Exception

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

exception dgenerate.ImageSeedError

Bases: Exception

Raised on image seed parsing and loading errors.

exception dgenerate.InvalidModelUriError

Bases: Exception

Thrown on model path syntax or logical usage error

exception dgenerate.InvalidSchedulerName

Bases: Exception

Unknown scheduler name used

exception dgenerate.ModelNotFoundError

Bases: Exception

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

exception dgenerate.OutOfMemoryError(message)

Bases: Exception

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

__init__(message)

exception dgenerate.RenderLoopConfigError

Bases: Exception

Raised by RenderLoopConfig.check() on configuration errors.

exception dgenerate.UnknownMimetypeError

Bases: Exception

class dgenerate.DataTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Represents model precision

AUTO = 0

Auto selection.

FLOAT16 = 1

16 bit floating point.

FLOAT32 = 2

32 bit floating point.

class dgenerate.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.PipelineTypes needed to utilize these arguments.

Returns:

dgenerate.pipelinewrapper.PipelineTypes

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.

Invalid to use with FLAX ModeTypes.

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 control_net_uris defined.

control_images: List[Image] | None = None

ControlNet guidance images to use if control_net_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.

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: Tuple[int, 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: Image | None = None

Image for img2img operations, or the base for inpainting operations.

All input images involved in a generation must match in dimension and be aligned by 8 pixels.

image_guidance_scale: float | None = None

This value is only relevant for pix2pix dgenerate.pipelinewrapper.ModelTypes.

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.

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.

mask_image: Image | None = None

Mask image for inpainting operations.

All input images involved in a generation must match in dimension and be aligned by 8 pixels.

prompt: Prompt | None = None

Primary prompt

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_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_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.ModelTypes.TORCH_UPSCALER_X4 model type only.

width: Tuple[int, 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.ImageGeneratedCallbackArgument

Bases: object

This argument object gets passed to callbacks registered to RenderLoop.image_generated_callbacks.

batch_index: int = 0

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

Reproduction of a command line that can be used to reproduce this image.

config_string: str = None

Reproduction of a dgenerate config file that can be used to reproduce this image.

diffusion_args: DiffusionArguments = None

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

The current generation step. (zero indexed)

image: Image = None

The generated image.

image_seed: ImageSeed | None = 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_filename: str = None

A suggested filename for saving this image as. This filename will be unique to the render loop run / configuration.

class dgenerate.ImageSeed(image: Image | None = None, mask_image: Image | None = None, control_images: List[Image] | None = None, floyd_image: Image | None = None)

Bases: object

An ImageSeed with attached image data

__init__(image: Image | None = None, mask_image: Image | None = None, control_images: List[Image] | None = None, floyd_image: Image | None = None)

anim_fps: int | float | None = None

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

anim_frame_duration: float | None = None

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

control_images: List[Image] | None

List of 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_image has a a value. As that is considered incorrect –image-seeds

frame_index: int | None = None

Frame index in the case that ImageSeed.is_animation_frame is True

image: Image | None

An optional image used for img2img mode, or inpainting mode in combination with ImageSeed.mask

is_animation_frame: bool

Is this part of an animation?

mask_image: Image | None

An optional inpaint mask image, may be None

total_frames: int | None = None

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

class dgenerate.ModelTypes(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_SDXL = 2

Stable Diffusion XL

TORCH_SDXL_PIX2PIX = 6

Stable Diffusion XL pix2pix prompt guided editing.

TORCH_UPSCALER_X2 = 7

Stable Diffusion X2 upscaler

TORCH_UPSCALER_X4 = 8

Stable Diffusion X4 upscaler

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=None, preprocessor_loader=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=None, preprocessor_loader=None)

Parameters:

• config – RenderLoopConfig or dgenerate.arguments.DgenerateArguments. If None is provided, a RenderLoopConfig instance will be created and assigned to RenderLoop.config.

• preprocessor_loader – dgenerate.preprocessors.loader.Loader. If None is provided, an instance will be created and assigned to RenderLoop.preprocessor_loader.

generate_template_variables() → Dict[str, Any]

Generate a dictionary from the render loop that describes its current / last used configuration.

This is consumed by the dgenerate.batchprocess.BatchProcessor that is created by dgenerate.batchprocess.create_config_runner() for use in Jinja2 templating.

Returns:

a dictionary of attribute names to values

generate_template_variables_help(values: Dict[str, Tuple[Type, Any]] | None = None, show_values: bool = True, header=None)

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

This is used to implement --templates-help in dgenerate.invoker.invoke_dgenerate()

Parameters:

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

• header – Override the default help message header.

Returns:

a human-readable description of all template variables

generate_template_variables_with_types() → Dict[str, Tuple[Type, Any]]

Generate a dictionary from the render loop that describes its current / last used configuration with type hints.

Returns:

a dictionary of attribute names to tuple(type_hint_type, value)

run()

Run the diffusion loop, this calls RenderLoopConfig.check() prior to running.

Raises:

• dgenerate.pipelinewrapper.ModelNotFoundError –

• dgenerate.pipelinewrapper.OutOfMemoryError –

disable_writes: bool = False

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

last_images and last_animations will not be available as template variables in batch processing scripts with this enabled, they will be empty lists

property generation_step

Returns the current generation step, (zero indexed)

image_generated_callbacks: List[Callable[[ImageGeneratedCallbackArgument], None]]

Optional callbacks for handling individual images that have been generated.

The callback has a single argument: ImageGeneratedCallbackArgument

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

refiner_extra_modules: Dict[str, Any] = None

Extra raw diffusers modules to use in the creation of any refiner model pipeline.

property written_animations: Iterator[str]

Iterator over animation filenames written by the last run

property written_images: Iterator[str]

Iterator 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

generate_template_variables(variable_prefix: str | None = None) → Dict[str, Any]

Generate a dictionary from this configuration object that is suitable for using as Jinja2 environmental variables.

Parameters:

variable_prefix – Prefix every variable name with this prefix if specified

Returns:

a dictionary of attribute names to values

generate_template_variables_with_types(variable_prefix: str | None = None) → Dict[str, Tuple[Type, Any]]

Generate a dictionary from this configuration object that maps attribute names to a tuple containing (type_hint_type, value)

Parameters:

variable_prefix – Prefix every variable name with this prefix if specified

Returns:

a dictionary of attribute names to tuple(type_hint_type, value)

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 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: List[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_preprocessors: List[str] | None = None

Corresponds to the --control-image-preprocessors 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: List[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: DataTypes = 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: List[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: List[float]

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

image_guidance_scales: List[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: List[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: List[str] | None = None

List of --image-seeds URI strings.

inference_steps: List[int]

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

lora_uris: List[str] | None = None

Optional user specified LoRA URIs, this corresponds to the --lora/--loras argument of the dgenerate command line tool.

mask_image_preprocessors: List[str] | None = None

Corresponds to the --mask-image-preprocessors argument of the dgenerate command line tool verbatim.

model_path: str | None = None

Primary diffusion model path, model_path argument of dgenerate command line tool.

model_type: ModelTypes = 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) ?

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: List[ImageSeedParseResult] | None = None

The results of parsing URIs mentioned in RenderLoopConfig.image_seeds, will only be available if RenderLoopConfig.check() has been called.

prompts: List[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.

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.

sdxl_aesthetic_scores: List[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: List[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: List[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: List[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: List[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: List[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: List[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: List[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: List[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: List[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_crops_coords_top_left: List[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_guidance_rescales: List[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: List[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: List[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: List[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: List[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: List[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: List[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: List[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: List[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.

sdxl_refiner_second_prompts: List[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_target_sizes: List[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: List[Prompt] | None = None

Optional list of SDXL secondary prompts, this corresponds to the --sdxl-secondary-prompts argument of the dgenerate command line tool.

sdxl_target_sizes: List[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.

seed_image_preprocessors: List[str] | None = None

Corresponds to the --seed-image-preprocessors argument of the dgenerate command line tool verbatim.

seeds: List[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.

textual_inversion_uris: List[str] | None = None

Optional user specified Textual Inversion URIs, this corresponds to the --textual-inversions argument of the dgenerate command line tool.

upscaler_noise_levels: List[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.ModelTypes.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.

dgenerate.create_config_runner(injected_args: Sequence[str] | None = None, render_loop: RenderLoop | None = None, version: Tuple[int, int, int] | str = '2.1.0', throw: bool = False)

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

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

• render_loop – RenderLoop instance, if None is 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 BatchProcessError being raised, a line number where the error occurred can be obtained using BatchProcessor.current_line.

Returns:

integer return-code, anything other than 0 is failure

dgenerate.gen_seeds(n)

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)

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.

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 exceptions or handle them.

Raises:

• dgenerate.arguments.DgenerateUsageError –

• dgenerate.mediainput.ImageSeedError –

• dgenerate.mediainput.UnknownMimetypeError –

• dgenerate.preprocessors.ImagePreprocessorArgumentError –

• dgenerate.preprocessors.ImagePreprocessorNotFoundError –

• dgenerate.pipelinewrapper.InvalidModelUriError –

• dgenerate.pipelinewrapper.InvalidSchedulerName –

• dgenerate.pipelinewrapper.OutOfMemoryError –

• dgenerate.pipelinewrapper.ModelNotFoundError –

• NotImplementedError –

• EnvironmentError –

Returns:

integer return-code, anything other than 0 is failure

dgenerate.main()

Entry point for the dgenerate command line tool.

dgenerate.parse_args(args: Sequence[str], throw: bool = True) → 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

Raises:

DgenerateUsageError –

Returns:

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