Upload README.md

README.md

@@ -1,27 +1,153 @@
-# VOSR-Mobile release package
+---
+license: apache-2.0
+base_model: CSWRY/VOSR
+pipeline_tag: image-to-image
+tags:
+  - image-super-resolution
+  - image-restoration
+  - quantized
+  - mobile
+  - qualcomm
+  - qnn
+  - snapdragon
+  - npu
+---
 
-This directory is the upload root for `AllGPTORG/VOSR_1.4B_Mobile`.
-Upload its contents to the repository root, so the Hub paths remain
-`onnx/...` and `sd8g3/...` rather than `Done/...`.
+# VOSR 1.4B Mobile
 
-## Contents
+`AllGPTORG/VOSR_1.4B_Mobile` is a mobile deployment package of the
+**VOSR-1.4B one-step** image super-resolution model, quantized and compiled as
+Qualcomm QNN DLC graphs for the Snapdragon 8 Gen 3 NPU.
 
-- `onnx/`: nine reference ONNX graphs.
-- `sd8g3/qnn-context/`: eleven SM8650 QNN context binaries and their metadata.
-- `sd8g3/wrappers/`: eleven ONNX Runtime EPContext wrappers.
-- `sd8g3/vosr_runtime_manifest.json`: app runtime contract and SHA-256 values.
+The package is designed for high-quality image restoration and super-resolution,
+including text-rich images. It preserves the original one-step VOSR pipeline while
+splitting the network into smaller graphs suitable for mobile integration.
 
-The QNN package targets Snapdragon 8 Gen 3 (`SM8650`) and QAIRT
-`2.45.0.260326154327`. CPU execution fallback is intentionally disabled.
+> This repository contains QNN deployment artifacts. It is not a Transformers or
+> Diffusers checkpoint and cannot be loaded with `from_pretrained()`.
 
-The staged manifest remains `complete: false` until all QNN files are uploaded.
-After the first upload, regenerate it with the immutable Hub commit and publish
-that manifest in a second commit:
+## Model summary
 
-```powershell
-python tools\generate_vosr_wrappers.py --blocks-per-context 6 --revision <COMMIT_SHA> --published
+| Property | Value |
+|---|---|
+| Base model | [CSWRY/VOSR](https://huggingface.co/CSWRY/VOSR), VOSR-1.4B one-step |
+| Task | Generative image restoration and super-resolution |
+| Target SoC | Qualcomm Snapdragon 8 Gen 3 / SM8650 |
+| Compile target | Samsung Galaxy S24 family, Android 14 |
+| Runtime format | Qualcomm QNN DLC |
+| Static tile size | 512 x 512 pixels |
+| Batch size | 1 |
+| Activations | FP16 (A16) |
+| DiT block weights | INT4 (W4A16) |
+| Auxiliary/final graph weights | INT8 (W8A16) |
+| Total DLC size | 1,736,469,708 bytes / 1.617 GiB |
+
+## Files
+
+The graphs must be executed in the order shown below.
+
+| Order | File | Precision | Size |
+|---:|---|---:|---:|
+| 1 | `vosr_dinov2l_layer17.dlc` | W8A16 | 229.50 MiB |
+| 2 | `vosr_qwen_vae_encoder.dlc` | W8A16 | 19.09 MiB |
+| 3 | `vosr_dit_prepare.dlc` | W8A16 | 42.61 MiB |
+| 4 | `vosr_dit_blocks_00_12.dlc` | W4A16 | 444.86 MiB |
+| 5 | `vosr_dit_blocks_12_18.dlc` | W4A16 | 222.62 MiB |
+| 6 | `vosr_dit_blocks_18_24.dlc` | W4A16 | 222.62 MiB |
+| 7 | `vosr_dit_blocks_24_36.dlc` | W4A16 | 444.86 MiB |
+| 8 | `vosr_dit_final.dlc` | W8A16 | 4.90 MiB |
+| 9 | `vosr_qwen_vae_decoder.dlc` | W8A16 | 24.97 MiB |
+
+`manifest.json` contains the same graph order, precision assignment, and exact
+byte size for programmatic use.
+
+## Tensor interface
+
+All image and latent tensors use NCHW layout.
+
+| Graph | Inputs | Outputs |
+|---|---|---|
+| DINOv2-L layer 17 | `lq_image`: FP16 `[1,3,512,512]` | `dino_features`: FP16 `[1,1024,1024]` |
+| Qwen VAE encoder | `lq_image`: FP16 `[1,3,512,512]`; `posterior_noise`: FP16 `[1,16,64,64]` | `lq_latent`: FP16 `[1,16,64,64]` |
+| DiT prepare | `latent_pair`: FP16 `[1,32,64,64]`; `timestep`: FP32 `[1]`; `next_timestep`: FP32 `[1]`; `dino_features`: FP16 `[1,1024,1024]` | `hidden`: FP16 `[1,1024,1536]`; `conditioning`: FP16 `[1,1536]`; `block_conditioning`: FP16 `[1,9216]`; `projected_dino`: FP16 `[1,1024,1536]` |
+| DiT block stages | `hidden`, `block_conditioning`, `projected_dino` | `hidden_out`: FP16 `[1,1024,1536]` |
+| DiT final | `hidden`: FP16 `[1,1024,1536]`; `conditioning`: FP16 `[1,1536]` | `velocity`: FP16 `[1,16,64,64]` |
+| Qwen VAE decoder | `normalized_latent`: FP16 `[1,16,64,64]` | `sr_image`: FP16 `[1,3,512,512]` |
+
+## Integration outline
+
+Use the Qualcomm AI Engine Direct SDK / QNN runtime to load and execute the DLCs.
+The host application is responsible for preprocessing, graph orchestration, random
+noise generation, the one-step latent update, tiling, and image postprocessing.
+
+1. Resize the low-resolution image to the requested output resolution using bicubic
+   interpolation, split it into 512 x 512 tiles if needed, convert RGB values to
+   FP16 NCHW, and normalize them to `[-1, 1]`.
+2. Run the DINO graph and Qwen VAE encoder on the same image tile. Supply seeded
+   normal noise as `posterior_noise` if reproducible output is required.
+3. Create an FP16 normal-noise latent `z` with shape `[1,16,64,64]`, concatenate
+   `lq_latent` and `z` along the channel axis, and use the result as `latent_pair`.
+4. For the one-step schedule, run DiT prepare with `timestep = [1.0]` and
+   `next_timestep = [0.0]`.
+5. Pass `hidden` sequentially through all four DiT block-stage DLCs. Reuse
+   `block_conditioning` and `projected_dino` for every stage.
+6. Run DiT final and apply the one-step update `z = z - velocity`.
+7. Decode the updated latent with the Qwen VAE decoder, clamp the output to
+   `[-1, 1]`, convert it back to RGB, and blend overlapping tiles when tiling.
+
+For 4x super-resolution, bicubic-upscale the source to the final target resolution
+before creating the model tiles. The network then restores detail at that target
+resolution.
+
+## Validation status
+
+- All nine graphs were quantized with representative intermediate activations.
+- All nine graphs were successfully compiled to QNN DLC format for SM8650.
+- The Qwen VAE encoder and DiT prepare graphs were profiled on the Snapdragon 8
+  Gen 3 NPU.
+- A single pre-linked QNN context is intentionally not included. Linking the entire
+  hybrid package exceeded the cloud linker memory limit, so applications should
+  execute the DLC sequence or link it with a compatible local QNN SDK.
+
+Performance, memory use, and image quality depend on the QNN SDK version, device
+firmware, thermal state, tiling implementation, and host-side orchestration. Test on
+the exact target device before shipping a production application.
+
+## Intended use
+
+This package is intended for research and mobile application development involving:
+
+- photo and screenshot restoration;
+- text-rich image enhancement;
+- single-image super-resolution;
+- Snapdragon NPU deployment experiments.
+
+It is not intended for forensic reconstruction or for recovering information that
+is not present in the source image. Generative restoration can introduce plausible
+but incorrect details.
+
+## Attribution
+
+This is a quantized mobile derivative of VOSR. The original architecture, training,
+and checkpoints were created by the VOSR authors. See the
+[official project](https://github.com/cswry/VOSR) and
+[paper](https://arxiv.org/abs/2604.03225) for full details.
+
+## Citation
+
+If you use this model, please cite the original VOSR work:
+
+```bibtex
+@inproceedings{wu2026vosr,
+  title     = {VOSR: A Vision-Only Generative Model for Image Super-Resolution},
+  author    = {Wu, Rongyuan and Sun, Lingchen and Zhang, Zhengqiang and Kong, Xiangtao and Zhao, Jixin and Wang, Shihao and Zhang, Lei},
+  booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
+  year      = {2026}
+}
 ```
 
-The Android app can then bundle the published manifest and download only the
-eleven files under `sd8g3/qnn-context/`. The large reference ONNX files are not
-downloaded by the app.
+## License
+
+Released under the Apache License 2.0, following the upstream VOSR repository.
+Users are responsible for reviewing and complying with the licenses and terms of
+all upstream components and the Qualcomm QNN SDK/runtime used for deployment.