Upscale Studio

Upscale Studio is a Windows desktop application for batch image upscaling. It provides a PySide6 GUI and uses the upstream nunif/waifu2x PyTorch backend for the actual ML processing.

Features

• Batch queue for images and folders with drag and drop.
• Preview panel with selected image details.
• Output settings for scale, denoise level, model style, and image format.
• CPU and CUDA device selection.
• Tile size, batch size, and TTA controls.
• Dark and light themes.
• English, Russian, and Ukrainian UI.
• Portable PyInstaller build with bundled resources and backend folders.
• Generated Windows application icon from resources/icons/UpscaleStudio.png.

System Requirements

• Windows 10 or Windows 11, 64-bit.
• Python 3.10, 3.11, or 3.12. Python 3.12 is recommended.
• Git for Windows.
• Internet connection for first setup.
• CPU mode works without an NVIDIA GPU.
• CUDA mode requires a supported NVIDIA GPU, driver, and PyTorch CUDA wheels.

Quick Start

git clone <repo-url>
cd UpscaleStudio
scripts\build_all_windows.bat

The finished application will be created at:

dist\UpscaleStudio\UpscaleStudio.exe

For CUDA setup:

scripts\build_all_windows.bat -Cuda

If Python is not installed and winget is available:

scripts\build_all_windows.bat -InstallPython

Setup

Run setup once before development or manual builds:

scripts\setup_windows.bat

Setup creates the GUI virtual environment, prepares the backend virtual environment, clones or updates vendor/nunif, installs dependencies, downloads waifu2x models unless -SkipModels is passed, and verifies that waifu2x.cli can be imported.

Useful setup options:

scripts\setup_windows.bat -Cuda
scripts\setup_windows.bat -SkipModels
scripts\setup_windows.bat -InstallPython
scripts\setup_windows.bat -PythonCommand C:\Path\To\python.exe

Development Run

scripts\run_dev.bat

or directly:

.venv\Scripts\python.exe -m app

Build

scripts\build_windows.bat

The build script regenerates the app icon, runs PyInstaller, bundles resources, copies the backend when it exists, and verifies that dist/UpscaleStudio/UpscaleStudio.exe was created.

Windows .ico files use 256x256 as the practical maximum icon entry size. The project also generates a separate 512x512 PNG for high-resolution use.

Clean

Remove generated files:

scripts\clean.bat

Remove generated files plus local virtual environments and the downloaded backend:

scripts\clean.bat -All

The default clean command removes build, dist, release, output, tmp, .cache, Python bytecode, and local logs. It keeps source files, resources, scripts, and vendor/nunif.

CUDA and GPU

Run setup with CUDA support:

scripts\setup_windows.bat -Cuda

Then choose CUDA in the app Device field. CPU mode passes --gpu -1 to waifu2x. CUDA mode passes --gpu 0.

If CUDA does not work, confirm that the NVIDIA driver is installed and check PyTorch:

.venv-backend\Scripts\python.exe -c "import torch; print(torch.cuda.is_available())"

Backend

Upscale Studio intentionally keeps nunif/waifu2x as a backend instead of porting the ML code to C++. This preserves compatibility with upstream models and command-line behavior.

Backend lookup order:

1. WAIFU2X_BACKEND_PYTHON and WAIFU2X_NUNIF_DIR environment variables.
2. .venv-backend and vendor/nunif during development.
3. backend/venv and backend/nunif inside the portable build folder.

Update the backend:

git -C vendor\nunif pull --ff-only
scripts\setup_windows.bat
scripts\build_windows.bat

Upstream backend:

https://github.com/nagadomi/nunif/tree/master/waifu2x

Project Structure

app/                  PySide6 application code
app/backend/          nunif/waifu2x process integration
app/gui/              GUI, themes, and translations
assets/screenshots/   GitHub README screenshots
resources/icons/      App icons and generated ICO/PNG assets
scripts/              Setup, build, run, clean, and icon scripts
vendor/nunif/         Local backend checkout created by setup
build/                Generated PyInstaller work files
dist/                 Generated portable application
output/               User output images

Generated folders are ignored by Git and should not be committed.

Troubleshooting

Python is not found:

scripts\setup_windows.bat -InstallPython

Git is not found:

• Install Git for Windows from https://git-scm.com/download/win.
• Restart the terminal and run setup again.

Backend is not ready:

• Run scripts\setup_windows.bat.
• Check that .venv-backend/Scripts/python.exe exists.
• Check that vendor/nunif/waifu2x/cli.py exists.
• Use the Refresh button in the app.

Build fails:

• Run scripts\clean.bat.
• Run scripts\setup_windows.bat.
• Run scripts\build_windows.bat.

Known Limitations

• The progress bar tracks completed queue items. Detailed backend progress is shown in the processing log.
• 16-bit output is not exposed in the GUI because upstream requires the wand image library.
• Video processing options from nunif are not exposed.
• The public repository should not include virtual environments, generated builds, user images, downloaded models, or local logs.

License and Credits

Upscale Studio is released under the MIT License. See LICENSE.

The image upscaling backend is based on nunif/waifu2x by nagadomi:

https://github.com/nagadomi/nunif/tree/master/waifu2x