> This is the documentation for LibreYOLO 1.5.0. Current version: https://www.libreyolo.com/docs/models/real-esrgan

# Real-ESRGAN
A practical blind super-resolution upscaler trained on synthetic degradations rather than only bicubic downscaling. LibreYOLO ships inference and validation for its 4x, 2x and fast 4x checkpoints.
Tasks: restore. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

Real-ESRGAN needs no optional extra. Everything it imports is in the base
install.

```bash
pip install libreyolo
```

## Predict

Weights download from Hugging Face on first use and are cached locally.

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreRealESRGANx4-restore.pt")
result = model(SAMPLE_IMAGE, save=True)

restored = result.restored
print(restored.array.shape, restored.array.dtype)
```

**CLI**

```bash
libreyolo predict model=LibreRealESRGANx4-restore.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True
```

**Tiled, for large images**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreRealESRGANx4-restore.pt")

# tile splits the forward pass into overlapping tiles and blends the
# seams back together; tile_pad is the halo added around each tile
# before it is cropped back out. Both are Python-only keyword
# arguments, not CLI flags.
result = model("large-photo.jpg", tile=512, tile_pad=10, save=True)
```

A restore result carries no boxes; `result.restored` is a dense `(H, W, 3)`
uint8 RGB image, on a canvas `Results.restore_scale` times the input in each
dimension. `save=True` writes that image directly rather than an annotated
plot. Input is converted to RGB and any alpha channel is dropped. A source
larger than memory allows can be split with `tile` and `tile_pad`, which blend
the tile seams back together in the output. See [prediction](/docs/v1.5.0/predict)
for sources, streaming and result handling.

## Variants

Three checkpoints, named for their upscale factor. `x4` is RRDBNet
(`RealESRGAN_x4plus`), 23 residual-in-residual dense blocks, the quality
default at 4x. `x2` is the same RRDBNet architecture at 2x. `x4t` is
SRVGGNetCompact (`realesr-general-x4v3`), a smaller, faster generator built for
video and lower-latency use at 4x. The upstream general-purpose model also
ships a paired denoise-strength network blended in at inference time; that
strength knob is not part of this port, which runs the base `x4t` generator.

## Validate

`val()` measures PSNR and SSIM between the restored output and a clean target
image, both computed in RGB on the original canvas with no border crop and no
resizing. SSIM uses an 11x11 Gaussian window with sigma 1.5, averaged over the
three color channels.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreRealESRGANx4-restore.pt")
metrics = model.val(data="my-restore-dataset.yaml")

print(metrics["metrics/PSNR"])
print(metrics["metrics/SSIM"])
```

**CLI**

```bash
libreyolo val model=LibreRealESRGANx4-restore.pt data=my-restore-dataset.yaml
```

The dataset argument is a YAML pairing a directory of degraded input images
with a directory of clean target images of matching resolution; see
[dataset formats](/docs/v1.5.0/reference/dataset-formats) for the exact keys.

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| restore | yes | yes | yes | yes | yes |  |  |  | yes | yes |  | yes |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

An exported artifact loads back through `LibreYOLO()` on its file suffix, so a
`.onnx` or `.engine` file behaves like a checkpoint and returns the same
`Results`. [Export](/docs/v1.5.0/export) lists the arguments every format accepts and
the extras a few of them add.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreRealESRGANx4-restore.pt")

# imgsz defaults to a small internal patch size when omitted, not
# your working resolution, so pass the size your deployment actually
# feeds the model.
model.export(format="onnx", imgsz=512)
model.export(format="tensorrt", imgsz=512, half=True)
```

**CLI**

```bash
libreyolo export model=LibreRealESRGANx4-restore.pt format=onnx imgsz=512
```

**Use the exported file**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# The factory routes on the file suffix, so an exported artifact loads
# like any checkpoint and returns the same Results object.
model = LibreYOLO("LibreRealESRGANx4-restore.onnx")
result = model(SAMPLE_IMAGE)

print(result.restored.array.shape)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreRealESRGANx4t-restore.pt` |  | restore | bsd-3-clause |
| `LibreRealESRGANx4-restore.pt` |  | restore | bsd-3-clause |
| `LibreRealESRGANx2-restore.pt` |  | restore | bsd-3-clause |

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: Real-ESRGAN, Tencent ARC Lab and Shenzhen Institutes of Advanced Technology, Chinese Academy of Sciences
- Upstream license: BSD-3-Clause
- Upstream source: https://github.com/xinntao/Real-ESRGAN
- LibreYOLO code: Apache-2.0 and BSD-3-Clause
- Weights: BSD-3-Clause, republished at https://huggingface.co/LibreYOLO
- Interpretation: BSD-3-Clause is a permissive license, so these weights can be used in commercial and closed-source products. It asks you to keep the copyright notice, the condition list and the disclaimer with any copy you redistribute, in source or compiled form, and its third clause forbids using the names of Xintao Wang or the project's contributors to endorse or promote a derived product without separate written permission. It carries no patent grant, unlike Apache-2.0. LibreYOLO's checkpoints are format conversions of the official pretrained generators, with the learned parameters unchanged; Real-ESRGAN's training is a GAN over a synthetic degradation pipeline that is not wired into this library, so there is no LibreYOLO-trained variant to license separately.

## Citation

```bibtex
@InProceedings{wang2021realesrgan,
    author    = {Xintao Wang and Liangbin Xie and Chao Dong and Ying Shan},
    title     = {Real-ESRGAN: Training Real-World Blind Super-Resolution with Pure Synthetic Data},
    booktitle = {International Conference on Computer Vision Workshops (ICCVW)},
    date      = {2021}
}
```

Copied from https://github.com/xinntao/Real-ESRGAN#bibtex


## Real-ESRGAN architecture

- x4: [SVG](/diagrams/models/real-esrgan/x4-restore.svg), [interactive diagram](/diagrams/models/real-esrgan/x4-restore.html)
- x2: [SVG](/diagrams/models/real-esrgan/x2-restore.svg), [interactive diagram](/diagrams/models/real-esrgan/x2-restore.html)
- x4t (SRVGG): [SVG](/diagrams/models/real-esrgan/x4t-restore.svg), [interactive diagram](/diagrams/models/real-esrgan/x4t-restore.html)
- RRDBNet shared topology: [SVG](/diagrams/models/real-esrgan/rrdb-family.svg), [interactive diagram](/diagrams/models/real-esrgan/rrdb-family.html)