#
MultiDiffusion

MultiDiffusion: Fusing Diffusion Paths for Controlled Image Generation is by Omer Bar-Tal, Lior Yariv, Yaron Lipman, and Tali Dekel.

The abstract from the paper is:

Recent advances in text-to-image generation with diffusion models present transformative capabilities in image quality. However, user controllability of the generated image, and fast adaptation to new tasks still remains an open challenge, currently mostly addressed by costly and long re-training and fine-tuning or ad-hoc adaptations to specific image generation tasks. In this work, we present MultiDiffusion, a unified framework that enables versatile and controllable image generation, using a pre-trained text-to-image diffusion model, without any further training or finetuning. At the center of our approach is a new generation process, based on an optimization task that binds together multiple diffusion generation processes with a shared set of parameters or constraints. We show that MultiDiffusion can be readily applied to generate high quality and diverse images that adhere to user-provided controls, such as desired aspect ratio (e.g., panorama), and spatial guiding signals, ranging from tight segmentation masks to bounding boxes.

You can find additional information about MultiDiffusion on the project page, original codebase, and try it out in a demo.

##
Tips

While calling StableDiffusionPanoramaPipeline, it’s possible to specify the `view_batch_size` parameter to be > 1. For some GPUs with high performance, this can speedup the generation process and increase VRAM usage.

To generate panorama-like images make sure you pass the width parameter accordingly. We recommend a width value of 2048 which is the default.

Circular padding is applied to ensure there are no stitching artifacts when working with panoramas to ensure a seamless transition from the rightmost part to the leftmost part. By enabling circular padding (set `circular_padding=True`), the operation applies additional crops after the rightmost point of the image, allowing the model to “see” the transition from the rightmost part to the leftmost part. This helps maintain visual consistency in a 360-degree sense and creates a proper “panorama” that can be viewed using 360-degree panorama viewers. When decoding latents in Stable Diffusion, circular padding is applied to ensure that the decoded latents match in the RGB space.

For example, without circular padding, there is a stitching artifact (default):

But with circular padding, the right and the left parts are matching (`circular_padding=True`):

Make sure to check out the Schedulers guide to learn how to explore the tradeoff between scheduler speed and quality, and see the reuse components across pipelines section to learn how to efficiently load the same components into multiple pipelines.

##
StableDiffusionPanoramaPipeline

###
class diffusers.StableDiffusionPanoramaPipeline

< source >

( vae: AutoencoderKL text_encoder: CLIPTextModel tokenizer: CLIPTokenizer unet: UNet2DConditionModel scheduler: DDIMScheduler safety_checker: StableDiffusionSafetyChecker feature_extractor: CLIPImageProcessor image_encoder: Optional = None requires_safety_checker: bool = True )

Parameters

- vae (AutoencoderKL) — Variational Auto-Encoder (VAE) model to encode and decode images to and from latent representations.
- text_encoder (CLIPTextModel) — Frozen text-encoder (clip-vit-large-patch14).
- tokenizer (CLIPTokenizer) — A `CLIPTokenizer` to tokenize text.
- unet (UNet2DConditionModel) — A `UNet2DConditionModel` to denoise the encoded image latents.
- scheduler (SchedulerMixin) — A scheduler to be used in combination with `unet` to denoise the encoded image latents. Can be one of DDIMScheduler, LMSDiscreteScheduler, or PNDMScheduler.
- safety_checker (`StableDiffusionSafetyChecker`) — Classification module that estimates whether generated images could be considered offensive or harmful. Please refer to the model card for more details about a model’s potential harms.
- feature_extractor (CLIPImageProcessor) — A `CLIPImageProcessor` to extract features from generated images; used as inputs to the `safety_checker`.

Pipeline for text-to-image generation using MultiDiffusion.

This model inherits from DiffusionPipeline. Check the superclass documentation for the generic methods implemented for all pipelines (downloading, saving, running on a particular device, etc.).

The pipeline also inherits the following loading methods:

- load_textual_inversion() for loading textual inversion embeddings
- load_lora_weights() for loading LoRA weights
- save_lora_weights() for saving LoRA weights
- load_ip_adapter() for loading IP Adapters

####
__call__

< source >

( prompt: Union = None height: Optional = 512 width: Optional = 2048 num_inference_steps: int = 50 timesteps: List = None guidance_scale: float = 7.5 view_batch_size: int = 1 negative_prompt: Union = None num_images_per_prompt: Optional = 1 eta: float = 0.0 generator: Union = None latents: Optional = None prompt_embeds: Optional = None negative_prompt_embeds: Optional = None ip_adapter_image: Union = None ip_adapter_image_embeds: Optional = None output_type: Optional = 'pil' return_dict: bool = True cross_attention_kwargs: Optional = None guidance_rescale: float = 0.0 circular_padding: bool = False clip_skip: Optional = None callback_on_step_end: Optional = None callback_on_step_end_tensor_inputs: List = ['latents'] **kwargs: Any ) →
StableDiffusionPipelineOutput or `tuple`

Parameters

- prompt (`str` or `List[str]`, optional) — The prompt or prompts to guide image generation. If not defined, you need to pass `prompt_embeds`.
- height (`int`, optional, defaults to 512) — The height in pixels of the generated image.
- width (`int`, optional, defaults to 2048) — The width in pixels of the generated image. The width is kept high because the pipeline is supposed generate panorama-like images.
- num_inference_steps (`int`, optional, defaults to 50) — The number of denoising steps. More denoising steps usually lead to a higher quality image at the expense of slower inference.
- timesteps (`List[int]`, optional) — The timesteps at which to generate the images. If not specified, then the default timestep spacing strategy of the scheduler is used.
- guidance_scale (`float`, optional, defaults to 7.5) — A higher guidance scale value encourages the model to generate images closely linked to the text `prompt` at the expense of lower image quality. Guidance scale is enabled when `guidance_scale > 1`.
- view_batch_size (`int`, optional, defaults to 1) — The batch size to denoise split views. For some GPUs with high performance, higher view batch size can speedup the generation and increase the VRAM usage.
- negative_prompt (`str` or `List[str]`, optional) — The prompt or prompts to guide what to not include in image generation. If not defined, you need to pass `negative_prompt_embeds` instead. Ignored when not using guidance (`guidance_scale < 1`).
- num_images_per_prompt (`int`, optional, defaults to 1) — The number of images to generate per prompt.
- eta (`float`, optional, defaults to 0.0) — Corresponds to parameter eta (η) from the DDIM paper. Only applies to the DDIMScheduler, and is ignored in other schedulers.
- generator (`torch.Generator` or `List[torch.Generator]`, optional) — A `torch.Generator` to make generation deterministic.
- latents (`torch.FloatTensor`, optional) — Pre-generated noisy latents sampled from a Gaussian distribution, to be used as inputs for image generation. Can be used to tweak the same generation with different prompts. If not provided, a latents tensor is generated by sampling using the supplied random `generator`.
- prompt_embeds (`torch.FloatTensor`, optional) — Pre-generated text embeddings. Can be used to easily tweak text inputs (prompt weighting). If not provided, text embeddings are generated from the `prompt` input argument.
- negative_prompt_embeds (`torch.FloatTensor`, optional) — Pre-generated negative text embeddings. Can be used to easily tweak text inputs (prompt weighting). If not provided, `negative_prompt_embeds` are generated from the `negative_prompt` input argument. ip_adapter_image — (`PipelineImageInput`, optional): Optional image input to work with IP Adapters.
- ip_adapter_image_embeds (`List[torch.FloatTensor]`, optional) — Pre-generated image embeddings for IP-Adapter. It should be a list of length same as number of IP-adapters. Each element should be a tensor of shape `(batch_size, num_images, emb_dim)`. It should contain the negative image embedding if `do_classifier_free_guidance` is set to `True`. If not provided, embeddings are computed from the `ip_adapter_image` input argument.
- output_type (`str`, optional, defaults to `"pil"`) — The output format of the generated image. Choose between `PIL.Image` or `np.array`.
- return_dict (`bool`, optional, defaults to `True`) — Whether or not to return a StableDiffusionPipelineOutput instead of a plain tuple.
- cross_attention_kwargs (`dict`, optional) — A kwargs dictionary that if specified is passed along to the `AttentionProcessor` as defined under `self.processor` in diffusers.models.attention_processor.
- guidance_rescale (`float`, optional, defaults to 0.0) — A rescaling factor for the guidance embeddings. A value of 0.0 means no rescaling is applied.
- circular_padding (`bool`, optional, defaults to `False`) — If set to `True`, circular padding is applied to ensure there are no stitching artifacts. Circular padding allows the model to seamlessly generate a transition from the rightmost part of the image to the leftmost part, maintaining consistency in a 360-degree sense.
- clip_skip (`int`, optional) — 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.
- callback_on_step_end (`Callable`, optional) — A function that calls at the end of each denoising steps during the inference. The function is called with the following arguments: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` will include a list of all tensors as specified by `callback_on_step_end_tensor_inputs`.
- callback_on_step_end_tensor_inputs (`List[str]`, optional) — The list of tensor inputs for the `callback_on_step_end` function. The tensors specified in the list will be passed as `callback_kwargs` argument. You will only be able to include variables listed in the `._callback_tensor_inputs` attribute of your pipeline class.

Returns

StableDiffusionPipelineOutput or `tuple`

If `return_dict` is `True`, StableDiffusionPipelineOutput is returned, otherwise a `tuple` is returned where the first element is a list with the generated images and the second element is a list of `bool`s indicating whether the corresponding generated image contains “not-safe-for-work” (nsfw) content.

The call function to the pipeline for generation.

Examples:

    >>> import torch
    >>> from diffusers import StableDiffusionPanoramaPipeline, DDIMScheduler

    >>> model_ckpt = "stabilityai/stable-diffusion-2-base"
    >>> scheduler = DDIMScheduler.from_pretrained(model_ckpt, subfolder="scheduler")
    >>> pipe = StableDiffusionPanoramaPipeline.from_pretrained(
    ...     model_ckpt, scheduler=scheduler, torch_dtype=torch.float16
    ... )

    >>> pipe = pipe.to("cuda")

    >>> prompt = "a photo of the dolomites"
    >>> image = pipe(prompt).images[0]

####
decode_latents_with_padding

< source >

( latents: Tensor padding: int = 8 ) →
torch.Tensor

Parameters

- latents (torch.Tensor) — The input latents to decode.
- padding (int, optional) — The number of latents to add on each side for padding. Defaults to 8.

Returns

torch.Tensor

The decoded image with padding removed.

Decode the given latents with padding for circular inference.

Notes:

- The padding is added to remove boundary artifacts and improve the output quality.
- This would slightly increase the memory usage.
- The padding pixels are then removed from the decoded image.

####
encode_prompt

< source >

( prompt device num_images_per_prompt do_classifier_free_guidance negative_prompt = None prompt_embeds: Optional = None negative_prompt_embeds: Optional = None lora_scale: Optional = None clip_skip: Optional = None )

Parameters

- prompt (`str` or `List[str]`, optional) — prompt to be encoded device — (`torch.device`): torch device
- num_images_per_prompt (`int`) — number of images that should be generated per prompt
- do_classifier_free_guidance (`bool`) — whether to use classifier free guidance or not
- negative_prompt (`str` or `List[str]`, optional) — The prompt or prompts not to guide the image generation. If not defined, one has to pass `negative_prompt_embeds` instead. Ignored when not using guidance (i.e., ignored if `guidance_scale` is less than `1`).
- prompt_embeds (`torch.FloatTensor`, optional) — Pre-generated text embeddings. Can be used to easily tweak text inputs, e.g. prompt weighting. If not provided, text embeddings will be generated from `prompt` input argument.
- negative_prompt_embeds (`torch.FloatTensor`, optional) — Pre-generated negative text embeddings. Can be used to easily tweak text inputs, e.g. prompt weighting. If not provided, negative_prompt_embeds will be generated from `negative_prompt` input argument.
- lora_scale (`float`, optional) — A LoRA scale that will be applied to all LoRA layers of the text encoder if LoRA layers are loaded.
- clip_skip (`int`, optional) — 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.

Encodes the prompt into text encoder hidden states.

####
get_guidance_scale_embedding

< source >

( w: Tensor embedding_dim: int = 512 dtype: dtype = torch.float32 ) →
`torch.FloatTensor`

Parameters

- w (`torch.Tensor`) — Generate embedding vectors with a specified guidance scale to subsequently enrich timestep embeddings.
- embedding_dim (`int`, optional, defaults to 512) — Dimension of the embeddings to generate.
- dtype (`torch.dtype`, optional, defaults to `torch.float32`) — Data type of the generated embeddings.

Returns

`torch.FloatTensor`

Embedding vectors with shape `(len(w), embedding_dim)`.

See https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298

####
get_views

< source >

( panorama_height: int panorama_width: int window_size: int = 64 stride: int = 8 circular_padding: bool = False ) →
List[Tuple[int, int, int, int]]

Parameters

- panorama_height (int) — The height of the panorama.
- panorama_width (int) — The width of the panorama.
- window_size (int, optional) — The size of the window. Defaults to 64.
- stride (int, optional) — The stride value. Defaults to 8.
- circular_padding (bool, optional) — Whether to apply circular padding. Defaults to False.

Returns

List[Tuple[int, int, int, int]]

A list of tuples representing the views. Each tuple contains four integers representing the start and end coordinates of the window in the panorama.

Generates a list of views based on the given parameters. Here, we define the mappings F_i (see Eq. 7 in the MultiDiffusion paper https://arxiv.org/abs/2302.08113). If panorama’s height/width < window_size, num_blocks of height/width should return 1.

##
StableDiffusionPipelineOutput

###
class diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput

< source >

( images: Union nsfw_content_detected: Optional )

Parameters

- images (`List[PIL.Image.Image]` or `np.ndarray`) — List of denoised PIL images of length `batch_size` or NumPy array of shape `(batch_size, height, width, num_channels)`.
- nsfw_content_detected (`List[bool]`) — List indicating whether the corresponding generated image contains “not-safe-for-work” (nsfw) content or `None` if safety checking could not be performed.

Output class for Stable Diffusion pipelines.