Correct benchmarks, video resolutions, I/O names, training data and usage examples

README.md

@@ -37,7 +37,7 @@ model-index:
           name: Set14
         metrics:
           - type: psnr
-            value: 33.21
+            value: 33.16
             name: PSNR
       - task:
           type: image-super-resolution
@@ -47,23 +47,13 @@ model-index:
           name: BSD100
         metrics:
           - type: psnr
-            value: 31.98
-            name: PSNR
-      - task:
-          type: image-super-resolution
-          name: Image Super-Resolution
-        dataset:
-          type: Urban100
-          name: Urban100
-        metrics:
-          - type: psnr
-            value: 31.38
+            value: 31.99
             name: PSNR
 ---
 
 # PiperSR-2x: ANE-Native Super Resolution for Apple Silicon
 
-Real-time 2x AI upscaling on Apple's Neural Engine. 44.4 FPS at 720p on M2 Max, 928 KB model, every op runs natively on ANE with zero CPU/GPU fallback.
+Real-time 2x AI upscaling on Apple's Neural Engine. 44.4 FPS for 360p → 720p video on M2 Max, 928 KB model, every op runs natively on ANE with zero CPU/GPU fallback.
 
 Not a converted PyTorch model — an architecture designed from ANE hardware measurements. Every dimension, operation, and data type is dictated by Neural Engine characteristics.
 
@@ -72,21 +62,26 @@ Not a converted PyTorch model — an architecture designed from ANE hardware mea
 | Model | Params | Set5 | Set14 | BSD100 | Urban100 |
 |-------|--------|------|-------|--------|----------|
 | Bicubic | — | 33.66 | 30.24 | 29.56 | 26.88 |
-| FSRCNN | 13K | 37.05 | 32.66 | 31.53 | 29.88 |
-| **PiperSR** | **453K** | **37.54** | **33.21** | **31.98** | **31.38** |
-| SAFMN | 228K | 38.00 | ~33.7 | ~32.2 | — |
+| FSRCNN | 12K | 37.00 | 32.63 | 31.53 | 29.88 |
+| SAFMN | 228K | 38.00 | 33.54 | 32.16 | 31.84 |
+| SPAN-S | 411K | 38.06 | 33.73 | 32.21 | 32.20 |
+| **PiperSR** | **453K** | **37.54** | **33.16** | **31.99** | **—** |
+
+2x, Y-channel PSNR (dB). PiperSR scores are for the shipped CoreML model and reproduce with `benchmark.py` on GitHub. Other scores are from each model's paper; the [full table with sources](https://github.com/ModelPiper/PiperSR#how-it-compares) is on GitHub. PiperSR has no Urban100 score because Urban100's test images were accidentally included in its training data.
 
-Beats FSRCNN across all benchmarks. Within 0.46 dB of SAFMN on Set5 — below the perceptual threshold for most content.
+Beats FSRCNN on every benchmark reported. Within 0.46 dB of SAFMN and 0.52 dB of SPAN-S on Set5, the cost of designing for the ANE instead of the GPU.
 
 ## Performance
 
 | Configuration | FPS | Hardware | Notes |
 |--------------|-----|----------|-------|
-| Full-frame 640×360 → 1280×720 | 44.4 | M2 Max | ANE predict 22.5 ms |
+| Full-frame 640×360 → 1280×720 | 44.4 | M2 Max | `PiperSR_2x_video_720p`, ANE predict 22.5 ms |
+| Full-frame 854×480 → 1708×960 | 30.0 | M2 Max | `PiperSR_2x_video_720p`, ANE predict 32.7 ms |
+| Full-frame 1280×720 → 2560×1440 | 14.0 | M2 Max | `PiperSR_2x_video_720p`, ANE predict 71.6 ms |
 | 128×128 tiles (static weights) | 125.6 | M2 | Baked weights, 2.82× vs dynamic |
 | 128×128 tiles (dynamic weights) | 44.5 | M2 | CoreML default |
 
-Real-time 2× upscaling at 30+ FPS on any Mac with Apple Silicon. The ANE sits idle during video playback — PiperSR puts it to work.
+Real-time 2× upscaling of 360p video (44.4 FPS on M2 Max). The ANE sits idle during video playback — PiperSR puts it to work.
 
 ## Architecture
 
@@ -100,7 +95,7 @@ Input (128×128×3 FP16)
 Output (256×256×3)
 ```
 
-Compiles to 5 MIL ops: `conv`, `add`, `silu`, `pixel_shuffle`, `const`. All verified ANE-native.
+Compiles to five network ops: `conv`, `silu`, `add`, `pixel_shuffle` and `clip` (BatchNorm is fused into the convolutions at export). CoreML's compute plan places every one of them on the ANE.
 
 ### Why ANE-native matters
 
@@ -115,25 +110,29 @@ PiperSR addresses every one of these by designing around ANE constraints.
 
 ## Model Variants
 
-| File | Use Case | Input → Output |
-|------|----------|----------------|
-| `PiperSR_2x.mlpackage` | Static images (128px tiles) | 128×128 → 256×256 |
-| `PiperSR_2x_video_720p.mlpackage` | Video (full-frame, BN-fused) | 640×360 → 1280×720 |
-| `PiperSR_2x_256.mlpackage` | Static images (256px tiles) | 256×256 → 512×512 |
+| File | Use Case | Input → Output | I/O type |
+|------|----------|----------------|----------|
+| `PiperSR_2x.mlpackage` | Static images (128px tiles) | 128×128 → 256×256 | Image (`input_image` → `output_image`) |
+| `PiperSR_2x_256.mlpackage` | Static images (256px tiles) | 256×256 → 512×512 | Image (`input_image` → `output_image`) |
+| `PiperSR_2x_video_720p.mlpackage` | Video frames (full-frame) | 640×360, 854×480 or 1280×720 (and portrait) → 2× | Float array, NCHW, [0, 1] (`input` → `clip_0`) |
+
+The tile models take any image size by splitting it into tiles. The `pipersr` Python package does this for you.
 
 ## Usage
 
-### With ToolPiper (recommended)
+### With ToolPiper Studio (recommended)
 
-PiperSR is integrated into [ToolPiper](https://modelpiper.com), a local macOS AI toolkit. Install ToolPiper, enable the MediaPiper browser extension, and every 720p video on the web is upscaled to 1440p in real time.
+PiperSR is integrated into [ToolPiper Studio](https://modelpiper.com), a local macOS AI toolkit. Install ToolPiper, enable the MediaPiper browser extension, and 360p web video is upscaled to 720p in real time.
 
 ```bash
-# Via MCP tool
-mcp__toolpiper__image_upscale image=/path/to/image.png
+# Via MCP tool (pass model, or ToolPiper uses its default 4x upscaler)
+mcp__toolpiper__image_upscale image=/path/to/image.png model=pipersr-2x
 
-# Via REST API
+# Via REST API (needs a ToolPiper developer token)
 curl -X POST http://127.0.0.1:9998/v1/images/upscale \
-  -F "image=@input.png" \
+  -H "Authorization: Bearer $TOOLPIPER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"image\":\"$(base64 -i input.png)\",\"model\":\"pipersr-2x\"}" \
   -o upscaled.png
 ```
 
@@ -146,43 +145,58 @@ let config = MLModelConfiguration()
 config.computeUnits = .cpuAndNeuralEngine  // NOT .all — .all is 23.6% slower
 
 let model = try PiperSR_2x(configuration: config)
-let input = try PiperSR_2xInput(x: pixelBuffer)
+let input = PiperSR_2xInput(input_image: pixelBuffer)  // 128×128 CVPixelBuffer
 let output = try model.prediction(input: input)
-// output.var_185 contains the 2× upscaled image
+// output.output_image is the 256×256 upscaled tile
 ```
 
 > **Important:** Use `.cpuAndNeuralEngine`, not `.all`. CoreML's `.all` silently misroutes pure-ANE ops onto the GPU, causing a 23.6% slowdown for this model.
 
+### With Python (pip)
+
+```bash
+pip install pipersr
+pipersr -i photo.png -o photo_2x.png
+```
+
+```python
+from pipersr import upscale
+
+upscale("photo.png").save("photo_2x.png")
+```
+
+The package bundles `PiperSR_2x.mlpackage` and handles tiling, so images of any size work.
+
 ### With coremltools (Python)
 
 ```python
 import coremltools as ct
 from PIL import Image
-import numpy as np
-
-model = ct.models.MLModel("PiperSR_2x.mlpackage")
 
-img = Image.open("input.png").resize((128, 128))
-arr = np.array(img).astype(np.float32) / 255.0
-arr = np.transpose(arr, (2, 0, 1))[np.newaxis]  # NCHW
+model = ct.models.MLModel(
+    "PiperSR_2x.mlpackage",
+    compute_units=ct.ComputeUnit.CPU_AND_NE,
+)
 
-result = model.predict({"x": arr})
+tile = Image.open("input.png").convert("RGB").crop((0, 0, 128, 128))
+result = model.predict({"input_image": tile})["output_image"]  # 256×256 PIL image
+result.save("tile_2x.png")
 ```
 
 ## Training
 
-Trained on DIV2K (800 training images) with L1 loss and random augmentation (flips, rotations). Total training cost: ~$6 on RunPod A6000 instances. Full training journey documented from 33.46 dB to 37.54 dB across 12 experiment findings.
+Trained on LSDIR + DIV2K (85,791 images) with L1 + wavelet (SWT) loss, random flips and rotations, and progressive patch sizes (64 → 128 px). Urban100's 100 test images were also included in the training data by mistake, so no Urban100 score is reported. Total training cost: ~$6 on RunPod A6000 instances. Full training journey documented from 33.46 dB to 37.54 dB across 12 experiment findings.
 
 ## Technical Details
 
 - **Compute units:** `.cpuAndNeuralEngine` (ANE primary, CPU for I/O only)
 - **Precision:** Float16
-- **Input format:** NCHW, normalized to [0, 1]
-- **Output format:** NCHW, [0, 1]
-- **Model size:** 928 KB (compiled .mlmodelc)
+- **Input format:** RGB image for the tile models; NCHW float array in [0, 1] for the video model
+- **Output format:** RGB image for the tile models; NCHW float array in [0, 1] for the video model
+- **Model size:** 928 KB (`PiperSR_2x.mlpackage`)
 - **Parameters:** 453K
-- **ANE ops used:** conv, batch_norm (fused at inference), silu, add, pixel_shuffle, const
-- **CPU fallback ops:** None
+- **ANE ops used:** conv (BatchNorm fused), silu, add, pixel_shuffle, clip
+- **CPU fallback ops:** None in the network. The tile models scale the input image on CPU
 
 ## License
 
@@ -194,16 +208,18 @@ Powered by PiperSR from ModelPiper — https://modelpiper.com
 
 ## Links
 
+- **ToolPiper Studio:** https://modelpiper.com
 - **GitHub:** https://github.com/ModelPiper/PiperSR
-- **ModelPiper:** https://modelpiper.com
+- **PyPI:** https://pypi.org/project/pipersr/
 
 ## Citation
 
 ```bibtex
-@software{pipersr2025,
-  title={PiperSR: ANE-Native Super Resolution for Apple Silicon},
-  author={ModelPiper},
-  year={2026},
-  url={https://huggingface.co/ModelPiper/PiperSR-2x}
+@software{pipersr2026,
+  author = {Racicot, Ben},
+  title = {PiperSR: Real-Time Super-Resolution for Apple Neural Engine},
+  year = {2026},
+  url = {https://github.com/ModelPiper/PiperSR},
+  note = {453K parameters, 928 KB CoreML. Available at https://modelpiper.com}
 }
 ```