jennyxue commited on
Commit
1b2b299
·
verified ·
1 Parent(s): 511e17c

Model card and the original license

Browse files
Files changed (2) hide show
  1. LICENSE +176 -0
  2. README.md +407 -0
LICENSE ADDED
@@ -0,0 +1,176 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
README.md ADDED
@@ -0,0 +1,407 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ base_model: CSWRY/VOSR
3
+ base_model_relation: quantized
4
+ license: apache-2.0
5
+ pipeline_tag: image-to-image
6
+ library_name: onnx
7
+ tags:
8
+ - onnx
9
+ - moonbox
10
+ - vosr
11
+ - super-resolution
12
+ - upscaling
13
+ - image-to-image
14
+ - diffusion
15
+ - one-step
16
+ ---
17
+
18
+ # VOSR 2.0 ONNX
19
+
20
+ ONNX builds of [VOSR 2.0](https://github.com/cswry/VOSR), made by Moonbox for on-device use with ONNX Runtime (CUDA, DirectML, CPU).
21
+ Each precision is a folder with one graph per part of the pipeline; large weights sit next to each graph as ONNX
22
+ external data (`*.onnx.data`), so keep a folder's files together.
23
+
24
+ ## Files
25
+
26
+ The last column is how far each graph's output is from the original PyTorch model run in fp32 on the same inputs
27
+ (relative RMS error). fp32 is the yardstick because the original's own bf16 run is not exact either. Image-quality
28
+ scores are added as each precision passes the image eval.
29
+
30
+ | Precision | File | Size | sha256 | Checked against fp32 |
31
+ |---|---|---|---|---|
32
+ | int8 | [`int8/image_encoder/model.onnx`](https://huggingface.co/moonbox-dev/VOSR-2.0-ONNX/blob/main/int8/image_encoder/model.onnx) | 0.46 GB | `991f96af4a0d` | 1.8e-03 (fp16 graph) |
33
+ | int8 | [`int8/transformer/model.onnx`](https://huggingface.co/moonbox-dev/VOSR-2.0-ONNX/blob/main/int8/transformer/model.onnx) | 1.41 GB | `e38ab9630515` | 36.7 / 35.1 dB vs fp32 on Set14 / BSD100 (int8 weights) |
34
+ | int8 | [`int8/vae_decoder/model.onnx`](https://huggingface.co/moonbox-dev/VOSR-2.0-ONNX/blob/main/int8/vae_decoder/model.onnx) | 0.05 GB | `3ca755f97a8d` | 2.9e-04 (fp16 graph) |
35
+ | int8 | [`int8/vae_encoder/model.onnx`](https://huggingface.co/moonbox-dev/VOSR-2.0-ONNX/blob/main/int8/vae_encoder/model.onnx) | 0.04 GB | `c3efac4d5f17` | 3.1e-04 (fp16 graph) |
36
+
37
+ ## How to run
38
+
39
+ VOSR 2.0 is a one-step generative 4x upscaler (CVPR 2026): a 1.4 B diffusion transformer that restores a picture in a
40
+ single step, conditioned on the bicubic-upscaled input's Qwen-Image VAE latent and its DINOv2-L features. These folders
41
+ hold its four graphs for 512 x 512 tiles: `image_encoder` (DINOv2-L, layer 17), `vae_encoder`, `transformer` (the
42
+ one flow step) and `vae_decoder`. The tiling and VOSR's wavelet colour fix run outside the graphs, as below.
43
+
44
+ **Run it** (ONNX Runtime; a picture is upscaled 4x with bicubic, cut into 512 px tiles with 64 px overlap,
45
+ restored tile by tile and blended, then colour-fixed against the bicubic picture):
46
+
47
+ ```python
48
+ import cv2, numpy as np, onnxruntime as ort
49
+ from PIL import Image
50
+
51
+ d, prov = "int8", ["CUDAExecutionProvider", "CPUExecutionProvider"]
52
+ g = {p: ort.InferenceSession(f"{d}/{p}/model.onnx", providers=prov)
53
+ for p in ("image_encoder", "vae_encoder", "transformer", "vae_decoder")}
54
+ rng = np.random.default_rng(42)
55
+
56
+ def tile(x): # x: [1, 3, 512, 512] in -1..1
57
+ tok = g["image_encoder"].run(None, {"lq": x})[0]
58
+ lat = g["vae_encoder"].run(None, {"lq": x})[0]
59
+ z = g["transformer"].run(None, {"lq_latent": lat, "noise": rng.standard_normal(lat.shape, np.float32), "tokens": tok})[0]
60
+ return g["vae_decoder"].run(None, {"latent": z})[0][0]
61
+
62
+ lr = Image.open("photo.png").convert("RGB")
63
+ up = lr.resize((lr.width * 4, lr.height * 4), Image.BICUBIC)
64
+ x = np.asarray(up, np.float32).transpose(2, 0, 1) / 127.5 - 1
65
+ H, W = x.shape[1:]
66
+ x = np.pad(x, ((0, 0), (0, max(512 - H, 0)), (0, max(512 - W, 0))), mode="reflect")
67
+ Hp, Wp = x.shape[1:]
68
+ pos = lambda n: sorted({*range(0, max(n - 512, 0) + 1, 448), max(n - 512, 0)})
69
+ ramp = np.minimum(np.arange(512) + 1, 64) / 64; w2 = np.outer(np.minimum(ramp, ramp[::-1]), np.minimum(ramp, ramp[::-1]))
70
+ acc, wsum = np.zeros_like(x), np.zeros((Hp, Wp))
71
+ for y0 in pos(Hp):
72
+ for x0 in pos(Wp):
73
+ acc[:, y0:y0 + 512, x0:x0 + 512] += tile(x[None, :, y0:y0 + 512, x0:x0 + 512].copy()) * w2
74
+ wsum[y0:y0 + 512, x0:x0 + 512] += w2
75
+ sr = ((acc / wsum)[:, :H, :W].transpose(1, 2, 0) + 1) / 2
76
+ src = np.asarray(up, np.float32) / 255 # wavelet colour fix (VOSR's default)
77
+ sr = np.clip(cv2.GaussianBlur(src, (0, 0), 5) + sr - cv2.GaussianBlur(sr.astype(np.float32), (0, 0), 5), 0, 1)
78
+ Image.fromarray((sr * 255).astype(np.uint8)).save("photo_x4.png")
79
+ ```
80
+
81
+ The original tiles in latent space and blends latents; tiling in pixels as above is simpler, but on pictures larger
82
+ than one tile it is not identical to the PyTorch pipeline.
83
+
84
+ **Precisions.** int8: the transformer's weights int8 per output channel (weight-only), other graphs as in fp16.
85
+ int4: the transformer's MatMul weights 4-bit (MatMulNBits, block 32) and its other weights int8, other graphs as in
86
+ fp16. No fp16 or bf16 transformer: converting the 5.6 GB fp32 graph needed more memory than our build machine has,
87
+ and VOSR's code mixes fp32 and fp16 tensors when exported in half precision. The example above uses `int8`.
88
+
89
+ **Benchmark.** Set14 and BSD100 at 4x (bicubic-downscaled inputs), the pipeline above on an RTX 3080 Laptop GPU with
90
+ ONNX Runtime 1.30: each precision's PSNR against the fp32 pipeline's output (same noise), and PSNR / SSIM (Y channel,
91
+ 4 px border cropped) against the ground truth. VOSR is a generative model trained for real-world degradations: it
92
+ adds plausible detail, which PSNR penalizes, so compare precisions with each other rather than with PSNR-oriented
93
+ upscalers.
94
+
95
+ | Pipeline | Size | vs fp32 PSNR (Set14 / BSD100) | PSNR-Y / SSIM-Y Set14 | PSNR-Y / SSIM-Y BSD100 | Time / picture | Peak VRAM |
96
+ |---|---|---|---|---|---|---|
97
+ | fp32 (reference, not published) | 6.68 GB | - | 25.82 / 0.698 | 24.96 / 0.655 | 0.61 s | 10.5 GB |
98
+ | int8 | 1.96 GB | 36.7 / 35.1 dB | 25.82 / 0.698 | 24.95 / 0.655 | 0.52 s | 5.5 GB |
99
+ | int4 | 1.46 GB | 30.6 / 30.1 dB | 25.57 / 0.690 | 24.79 / 0.646 | 0.54 s | 4.5 GB |
100
+
101
+ ## How these were made
102
+
103
+ From [VOSR 2.0](https://github.com/cswry/VOSR) at revision `516f292b99`: each part exported with `torch.onnx`, then converted or quantized
104
+ with ONNX Runtime's tools (fp16 / bf16 casts, int8 and int4 weight quantization). Every graph was checked against
105
+ the original before upload; the `sha256` column above is what the files must hash to.
106
+
107
+ ## License
108
+
109
+ Apache-2.0. These files are a derivative of the original model and carry its license: it is copied in this
110
+ repository, and it governs your use of these files. The original model card follows unchanged.
111
+
112
+ ---
113
+
114
+ # Original model card
115
+
116
+ <div align="center">
117
+
118
+ <p align="center">
119
+ <img src="https://raw.githubusercontent.com/cswry/VOSR/516f292b99cf23c76fdc33351e86dc4f97711fe8/assets/logo.png" alt="VOSR logo" width="72%">
120
+ </p>
121
+
122
+ # VOSR: A Vision-Only Generative Model for Image Super-Resolution
123
+
124
+ <p align="center"><i>A framework for native generative image restoration.</i></p>
125
+
126
+ #### &#x1F6A9; Accepted by CVPR 2026
127
+
128
+ [![Paper](https://img.shields.io/badge/Paper-arXiv-b31b1b.svg)](https://arxiv.org/pdf/2604.03225)
129
+ [![VOSR-ModelScope](https://img.shields.io/badge/VOSR-ModelScope-6246EA.svg)](https://modelscope.cn/models/LULALULALU/VOSR_CKPT)
130
+ [![VOSR-HuggingFace](https://img.shields.io/badge/VOSR-HuggingFace-FCC624.svg)](https://huggingface.co/CSWRY/VOSR)
131
+ [![ScreenSR-ModelScope](https://img.shields.io/badge/ScreenSR-ModelScope-0EA5E9.svg)](https://modelscope.cn/datasets/LULALULALU/ScreenSR)
132
+ [![ScreenSR-HuggingFace](https://img.shields.io/badge/ScreenSR-HuggingFace-FFB000.svg)](https://huggingface.co/datasets/CSWRY/ScreenSR)
133
+
134
+ [Rongyuan Wu](https://scholar.google.com/citations?user=A-U8zE8AAAAJ&hl=zh-CN)<sup>1,2,&#42;</sup> |
135
+ [Lingchen Sun](https://scholar.google.com/citations?user=ZCDjTn8AAAAJ&hl=zh-CN)<sup>1,2,&#42;</sup> |
136
+ [Zhengqiang Zhang](https://scholar.google.com/citations?user=UX26wSMAAAAJ&hl=en)<sup>1,2</sup> |
137
+ [Xiangtao Kong](https://scholar.google.com/citations?user=lueNzSgAAAAJ&hl=zh-CN)<sup>1,2</sup> <br>
138
+ [Jixin Zhao](https://scholar.google.com/citations?user=0Z89rfUAAAAJ)<sup>1,2</sup> |
139
+ [Shihao Wang](https://scholar.google.com/citations?user=7TWugs4AAAAJ&hl=zh-CN)<sup>1</sup> |
140
+ [Lei Zhang](https://www4.comp.polyu.edu.hk/~cslzhang/)<sup>1,2,&dagger;</sup>
141
+
142
+ <sup>1</sup> The Hong Kong Polytechnic University
143
+ <sup>2</sup> OPPO Research Institute
144
+
145
+ <sup>&#42;</sup> Equal contribution. <sup>&dagger;</sup> Corresponding author.
146
+
147
+ </div>
148
+
149
+ <!-- Optional teaser image -->
150
+ <!-- ![teaser](https://raw.githubusercontent.com/cswry/VOSR/516f292b99cf23c76fdc33351e86dc4f97711fe8/assets/teaser.png) -->
151
+
152
+ <p align="center">
153
+ <img src="https://raw.githubusercontent.com/cswry/VOSR/516f292b99cf23c76fdc33351e86dc4f97711fe8/assets/overview.jpg" alt="VOSR overview" width="100%">
154
+ </p>
155
+ <p align="center"><em>Overview of the VOSR framework, including the overall pipeline and our condition / guidance design.</em></p>
156
+
157
+
158
+ ## &#x1F4CC; Quick Links
159
+
160
+ - [&#x1F4F0; News](#news)
161
+ - [&#x1F9F0; Preparation](#preparation)
162
+ - [&#x1F3CB;&#xFE0F; Training](#training)
163
+ - [&#x1F50D; Inference](#inference)
164
+ - [&#x1F4EE; Contact](#contact)
165
+ - [&#x1F4DA; Citation](#citation)
166
+
167
+ <a id="news"></a>
168
+ ## &#x1F4F0; News
169
+
170
+ - 2026.08.22 **VOSR 2.0** released: a one-step 1.4B DiT, vision-only model with improved fine-structure restoration. See [visual comparison](https://cswry.github.io/vosr2/). Thanks to [ylchen333](https://github.com/ylchen333) for bringing VOSR to ComfyUI with [ComfyUI-VOSR2](https://github.com/ylchen333/ComfyUI-VOSR2).
171
+
172
+ - 2026.04.10 Public release: training and inference code, [pretrained checkpoints](https://modelscope.cn/models/LULALULALU/VOSR_CKPT), bundled VAE / decoder assets, and the [ScreenSR](https://modelscope.cn/datasets/LULALULALU/ScreenSR) benchmark. Setup and file layout: [Preparation](#preparation); commands: [Training](#training) and [Inference](#inference).
173
+
174
+ ---
175
+
176
+ <p align="center">
177
+ <img src="https://raw.githubusercontent.com/cswry/VOSR/516f292b99cf23c76fdc33351e86dc4f97711fe8/assets/vosr_comparison_figure.png" alt="VOSR performance, efficiency, and training cost comparison" width="100%">
178
+ </p>
179
+ <p align="center"><em>Comparison with prior methods in performance, inference efficiency, and training cost.</em></p>
180
+
181
+ <p align="center">
182
+ <img src="https://raw.githubusercontent.com/cswry/VOSR/516f292b99cf23c76fdc33351e86dc4f97711fe8/assets/vis_comp.jpg" alt="Qualitative comparison on natural and text-rich images" width="100%">
183
+ </p>
184
+ <p align="center"><em>VOSR better preserves fine structures and text readability.</em></p>
185
+
186
+ <a id="preparation"></a>
187
+ ## &#x1F9F0; Preparation
188
+
189
+ ### Dependencies and Installation
190
+
191
+ ```bash
192
+ ## clone this repository
193
+ git clone https://github.com/cswry/VOSR.git
194
+ cd VOSR
195
+
196
+ # create an environment with python >= 3.8
197
+ conda create -n vosr python=3.8
198
+ conda activate vosr
199
+ pip install -r requirements.txt
200
+ ```
201
+
202
+ ### &#x1F4E6; Model Weights
203
+
204
+ Download all pretrained weights from [ModelScope](https://modelscope.cn/models/LULALULALU/VOSR_CKPT) or [Hugging Face](https://huggingface.co/CSWRY/VOSR), and place them under `preset/ckpts/`. The expected structure:
205
+
206
+ ```text
207
+ preset/ckpts/
208
+ |-- Qwen-Image-vae-2d/ # Qwen-Image VAE (2D, for 1.4B models)
209
+ |-- stable-diffusion-2-1-base/ # SD2.1 VAE (for 0.5B models)
210
+ |-- sd21_lwdecoder.pth # Lightweight decoder for SD2.1 VAE
211
+ |-- torch_cache/ # DINOv2 pretrained weights
212
+ |-- VOSR2/ # VOSR 2.0 one-step (1.4B) model
213
+ |-- VOSR_0.5B_ms/ # 0.5B multi-step model
214
+ |-- VOSR_0.5B_os/ # 0.5B one-step (distilled) model
215
+ |-- VOSR_1.4B_ms/ # 1.4B multi-step model
216
+ `-- VOSR_1.4B_os/ # 1.4B one-step (distilled) model
217
+ ```
218
+
219
+ #### VAE and decoder
220
+
221
+ For `VOSR-0.5B`, we provide `sd21_lwdecoder.pth`, a lightweight replacement for the original SD2.1 VAE decoder. It achieves comparable overall visual quality in our evaluation, while performing slightly better on text-rich and document-like images.
222
+
223
+ When scaling to `VOSR-1.4B`, we adopt the 16-channel Qwen-Image VAE to better preserve input fidelity. Although Qwen-Image is designed for T2I generation, it is released in a video-VAE form, which is unnecessarily slow for image SR inference. We therefore provide `Qwen-Image-vae-2d`, an image-only 2D variant extracted from the original model to remove the overhead of the full 3D design.
224
+
225
+ ### &#x1F5C2;&#xFE0F; Training Data
226
+
227
+ We support two data loading modes, configured via `dataset_type` in the YAML config:
228
+
229
+ - `txt` - Each folder contains individual image files. A txt config lists folders with sampling weights.
230
+ - `webdataset` - Each folder contains `.tar` shards. Same txt config format, loaded via WebDataset.
231
+
232
+ Create a dataset config file (e.g., `configs/train_txt/train_dataset_txt.txt`):
233
+
234
+ ```text
235
+ /path/to/dataset_A, 2
236
+ /path/to/dataset_B, 1
237
+ /path/to/dataset_C, 1
238
+ ```
239
+
240
+ Each line: `<folder_path>, <sampling_weight>`. Higher weight = more frequent sampling.
241
+
242
+ For `txt` mode, each folder should contain HQ images (`.png` / `.jpg`). For `webdataset` mode, each folder should contain `.tar` shards with images inside.
243
+
244
+ ### &#x1F9EA; New Real-World Paired Benchmark
245
+
246
+ Download the [ScreenSR benchmark from ModelScope](https://modelscope.cn/datasets/LULALULALU/ScreenSR) or [Hugging Face](https://huggingface.co/datasets/CSWRY/ScreenSR), place it wherever you like, and then point `-i` to that folder when running inference.
247
+
248
+ [ScreenSR](https://modelscope.cn/datasets/LULALULALU/ScreenSR) is a real-world paired benchmark for generative SR, built with a screen re-photography pipeline. It provides cleaner references, more diverse content, and broader variation in scenes and scales than existing real-world paired SR benchmarks.
249
+
250
+ <p align="center">
251
+ <img src="https://raw.githubusercontent.com/cswry/VOSR/516f292b99cf23c76fdc33351e86dc4f97711fe8/assets/montage_13x10_256px.jpg" alt="ScreenSR benchmark montage" width="100%">
252
+ </p>
253
+ <p align="center"><em>Thumbnail montage of the ScreenSR benchmark, covering diverse scenes, subjects, and multilingual text.</em></p>
254
+
255
+ ---
256
+
257
+ <a id="training"></a>
258
+ ## &#x1F3CB;&#xFE0F; Training
259
+
260
+ The provided training configs disable experiment tracking by default
261
+ (`report_to: none`). To enable Weights & Biases logging, run `wandb login`
262
+ with your own account and set `report_to: wandb` in the YAML config.
263
+
264
+ ### Multi-step Training
265
+
266
+ ```bash
267
+ # VOSR-0.5B
268
+ torchrun --nproc_per_node=8 train_vosr.py --config configs/train_yml/multi_step/VOSR_0.5B.yml
269
+
270
+ # VOSR-1.4B
271
+ torchrun --nproc_per_node=8 train_vosr.py --config configs/train_yml/multi_step/VOSR_1.4B.yml
272
+ ```
273
+
274
+ ### One-step Distillation
275
+
276
+ Requires a trained multi-step teacher checkpoint. Set `teacher_ckpt` and `pretrained_ckpt` in the YAML config.
277
+
278
+ ```bash
279
+ # VOSR-0.5B one-step
280
+ torchrun --nproc_per_node=8 train_vosr_distill.py --config configs/train_yml/one_step/VOSR_0.5B.yml
281
+
282
+ # VOSR-1.4B one-step
283
+ torchrun --nproc_per_node=8 train_vosr_distill.py --config configs/train_yml/one_step/VOSR_1.4B.yml
284
+ ```
285
+
286
+ ---
287
+
288
+ <a id="inference"></a>
289
+ ## &#x1F50D; Inference
290
+
291
+ Single-GPU inference.
292
+
293
+ ### VOSR 2.0 one-step (default)
294
+
295
+ VOSR 2.0 is the default one-step model (1.4B DiT, vision-only, with improved fine-structure restoration).
296
+
297
+ ```bash
298
+ # VOSR2-1.4B one-step
299
+ python inference_vosr_onestep.py \
300
+ -c preset/ckpts/VOSR2 \
301
+ -i preset/datasets/inp_data \
302
+ -o preset/results \
303
+ -u 4
304
+ ```
305
+
306
+ ### Multi-step models
307
+
308
+ Multi-step sampling defaults to **25 steps** (`--infer_steps`, default 25). Override if you need fewer or more function evaluations.
309
+
310
+ Two knobs mainly affect the trade-off between faithfulness to the LR input and generative detail (both can be set via CLI to override `args.json`):
311
+
312
+ - `--cfg_scale` - Higher values tend to emphasize fidelity to the condition; lower values give more generative freedom. The sweet spot depends on input degradation strength. In our experiments, roughly `-0.5` to `2` is a usable range; `0.5` is a practical default.
313
+ - `--weak_cond_strength_aelq` - During training this is sampled uniformly in `[0.05, 0.25]` so the checkpoint supports a wide range at inference via the same flag (smaller -> more generative, larger -> more faithful). Default `0.1`.
314
+
315
+ Benchmark presets (multi-step): for apples-to-apples evaluation we use `--cfg_scale -0.5` on RealSR and `--cfg_scale 0.5` on [ScreenSR](https://modelscope.cn/datasets/LULALULALU/ScreenSR).
316
+
317
+ ```bash
318
+ # Inputs under preset/datasets/inp_data follow RealSR-style evaluation; use --cfg_scale -0.5 (see benchmark presets above).
319
+
320
+ # VOSR-0.5B multi-step (25 steps)
321
+ python inference_vosr.py \
322
+ -c preset/ckpts/VOSR_0.5B_ms \
323
+ -i preset/datasets/inp_data \
324
+ -o preset/results \
325
+ -u 4
326
+
327
+ # VOSR-1.4B multi-step (25 steps)
328
+ python inference_vosr.py \
329
+ -c preset/ckpts/VOSR_1.4B_ms \
330
+ -i preset/datasets/inp_data \
331
+ -o preset/results \
332
+ -u 4
333
+ ```
334
+
335
+ ### One-step models
336
+
337
+ One-step models use `--infer_steps` with default `1` (typical for distilled checkpoints).
338
+
339
+ ```bash
340
+ # VOSR-0.5B one-step
341
+ python inference_vosr_onestep.py \
342
+ -c preset/ckpts/VOSR_0.5B_os \
343
+ -i preset/datasets/inp_data \
344
+ -o preset/results \
345
+ -u 4
346
+
347
+ # VOSR-1.4B one-step
348
+ python inference_vosr_onestep.py \
349
+ -c preset/ckpts/VOSR_1.4B_os \
350
+ -i preset/datasets/inp_data \
351
+ -o preset/results \
352
+ -u 4
353
+ ```
354
+
355
+ ### Common arguments
356
+
357
+ `-c` checkpoint path, `-i` input image or folder, `-o` output directory, `-u` upscale factor. Outputs are saved as **PNG directly into the `-o` folder**; color alignment defaults to `wavelet` (`--align_method wavelet|adain|nofix`).
358
+
359
+ - Multi-step (`inference_vosr.py`): `--infer_steps` (default `25`), `--cfg_scale`, `--weak_cond_strength_aelq` (see above).
360
+ - One-step (`inference_vosr_onestep.py`): `--infer_steps` (default `1`).
361
+ - Both: `--posterior_mode` / `--no-posterior_mode` — deterministic VAE latent (`latent_dist.mode()`) is the default, for reproducible results and seam-free tiled inference.
362
+
363
+ ### Tiled inference for large images
364
+
365
+ Large images are tiled in latent space to bound GPU memory:
366
+
367
+ - `--tile_size 512` — DiT tile size in pixels (default `0` = disabled). Use for large images; overlapping tiles are Gaussian-blended.
368
+ - `--vae_tile_size 1024` — VAE encoder/decoder tile size in pixels (default `0` = full-image VAE). The Qwen VAE attention is O(N)-memory, so full-image encode/decode already fits up to ~8K inputs; VAE tiling is only needed for extreme sizes.
369
+ - `--vae_tile_overlap` — VAE tile overlap (default: follows `--tile_overlap`).
370
+
371
+ ```bash
372
+ # VOSR-1.4B one-step on a large image with DiT + VAE tiling
373
+ python inference_vosr_onestep.py \
374
+ -c preset/ckpts/VOSR_1.4B_os \
375
+ -i large_input.png \
376
+ -o preset/results \
377
+ -u 4 --tile_size 512 --vae_tile_size 1024
378
+ ```
379
+
380
+ ---
381
+
382
+ <a id="contact"></a>
383
+ ## &#x1F4EE; Contact
384
+
385
+ If you have any questions, please feel free to contact: `rong-yuan.wu@connect.polyu.hk`
386
+
387
+ <a id="citation"></a>
388
+ ## &#x1F4DA; Citation
389
+
390
+ If VOSR is useful for your research, please consider citing:
391
+
392
+ ```bibtex
393
+ @inproceedings{wu2026vosr,
394
+ title = {VOSR: A Vision-Only Generative Model for Image Super-Resolution},
395
+ author = {Wu, Rongyuan and Sun, Lingchen and Zhang, Zhengqiang and Kong, Xiangtao and Zhao, Jixin and Wang, Shihao and Zhang, Lei},
396
+ booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
397
+ year = {2026}
398
+ }
399
+ ```
400
+
401
+ ## Acknowledgements
402
+
403
+ This project benefits from [stable-diffusion-2-1-base](https://huggingface.co/Manojb/stable-diffusion-2-1-base), [LightningDiT](https://github.com/hustvl/LightningDiT), [Qwen-Image](https://huggingface.co/Qwen/Qwen-Image), [DINOv2](https://github.com/facebookresearch/dinov2), [BasicSR](https://github.com/XPixelGroup/BasicSR), [Real-ESRGAN](https://github.com/xinntao/Real-ESRGAN), [RCGM](https://github.com/LINs-lab/RCGM), and [Shortcut-models](https://github.com/kvfrans/shortcut-models). We thank the authors for their open-source contributions.
404
+
405
+ ## &#x2696;&#xFE0F; License
406
+
407
+ This project is released under the Apache License 2.0 unless otherwise noted. See [LICENSE](https://raw.githubusercontent.com/cswry/VOSR/516f292b99cf23c76fdc33351e86dc4f97711fe8/LICENSE) for details. Downloadable model weights, benchmark data, and external assets may have separate terms on their hosting pages.