MeutrinoV/image-upscaler-real-esrgan

Image-Upscaler-Real-ESRGAN

A web app that upscales any image to ultra-high resolution using Real-ESRGAN super-resolution. Edges stay sharp, detail is reconstructed, and text on labels stays legible (and gets sharper) instead of turning to mush.

Drag in an image, pick a model and scale, and get a crisp result with a side-by-side before/after slider and one-click PNG download.

Features

• —Real Real-ESRGAN — official pretrained weights run through a clean, dependency-light PyTorch implementation of the RRDBNet / SRVGGNet generators (no basicsr, so no torchvision.functional_tensor breakage).
• —Multiple models for different content: | Model | Best for | Native scale | |-------|----------|--------------| | realesrgan-x4plus (default) | Photos, documents, text & labels | 4× | | realesrgan-x2plus | General, lighter upscale | 2× | | realesr-general-x4v3 | Noisy / compressed real-world images | 4× | | realesrgan-x4plus-anime | Illustrations & line art | 4× |
• —Up to 8× output scale — the network runs at its native factor, then the result is resampled to the exact requested size.
• —Tiled inference so large images don't blow up memory; works on CPU.
• —Alpha channel preserved — logos and labels with transparency stay clean.
• —Live green-terminal progress — a CRT-style activity log streams real milestones over Server-Sent Events (weight download %, per-tile reconstruction, encoding) with an animated progress bar.
• —Before/after comparison slider, drag-and-drop upload, live metadata (input/output size, model, processing time), and a one-tap PNG download.
• —Tasteful site animations that pause during inference so they never steal CPU from upscaling (and respect prefers-reduced-motion).
• —Runs fully locally — uploaded images never leave your machine.

Deploy to Hugging Face Spaces

This repo is ready to run as a Docker Space. With an HF Pro account you get persistent storage (so model weights are cached across restarts), faster builds, and the option to upgrade the Space's CPU.

1. 1.Create a new Space at https://huggingface.co/new-space — pick Docker as the SDK (any template; the Dockerfile here overrides it).
2. 2.Push this repo to the Space:

   git remote add space https://huggingface.co/spaces/<your-username>/<space-name>
   git push space HEAD:main

(or link the GitHub repo directly via the Space's "Settings → Repository" page to auto-sync on push.)

1. 1.Enable persistent storage in Settings → Variables and secrets: the app auto-detects /data and caches weights there. No env var needed; it falls back to the container's local dir if /data isn't mounted.
2. 2.(Optional) Upgrade the Space CPU under Settings → Hardware — even the "CPU upgrade" tier (8 vCPU / 32 GB RAM) is plenty fast for Real-ESRGAN.

The Space card metadata (title, emoji, sdk: docker, app_port: 7860, etc.) lives in this README's YAML front-matter — HF reads it automatically.

Quick start (local)

./run.sh

This creates a virtualenv, installs dependencies, and starts the server at http://localhost:8000. Open it in a browser and upscale away.

The first upscale for a given model downloads its weights (~5–65 MB) from the official Real-ESRGAN GitHub releases into weights/. Subsequent runs are instant to start.

Manual setup

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn backend.app:app --host 0.0.0.0 --port 8000

Configuration (env vars)

API

POST /api/upscale — multipart form:

Returns image/png. Response headers include X-Elapsed-Seconds, X-Input-Size, X-Output-Size, and X-Model.

curl -F "file=@photo.jpg" -F "model=realesrgan-x4plus" -F "outscale=4" \
  http://localhost:8000/api/upscale -o upscaled.png

Live-progress API (used by the UI)

For streaming progress, create a job and subscribe to its event stream:

• —POST /api/jobs — same form fields as /api/upscale; returns { "job_id" }.
• —GET /api/jobs/{job_id}/events — Server-Sent Events with JSON payloads { type: log|progress|done|error, message, percent, t, ... }.
• —GET /api/jobs/{job_id}/result — fetch the finished PNG (one-shot; the job is freed afterwards).

Other endpoints: GET /api/models, GET /api/health.

Performance notes

Inference runs on GPU automatically when CUDA is available, otherwise on CPU. On CPU, time scales with input pixels × native model scale — a ~0.1 MP image takes a couple of seconds at 4×; larger images take proportionally longer. The default 32 MP input cap comfortably covers full-resolution phone/DSLR photos; raise MAX_INPUT_PIXELS to go further. Lower the tile size to cut memory use on big images; set DEVICE=cuda for a large speedup on a GPU.

Project layout

backend/
  app.py            FastAPI server + endpoints, serves the frontend
  upscaler.py       model loading, tiled inference, alpha handling
  weights.py        model registry + on-demand weight download
  models/
    rrdbnet.py      RRDBNet generator (x4plus / x2plus / anime)
    srvgg.py        SRVGGNetCompact generator (general-x4v3)
frontend/
  index.html        UI
  style.css         styling
  app.js            upload, request, before/after slider
run.sh              one-command launcher

Credits

Models and method by Xintao Wang et al., Real-ESRGAN (BSD-3-Clause). This project reimplements the generator networks for clean weight loading and wraps them in a web UI.