Oxicloud/benches/BASELINE.md

# Thumbnail performance — Phase 0 baseline

> **Phase 1.1 (shrink-on-load) is now merged — see "Phase 1.1 results" at the
> bottom for the before/after.** The tables below remain the Phase 0 baseline
> (the "before").

The "before" numbers every later phase must beat. Captured on **14 cores** with
the current `image` 0.25 pipeline (`render_thumbnail_from_data` /
`render_all_thumbnails_from_data` in
`src/infrastructure/services/thumbnail_service.rs`).

> Heap = logical allocation high-water mark (counting allocator), not RSS.
> The synthetic corpus is high-entropy (gradient + noise), so JPEG sizes and
> decode work are realistic-to-slightly-pessimistic. Drop real photos into
> `benches/corpus/` (same filenames) to re-baseline on real data.

## Reproduce

```bash
# Peak RAM + saturated throughput (Task 0.3) → target/bench-baseline-fase0.json
cargo run --release --features bench --example bench_thumbnails_mem

# Per-size latency + output bytes (Task 0.2) → target/criterion/report/index.html
cargo bench --features bench           # do NOT pipe through `tail` — it truncates the log;
                                       # results are saved under target/criterion/ regardless
```

## A. Per-image — peak heap, single-thread latency, output size

| case             | fmt  |   source  |   MP | render_all ms | peak heap MB | out KB (3 sizes) |
|------------------|------|-----------|-----:|--------------:|-------------:|-----------------:|
| jpeg_12mp        | jpeg | 4000×3000 | 12.0 |        111.30 |         96.1 |               57 |
| jpeg_24mp        | jpeg | 6000×4000 | 24.0 |        207.23 |        151.0 |               41 |
| jpeg_48mp        | jpeg | 8000×6000 | 48.0 |        397.67 |        260.9 |               38 |
| jpeg_exif_orient | jpeg | 4000×3000 | 12.0 |        121.82 |        107.6 |               59 |
| png_large        | png  | 3000×2000 |  6.0 |         34.36 |         58.4 |               63 |
| webp_large       | webp | 1280×853  |  1.1 |         21.05 |         20.7 |              113 |
| gif_large        | gif  | 600×600   |  0.4 |         12.86 |         15.4 |              232 |
| small_300        | jpeg | 300×300   |  0.1 |          9.94 |          8.0 |              184 |

## B. Saturated throughput (14 threads, 3 s window)

| case      |   source  |   MP | photos/sec | eff ms/photo |
|-----------|-----------|-----:|-----------:|-------------:|
| jpeg_12mp | 4000×3000 | 12.0 |       44.4 |        22.52 |
| jpeg_24mp | 6000×4000 | 24.0 |       25.3 |        39.51 |
| jpeg_48mp | 8000×6000 | 48.0 |       12.4 |        80.49 |

Scaling is sub-linear (14 threads ≈ 4.9× single-thread): memory-bandwidth bound
(moving 96–261 MB per decode) + rayon oversubscription (each caller thread fans
3 sizes onto the shared rayon pool).

## C. Per-size latency — criterion median ms (one size in isolation vs all-three)

| case             | Icon ms | Preview ms | Large ms | all-3 ms | Large/all |
|------------------|--------:|-----------:|---------:|---------:|----------:|
| jpeg_12mp        |   75.42 |      97.17 |   106.30 |   107.11 |     99.3% |
| jpeg_24mp        |  148.65 |     190.05 |   200.70 |   203.44 |     98.7% |
| jpeg_48mp        |  303.31 |     375.33 |   386.04 |   391.24 |     98.7% |
| jpeg_exif_orient |   90.68 |     122.57 |   119.27 |   119.33 |    100.0% |
| png_large        |   13.32 |      25.87 |    32.26 |    32.59 |     99.0% |
| webp_large       |   15.83 |      19.51 |    24.47 |    24.45 |    100.1% |
| gif_large        |    2.28 |       5.15 |    12.94 |    12.92 |    100.2% |
| small_300        |    0.85 |       3.22 |     9.94 |     9.92 |    100.2% |

## Key findings (these steer Phase 1)

1. **Decode dominates: 70–99 % of total time.** For jpeg_12mp, rendering all
   three sizes (107 ms) costs barely more than rendering Icon alone (75 ms) —
   the full-resolution decode is the shared cost; per-size resize+encode is
   cheap on top. ⇒ **Shrink-on-load (Task 1.1) is the single biggest lever**,
   bigger than first estimated.

2. **Peak heap scales linearly with megapixels** (~2× the RGBA bitmap):
   12 MP→96 MB, 48 MP→261 MB. With the real `cpus/2` semaphore that is up to
   7×261 MB ≈ 1.8 GB on a 48 MP burst — the OOM ceiling that caps concurrency.
   Shrink-on-load collapses this ~16× and unlocks Task 1.5 (raise the semaphore).

3. **Task 2.1 "defer Large" is now DROPPED — the benchmark refutes it.**
   Because all three sizes share one decode (Large/all ≈ 99 %), deferring Large
   saves ~9 ms eager but forces a *second full decode* (~106 ms) when the
   lightbox opens — it roughly **doubles** total decode work. Keep generating
   all sizes in one pass.

4. **No-upscale (Task 1.4) confirmed minor:** small_300's Large (9.9 ms)
   upscales 300→800; clamping recovers a few ms and avoids artefacts.

5. **PNG/GIF/WebP get no DCT shrink-on-load** — only `fast_image_resize`
   (Task 1.2) speeds their resize portion.

---

# Phase 1.1 results — shrink-on-load (DCT scale-on-decode for JPEG)

Implemented via `jpeg-decoder` in `decode_oriented` / `decode_jpeg_scaled`
(`src/infrastructure/services/thumbnail_service.rs`). The JPEG decoder now emits
the image at the smallest DCT scale (1/8·1/4·1/2·1/1) whose long axis is still ≥
the largest needed thumbnail (800 px), so the full-resolution bitmap is never
materialised. Non-JPEG and unusual JPEG colour spaces fall back to a full decode.
Same machine (14 cores), same corpus.

### Latency — `render_all`, single thread (ms)

| case      | before | after  | speedup |
|-----------|-------:|-------:|--------:|
| jpeg_12mp | 111.30 |  60.64 |  1.84×  |
| jpeg_24mp | 207.23 | 113.71 |  1.82×  |
| jpeg_48mp | 397.67 | 202.88 |  1.96×  |
| jpeg_exif | 121.82 |  60.12 |  2.03×  |
| png_large |  34.36 |  33.67 |  ~1×  (no DCT, expected) |

### Peak heap per decode (MB) — the headline win

| case      | before | after | reduction |
|-----------|-------:|------:|----------:|
| jpeg_12mp |   96.1 |  17.6 |   5.5×  |
| jpeg_24mp |  151.0 |  24.9 |   6.1×  |
| jpeg_48mp |  260.9 |  17.6 |  14.8×  |
| jpeg_exif |  107.6 |  18.9 |   5.7×  |

Peak heap is now **decoupled from source resolution** (~18–25 MB regardless of
MP — bounded by the 800 px decode, not the original). 48 MP now uses *less* than
24 MP because it hits the 1/8 scale (1000×750) vs 24 MP's 1/4 (1500×1000).

### Saturated throughput (14 threads, photos/sec)

| case      | before | after | speedup |
|-----------|-------:|------:|--------:|
| jpeg_12mp |   44.4 | 140.8 |  3.17×  |
| jpeg_24mp |   25.3 |  74.7 |  2.95×  |
| jpeg_48mp |   12.4 |  45.3 |  3.65×  |

Throughput improved **more** than single-thread latency (3.2× vs 1.8× at 12 MP):
parallel efficiency rose from ~4.9× to ~8.5× across 14 threads because the 16×
smaller decode buffers relieve the memory-bandwidth ceiling.

### Quality gate — shrink-on-load vs full decode (Preview 400 px)

| case      | SSIM   | PSNR dB |
|-----------|-------:|--------:|
| jpeg_12mp | 0.9875 |   47.42 |
| jpeg_24mp | 0.9927 |   48.91 |
| jpeg_48mp | 0.9939 |   49.37 |
| small_300 | 0.9995 |   55.17 |

All **SSIM ≥ 0.98** (acceptance criterion met) and PSNR 47–55 dB (>40 dB =
visually indistinguishable). Output bytes unchanged (e.g. 12 MP: 57→58 KB).

### Follow-ups this unlocked
- **Task 1.5** (raise `cpus/2` → `cpus`): peak heap no longer scales with MP, so
  the OOM ceiling that justified halving concurrency is largely gone. ✅ done below.
- The `MAX_DECODE_PIXELS` 50 MP reject could be relaxed — huge JPEGs now decode
  cheaply at 1/8 — but that is a behaviour change, deferred.

---

# Phase 1.5 results — raise decode-concurrency cap (`cpus/2` → `cpus`)

`max_concurrent_decodes()` now defaults to all cores (was half), overridable via
`OXICLOUD_THUMBNAIL_DECODE_CONCURRENCY`. Safe only because Phase 1.1 decoupled
peak heap from source resolution.

Measured with a harness that mirrors the **real service path** (Table D:
`tokio::Semaphore(permits)` + `spawn_blocking`, many concurrent requests),
14 cores, 3 s window:

| case      | 7 permits (`cpus/2`, old) | 14 permits (`cpus`, new) | 28 (`cpus*2`) |
|-----------|--------------------------:|-------------------------:|--------------:|
| jpeg_12mp |                      92.7 |          **133.7 (1.44×)** | 133.3 (—) |
| jpeg_24mp |                      49.5 |           **69.9 (1.41×)** | 71.1 (+1.7%) |

- **~1.4× throughput** on the real path, for free; peak heap unchanged (17–25 MB).
- `cpus*2` yields nothing → `cpus` is the right ceiling for CPU-bound work.
- It's 1.4× not 2× because `render_all` fans its 3 sizes onto rayon, so 7 permits
  already partly fill all cores — the remaining headroom is **Task 1.7**
  (rayon oversubscription).

---

# Phase 1.2 results — SIMD resize (`fast_image_resize`, Lanczos3)

Replaced the `image` crate's scalar resampler with `fast_image_resize`
(AVX2/SSE4.1/NEON) in the shared `encode_thumbnail` helper; `render_all` now
converts to RGB8 once and SIMD-resizes the shared buffer per size. Lanczos3 for
downscaling, CatmullRom when upscaling (avoids Lanczos ringing). Also folded the
duplicated path-variant `generate_all_sizes_background` into the shared render
path, so it too gets shrink-on-load + SIMD. "before" = post-1.5 state.

### Single-thread latency `render_all` (ms) and peak heap (MB)

| case      | ms before | ms after | speedup | heap before | heap after |
|-----------|----------:|---------:|--------:|------------:|-----------:|
| jpeg_12mp |     60.89 |    56.46 |  1.08×  |        17.6 |    **7.1** |
| jpeg_24mp |    113.98 |   106.76 |  1.07×  |        24.9 |   **10.1** |
| jpeg_48mp |    203.29 |   198.75 |  1.02×  |        17.6 |    **7.1** |
| **png_large** | 33.63 | **12.92** | **2.60×** |    58.4 |   **27.1** |
| gif_large |     12.93 |     7.99 |  1.62×  |        15.4 |        5.9 |
| webp_large|     21.15 |    16.89 |  1.25×  |        20.7 |        8.3 |
| small_300 |     10.64 |     6.37 |  1.67×  |         8.0 |        3.9 |

- **JPEG: only ~6–8 %** — shrink-on-load already shrank the decoded bitmap, so
  the resize was a small slice of the time. But **peak heap fell another ~2.5×**
  (7 MB): fir works on tight RGB buffers with no intermediate `DynamicImage`,
  and RGB conversion now happens once instead of per size.
- **PNG: 2.6×** (and GIF/WebP 1.25–1.6×) — exactly as predicted: these decode at
  full resolution (no DCT shrink), so the SIMD resize dominates the win.

### Throughput (≈ +10–15 %, run-to-run noisy)

Saturated 12 MP ≈ 142→157 photos/s; semaphore-bounded 12 MP @ 14 permits
≈ 134→148. Directionally up; treat as noise-bounded.

### Quality gate (vs full-decode CatmullRom at identical dims)

| case      | SSIM   | PSNR dB |
|-----------|-------:|--------:|
| jpeg_12mp | 0.9865 |   47.21 |
| jpeg_24mp | 0.9923 |   48.73 |
| jpeg_48mp | 0.9938 |   49.33 |
| small_300 | 0.9921 |   42.59 |

All **≥ 0.98**. (The upscale case `small_300` needed the Lanczos3→CatmullRom
upscale rule — Lanczos rings when enlarging; it was 0.954 before that fix.)

### Note
Output thumbnails are now exactly `max_dim` on the long side (e.g. 400×266),
vs the old `image::resize` fit-within which produced 399×266 — a ≤1 px change,
invisible under the frontend's `object-fit: cover`.

---

# Phase 1.7 — TESTED AND REVERTED (rayon oversubscription)

Hypothesis: `render_all`'s internal `par_iter` over the 3 sizes oversubscribes
the global rayon pool under load (cpus×3 tasks), capping burst throughput.
Tested by resizing the 3 sizes **sequentially** (parallelism across images
only). Measured before/after on 14 cores, two runs each:

| metric                       | before (par_iter) | after (sequential) | verdict |
|------------------------------|------------------:|-------------------:|---------|
| **PNG single-image latency** |          12.9 ms  |       **21.3 ms**  | **−66 % WORSE** |
| JPEG 12 MP single-image      |          57.8 ms  |          58.5 ms   | neutral |
| Saturated 12 MP (photos/s)   |            155.8  |        170 / 158   | flat (noise) |
| Semaphore @14 12 MP          |            157.7  |        164 / 157   | flat |
| Semaphore @28 12 MP          |            160.4  |        162 / 159   | flat |

**Verdict: reverted.** Throughput at the real operating point (14 permits) is
flat — rayon oversubscription was **not** the bottleneck. The "1.4× not 2×" of
Phase 1.5 is the single-threaded JPEG decode (which dominates post-shrink) plus
memory bandwidth, not rayon scheduling; even 28 concurrent renders (84 rayon
tasks) show no thrash. Meanwhile full-decode formats (PNG) regressed 66 % on
single-image latency because their resize-from-full-resolution genuinely
benefits from the per-image parallelism. Net negative → kept `par_iter`.

(Another "measure before believing" result, like the dropped Task 2.1.)