Image-Enhancer / README.md
Ribakoo's picture
Initial commit: VectorForge 2D enhancement engine
a34a6d1
|
Raw History Blame Contribute Delete
4.76 kB
---
title: Image Enhancer
emoji: ⚡
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: 6.32.0
python_version: '3.12'
app_file: app.py
pinned: false
license: mit
---
# VectorForge ⚡
> **High-Performance 2D Character Super-Resolution & Vectorization Engine**
> Converts low-resolution raster character art, logos, and stickers into crisp 4× PNGs and infinitely-scalable mathematical SVG vectors — completely free and offline-capable.
[![FastAPI](https://img.shields.io/badge/API-FastAPI-009688?style=flat-square&logo=fastapi)](https://fastapi.tiangolo.com)
[![ONNX Runtime](https://img.shields.io/badge/Inference-ONNX_Runtime-005CED?style=flat-square)](https://onnxruntime.ai)
[![Rust VTracer](https://img.shields.io/badge/Vector_Engine-VTracer_Rust-DEA584?style=flat-square&logo=rust)](https://github.com/visioncortex/vtracer)
[![License](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
---
## ✨ Features
- **Hybrid 2D Pipeline**: Neural super-resolution cleans JPEG noise and reconstructs sharp boundary edges before passing clean contours to the vectorizer.
- **Dual Output**: Export both **4× Crisp Raster (PNG)** and **Infinite-Resolution Vector (SVG)** simultaneously.
- **Transparent PNG (RGBA) Preservation**: Full alpha channel support for character sprites, stickers, and cutouts.
- **Interactive Split Slider UI**: Compare original vs. enhanced results side-by-side with a real-time drag handle.
- **100% Free Hosting**: Ready for 1-click deployment to **Hugging Face Spaces (Free 16GB RAM / 2 vCPU)** with zero server costs.
- **Remote Access via Quick Tunnel**: Built-in Cloudflare tunnel helper lets you use your local machine as the server and access it from your smartphone or laptop anywhere.
---
## 🏗️ Architecture
```mermaid
flowchart TD
A["Input Image (PNG / JPG / WebP)"] --> B{"Enhancement Mode"}
B -->|"AI Upscale"| C["Waifu2x CUNet (ONNX Runtime)<br/>Edge Reconstruction & Denoising"]
B -->|"Direct Vectorize"| D["VTracer Engine (Rust Core)<br/>Mathematical Spline Fitting"]
B -->|"Hybrid (Recommended)"| C
C -->|"Cleaned 4x Raster"| E["Crisp 4x PNG Export"]
C -->|"Cleaned Input"| D
D --> F["Scalable SVG Vector Export"]
```
---
## 🚀 Quick Start (Local)
### 1. Clone & Install Dependencies
```bash
git clone https://github.com/your-username/vectorforge.git
cd vectorforge
pip install -r requirements.txt
```
### 2. Start the Server
```bash
python run_server.py
```
Open your browser to:
- **Web UI:** [http://localhost:7860](http://localhost:7860)
- **Interactive API Docs:** [http://localhost:7860/docs](http://localhost:7860/docs)
---
## 🌐 Remote Access From Anywhere (100% Free)
If you run the app on your home PC or laptop and want to use it on your phone while away:
```bash
python tunnel_helper.py
```
This will automatically create a secure HTTPS URL (e.g. `https://random-word.trycloudflare.com`) that routes to your local VectorForge server without opening router ports or paying for hosting.
---
## ☁️ 1-Click Free Cloud Deployment (Hugging Face Spaces)
You can host VectorForge 24/7 for free on Hugging Face Spaces:
1. Create a free account on [Hugging Face](https://huggingface.co).
2. Click **New Space** $\rightarrow$ Choose **Docker** SDK $\rightarrow$ Choose **Blank / Docker**.
3. Push this repository to your Space:
```bash
git remote add space https://huggingface.co/spaces/<your-username>/<your-space-name>
git push space main
```
4. Hugging Face builds the Docker container and provides a permanent public HTTPS URL with **16GB RAM** at **$0 cost**.
---
## 📡 REST API Reference
### `POST /api/process`
Upload an image and run enhancement.
**Form Data:**
- `file`: Image file (PNG, JPG, WebP)
- `mode`: `"hybrid"` | `"ai_upscale"` | `"vectorize"` (default: `"hybrid"`)
- `preset`: `"character"` | `"flat_icon"` | `"detailed_lineart"` | `"monochrome"`
- `scale`: `2` or `4` (default: `4`)
- `denoise`: `true` | `false`
**Example Response:**
```json
{
"job_id": "4998b1c988e7",
"mode": "hybrid",
"original_size": [128, 128],
"enhanced_size": [512, 512],
"original_filesize": 1151,
"enhanced_png_filesize": 104980,
"svg_filesize": 147452,
"elapsed_seconds": 0.83,
"png_url": "/api/download/4998b1c988e7/png",
"svg_url": "/api/download/4998b1c988e7/svg"
}
```
### `GET /api/download/{job_id}/{format}`
Download generated outputs (`format` = `png` or `svg`).
---
## ⚡ Benchmarks
*Tested on Intel Core i7 CPU (No GPU required):*
- **128×128 Icon (Hybrid 4× + SVG):** ~0.8s
- **256×256 Sprite (Hybrid 4× + SVG):** ~1.9s
- **512×512 Character (AI 2× Upscale):** ~2.3s
---
## 📄 License
MIT License. See [LICENSE](LICENSE) for details.