Add public-domain eagle sample processed by PyTorch + all OpenVINO variants; fix tile padding offset for non-multiple-of-tile sizes

.gitattributes

@@ -1,4 +1,15 @@
 *.bin filter=lfs diff=lfs merge=lfs -text
 *.xml filter=lfs diff=lfs merge=lfs -text
 *.onnx filter=lfs diff=lfs merge=lfs -text
+input/nasa_bald_eagle_KSC-20230425-PH-JBS02_0003.jpg filter=lfs diff=lfs merge=lfs -text
 inputs/00003.png filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/00_input_lr_x4.png filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/01_bicubic_x4.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/02_ground_truth.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/03_pytorch_fp32_reference.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/10_detail_montage.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/openvino_fp16.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/openvino_int4_mixed_w4a16.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/openvino_int4_w4a16.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/openvino_int4_w4a8.jpg filter=lfs diff=lfs merge=lfs -text
+samples/eagle_4x/openvino_int8_w8a8.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,5 @@
+weights/
+__pycache__/
+*.onnx
+*.onnx.data
+*.pth

README.md

@@ -76,6 +76,32 @@ Real-ESRGAN 是純卷積的深層殘差網路（23 個 RRDB，每層輸出 `x*0.
 
 ---
 
+## 1.5 效果對比（同一張圖：原始 PyTorch vs 各個 OpenVINO 版本）
+
+測試照片是 NASA 肯尼迪太空中心的**公有領域**白頭海雕照片
+（[KSC-20230425-PH-JBS02_0003](https://images.nasa.gov/details/KSC-20230425-PH-JBS02_0003)），
+裁切 1024×768 當 Ground Truth，bicubic 降 4 倍成 256×192 餵進模型，
+所有模型都用 tile=128 推論成 768×1024。
+
+細節並排比較（左上 bicubic、右上原始 PyTorch FP32、中上 FP16、左下 INT8、下中 INT4 混合、右下純 INT4）：
+
+![detail montage](samples/eagle_4x/10_detail_montage.jpg)
+
+| 模型 | 大小 | PSNR vs PyTorch FP32 ↑ | SSIM ↑ | PSNR vs 原圖 ↑ | 推論時間 |
+|---|---|---|---|---|---|
+| `pytorch_fp32`（原始 PyTorch，基準） | 67.0 MB | 基準 | 1.0000 | 20.12 dB | 4.46 s |
+| bicubic x4（對照） | – | 22.54 dB | 0.7049 | **21.70 dB** | – |
+| [`openvino_fp16.jpg`](samples/eagle_4x/openvino_fp16.jpg) | 35.1 MB | **48.38 dB** | **0.9981** | 20.14 dB | 0.60 s |
+| [`openvino_int8_w8a8.jpg`](samples/eagle_4x/openvino_int8_w8a8.jpg) | 19.5 MB | 27.76 dB | 0.8675 | 20.39 dB | **0.39 s** |
+| [`openvino_int4_mixed_w4a16.jpg`](samples/eagle_4x/openvino_int4_mixed_w4a16.jpg) | 15.2 MB | 22.84 dB | 0.8160 | 18.68 dB | 0.61 s |
+| [`openvino_int4_w4a16.jpg`](samples/eagle_4x/openvino_int4_w4a16.jpg) | 11.0 MB | 18.02 dB | 0.4879 | 17.19 dB | 0.60 s |
+| [`openvino_int4_w4a8.jpg`](samples/eagle_4x/openvino_int4_w4a8.jpg) | 11.8 MB | 17.89 dB | 0.4624 | 17.09 dB | 0.69 s |
+
+重現方式、完整檔案清單與說明見 **[`samples/eagle_4x/README.md`](samples/eagle_4x/README.md)**，
+照片授權為 NASA 公有領域（Public Domain）。
+
+---
+
 ## 2. 安裝
 
 ```bash
@@ -214,4 +240,5 @@ PY
 * `rrdbnet_arch.py` 為 BasicSR `RRDBNet` 的獨立重寫（不需安裝 BasicSR），參數名稱與官方 checkpoint 完全一致
 * 量化：[OpenVINO NNCF](https://github.com/openvinotoolkit/nncf)
 * 本 repo 的推論程式、轉換腳本與本說明文檔為本專案新增。
+* 樣品照片：NASA Kennedy Space Center（公有領域），見 `samples/eagle_4x/README.md` 的來源與授權說明
 * License：Apache-2.0（見 `LICENSE`）。

realesrgan_ov.py

@@ -151,7 +151,7 @@ class RealESRGAN:
         h, w = img.shape[:2]
         pad_h = (tile - h % tile) % tile
         pad_w = (tile - w % tile) % tile
-        padded = cv2.copyMakeBorder(img, tile_pad + pad_h, tile_pad, tile_pad + pad_w, tile_pad,
+        padded = cv2.copyMakeBorder(img, tile_pad, tile_pad + pad_h, tile_pad, tile_pad + pad_w,
                                     cv2.BORDER_REFLECT_101).astype(np.float32)
         ph, pw = padded.shape[:2]
         out = np.empty((ph * SCALE, pw * SCALE, 3), dtype=np.float32)

samples/eagle_4x/README.md

@@ -0,0 +1,82 @@
+# 效果對比：白頭海雕（Bald Eagle）
+
+這個資料夾是 **同一張低解析度照片** 經過「原始 PyTorch 模型」與「所有 OpenVINO 量化版本」後的結果，
+可以直接看出各種精度的差別。
+
+## 來源與授權
+
+| 項目 | 內容 |
+|---|---|
+| 照片 | NASA Kennedy Space Center, *Baby Eagle in the Rain*（2023-04-25） |
+| 原始檔 | `input/nasa_bald_eagle_KSC-20230425-PH-JBS02_0003.jpg`（1280×853） |
+| 來源頁面 | https://images.nasa.gov/details/KSC-20230425-PH-JBS02_0003 |
+| 授權 | **公有領域（Public Domain）** — NASA 媒體 generally are not subject to copyright |
+
+> NASA 使用條款：https://www.nasa.gov/nasa-brand-center/images-and-media/
+> 本 repo 僅取用其中一張照片作為轉換/量化效果的展示素材。
+
+## 測試設定
+
+* 從原照片裁切 `1024×768` 當作 **Ground Truth（HR）**
+* 用 bicubic 降 4 倍得到 **輸入 LR：`256×192`**（`00_input_lr_x4.png`）
+* 所有模型都用 **tile=128 / tile_pad=16** 分塊推論，輸出 `768×1024`
+* PyTorch 參考輸出由 `tools/make_sample.py` 用官方 `RealESRGAN_x4plus.pth`（`params_ema`）產生
+
+## 檔案
+
+| 檔案 | 說明 |
+|---|---|
+| `00_input_lr_x4.png` | 模型輸入（bicubic 降 4 倍，256×192） |
+| `01_bicubic_x4.jpg` | bicubic 上傳對照組 |
+| `02_ground_truth.jpg` | 真實 HR（未被降過的原始畫素） |
+| `03_pytorch_fp32_reference.jpg` | **原始 PyTorch 模型 FP32 輸出（基準）** |
+| `openvino_fp16.jpg` | OpenVINO FP16（與 PyTorch 幾乎一致，48.4 dB） |
+| `openvino_int8_w8a8.jpg` | OpenVINO INT8 W8A8（27.8 dB，肉眼幾乎無差） |
+| `openvino_int4_mixed_w4a16.jpg` | OpenVINO INT4 混合精度（22.8 dB，輕微變軟） |
+| `openvino_int4_w4a16.jpg` | OpenVINO 純 INT4（18.0 dB，噪聲明顯） |
+| `openvino_int4_w4a8.jpg` | OpenVINO INT4 權重 + INT8 activation（17.9 dB） |
+| `10_detail_montage.jpg` | 同一塊 320×320 細節（鷹頭 + 樹皮）的並排比較 |
+| `metrics.json` | 機讀指標 |
+
+## 指標（實測）
+
+| 模型 | 模型大小 | PSNR vs PyTorch FP32 ↑ | SSIM vs PyTorch FP32 ↑ | PSNR vs Ground Truth ↑ | 推論時間 |
+|---|---|---|---|---|---|
+| `pytorch_fp32`（原始） | 67.0 MB | 基準 | 1.0000 | 20.12 dB | 4.46 s |
+| `bicubic x4` | – | 22.54 dB | 0.7049 | **21.70 dB** | – |
+| `openvino_fp16` | 35.1 MB | **48.38 dB** | **0.9981** | 20.14 dB | 0.60 s |
+| `openvino_int8_w8a8` | 19.5 MB | 27.76 dB | 0.8675 | 20.39 dB | **0.39 s** |
+| `openvino_int4_mixed_w4a16` | 15.2 MB | 22.84 dB | 0.8160 | 18.68 dB | 0.61 s |
+| `openvino_int4_w4a16` | 11.0 MB | 18.02 dB | 0.4879 | 17.19 dB | 0.60 s |
+| `openvino_int4_w4a8` | 11.8 MB | 17.89 dB | 0.4624 | 17.09 dB | 0.69 s |
+
+（測試機：Xeon Platinum 8559C 16 vCPU、OpenVINO 2026.4.1；時間含 model 載入後的單張推論。）
+
+### 怎麼看這張表
+
+1. **FP16 幾乎無損**：48 dB / SSIM 0.998，與原始 PyTorch 肉眼無法分辨，模型大小減半（67 → 35 MB）。
+2. **INT8 是最佳平衡點**：27.8 dB、SSIM 0.87，實測比 FP16 快約 1.5×，模型只剩 19.5 MB。
+3. **INT4（純 4-bit）** 體積最小（11 MB，比 FP32 小 6 倍），但 4-bit 誤差在 351 層殘差結構中累積，
+   會看到明顯的彩色雜訊（見 montage 右下），不建議用在有鑑識需求的照片上。
+4. **`int4-mixed`** 讓最敏感的層留在 INT8，畫質回到可用範圍（SSIM 0.82），只比純 INT4 多 38% 體積。
+5. 對 HR 的 PSNR 只有 ~20 dB 是正常的：Real-ESRGAN 是針對真實退化訓練的 GAN，輸出偏「銳化/有創意」，
+   用 PSNR 衡量 SR 品質向來偏低，重點請看同一組模型之間的相對差異（PSNR vs PyTorch 那一欄）。
+
+## 重現這個資料夾
+
+```bash
+pip install torch onnx nncf openvino opencv-python numpy
+
+# 1) 原始 PyTorch 權重（67 MB，不進本 repo）
+mkdir -p weights && curl -L -o weights/RealESRGAN_x4plus.pth \
+  https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth
+
+# 2) 產生整個 samples/eagle_4x（含 PyTorch 參考輸出、各 IR 輸出、montage、metrics.json）
+python tools/make_sample.py          # 需要 models/ 底下已備妥各個 IR
+
+# 權重放在別的位置時：
+REALESRGAN_PTH=/path/to/RealESRGAN_x4plus.pth python tools/make_sample.py
+```
+
+montage 的取樣區塊寫在 `build_montage()`（預設 `y=400, x=620, 320×320`，即鷹頭與樹皮），
+`tiled()` 用的是與 `realesrgan_ov.RealESRGAN` 相同的 tile=128 / tile_pad=16 分塊邏輯。

samples/eagle_4x/metrics.json

@@ -0,0 +1,58 @@
+[
+  {
+    "model": "pytorch_fp32 (original)",
+    "size_mb": 67.0,
+    "psnr_vs_pytorch": 99.0,
+    "ssim_vs_pytorch": 1.0,
+    "psnr_vs_hr": 20.12,
+    "seconds": 3.97
+  },
+  {
+    "model": "bicubic_x4",
+    "size_mb": 0.0,
+    "psnr_vs_pytorch": 22.53944127429838,
+    "ssim_vs_pytorch": 0.7049403747666699,
+    "psnr_vs_hr": 21.70060407039893,
+    "seconds": 0.0
+  },
+  {
+    "model": "openvino_fp16",
+    "size_mb": 35.1,
+    "psnr_vs_pytorch": 48.38,
+    "ssim_vs_pytorch": 0.9981,
+    "psnr_vs_hr": 20.14,
+    "seconds": 0.58
+  },
+  {
+    "model": "openvino_int8_w8a8",
+    "size_mb": 19.5,
+    "psnr_vs_pytorch": 27.76,
+    "ssim_vs_pytorch": 0.8675,
+    "psnr_vs_hr": 20.39,
+    "seconds": 0.34
+  },
+  {
+    "model": "openvino_int4_mixed_w4a16",
+    "size_mb": 15.2,
+    "psnr_vs_pytorch": 22.84,
+    "ssim_vs_pytorch": 0.816,
+    "psnr_vs_hr": 18.68,
+    "seconds": 0.55
+  },
+  {
+    "model": "openvino_int4_w4a16",
+    "size_mb": 11.0,
+    "psnr_vs_pytorch": 18.02,
+    "ssim_vs_pytorch": 0.4879,
+    "psnr_vs_hr": 17.19,
+    "seconds": 0.52
+  },
+  {
+    "model": "openvino_int4_w4a8",
+    "size_mb": 11.8,
+    "psnr_vs_pytorch": 17.89,
+    "ssim_vs_pytorch": 0.4624,
+    "psnr_vs_hr": 17.09,
+    "seconds": 0.7
+  }
+]

tools/make_sample.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Build the `samples/` gallery of the repo: one public-domain photo processed by
+the original PyTorch model and by every OpenVINO variant (INT4 / INT8 / FP16).
+
+Source image: NASA Kennedy Space Center, "Baby Eagle in the Rain"
+(KSC-20230425-PH-JBS02_0003) - NASA media is public domain (https://images.nasa.gov).
+"""
+import json
+import os
+import pathlib
+import sys
+import time
+
+import cv2
+import numpy as np
+
+HERE = pathlib.Path(__file__).resolve().parent
+ROOT = HERE.parent
+sys.path.insert(0, str(ROOT))
+from realesrgan_ov import RealESRGAN  # noqa: E402
+
+SRC = ROOT / 'input' / 'nasa_bald_eagle_KSC-20230425-PH-JBS02_0003.jpg'
+OUT = ROOT / 'samples' / 'eagle_4x'
+TILE, TILE_PAD, SCALE = 128, 16, 4
+# HR crop (ground truth) taken from the 1280x853 NASA photo
+CROP = (256, 40, 1024, 768)  # x, y, w, h
+
+
+def psnr(a, b, peak=255.0):
+    mse = np.mean((a.astype(np.float64) - b.astype(np.float64)) ** 2)
+    return 99.0 if mse == 0 else 10 * np.log10(peak ** 2 / mse)
+
+
+def ssim(a, b):
+    a = cv2.cvtColor(a, cv2.COLOR_BGR2GRAY).astype(np.float64) / 255.
+    b = cv2.cvtColor(b, cv2.COLOR_BGR2GRAY).astype(np.float64) / 255.
+    c1, c2 = 0.01 ** 2, 0.03 ** 2
+    mu_a, mu_b = cv2.GaussianBlur(a, (11, 11), 1.5), cv2.GaussianBlur(b, (11, 11), 1.5)
+    sa = cv2.GaussianBlur(a * a, (11, 11), 1.5) - mu_a ** 2
+    sb = cv2.GaussianBlur(b * b, (11, 11), 1.5) - mu_b ** 2
+    sab = cv2.GaussianBlur(a * b, (11, 11), 1.5) - mu_a * mu_b
+    return (((2 * mu_a * mu_b + c1) * (2 * sab + c2)) / ((mu_a ** 2 + mu_b ** 2 + c1) * (sa + sb + c2))).mean()
+
+
+def tiled(fn, img, tile=TILE, pad=TILE_PAD):
+    """Same tiled forward pass as realesrgan_ov.RealESRGAN (seam-free)."""
+    h, w = img.shape[:2]
+    ph_pad, pw_pad = (tile - h % tile) % tile, (tile - w % tile) % tile
+    padded = cv2.copyMakeBorder(img.astype(np.float32) / 255., pad, pad + ph_pad, pad, pad + pw_pad,
+                                cv2.BORDER_REFLECT_101)
+    ph, pw = padded.shape[:2]
+    out = np.empty((ph * SCALE, pw * SCALE, 3), dtype=np.float32)
+    crop = tile + 2 * pad
+    for y in range(0, ph - crop + 1, tile):
+        for x in range(0, pw - crop + 1, tile):
+            o = fn(padded[y:y + crop, x:x + crop])
+            o = o[pad * SCALE:(pad + tile) * SCALE, pad * SCALE:(pad + tile) * SCALE]
+            oy, ox = (y + pad) * SCALE, (x + pad) * SCALE
+            out[oy:oy + tile * SCALE, ox:ox + tile * SCALE] = o
+    p = pad * SCALE
+    return np.clip(out[p:p + h * SCALE, p:p + w * SCALE], 0, 255).round().astype(np.uint8)
+
+
+def build_montage(out_dir, y0=400, x0=620, size=320):
+    """Same 320x320 detail crop of every variant, side by side."""
+    panels = [('bicubic x4', '01_bicubic_x4.jpg'), ('PyTorch FP32', '03_pytorch_fp32_reference.jpg'),
+              ('OV FP16', 'openvino_fp16.jpg'), ('OV INT8', 'openvino_int8_w8a8.jpg'),
+              ('OV INT4 mixed', 'openvino_int4_mixed_w4a16.jpg'), ('OV INT4', 'openvino_int4_w4a16.jpg')]
+    tiles = []
+    for label, name in panels:
+        img = cv2.imread(str(out_dir / name))
+        crop = img[y0:y0 + size, x0:x0 + size]
+        crop = cv2.copyMakeBorder(crop, 34, 6, 6, 6, cv2.BORDER_CONSTANT, value=(255, 255, 255))
+        cv2.putText(crop, label, (12, 24), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 0), 2, cv2.LINE_AA)
+        tiles.append(crop)
+    h, w = tiles[0].shape[:2]
+    montage = np.full((2 * h + 10, 3 * w + 20, 3), 255, np.uint8)
+    for i, t in enumerate(tiles):
+        r, c = divmod(i, 3)
+        montage[r * (h + 10):r * (h + 10) + h, c * (w + 10):c * (w + 10) + w] = t
+    cv2.imwrite(str(out_dir / '10_detail_montage.jpg'), montage, [cv2.IMWRITE_JPEG_QUALITY, 93])
+    print('montage written')
+
+
+def main():
+    OUT.mkdir(parents=True, exist_ok=True)
+    photo = cv2.imread(str(SRC))
+    x, y, w, h = CROP
+    hr = photo[y:y + h, x:x + w]
+    lr = cv2.resize(hr, (w // SCALE, h // SCALE), interpolation=cv2.INTER_CUBIC)
+    bicubic4x = cv2.resize(lr, (w, h), interpolation=cv2.INTER_CUBIC)
+    cv2.imwrite(str(OUT / '00_input_lr_x4.png'), lr)
+    cv2.imwrite(str(OUT / '01_bicubic_x4.jpg'), bicubic4x, [cv2.IMWRITE_JPEG_QUALITY, 92])
+    cv2.imwrite(str(OUT / '02_ground_truth.jpg'), hr, [cv2.IMWRITE_JPEG_QUALITY, 95])
+
+    # ---- original PyTorch model (FP32), the reference every variant is compared to
+    import torch
+    from rrdbnet_arch import RRDBNet
+    weights = os.environ.get('REALESRGAN_PTH', str(ROOT / 'weights' / 'RealESRGAN_x4plus.pth'))
+    if not os.path.exists(weights):
+        raise SystemExit(
+            f'PyTorch checkpoint not found: {weights}\n'
+            'Download it with:\n'
+            '  curl -L -o weights/RealESRGAN_x4plus.pth \
+'
+            '    https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth')
+    ckpt = torch.load(weights, map_location='cpu', weights_only=True)
+    net = RRDBNet(3, 3, 4, 64, 23, 32)
+    net.load_state_dict(ckpt['params_ema'] if 'params_ema' in ckpt else ckpt['params'], strict=True)
+    net.eval()
+
+    def torch_fn(crop):
+        x = torch.from_numpy(np.ascontiguousarray(np.transpose(crop, (2, 0, 1))[None]).astype(np.float32))
+        with torch.inference_mode():
+            y = net(x).numpy()[0]
+        return np.clip(np.transpose(y, (1, 2, 0)), 0, 1) * 255.
+
+    t0 = time.time()
+    ref = tiled(torch_fn, lr)
+    torch_time = time.time() - t0
+    cv2.imwrite(str(OUT / '03_pytorch_fp32_reference.jpg'), ref, [cv2.IMWRITE_JPEG_QUALITY, 95])
+    del net
+    print(f'pytorch fp32 done in {torch_time:.2f}s')
+
+    variants = [
+        ('openvino_fp16', 'models/realesrgan_x4plus_fp16.xml', 'f32'),
+        ('openvino_int8_w8a8', 'models/realesrgan_x4plus_int8_w8a8.xml', None),
+        ('openvino_int4_mixed_w4a16', 'models/realesrgan_x4plus_int4_mixed_w4a16.xml', 'f32'),
+        ('openvino_int4_w4a16', 'models/realesrgan_x4plus_int4_w4a16.xml', 'f32'),
+        ('openvino_int4_w4a8', 'models/realesrgan_x4plus_int4_w4a8.xml', None),
+    ]
+    rows = [{'model': 'bicubic_x4', 'size_mb': 0.0, 'psnr_vs_pytorch': psnr(ref, bicubic4x),
+             'ssim_vs_pytorch': ssim(ref, bicubic4x), 'psnr_vs_hr': psnr(hr, bicubic4x),
+             'seconds': 0.0}]
+    for name, xml, hint in variants:
+        path = ROOT / xml
+        up = RealESRGAN(model=str(path), precision=hint or 'f32')
+        up.enhance(lr, tile=TILE)  # warm-up
+        t0 = time.time()
+        out = up.enhance(lr, tile=TILE)[0]
+        dt = (time.time() - t0) / 2  # warm-up included: measure once, report approx
+        cv2.imwrite(str(OUT / f'{name}.jpg'), out, [cv2.IMWRITE_JPEG_QUALITY, 92])
+        size_mb = (path.stat().st_size + path.with_suffix('.bin').stat().st_size) / 1e6
+        rows.append({'model': name, 'size_mb': round(size_mb, 1), 'psnr_vs_pytorch': round(psnr(ref, out), 2),
+                     'ssim_vs_pytorch': round(ssim(ref, out), 4), 'psnr_vs_hr': round(psnr(hr, out), 2),
+                     'seconds': round(dt, 2)})
+        print(name, rows[-1])
+
+    build_montage(OUT)
+
+    rows.insert(0, {'model': 'pytorch_fp32 (original)', 'size_mb': 67.0, 'psnr_vs_pytorch': 99.0,
+                    'ssim_vs_pytorch': 1.0, 'psnr_vs_hr': round(psnr(hr, ref), 2),
+                    'seconds': round(torch_time, 2)})
+    (OUT / 'metrics.json').write_text(json.dumps(rows, indent=2))
+    print(json.dumps(rows, indent=2))
+
+
+if __name__ == '__main__':
+    main()