Super-Resolution

Upscale and restore images from the command line with Real-ESRGAN, with optional GFPGAN face enhancement.

This repository provides superimage.py, an inference CLI built on Real-ESRGAN. The Real-ESRGAN package (v0.3.0) is vendored directly in the repo under realesrgan/, so only its dependencies need to be installed. The tool upscales a single image or a whole folder using one of six pretrained models, and can additionally restore faces with GFPGAN.

Features

• Upscale a single image or every file in a folder in one run (defaults: inputs/ → results/)
• Six selectable models: RealESRGAN_x4plus (default), RealESRNet_x4plus, RealESRGAN_x4plus_anime_6B, RealESRGAN_x2plus, realesr-animevideov3, realesr-general-x4v3
• Adjustable final upscale factor (-s, default 4)
• Denoise strength control for realesr-general-x4v3 (-dn), implemented by blending the normal and weak-denoise (wdn) weights via deep network interpolation
• Optional face enhancement with GFPGAN (--face_enhance), with the Real-ESRGAN upsampler used for the background
• Tiled inference for large images or limited GPU memory (-t, --tile_pad, --pre_pad)
• RGBA input support with a selectable alpha-channel upsampler (--alpha_upsampler realesrgan|bicubic); RGBA results are always saved as PNG
• Output naming control: output folder (-o), base file name (-f), suffix (--suffix, default out), extension (--ext auto|jpg|png)
• Runs on GPU when CUDA is available (device selectable with -g), otherwise on CPU

Requirements

• Python 3 (the repository was built with Python 3.10, per the committed bytecode)
• There is no requirements.txt; the dependencies below are derived from the actual imports:

pip install torch torchvision basicsr gfpgan opencv-python numpy

The realesrgan package itself does not need to be installed — version 0.3.0 is vendored in this repository under realesrgan/.

Installation

git clone https://github.com/mkamranr/Super-Resolution.git
cd Super-Resolution
pip install torch torchvision basicsr gfpgan opencv-python numpy

Download the models/weights

1. Real-ESRGAN / GFPGAN model weights — download from: https://drive.google.com/drive/folders/1tR_sweWBIupos-oKmrmsFerOtGgn_26f?usp=sharing and place them under the weights/ folder. The script loads weights/<model_name>.pth (unless you pass --model_path). The repo already includes RealESRGAN_x4plus_anime_6B.pth, realesr-animevideov3.pth, realesr-general-x4v3.pth and realesr-general-wdn-x4v3.pth; the download additionally provides RealESRGAN_x4plus.pth (the default model), RealESRGAN_x2plus.pth, RealESRNet_x4plus.pth and GFPGAN.pth (used with --face_enhance).

2. GFPGAN auxiliary weights (face detection and parsing models, needed for --face_enhance) — download from: https://drive.google.com/drive/folders/1ZYA9K2IUKwyMPQ0sqw8AJJS40Whl8tf0?usp=sharing and place them (detection_Resnet50_Final.pth, parsing_parsenet.pth) under the gfpgan/weights/ folder. Note: the original instructions said "gfpgan/weighs" — that is a typo; the correct folder is gfpgan/weights/, which is the directory present in this repo and the path the GFPGAN library resolves relative to the working directory.

Usage

Run from the repository root (weight paths are relative).

# Upscale every image in ./inputs to ./results (RealESRGAN_x4plus, 4x)
python superimage.py

# Upscale a single image -> results/photo_out.jpg
python superimage.py -i photo.jpg

# Anime-optimized model
python superimage.py -i inputs -n RealESRGAN_x4plus_anime_6B

# General model with adjustable denoising (0 = keep noise, 1 = strong denoise)
python superimage.py -i inputs -n realesr-general-x4v3 -dn 0.7

# Upscale + restore faces with GFPGAN
python superimage.py -i portrait.jpg --face_enhance --gfpgan_model_path weights/GFPGAN.pth

# Tiled inference for large images / limited GPU memory
python superimage.py -i large.png -t 400

Options

Option	Default	Description
-i, --input	inputs	Input image file or folder
-n, --model_name	RealESRGAN_x4plus	One of: RealESRGAN_x4plus, RealESRNet_x4plus, RealESRGAN_x4plus_anime_6B, RealESRGAN_x2plus, realesr-animevideov3, realesr-general-x4v3
-o, --output	results	Output folder
-f, --output_file_name	none	Output base name (any extension in it is ignored; suffix/extension rules still apply)
-dn, --denoise_strength	0.5	Denoise strength 0–1; only used by realesr-general-x4v3
-s, --outscale	4	Final upsampling scale of the image
--model_path	none	Explicit path to model weights (overrides weights/<model_name>.pth)
--gfpgan_model_path	none	Path to the GFPGAN model; required with --face_enhance
--suffix	out	Suffix of the restored image; pass --suffix '' for none
-t, --tile	0	Tile size; 0 disables tiling
--tile_pad	10	Tile padding
--pre_pad	0	Pre-padding size at each border
--face_enhance	off	Use GFPGAN to enhance faces
--fp32	(forced on)	The script forces fp32 internally — see Notes
--alpha_upsampler	realesrgan	Alpha-channel upsampler: realesrgan or bicubic
--ext	auto	Output extension: auto (same as input), jpg, png
-g, --gpu-id	none	GPU device id (e.g. 0, 1)

Outputs are written as <output>/<name>_<suffix>.<ext> (e.g. results/photo_out.jpg); with --suffix '' the suffix is dropped, and RGBA inputs are always saved as .png.

How it works

superimage.py builds the network matching the chosen model name — an RRDBNet for the RealESRGAN_x4plus / RealESRNet_x4plus / anime_6B / x2plus variants, or the compact SRVGGNetCompact for realesr-animevideov3 and realesr-general-x4v3 — and loads its weights from weights/<model_name>.pth. The network is wrapped in RealESRGANer (from the vendored package), which handles pre-padding, optional tile-by-tile processing, alpha-channel upsampling and the final rescale to --outscale, running on CUDA when available and on CPU otherwise. For realesr-general-x4v3 with a denoise strength below 1, the normal and wdn weights are interpolated (DNI) according to -dn. With --face_enhance, GFPGAN detects and restores faces (using the detection/parsing models in gfpgan/weights/) and pastes them back onto the Real-ESRGAN-upscaled background. Each result is written to the output folder; per-image runtime errors are printed and the image is skipped.

Project structure

superimage.py         # CLI entry point (inference)
realesrgan/           # Vendored Real-ESRGAN v0.3.0 package
├── utils.py          #   RealESRGANer: pre-pad, tiling, DNI, alpha handling, resize
├── archs/            #   SRVGGNetCompact + U-Net discriminator architectures
├── data/, models/    #   Upstream dataset/model definitions (registry only; not used at inference)
└── train.py          #   Upstream training pipeline (no training configs in this repo)
weights/              # Model weights: 4 included, the rest via the download link
gfpgan/weights/       # Target folder for GFPGAN's face detection/parsing models
LICENSE               # GPL-3.0

Notes / Limitations

• Half precision is effectively disabled: the script sets args.fp32 = True unconditionally, so inference always runs in fp32 and the --fp32 flag is a no-op.
• --face_enhance requires --gfpgan_model_path (it defaults to None, which GFPGANer cannot handle). Use the GFPGAN.pth from the weights download, e.g. --gfpgan_model_path weights/GFPGAN.pth.
• Weights are not auto-downloaded; if weights/<model_name>.pth is missing, loading fails.
• realesr-general-x4v3 with -dn other than 1 needs both realesr-general-x4v3.pth and realesr-general-wdn-x4v3.pth (both included in the repo).
• When the input is a folder, every file in it is processed — non-image files will cause errors.
• If you hit CUDA out-of-memory on large images, set a smaller --tile value.

License

This project is licensed under the GNU General Public License v3.0 — see LICENSE.