Upload README.md with huggingface_hub

README.md

@@ -16,46 +16,49 @@ tags:
 # OracleZoom
 
 **Privileged-Latent Distillation for faithful extreme super-resolution.**
-OracleZoom drives Chain-of-Zoom's recursive 4x super-resolution out to 256x while staying *faithful*, adding real detail instead of hallucinating. This repo ships one ready-to-use file: the **merged super-resolution transformer**.
+OracleZoom drives Chain-of-Zoom's recursive 4x super-resolution out to 256x while staying *faithful*, adding real detail instead of hallucinating. **This repo is self-contained**: the merged model, the inference code, and the required checkpoints are all here. You only download two public base models (Stable Diffusion 3-medium, Qwen2.5-VL-3B) automatically.
 
-[![Code](https://img.shields.io/badge/Code-OPD--Zoom-black?logo=github)](https://github.com/dipta007/OPD-Zoom)
-[![Base](https://img.shields.io/badge/Backbone-OSEDiff%20/%20SD3-blue)](https://huggingface.co/stabilityai/stable-diffusion-3-medium-diffusers)
-[![Paper](https://img.shields.io/badge/Paper-WACV%202027%20(in%20submission)-red)](https://github.com/dipta007/OPD-Zoom)
+[![Base](https://img.shields.io/badge/Base-SD3%20%2B%20Qwen2.5--VL-blue)](https://huggingface.co/stabilityai/stable-diffusion-3-medium-diffusers)
+[![Method](https://img.shields.io/badge/Method-Chain--of--Zoom-orange)](https://github.com/bryanswkim/Chain-of-Zoom)
+[![Paper](https://img.shields.io/badge/Paper-WACV%202027%20(in%20submission)-red)](#)
 [![License](https://img.shields.io/badge/License-CC--BY--NC--4.0-lightgrey)](https://creativecommons.org/licenses/by-nc/4.0/)
 
-## What's in this repo
-- **`merged_transformer.safetensors`** (fp32, ~8.35 GB): the complete OracleZoom super-resolution transformer, Stable Diffusion 3 + Chain-of-Zoom's SR module + our distilled adapter, all merged into one set of weights. This is all you need.
+## Quickstart (no repo to clone)
 
-## Quickstart (one command)
-Zooms your images 4x -> 16x -> 64x -> 256x with the merged transformer. Needs one NVIDIA GPU (~16 GB).
+Needs one NVIDIA GPU (~16 GB) and Python 3.10.
 
 ```bash
-# 1. Get the pipeline (Chain-of-Zoom is included as a submodule)
-git clone --recursive https://github.com/dipta007/OPD-Zoom
-cd OPD-Zoom
-
-# 2. Install dependencies (Python 3.10)
-pip install -r ref/coz/requirements.txt
+# 0. One-time: Stable Diffusion 3 is gated, so accept its license on HF, then log in
 pip install -U "huggingface_hub[cli]"
+hf auth login
+
+# 1. Download this repo (merged model + code + checkpoints)
+hf download dipta007/OracleZoom --local-dir OracleZoom
+cd OracleZoom
 
-# 3. Download the merged model into the pipeline
-hf download dipta007/OracleZoom merged_transformer.safetensors --local-dir ckpt/OracleZoom
+# 2. Install dependencies
+pip install -r requirements.txt
 
-# 4. Put your images in ./inputs, then run the 4-step zoom
-python -m opd_zoom.teacher.oracle_infer \
-  --mode student \
-  --full_transformer ckpt/OracleZoom/merged_transformer.safetensors \
-  --gt_dir ./inputs --out ./outputs --rec_num 4
+# 3. Put your photos in ./inputs, then zoom 4x -> 16x -> 64x -> 256x
+mkdir -p inputs && cp /path/to/photo.jpg inputs/
+python inference.py --input ./inputs --output ./outputs
 ```
 
-**Results:** `outputs/per-scale/scale1/<name>.png` ... `scale4/<name>.png` are your image at **4x / 16x / 64x / 256x**.
+**Results:** `outputs/per-scale/scale1/<name>.png` ... `scale4/<name>.png` are your image at **4x / 16x / 64x / 256x** (`scale0` is the 512x512 input crop). Stable Diffusion 3-medium and Qwen2.5-VL-3B download automatically on first run.
 
-> Notes: Stable Diffusion 3-medium and the Qwen2.5-VL prompter download automatically on first run (a HuggingFace login may be needed for SD3). Chain-of-Zoom's own SR and VLM checkpoints must sit under `ref/coz/ckpt/` (`SR_LoRA`, `SR_VAE`, `VLM_LoRA`); see the [Chain-of-Zoom](https://github.com/bryanswkim/Chain-of-Zoom) repo to fetch them. That is the only extra download.
+## What's in this repo
+| Path | What it is |
+|---|---|
+| `merged_transformer.safetensors` | The OracleZoom super-resolution transformer (SD3 + Chain-of-Zoom's SR module + our distilled adapter, merged), fp32, ~8.35 GB. |
+| `inference.py` | Self-contained runner: loads the pipeline, does the 4-step recursive zoom with VLM prompting. |
+| `coz/` | Vendored Chain-of-Zoom inference code (the one-step SR wrapper + helpers). |
+| `ckpt/` | Chain-of-Zoom's SR-VAE and VLM-prompt (Qwen LoRA) checkpoints needed by the pipeline. |
+| `requirements.txt` | Python dependencies. |
 
 ## Method
 Recursive SR (Chain-of-Zoom) reuses a 4x backbone step after step to reach 16x-256x. Each step is **blind**: it sees only a blurred crop of its own previous output and must invent the missing detail, so errors compound and the invention may be hallucinated.
 
-**Privileged-latent distillation.** A *privileged teacher* is shown the ground-truth high-resolution patch **at training time only** and distills its real detail into the blind student, in **decode space**. Only a small adapter is trained; the backbone, VAE, and prompter stay frozen. **A KL leash** to the deployed backbone keeps a deep sharpness reward from drifting into a metric-gaming texture, so detail stays faithful. (Trained: rank-16 adapter, 7.1M params, 1,000 curated 4K images; beta_reward 0.4, beta_kl 8.0. The released weights above have this adapter already merged in.)
+**Privileged-latent distillation.** A *privileged teacher* is shown the ground-truth high-resolution patch **at training time only** and distills its real detail into the blind student, in **decode space**. Only a small adapter is trained; the backbone, VAE, and prompter stay frozen. **A KL leash** to the deployed backbone keeps a deep sharpness reward from drifting into a metric-gaming texture, so detail stays faithful. Trained: rank-16 adapter (7.1M params), 1,000 curated 4K images; beta_reward 0.4, beta_kl 8.0. The released weights have this adapter already merged in.
 
 ## Results
 Under Chain-of-Zoom's exact protocol on a curated 4K benchmark and six test sets:
@@ -73,17 +76,16 @@ Sharpness is the axis prior methods are built for; the decisive gap is **faithfu
 - **In-scope:** research on faithful extreme (recursive) super-resolution of natural photographs.
 - **Out-of-scope:** forensic/evidentiary use (detail past 4x is generated, not recovered); real-camera-zoom claims (the benchmark uses synthetic center-crop zoom).
 
+## Acknowledgements & Licensing
+The `coz/` code and the checkpoints in `ckpt/` are from [Chain-of-Zoom](https://github.com/bryanswkim/Chain-of-Zoom) and are redistributed here for convenience; please respect their original license and cite them. The pipeline uses Stable Diffusion 3-medium and Qwen2.5-VL-3B under their respective licenses. OracleZoom's own contribution (the distilled adapter, merged into `merged_transformer.safetensors`) is released for **research, non-commercial** use (CC-BY-NC-4.0).
+
 ## Citation
 ```bibtex
 @inproceedings{dipta2027oraclezoom,
   title={OracleZoom: Privileged-Latent Distillation for Faithful Extreme Super-Resolution},
   author={Shubhashis Roy Dipta},
   year={2027},
-  note={In submission, WACV 2027},
-  url={https://github.com/dipta007/OPD-Zoom}
+  note={In submission, WACV 2027}
 }
 ```
-Please also cite Chain-of-Zoom and OSEDiff, whose components this builds on.
-
-## License
-Released for **research, non-commercial** use (CC-BY-NC-4.0). Built on OSEDiff / Stable Diffusion 3 and used with a Qwen2.5-VL prompter inside Chain-of-Zoom; the respective upstream licenses apply to those components.
+Please also cite Chain-of-Zoom and OSEDiff.