stable-diffusion-inpainting

Generates new image content within masked regions of an existing image using latent diffusion conditioned on text prompts. The model encodes the input image and mask into latent space, applies iterative denoising steps guided by CLIP text embeddings, and decodes the result back to pixel space. The mask acts as a spatial constraint, preserving unmasked regions while regenerating masked areas to match the text description.

Conditions image generation on natural language text by encoding prompts through OpenAI's CLIP text encoder, producing 768-dimensional embeddings that guide the diffusion process. The UNet denoising network cross-attends to these embeddings at multiple resolution scales, progressively refining the image to match semantic content described in the prompt. This enables fine-grained control over generated content through natural language without requiring structured input schemas.

Enables downloading and caching model weights from the Hugging Face Hub using a simple model_id string (e.g., 'stable-diffusion-v1-5/stable-diffusion-inpainting'). The pipeline automatically handles authentication, version management, and local caching, storing downloaded weights in ~/.cache/huggingface/hub. Users can specify custom cache directories or offline mode, and the system supports resumable downloads for large checkpoints (4-7GB).

Implements a configurable diffusion sampling loop that progressively denoises latent representations over 20-50 timesteps using a learned UNet noise predictor. The process supports multiple noise schedulers (DDPM, DDIM, PNDMScheduler) that control the denoising trajectory, allowing trade-offs between speed (fewer steps, DDIM) and quality (more steps, DDPM). Each step predicts and subtracts estimated noise, guided by text embeddings and mask constraints, until reaching clean latent codes suitable for decoding.

Compresses images to and from a learned latent space using a variational autoencoder (VAE), reducing spatial dimensions by 8x (512x512 → 64x64) while preserving semantic content. The encoder maps images to 4-channel latent distributions; the decoder reconstructs images from latent codes. This compression enables efficient diffusion in latent space (8x faster than pixel-space diffusion) while maintaining visual quality through careful VAE training on high-resolution image datasets.

Preserves unmasked image regions during inpainting by concatenating the original masked image latents (encoded via VAE) with the diffusion latents as additional input channels to the UNet. At each denoising step, the model receives both the noisy latent prediction and the original masked image context, enabling it to learn to regenerate only masked regions while maintaining consistency with preserved areas. This is implemented via channel concatenation rather than separate mask encoding, reducing architectural complexity.

Implements conditional guidance by training the model on both conditioned (with text embeddings) and unconditional (with null embeddings) samples, enabling inference-time guidance strength control via a guidance_scale parameter. During sampling, the model predicts noise for both conditioned and unconditional cases, then interpolates between them: predicted_noise = unconditional_noise + guidance_scale * (conditioned_noise - unconditional_noise). Higher guidance_scale values increase adherence to text prompts at the cost of reduced diversity and potential artifacts.

Supports generating multiple images in parallel within a single forward pass by batching latent tensors, enabling efficient GPU utilization. The pipeline handles variable input dimensions (512x512, 768x768, etc.) by resizing inputs to compatible dimensions and adjusting latent spatial dimensions accordingly. Batch processing reduces per-image overhead and improves throughput compared to sequential generation, though memory usage scales linearly with batch size.

Enables reproducible image generation by accepting a seed parameter that initializes the random number generator for latent initialization and stochastic sampling steps. With a fixed seed, the same prompt and mask produce identical outputs across multiple runs, enabling debugging, quality assurance, and consistent results in production. The seed controls both initial noise sampling and stochastic scheduler behavior (if using stochastic samplers like DDPM).

Extends classifier-free guidance to support negative prompts by computing noise predictions for both positive and negative text embeddings, then using the difference to steer generation away from unwanted content. The guidance formula becomes: predicted_noise = unconditional_noise + guidance_scale * (positive_noise - unconditional_noise) - guidance_scale * (negative_noise - unconditional_noise). This enables users to specify what they don't want in generated images without explicit architectural changes.

Provides a high-level StableDiffusionInpaintPipeline class that abstracts away low-level diffusion mechanics (VAE encoding, noise scheduling, UNet inference, VAE decoding) into a simple __call__ interface. Users specify image, mask, and prompt; the pipeline handles all intermediate steps including device management, dtype conversion, and memory optimization. This abstraction enables non-experts to use inpainting without understanding diffusion theory while maintaining extensibility for advanced users.