RealESRGANer

Main inference class for upsampling images with Real-ESRGAN models

Overview

RealESRGANer is the primary helper class for upsampling images with Real-ESRGAN. It handles model loading, preprocessing, tiled inference for large images, and post-processing.

Class Definition

RealESRGANer

from realesrgan import RealESRGANer

upsampler = RealESRGANer(
    scale=4,
    model_path='weights/RealESRGAN_x4plus.pth',
    model=model,
    tile=0,
    tile_pad=10,
    pre_pad=10,
    half=False,
    device=None,
    gpu_id=None,
    dni_weight=None
)

Parameters

scale · int · required

Upsampling scale factor used in the networks. Typically 2 or 4.

model_path · str | list[str] · required

Path to the pretrained model. Can be:

• Local file path
• URL (will be downloaded automatically)
• List of two paths for Deep Network Interpolation (DNI)

model · nn.Module · required

The defined neural network model (e.g., RRDBNet or SRVGGNetCompact).

tile · int · default: "0"

Tile size for processing large images in chunks to avoid GPU memory issues. Set to 0 to disable tiling.

tile_pad · int · default: "10"

Padding size for each tile to remove border artifacts during tiled inference.

pre_pad · int · default: "10"

Padding size added to input images before processing to avoid border artifacts.

half · bool · default: "False"

Whether to use half precision (FP16) during inference for faster processing and lower memory usage.

device · torch.device · default: "None"

The torch device to use. If None, automatically selects CUDA if available, otherwise CPU.

gpu_id · int · default: "None"

Specific GPU device ID to use (e.g., 0, 1, 2 for multi-GPU systems).

dni_weight · list[float] · default: "None"

Weights for Deep Network Interpolation when using two models. Must sum to 1.0 (e.g., [0.5, 0.5]).

Methods

enhance()

Main method to upscale an input image.

output, img_mode = upsampler.enhance(
    img,
    outscale=None,
    alpha_upsampler='realesrgan'
)

Parameters

img · numpy.ndarray · required

Input image as a numpy array (BGR format from OpenCV). Supports:

• 8-bit images (0-255)
• 16-bit images (0-65535)
• Grayscale (2D array)
• RGB (H×W×3)
• RGBA with alpha channel (H×W×4)

outscale · float · default: "None"

Final output scale. If different from the model’s scale, the output will be resized using Lanczos interpolation.

alpha_upsampler · str · default: "'realesrgan'"

Method to upscale the alpha channel for RGBA images. Options:

• 'realesrgan': Use the same model
• 'bicubic': Use OpenCV’s bicubic interpolation

Returns

output · numpy.ndarray

Upsampled image as a numpy array with the same bit depth as input (uint8 or uint16).

img_mode · str

Image mode: ‘L’ (grayscale), ‘RGB’, or ‘RGBA’.

pre_process()

Preprocesses the input image with padding to ensure divisibility.

upsampler.pre_process(img)

img · numpy.ndarray · required

Input image as numpy array (RGB format, normalized to [0, 1]).

This method converts the image to a PyTorch tensor, applies pre-padding and mod-padding, and stores the result in self.img.

post_process()

Removes padding added during preprocessing and returns the final output.

output_tensor = upsampler.post_process()

Returns

output · torch.Tensor

Processed output tensor with padding removed.

Usage Examples

Basic Upsampling

import cv2
from basicsr.archs.rrdbnet_arch import RRDBNet
from realesrgan import RealESRGANer

# Define the model
model = RRDBNet(
    num_in_ch=3,
    num_out_ch=3,
    num_feat=64,
    num_block=23,
    num_grow_ch=32,
    scale=4
)

# Initialize upsampler
upsampler = RealESRGANer(
    scale=4,
    model_path='weights/RealESRGAN_x4plus.pth',
    model=model,
    tile=0,
    tile_pad=10,
    pre_pad=0,
    half=False
)

# Read and upscale image
img = cv2.imread('input.jpg', cv2.IMREAD_UNCHANGED)
output, _ = upsampler.enhance(img, outscale=4)

# Save result
cv2.imwrite('output.png', output)

Tiled Inference for Large Images

# For large images, use tiling to avoid GPU memory issues
upsampler = RealESRGANer(
    scale=4,
    model_path='weights/RealESRGAN_x4plus.pth',
    model=model,
    tile=512,        # Process in 512×512 tiles
    tile_pad=10,
    pre_pad=0,
    half=True        # Use FP16 for faster inference
)

output, _ = upsampler.enhance(img, outscale=4)

Deep Network Interpolation (DNI)

# Blend two models for custom denoise strength
upsampler = RealESRGANer(
    scale=4,
    model_path=[
        'weights/realesr-general-x4v3.pth',
        'weights/realesr-general-wdn-x4v3.pth'
    ],
    dni_weight=[0.5, 0.5],  # 50% each model
    model=model,
    tile=0,
    tile_pad=10,
    pre_pad=0,
    half=False
)

output, _ = upsampler.enhance(img)

RGBA Image with Alpha Channel

# Read RGBA image with transparency
img = cv2.imread('input.png', cv2.IMREAD_UNCHANGED)

# Upscale with Real-ESRGAN for alpha channel
output, img_mode = upsampler.enhance(
    img,
    outscale=4,
    alpha_upsampler='realesrgan'
)

print(f"Image mode: {img_mode}")  # 'RGBA'
cv2.imwrite('output.png', output)

Source Reference

Implemented in realesrgan/utils.py:14