diffusers/v0.37.0/en/api/pipelines/panorama.md

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[[diffusers.StableDiffusionPanoramaPipeline]]

diffusers.StableDiffusionPanoramaPipeline[[diffusers.StableDiffusionPanoramaPipeline]]

Source

__call__diffusers.StableDiffusionPanoramaPipeline.__call__https://github.com/huggingface/diffusers/blob/v0.37.0/src/diffusers/pipelines/stable_diffusion_panorama/pipeline_stable_diffusion_panorama.py#L801[{"name": "prompt", "val": ": str | list[str] = None"}, {"name": "height", "val": ": int | None = 512"}, {"name": "width", "val": ": int | None = 2048"}, {"name": "num_inference_steps", "val": ": int = 50"}, {"name": "timesteps", "val": ": list = None"}, {"name": "guidance_scale", "val": ": float = 7.5"}, {"name": "view_batch_size", "val": ": int = 1"}, {"name": "negative_prompt", "val": ": str | list[str] | None = None"}, {"name": "num_images_per_prompt", "val": ": int | None = 1"}, {"name": "eta", "val": ": float = 0.0"}, {"name": "generator", "val": ": torch._C.Generator | list[torch._C.Generator] | None = None"}, {"name": "latents", "val": ": torch.Tensor | None = None"}, {"name": "prompt_embeds", "val": ": torch.Tensor | None = None"}, {"name": "negative_prompt_embeds", "val": ": torch.Tensor | None = None"}, {"name": "ip_adapter_image", "val": ": PIL.Image.Image | numpy.ndarray | torch.Tensor | list[PIL.Image.Image] | list[numpy.ndarray] | list[torch.Tensor] | None = None"}, {"name": "ip_adapter_image_embeds", "val": ": list[torch.Tensor] | None = None"}, {"name": "output_type", "val": ": str | None = 'pil'"}, {"name": "return_dict", "val": ": bool = True"}, {"name": "cross_attention_kwargs", "val": ": dict[str, typing.Any] | None = None"}, {"name": "guidance_rescale", "val": ": float = 0.0"}, {"name": "circular_padding", "val": ": bool = False"}, {"name": "clip_skip", "val": ": int | None = None"}, {"name": "callback_on_step_end", "val": ": typing.Optional[typing.Callable[[int, int], NoneType]] = None"}, {"name": "callback_on_step_end_tensor_inputs", "val": ": list = ['latents']"}, {"name": "**kwargs", "val": ": typing.Any"}]- 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 0[StableDiffusionPipelineOutput](/docs/diffusers/v0.37.0/en/api/pipelines/stable_diffusion/gligen#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) or tupleIf return_dictisTrue, [StableDiffusionPipelineOutput](/docs/diffusers/v0.37.0/en/api/pipelines/stable_diffusion/gligen#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) is returned, otherwise a tupleis returned where the first element is a list with the generated images and the second element is a list ofbool`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]

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.Tensor, 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.Tensor, 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.Tensor, 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.Tensor], 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](/docs/diffusers/v0.37.0/en/api/pipelines/stable_diffusion/gligen#diffusers.pipelines.stable_diffusion.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 bools indicating whether the corresponding generated image contains "not-safe-for-work" (nsfw) content.

decode_latents_with_padding[[diffusers.StableDiffusionPanoramaPipeline.decode_latents_with_padding]]

Source

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.

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.

encode_prompt[[diffusers.StableDiffusionPanoramaPipeline.encode_prompt]]

Source

Encodes the prompt into text encoder hidden states.

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.Tensor, 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.Tensor, 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.

get_guidance_scale_embedding[[diffusers.StableDiffusionPanoramaPipeline.get_guidance_scale_embedding]]

Source

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

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

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

get_views[[diffusers.StableDiffusionPanoramaPipeline.get_views]]

Source

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://huggingface.co/papers/2302.08113). If panorama's height/width < window_size, num_blocks of height/width should return 1.

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.

StableDiffusionPipelineOutput[[diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput]]

diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput[[diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput]]

Source

Output class for Stable Diffusion pipelines.

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.