BasicSR: Image and Video Super-Resolution Toolbox

Common errors

• ModuleNotFoundError: No module named 'torch'

  cause PyTorch (and often torchvision) is not installed, or is not accessible in the current Python environment, or installed incorrectly for your CUDA version.
  fix Install PyTorch and Torchvision following official instructions, ensuring compatibility with your system's CUDA (if applicable). Example for CUDA 11.8: `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`.

• yaml.scanner.ScannerError: while scanning a simple key

  cause Your YAML configuration file (e.g., options/train.yml) has an indentation error, a missing colon, or another syntax mistake.
  fix Carefully review the specified YAML file for syntax errors, especially indentation and proper key-value pair formatting. Use a YAML linter if available.

• KeyError: 'name' (or similar for other config parameters)

  cause A required key is missing from your YAML configuration file, or the path to the YAML file is incorrect, leading to an empty or malformed dictionary being loaded.
  fix Verify that your YAML configuration file is correctly structured and contains all necessary keys for the operation (e.g., `name`, `network_g`, `path`). Double-check the file path provided to the `basicsr` script or function.

• RuntimeError: CUDA error: device-side assert triggered

  cause This often indicates an issue with input data (e.g., incorrect dimensions, data type, or value range) being passed to a model running on GPU, or a GPU memory issue.
  fix Ensure your input images (or tensors) match the expected format (e.g., HWC, BGR, uint8 for `cv2` operations or NCHW, float32, [0,1] or [-1,1] for PyTorch models). Check for sufficient GPU memory, especially with large models or batch sizes.

Warnings

• breaking As of v1.4.0, BasicSR officially moved under the 'XPixelGroup' organization. While direct breaking changes for user code might be minimal, internal paths or configuration assumptions could be affected for those updating from much older versions or directly referencing internal modules.
  Fix: Review your code for any hardcoded paths or imports that might implicitly assume the old repository structure. Update to the latest version and verify functionality. Re-download any pre-trained models if paths change.
• gotcha Older BasicSR versions (prior to v1.4.2) could encounter `ModuleNotFoundError` for `torch` if it wasn't pre-installed. This was due to `torch` not always being in `setup_requires`, leading to a race condition or failed imports during initial setup.
  Fix: Always ensure `torch` and `torchvision` are installed correctly for your specific CUDA version *before* installing `basicsr`. Use PyTorch's official installation instructions, e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118`.
• gotcha BasicSR heavily relies on YAML configuration files for training and testing. Incorrect file paths, malformed YAML syntax, or missing required parameters are common sources of errors.
  Fix: Carefully review your `.yml` configuration files for correct syntax, valid paths, and all necessary parameters as outlined in the official examples. Use the `force_yml` option (available since v1.3.4.2) for command-line overrides if needed.
• gotcha A bug in `bgr2ycbcr` color conversion was fixed in v1.4.1. If you were using BasicSR's internal color conversion utilities in older versions for custom pipelines, your results might have been subtly incorrect.
  Fix: Upgrade to v1.4.1 or later. If using older versions and custom color conversion, consider manually implementing or verifying conversion logic with external libraries like `OpenCV` or `scikit-image`.
• gotcha Specific features like the official `torchvision.ops.deform_conv2d` require `torchvision>=0.9.0`. Using older `torchvision` versions might lead to compatibility issues or `AttributeError` for these advanced operators.
  Fix: Ensure your `torchvision` installation meets the minimum version requirement for the specific features you intend to use. Always follow the recommended PyTorch/Torchvision installation for your environment.

Install

• pip install basicsr Stable Release
• pip install --upgrade basicsr Upgrade
• pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 pip install basicsr With PyTorch CUDA (example for CUDA 11.8)

Imports

• RealESRGANer

  from basicsr.utils.realesrgan_utils import RealESRGANer

  A utility class that simplifies loading and running Real-ESRGAN models.
• RRDBNet

  from basicsr.archs.rrdbnet_arch import RRDBNet

  One of the common deep learning architectures used in super-resolution, e.g., by ESRGAN.
• img2tensor

  from basicsr.utils.img_util import img2tensor, tensor2img

  Utilities for converting images between NumPy arrays and PyTorch tensors.
• load_file_from_url

  from basicsr.utils.download_util import load_file_from_url

  Helper to download model checkpoints from URLs.

Quickstart

This quickstart demonstrates how to programmatically perform super-resolution inference using a pre-trained Real-ESRGAN model. It covers creating a dummy input image, downloading the necessary model weights, initializing the `RealESRGANer` utility, and processing the image to save the super-resolved output. The example uses a common `RealESRGAN_x4plus` model from a public URL.

import os
import cv2
import torch
import numpy as np
from basicsr.archs.rrdbnet_arch import RRDBNet
from basicsr.utils.realesrgan_utils import RealESRGANer
from basicsr.utils.download_util import load_file_from_url

# 1. Create a dummy low-resolution image (e.g., 64x64, 3 channels)
# In a real application, this would be loaded from a file (e.g., cv2.imread)
dummy_lr_img = np.random.randint(0, 256, (64, 64, 3), dtype=np.uint8)

# 2. Define model parameters and download URL for a pre-trained Real-ESRGAN model
model_scale = 4
model_path_url = "https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth"
output_filename = "dummy_sr_image.png"

# 3. Download the model weights
try:
    # Model weights will be saved to a 'weights' directory by default
    model_path = load_file_from_url(url=model_path_url, model_dir='weights', progress=True)
except Exception as e:
    print(f"Could not download model from {model_path_url}: {e}")
    model_path = None # Set to None if download fails

if model_path:
    # 4. Initialize the RealESRGANer for inference
    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')

    upsampler = RealESRGANer(
        scale=model_scale,
        model_path=model_path,
        dni_weight=None, # Not used for standard RealESRGAN_x4plus
        model_arch=RRDBNet,
        tile=0, # Process image without tiling for small inputs
        tile_pad=10,
        pre_pad=0,
        half=False, # Use float32, set to True for float16 inference if supported
        device=device
    )

    # 5. Perform inference (enhance expects a NumPy array (HWC, BGR, uint8))
    output_image, _ = upsampler.enhance(dummy_lr_img, outscale=model_scale)

    # 6. Save the output image
    cv2.imwrite(output_filename, output_image)
    print(f"Super-resolved image saved to {output_filename}")
else:
    print("Skipping quickstart inference due to model download failure or missing model path.")

# Clean up downloaded weights directory if desired (optional)
# import shutil
# if os.path.exists('weights'):
#     shutil.rmtree('weights')