File size: 4,762 Bytes
a34a6d1
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
---
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.