Implementation:AUTOMATIC1111 Stable diffusion webui Sample hr pass

Knowledge Sources	stable-diffusion-webui
Domains	Diffusion Models, Image Upscaling, Multi-Pass Generation
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for executing the second pass of high-resolution fix generation by upscaling first-pass latents and running a refinement denoising pass, provided by the AUTOMATIC1111 stable-diffusion-webui repository.

Description

sample_hr_pass() is a method of StableDiffusionProcessingTxt2Img that implements the second phase of hires fix generation. It receives the first-pass output (either latent samples or decoded pixel tensors) and produces the final high-resolution result through these steps:

Upscaling -- Two modes are supported:
- Latent-space upscaling (latent_scale_mode is not None): Uses torch.nn.functional.interpolate() to resize latent samples directly, with configurable interpolation mode and antialiasing. This is fast but may produce softer results.
- Pixel-space upscaling (latent_scale_mode is None): Decodes latents to pixels, uses a neural or traditional upscaler (ESRGAN, Lanczos, etc.) via images.resize_image(), then re-encodes to latent space with images_tensor_to_samples().

Truncation -- If the target resolution requires aspect ratio adjustment, the latent is center-cropped by truncate_x and truncate_y values.

Noise generation -- A new ImageRNG is created for the upscaled resolution, and fresh noise is generated for the second pass.

Conditioning -- HR-specific conditioning (from hr_prompt / hr_negative_prompt) is computed or reused via calculate_hr_conds().

Second-pass sampling -- The sampler's sample_img2img() method runs the denoising loop starting from a partially noised version of the upscaled latent, using the configured hr_second_pass_steps (or falling back to the first-pass step count).

Final decode -- The refined latent is decoded via decode_latent_batch() and returned as DecodedSamples.

The method also supports optional intermediate image saving (before the hires fix is applied), extra network activation for the HR pass, token merging ratio adjustments, and script hooks (before_hr, process_before_every_sampling).

Usage

This method is called automatically by StableDiffusionProcessingTxt2Img.sample() when enable_hr=True. It is not typically called directly by user code. It can also be invoked when using the txt2img API with hires fix parameters.

Code Reference

Source Location

Repository: stable-diffusion-webui
File: modules/processing.py
Lines: 1364-1464

Signature

def sample_hr_pass(self, samples, decoded_samples, seeds, subseeds, subseed_strength, prompts):
    """
    Executes the high-resolution fix second pass.

    Args:
        samples: First-pass latent tensor of shape (B, 4, H/8, W/8), or None
                 if pixel-space upscaling is used.
        decoded_samples: Decoded pixel tensor of shape (B, 3, H, W) in [-1, 1] range,
                         or None if latent-space upscaling is used.
        seeds: List of seed values for each image in the batch.
        subseeds: List of subseed values for each image in the batch.
        subseed_strength: Subseed interpolation strength.
        prompts: List of prompt strings for each image in the batch.

    Returns:
        DecodedSamples: List of decoded image tensors from the second pass.
    """

Import

from modules.processing import StableDiffusionProcessingTxt2Img
# sample_hr_pass is a method on StableDiffusionProcessingTxt2Img instances

I/O Contract

Inputs

Name	Type	Required	Description
samples	torch.Tensor or None	Yes	First-pass latent samples of shape (B, 4, H_low/8, W_low/8). None when pixel-space upscaling was used in the calling code.
decoded_samples	torch.Tensor or None	Yes	First-pass decoded pixel tensors of shape (B, 3, H_low, W_low) in [-1, 1] range. None when latent-space upscaling is used.
seeds	list[int]	Yes	List of seed values for each image in the batch, used for intermediate image saving and RNG reseeding.
subseeds	list[int]	Yes	List of subseed values for each image in the batch.
subseed_strength	float	Yes	Strength of subseed interpolation (0.0 = use seed only, 1.0 = use subseed only).
prompts	list[str]	Yes	List of prompt strings for each image, used for intermediate image saving.

Outputs

Name	Type	Description
return	DecodedSamples	A list of decoded image tensors (each of shape (3, H_target, W_target)) from the second denoising pass. DecodedSamples is a list subclass with `already_decoded = True`.

Usage Examples

Basic Usage

from modules.processing import StableDiffusionProcessingTxt2Img, process_images
import modules.shared as shared

# Hires fix is enabled through the processing parameters
p = StableDiffusionProcessingTxt2Img(
    sd_model=shared.sd_model,
    prompt="a majestic mountain landscape, highly detailed, 8k",
    negative_prompt="blurry, low resolution",
    seed=42,
    width=512,
    height=512,
    steps=25,
    cfg_scale=7.0,
    sampler_name="DPM++ 2M",
    scheduler="Karras",
    enable_hr=True,
    hr_scale=2.0,                # Output will be 1024x1024
    hr_upscaler="Latent",        # Use latent-space bilinear upscaling
    hr_second_pass_steps=15,     # 15 denoising steps for refinement
    denoising_strength=0.5,      # Moderate refinement
)

# sample_hr_pass() is called internally by process_images()
processed = process_images(p)
# processed.images[0] is a 1024x1024 PIL Image

With Pixel-Space Upscaler and Separate HR Prompt

p = StableDiffusionProcessingTxt2Img(
    sd_model=shared.sd_model,
    prompt="portrait of a woman",
    negative_prompt="ugly, deformed",
    seed=123,
    width=512,
    height=768,
    steps=30,
    cfg_scale=7.5,
    sampler_name="Euler a",
    enable_hr=True,
    hr_scale=2.0,
    hr_upscaler="R-ESRGAN 4x+",   # Neural pixel-space upscaler
    hr_second_pass_steps=20,
    denoising_strength=0.45,
    hr_prompt="portrait of a woman, highly detailed skin texture, sharp focus",
    hr_negative_prompt="ugly, deformed, blurry",
)

processed = process_images(p)
# Output: 1024x1536 with enhanced detail

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment