upscalex 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- upscalex/__init__.py +11 -0
- upscalex/cli.py +296 -0
- upscalex/engine.py +697 -0
- upscalex/server.py +241 -0
- upscalex/utils.py +198 -0
- upscalex-0.1.0.dist-info/METADATA +268 -0
- upscalex-0.1.0.dist-info/RECORD +10 -0
- upscalex-0.1.0.dist-info/WHEEL +4 -0
- upscalex-0.1.0.dist-info/entry_points.txt +3 -0
- upscalex-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: upscalex
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: UpscaleX MCP/CLI: Production-grade 8K/16K image upscaler CLI and Model Context Protocol (MCP) server powered by RealESRGAN, Vulkan GPU acceleration, and Lanczos supersampling.
|
|
5
|
+
Project-URL: Homepage, https://github.com/The-Open-Source-Founder/upscalex
|
|
6
|
+
Project-URL: Documentation, https://github.com/The-Open-Source-Founder/upscalex#readme
|
|
7
|
+
Project-URL: Repository, https://github.com/The-Open-Source-Founder/upscalex.git
|
|
8
|
+
Project-URL: Issues, https://github.com/The-Open-Source-Founder/upscalex/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/The-Open-Source-Founder/upscalex/releases
|
|
10
|
+
Author-email: Arunmozhi Varman <arunmozhi@example.com>
|
|
11
|
+
License: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: 16k,8k,ai,cli,image-processing,mcp,realesrgan,super-resolution,upscale,upscalex,vulkan
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
24
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
25
|
+
Requires-Python: >=3.10
|
|
26
|
+
Requires-Dist: click>=8.1.0
|
|
27
|
+
Requires-Dist: fastmcp>=0.4.0
|
|
28
|
+
Requires-Dist: pillow>=10.0.0
|
|
29
|
+
Requires-Dist: rich>=13.0.0
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
<p align="center">
|
|
35
|
+
<img src="https://raw.githubusercontent.com/The-Open-Source-Founder/upscalex/main/assets/banner.png" alt="UpscaleX Banner" width="100%">
|
|
36
|
+
</p>
|
|
37
|
+
|
|
38
|
+
# UpscaleX MCP/CLI
|
|
39
|
+
|
|
40
|
+
[](LICENSE)
|
|
41
|
+
[](https://www.python.org/downloads/)
|
|
42
|
+
[](https://modelcontextprotocol.io)
|
|
43
|
+
[](https://www.khronos.org/vulkan/)
|
|
44
|
+
|
|
45
|
+
UpscaleX is a production-grade 8K and 16K image upscaler CLI and Model Context Protocol (MCP) server powered by RealESRGAN, Vulkan GPU hardware acceleration, and Lanczos supersampling.
|
|
46
|
+
|
|
47
|
+
Engineered for digital print workflows, large-format poster production, fine art reproductions, and autonomous AI coding agents in Claude Desktop, Antigravity, and Cursor.
|
|
48
|
+
|
|
49
|
+
> Looking for quick setup? Read the [Installation Guide](INSTALLATION.md) for a copy-paste AI Agent setup prompt and manual instructions, or provide your AI coding assistant with the [UpscaleX Agent Skill](SKILLS.md).
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Table of Contents
|
|
54
|
+
|
|
55
|
+
- [Key Features](#key-features)
|
|
56
|
+
- [Installation Guide](INSTALLATION.md)
|
|
57
|
+
- [AI Agent Skill](SKILLS.md)
|
|
58
|
+
- [Visual Quality Comparison](#visual-quality-comparison)
|
|
59
|
+
- [Documentation Directory](#documentation-directory)
|
|
60
|
+
- [Quickstart with uv](#quickstart-with-uv)
|
|
61
|
+
- [Command-Line Interface](#command-line-interface)
|
|
62
|
+
- [Model Context Protocol (MCP) Integration](#model-context-protocol-mcp-integration)
|
|
63
|
+
- [Model Matrix](#model-matrix)
|
|
64
|
+
- [Testing and Verification](#testing-and-verification)
|
|
65
|
+
- [Contributing](#contributing)
|
|
66
|
+
- [License](#license)
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Key Features
|
|
71
|
+
|
|
72
|
+
- **Dual-Mode Operation**: Interactive command-line interface (`upscalex`) and standard Model Context Protocol server (`upscalex-mcp`).
|
|
73
|
+
- **8K and 16K Presets**:
|
|
74
|
+
- **16K**: Native 4x RealESRGAN deep-learning model upscale producing master files up to 400+ Megapixels.
|
|
75
|
+
- **8K**: 4x deep-learning inference followed by Lanczos-3 downsampling (Supersampling Anti-Aliasing / SSAA) for sharp edges and zero noise.
|
|
76
|
+
- **Custom Dimensions**: Proportional scaling to arbitrary resolutions or physical print aspect ratios.
|
|
77
|
+
- **Cross-Platform Architecture**: Tested and supported across **Windows**, **Linux** (Ubuntu, Debian, Fedora), and **macOS** (Apple Silicon arm64 & Intel x86_64).
|
|
78
|
+
- **GPU Acceleration with Seamless CPU Fallback**: Automatically discovers and utilizes discrete Vulkan GPUs (NVIDIA RTX/GeForce, AMD Radeon, Intel Arc/Iris, Apple Silicon via MoltenVK). In headless Docker containers or environments without GPU drivers, the engine falls back to multi-threaded CPU Lanczos super-resolution with zero crashes.
|
|
79
|
+
- **Hardware Diagnostics**: Integrated `upscalex doctor` command inspects system compute devices, Vulkan support, and recommended tile dimensions.
|
|
80
|
+
- **Memory-Safe Tiling**: Sliding-window spatial tile decomposition (`--tile-size 256`) processes ultra-gigapixel images without Out-Of-Memory (OOM) failures on 4GB to 8GB GPUs.
|
|
81
|
+
- **Automated Engine Provisioning**: Downloads and validates the precompiled platform binary automatically if not found locally.
|
|
82
|
+
- **Print Fidelity Analysis**: Automatically calculates physical print dimensions in inches and centimeters at 300 DPI, 150 DPI, and 72 DPI.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Visual Quality Comparison
|
|
87
|
+
|
|
88
|
+
Below is an empirical comparison demonstrating UpscaleX 4x super-resolution reconstruction on a low-resolution pixelated source (`663 × 531` px, 0.35 MP) upscaled to high-definition print fidelity (`2,652 × 2,124` px, 5.63 MP) using the `realesrgan-x4plus` model.
|
|
89
|
+
|
|
90
|
+
<p align="center">
|
|
91
|
+
<img src="https://raw.githubusercontent.com/The-Open-Source-Founder/upscalex/main/assets/comparison.png" alt="UpscaleX Quality Comparison" width="100%">
|
|
92
|
+
</p>
|
|
93
|
+
|
|
94
|
+
| Metric | Original Source | UpscaleX 4x Output |
|
|
95
|
+
| :--- | :--- | :--- |
|
|
96
|
+
| **Pixel Dimensions** | `663 × 531` | **`2,652 × 2,124`** |
|
|
97
|
+
| **Total Megapixels** | 0.35 MP | **5.63 MP** (16× Pixel Multiplication) |
|
|
98
|
+
| **Edge Reconstruction** | Heavy block pixelation, ringing | Reconstructed circular spokes, sharp contours |
|
|
99
|
+
| **Max 300 DPI Print Size** | 2.2 × 1.8 inches | **8.8 × 7.1 inches** |
|
|
100
|
+
| **Model** | — | `realesrgan-x4plus` |
|
|
101
|
+
| **Hardware** | — | NVIDIA GeForce RTX 3050 Laptop GPU (10.8s) |
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Documentation Directory
|
|
106
|
+
|
|
107
|
+
Comprehensive technical guides are available in the [`docs/`](docs/) directory and repository root:
|
|
108
|
+
|
|
109
|
+
- [Installation Guide](INSTALLATION.md): AI Agent autonomous copy-paste prompt and manual installation procedures.
|
|
110
|
+
- [AI Agent Skill Specification](SKILLS.md): Standard agent skill definition for Claude, Cursor, and Antigravity.
|
|
111
|
+
- [CLI Reference Guide](docs/cli-guide.md): Complete flag documentation, tiling strategies, and execution examples.
|
|
112
|
+
- [Model Context Protocol (MCP) Guide](docs/mcp-guide.md): JSON-RPC tool contracts, parameter schemas, and multi-client configuration.
|
|
113
|
+
- [Architecture & Mathematics Specification](docs/architecture.md): Deep-learning foundations, RRDB networks, Lanczos kernels, and memory bounds.
|
|
114
|
+
- [Contributing Guide](CONTRIBUTING.md): Code standards, test procedures, and pull request workflow.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Quickstart
|
|
119
|
+
|
|
120
|
+
### Option 1: Install from PyPI (Simplest for CLI & MCP)
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
pip install upscalex
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Option 2: Clone and Install from Source (with uv)
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
git clone https://github.com/The-Open-Source-Founder/upscalex.git
|
|
130
|
+
cd upscalex
|
|
131
|
+
|
|
132
|
+
# Create virtual environment and install package
|
|
133
|
+
uv venv
|
|
134
|
+
uv pip install -e .
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Inspect Available Models
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
upscalex models
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Command-Line Interface
|
|
146
|
+
|
|
147
|
+
### 16K Upscale (Default 4x Model)
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
upscalex upscale input.png --target 16k
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### 8K Supersampled Upscale
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
upscalex upscale poster.png --target 8k -o poster_8k.png
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### 2D Illustration / Anime Artwork
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
upscalex upscale graphic.png --model realesrgan-x4plus-anime --target 8k
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Image and Print Sizing Inspection
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
upscalex info input.png
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Hardware and Content-Aware Model Recommendation
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
upscalex recommend input.png
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
For complete options and arguments, see the [CLI Guide](docs/cli-guide.md).
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Model Context Protocol (MCP) Integration
|
|
182
|
+
|
|
183
|
+
UpscaleX runs as a native MCP server, enabling LLM agents to inspect image properties, evaluate print viability, and execute upscaling autonomously.
|
|
184
|
+
|
|
185
|
+
### Server Invocation
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
upscalex-mcp
|
|
189
|
+
# or
|
|
190
|
+
upscalex serve
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Client Configuration
|
|
194
|
+
|
|
195
|
+
Add this entry to your MCP client configuration file:
|
|
196
|
+
|
|
197
|
+
```json
|
|
198
|
+
{
|
|
199
|
+
"mcpServers": {
|
|
200
|
+
"upscalex": {
|
|
201
|
+
"command": "uv",
|
|
202
|
+
"args": [
|
|
203
|
+
"run",
|
|
204
|
+
"--directory",
|
|
205
|
+
"/path/to/upscalex",
|
|
206
|
+
"upscalex-mcp"
|
|
207
|
+
]
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Detailed configuration instructions for Claude Desktop, Antigravity, and Cursor are provided in the [MCP Guide](docs/mcp-guide.md).
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Model Matrix and Catalog
|
|
218
|
+
|
|
219
|
+
UpscaleX supports both pre-packaged core models and on-demand downloadable community models:
|
|
220
|
+
|
|
221
|
+
| Model ID | Scale | Target Media | VRAM Requirement | Status | Description |
|
|
222
|
+
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
223
|
+
| `realesrgan-x4plus` | 4x | Photos / Fine Art | Medium (4GB VRAM) | **Installed** | Flagship model for high-fidelity photography, art, and exhibition posters. |
|
|
224
|
+
| `realesrgan-x4plus-anime` | 4x | Anime / Illustration | Medium (4GB VRAM) | **Installed** | Preserves flat colors, sharp contours, and line definition in 2D illustrations. |
|
|
225
|
+
| `realesr-animevideov3-x4` | 4x | Video / Fast Previews | Low (1GB-2GB / CPU) | **Installed** | Lightweight 4x feed-forward model for fast turnaround and low-spec systems. |
|
|
226
|
+
| `realesr-animevideov3-x2` | 2x | Animation / Video | Low (1GB-2GB / CPU) | **Installed** | Fast 2x model for video frames, icons, and lightweight web assets. |
|
|
227
|
+
| `realesr-animevideov3-x3` | 3x | Animation / Video | Low (1GB-2GB / CPU) | **Installed** | Fast 3x model for intermediate scaling. |
|
|
228
|
+
| `realesr-general-x4v3` | 4x | General / Compact | Low (2GB VRAM) | **Installed** | Official compact general model with low memory consumption. |
|
|
229
|
+
| `4x-ultrasharp` | 4x | Portraits / Ultra-Detail | Medium-High (4GB-6GB) | Downloadable | Community champion for micro-textures, portraits, fabrics, and skin. |
|
|
230
|
+
| `4x-nmkd-superscale` | 4x | Clean Photorealistic | Medium-High (4GB-6GB) | Downloadable | Trained on clean photography; preserves hair, threads, and foliage. |
|
|
231
|
+
| `realesrgan-anime-6b` | 4x | Anime / Fast | Low (1GB-2GB / CPU) | Downloadable | 6-block lightweight anime model for rapid processing. |
|
|
232
|
+
|
|
233
|
+
### Download Additional Models
|
|
234
|
+
|
|
235
|
+
Download models through the CLI or via the `download_model` MCP tool:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
# Download 4x UltraSharp for portraits
|
|
239
|
+
upscalex download-model 4x-ultrasharp
|
|
240
|
+
|
|
241
|
+
# Download NMKD clean photo model
|
|
242
|
+
upscalex download-model 4x-nmkd-superscale
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Testing and Verification
|
|
248
|
+
|
|
249
|
+
Run the test suite to verify model resolution calculation, CLI exit codes, and live GPU inference:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
uv pip install -e ".[dev]"
|
|
253
|
+
uv run pytest -v
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
All tests must pass prior to submitting changes.
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## Contributing
|
|
261
|
+
|
|
262
|
+
Contributions to UpscaleX are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards, pull request processes, and development guidelines.
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## License
|
|
267
|
+
|
|
268
|
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
upscalex/__init__.py,sha256=YZ8yw8hMk3Cj8MAjiiLqX2O0dSBijlCJxm21vyIzsGI,261
|
|
2
|
+
upscalex/cli.py,sha256=QtuqCjqq6qVtrCp6LT0b8UFUp-ZQp441JKfKR3gsbl0,12152
|
|
3
|
+
upscalex/engine.py,sha256=Dvos6FhA8ohqfeAzabKC3FUksbVrrLf4NaDskkVgS50,29641
|
|
4
|
+
upscalex/server.py,sha256=QoTY3Rj9ssyOMldk3yGNUraqe8D3O4l6NqHF9lyXuxc,8261
|
|
5
|
+
upscalex/utils.py,sha256=aySedZBY9uMrhIkVkV-SniF8TwzqCivQ5QmpQZsIVCY,6936
|
|
6
|
+
upscalex-0.1.0.dist-info/METADATA,sha256=kypryysql5FPMRBHL3EZe4M5Nrx5g49ZsoMwRTzW2gE,11004
|
|
7
|
+
upscalex-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
8
|
+
upscalex-0.1.0.dist-info/entry_points.txt,sha256=0nFVDvlksZDXc5a6UU2N0Y6HK4H_r3aELmvJ_BqKmk8,83
|
|
9
|
+
upscalex-0.1.0.dist-info/licenses/LICENSE,sha256=elQj-rrobIEPAYk4RFLHqtytjvGRm82hUqb_2Zlzif4,1073
|
|
10
|
+
upscalex-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Arunmozhi Varman
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|