Add Gradio head-to-head baseline (V1/V2/V3) and bench Space entrypoint

- app_gradio_baseline.py: three idiomatic Gradio variants (V1/V2/V3)
exposing the three failure modes claimed in the paper.
- bench_gradio_baseline.py: headless 9-call benchmark across all variants,
emits CSV + per-variant summary table.
- app_bench_space.py: HF Space entrypoint with browser UI for
reproducibility (used by the voxpixel-baseline Space).
- prepare_runpod.sh: alternative RunPod bootstrap script.
- Dockerfile: switch CMD to use APP_FILE env var (defaults to app.py;
backward compatible with the production Space).
- .gitignore: exclude patient data (Test Images/), build artifacts,
benchmark outputs, and Paper.tex.

.gitignore

@@ -1,3 +1,24 @@
 SRMA-Mamba/selective_scan/build/
 *.so
 *.o
+
+# Patient data and benchmark outputs (must not be committed)
+Test Images/
+gradio_baseline_results.csv
+v2_pred.nii.gz
+v3_pred.nii.gz
+
+# Python build/cache artifacts
+__pycache__/
+*.pyc
+*.pyo
+
+# Research paper / LaTeX build artifacts (kept local only)
+Paper.tex
+*.aux
+*.log
+*.out
+*.synctex.gz
+*.bbl
+*.blg
+*.toc

Dockerfile

@@ -95,4 +95,5 @@ PY
 
 EXPOSE 7860
 
-CMD ["python", "app.py"]
+ENV APP_FILE=app.py
+CMD ["sh", "-c", "exec python ${APP_FILE}"]

README.md

@@ -1086,6 +1086,66 @@ If you use LiverProfile AI in your research, please cite:
 }
 ```
 
+## Reproducing the Gradio head-to-head baseline (paper Section V)
+
+The accompanying paper compares VoxPixel against three idiomatic Gradio
+configurations on the same SRMA-Mamba checkpoints, the same volumes, and
+the same GPU. The comparison is fully reproducible from this repository.
+
+### Files
+
+- `app_gradio_baseline.py` — three Gradio variants in one file:
+  - **V1** (`gr.Image`): demonstrates that NIfTI ingestion is not
+    supported by the default image component.
+  - **V2** (`gr.File` + naive single-shot full-volume forward pass):
+    demonstrates CUDA OOM on full 3D volumes when no sliding-window
+    aggregator is wired in.
+  - **V3** (`gr.File` + manually-wired MONAI `SlidingWindowInferer`):
+    demonstrates that even with sliding-window inference, the naive
+    Gradio I/O contract drops the NIfTI affine, biasing the reported
+    liver volume in ml.
+- `bench_gradio_baseline.py` — headless benchmark that runs the same
+  9-call protocol used for VoxPixel (Table III) for each variant and
+  writes a CSV.
+
+### Launch a single variant interactively
+
+```bash
+python app_gradio_baseline.py --variant v1   # try uploading .nii.gz; rejected
+python app_gradio_baseline.py --variant v2   # full-volume single-shot
+python app_gradio_baseline.py --variant v3   # + sliding window
+```
+
+### Run the 9-call benchmark across all three variants
+
+```bash
+python bench_gradio_baseline.py \
+    --volumes ./test_volumes/56.nii.gz \
+              ./test_volumes/58.nii.gz \
+              ./test_volumes/60.nii.gz \
+    --trials 3 \
+    --modality T1 \
+    --out gradio_baseline_results.csv
+```
+
+This produces 27 rows (3 variants × 3 volumes × 3 trials) in
+`gradio_baseline_results.csv`, plus a printed per-variant summary
+table whose columns map directly to the head-to-head table in the
+paper:
+
+| Column | Meaning |
+| --- | --- |
+| `status` | `OK`, `OOM`, `UI_REJECT`, or `ERROR` |
+| `runtime_s` | End-to-end inference time |
+| `peak_vram_gb` | Peak `torch.cuda.max_memory_allocated()` |
+| `naive_volume_ml` | Liver volume computed under the identity affine the naive Gradio app writes to disk (the value a downstream user would see) |
+| `true_volume_ml` | Liver volume computed under the original NIfTI affine (the spatially-correct value, which Gradio loses) |
+| `voxpixel_volume_ml` | The corresponding VoxPixel value from Table III |
+| `abs_err_naive_vs_voxpixel_ml` | Affine-loss bias in ml |
+
+Run on the same GPU as your VoxPixel measurements so the comparison is
+apples-to-apples.
+
 ## Disclaimer
 
 **Important**: This software is intended for **research purposes only**. It is not approved for clinical use or diagnostic purposes without proper validation and regulatory approval. Always consult with qualified medical professionals for clinical decision-making.

app_bench_space.py

@@ -0,0 +1,280 @@
+"""
+Hugging Face Space entrypoint: head-to-head Gradio baseline benchmark
+for the VoxPixel paper (Section V).
+
+This is a SEPARATE Space from the production VoxPixel app. Same repo,
+same Dockerfile, same dependencies; the entrypoint is selected by the
+APP_FILE environment variable in the Space's "Variables and secrets"
+settings (set APP_FILE=app_bench_space.py for this Space).
+
+Purpose: let any reviewer reproduce the V1/V2/V3 vs. VoxPixel head-to-
+head comparison from the browser. Upload one or more NIfTI volumes,
+choose how many trials per volume, click "Run benchmark"; the app runs
+the same protocol used in Table III of the paper, displays a summary
+inline, and writes a downloadable CSV.
+
+Failure modes the experiment exposes (paper Section II / V):
+    V1: gr.Image rejects .nii / .nii.gz at upload (NIfTI ingestion).
+    V2: single-shot full-volume forward pass -> CUDA OOM (no sliding window).
+    V3: + manually-wired MONAI sliding window, but the output mask
+        is written with affine = identity, biasing liver volume in ml
+        (no spatial-metadata round-trip in the Gradio I/O contract).
+"""
+
+import csv
+import gc
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+import gradio as gr
+import torch
+
+from app_gradio_baseline import predict_v2, predict_v3
+from bench_gradio_baseline import (
+    VOXPIXEL_TRUTH_ML,
+    run_v1,
+    run_with_safety,
+)
+
+
+CSV_FIELDS = [
+    "variant", "trial", "volume", "size_mb",
+    "status", "runtime_s", "peak_vram_gb",
+    "voxel_count", "naive_volume_ml", "true_volume_ml",
+    "voxpixel_volume_ml", "abs_err_naive_vs_voxpixel_ml",
+    "error",
+]
+
+
+def _file_path(file_obj) -> str:
+    """Gradio 4.x returns a list of objects with .name; older versions
+    sometimes pass a path string directly. Handle both defensively."""
+    return getattr(file_obj, "name", str(file_obj))
+
+
+def _row(variant: str, trial: int, vol_path: str, res: dict) -> dict:
+    vol_name = Path(vol_path).name
+    size_mb = round(os.path.getsize(vol_path) / (1024 ** 2), 2)
+    naive_ml = res.get("naive_volume_ml")
+    voxpixel = VOXPIXEL_TRUTH_ML.get(vol_name)
+    if (voxpixel is not None and naive_ml is not None
+            and naive_ml == naive_ml):  # NaN check
+        abs_err = abs(naive_ml - voxpixel)
+    else:
+        abs_err = float("nan")
+    return {
+        "variant": variant,
+        "trial": trial,
+        "volume": vol_name,
+        "size_mb": size_mb,
+        "status": res.get("status", "?"),
+        "runtime_s": round(res.get("runtime_s", 0.0), 3),
+        "peak_vram_gb": round(res.get("peak_vram_gb", 0.0), 2),
+        "voxel_count": res.get("voxel_count", 0),
+        "naive_volume_ml": naive_ml,
+        "true_volume_ml": res.get("true_volume_ml"),
+        "voxpixel_volume_ml": voxpixel,
+        "abs_err_naive_vs_voxpixel_ml": abs_err,
+        "error": res.get("error", ""),
+    }
+
+
+def _summary_markdown(rows: list) -> str:
+    by_variant: dict = {}
+    for r in rows:
+        v = r["variant"]
+        d = by_variant.setdefault(v, {
+            "n": 0, "ok": 0, "oom": 0, "ui_reject": 0, "err": 0,
+            "rt_sum": 0.0, "vram_max": 0.0,
+            "naive_err_sum": 0.0, "naive_err_n": 0,
+        })
+        d["n"] += 1
+        s = r["status"]
+        if s == "OK":
+            d["ok"] += 1
+            d["rt_sum"] += r["runtime_s"]
+            d["vram_max"] = max(d["vram_max"], r["peak_vram_gb"])
+            err = r["abs_err_naive_vs_voxpixel_ml"]
+            if err == err:
+                d["naive_err_sum"] += err
+                d["naive_err_n"] += 1
+        elif s == "OOM":
+            d["oom"] += 1
+        elif s == "UI_REJECT":
+            d["ui_reject"] += 1
+        else:
+            d["err"] += 1
+
+    lines = [
+        "### Per-variant summary",
+        "",
+        "| Variant | Success / Total | OOM | UI reject | Other err | "
+        "Mean runtime (s) | Peak VRAM (GB) | "
+        "Mean \\|naive − VoxPixel\\| (ml) |",
+        "|---|---|---|---|---|---|---|---|",
+    ]
+    for v, d in by_variant.items():
+        mean_rt = (d["rt_sum"] / d["ok"]) if d["ok"] else float("nan")
+        mean_err = (
+            (d["naive_err_sum"] / d["naive_err_n"])
+            if d["naive_err_n"] else float("nan")
+        )
+        lines.append(
+            f"| **{v}** | {d['ok']}/{d['n']} | {d['oom']} | {d['ui_reject']} "
+            f"| {d['err']} | {mean_rt:.2f} | {d['vram_max']:.2f} "
+            f"| {mean_err:.2f} |"
+        )
+    return "\n".join(lines)
+
+
+def _table_data(rows: list) -> list:
+    return [
+        [r["variant"], r["trial"], r["volume"], r["size_mb"],
+         r["status"], r["runtime_s"], r["peak_vram_gb"],
+         r["voxel_count"], r["naive_volume_ml"], r["true_volume_ml"],
+         r["voxpixel_volume_ml"], r["abs_err_naive_vs_voxpixel_ml"]]
+        for r in rows
+    ]
+
+
+def run_benchmark(files, trials: int, modality: str,
+                  progress=gr.Progress()):
+    if not files:
+        return ("**Please upload at least one .nii / .nii.gz volume.**",
+                None, None, "")
+
+    paths = [_file_path(f) for f in files]
+    log_lines: list = []
+
+    progress(0.0, desc="Loading model...")
+    try:
+        from app_gradio_baseline import _get_model
+        _get_model(modality)
+    except Exception as e:
+        return (f"**Failed to load model: {e}**\n\n"
+                "Check that the Space hardware has a GPU and that "
+                "mamba_ssm / selective_scan_cuda_oflex built successfully.",
+                None, None, "")
+
+    log_lines.append(
+        f"Model loaded ({modality}). Hardware: "
+        f"{torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU'}"
+    )
+
+    rows: list = []
+    runners = [
+        ("V1", lambda p, m: run_v1(p, m)),
+        ("V2", lambda p, m: run_with_safety(predict_v2, p, m)),
+        ("V3", lambda p, m: run_with_safety(predict_v3, p, m)),
+    ]
+    total_calls = len(paths) * trials * len(runners)
+    done = 0
+
+    for vol_path in paths:
+        vol_name = Path(vol_path).name
+        for variant, runner in runners:
+            for trial in range(1, int(trials) + 1):
+                msg = (f"[{variant}] trial {trial}/{int(trials)} on "
+                       f"{vol_name}")
+                log_lines.append(msg)
+                progress(done / total_calls, desc=msg)
+                res = runner(vol_path, modality)
+                rows.append(_row(variant, trial, vol_path, res))
+                done += 1
+                if torch.cuda.is_available():
+                    torch.cuda.empty_cache()
+                gc.collect()
+
+    csv_path = os.path.join(
+        tempfile.gettempdir(), "gradio_baseline_results.csv"
+    )
+    with open(csv_path, "w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=CSV_FIELDS)
+        w.writeheader()
+        w.writerows(rows)
+
+    summary_md = _summary_markdown(rows)
+    return summary_md, _table_data(rows), csv_path, "\n".join(log_lines)
+
+
+with gr.Blocks(title="VoxPixel — Head-to-Head Gradio Baseline") as demo:
+    gr.Markdown("""
+# VoxPixel — Head-to-Head Gradio Baseline (paper §V)
+
+This Space reproduces the head-to-head experiment between three idiomatic
+Gradio configurations and the production VoxPixel deployment, using the
+**same SRMA-Mamba checkpoints** and the **same protocol** as Table III of
+the paper.
+
+| Variant | What it implements | Failure mode demonstrated |
+| --- | --- | --- |
+| **V1** | `gr.Image` interface | NIfTI ingestion not supported by Gradio's image components |
+| **V2** | `gr.File` + nibabel + single-shot full-volume forward pass | CUDA OOM on full 3D volumes (no sliding window) |
+| **V3** | `gr.File` + nibabel + manually-wired MONAI `SlidingWindowInferer` | Spatial metadata loss — output mask written with `affine = identity`, biasing liver volume in ml |
+
+Upload one or more `.nii / .nii.gz` volumes, choose trials per volume, and
+click **Run benchmark**. Three trials per volume across three volumes
+reproduces the 9-call protocol used for VoxPixel.
+
+Reference values for the affine-loss bias column come from VoxPixel
+runs in the paper:
+""")
+    gr.Markdown(
+        "\n".join(
+            f"- `{k}` → **{v:.2f} ml** (VoxPixel)"
+            for k, v in VOXPIXEL_TRUTH_ML.items()
+        )
+    )
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            files = gr.File(
+                label="NIfTI volumes (.nii / .nii.gz)",
+                file_count="multiple",
+                file_types=[".nii", ".gz"],
+            )
+            trials = gr.Slider(
+                label="Trials per volume",
+                minimum=1, maximum=5, value=3, step=1,
+            )
+            modality = gr.Radio(
+                label="Modality",
+                choices=["T1", "T2"], value="T1",
+            )
+            run_btn = gr.Button(
+                "Run head-to-head benchmark", variant="primary",
+            )
+            gr.Markdown(
+                "First run takes ~30–60 s extra to load the model. "
+                "Each V2/V3 trial typically takes 2–5 s on an L40S."
+            )
+
+        with gr.Column(scale=3):
+            summary_md = gr.Markdown(label="Summary")
+            results_df = gr.Dataframe(
+                headers=[
+                    "variant", "trial", "volume", "size_mb",
+                    "status", "runtime_s", "peak_vram_gb",
+                    "voxel_count", "naive_volume_ml", "true_volume_ml",
+                    "voxpixel_volume_ml", "abs_err_naive_vs_voxpixel_ml",
+                ],
+                label="Per-run results",
+                wrap=True,
+            )
+            csv_file = gr.File(label="Download results CSV")
+            log_box = gr.Textbox(label="Log", lines=10)
+
+    run_btn.click(
+        fn=run_benchmark,
+        inputs=[files, trials, modality],
+        outputs=[summary_md, results_df, csv_file, log_box],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", "7860")),
+    )

app_gradio_baseline.py

@@ -0,0 +1,367 @@
+"""
+Head-to-head Gradio baseline for the VoxPixel paper (Section V).
+
+This file deliberately implements the SRMA-Mamba liver segmentation model
+in three idiomatic Gradio configurations to expose, on the same hardware
+and with the same checkpoints used by VoxPixel, the three failure modes
+called out by reviewers:
+
+    V1: gr.Image(...)            -> failure mode 1: NIfTI ingestion not
+                                    supported. The component rejects
+                                    .nii / .nii.gz at upload time.
+
+    V2: gr.File + nibabel +      -> failure mode 3: CUDA OOM. A single
+        single-shot full-volume     forward pass on the full 3D volume
+        forward pass.               exceeds GPU memory on standard scans
+                                    because no sliding-window aggregator
+                                    is available out of the box.
+
+    V3: gr.File + nibabel +      -> failure mode 2: spatial metadata
+        manually-wired MONAI        loss. Inference succeeds, but the
+        SlidingWindowInferer.       output mask is written with
+                                    affine = identity because Gradio's
+                                    I/O contract does not preserve the
+                                    NIfTI affine. Reported liver volume
+                                    in ml is therefore biased relative
+                                    to the spatially-correct VoxPixel
+                                    output.
+
+This is NOT a production app. See app.py for VoxPixel itself. This file
+exists so reviewers can reproduce the head-to-head table in the paper.
+
+Usage (interactive):
+    python app_gradio_baseline.py --variant v1
+    python app_gradio_baseline.py --variant v2
+    python app_gradio_baseline.py --variant v3
+
+Usage (programmatic, called by bench_gradio_baseline.py):
+    from app_gradio_baseline import predict_v2, predict_v3
+"""
+
+import os
+import sys
+import time
+import argparse
+from pathlib import Path
+
+import numpy as np
+import torch
+import nibabel as nib
+import gradio as gr
+
+
+_model_cache: dict = {}
+
+
+def _load_bare_model(modality: str = "T1") -> torch.nn.Module:
+    """Load architecture + checkpoint with no sliding-window inferer,
+    no warm-up, no torch.compile, no channels-last layout. This is what
+    a researcher writing a naive Gradio wrapper would produce."""
+    # Imported lazily so V1 (which never calls this) can run on a laptop
+    # without mamba_ssm / selective_scan_cuda_oflex installed.
+    from config import (
+        build_SRMAMamba,
+        BUILD_SRMAMAMBA_AVAILABLE,
+        SRMA_MAMBA_DIR,
+    )
+
+    if not BUILD_SRMAMAMBA_AVAILABLE or build_SRMAMamba is None:
+        raise ImportError(
+            "SRMA-Mamba builder not available. Run setup.sh / install "
+            "mamba_ssm and selective_scan_cuda_oflex first."
+        )
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    if SRMA_MAMBA_DIR:
+        original_cwd = os.getcwd()
+        try:
+            os.chdir(SRMA_MAMBA_DIR)
+            model = build_SRMAMamba()
+        finally:
+            os.chdir(original_cwd)
+    else:
+        model = build_SRMAMamba()
+
+    ckpt_path = f"checkpoint_{modality}.pth"
+    if not os.path.exists(ckpt_path):
+        local = os.path.join(os.path.dirname(__file__), ckpt_path)
+        if os.path.exists(local):
+            ckpt_path = local
+        else:
+            from huggingface_hub import hf_hub_download
+            repo_id = os.environ.get(
+                "HF_MODEL_REPO", "HarshithReddy01/srmamamba-liver-segmentation"
+            )
+            ckpt_path = hf_hub_download(
+                repo_id=repo_id, filename=f"checkpoint_{modality}.pth", cache_dir="."
+            )
+
+    ckpt = torch.load(ckpt_path, map_location=device)
+    state = (
+        ckpt["state_dict"]
+        if isinstance(ckpt, dict) and "state_dict" in ckpt
+        else ckpt
+    )
+    model.load_state_dict(state)
+    model.eval().to(device)
+    return model
+
+
+def _get_model(modality: str = "T1") -> torch.nn.Module:
+    if modality not in _model_cache:
+        _model_cache[modality] = _load_bare_model(modality)
+    return _model_cache[modality]
+
+
+def _normalize(vol: np.ndarray) -> np.ndarray:
+    """Z-score normalization over nonzero voxels. Mirrors what
+    NormalizeIntensityd(nonzero=True) does in the VoxPixel pipeline,
+    inlined here so the comparison is about deployment, not preprocessing."""
+    vol = vol.astype(np.float32)
+    nz = vol[vol > 1e-6]
+    if nz.size == 0:
+        return vol
+    mu = float(nz.mean())
+    sigma = float(nz.std()) + 1e-8
+    out = np.where(vol > 1e-6, (vol - mu) / sigma, 0.0)
+    return out.astype(np.float32)
+
+
+def _threshold_for(modality: str) -> float:
+    if modality.upper() == "T1":
+        return float(os.environ.get("T1_THRESHOLD", "0.65"))
+    return float(os.environ.get("SEGMENTATION_THRESHOLD", "0.5"))
+
+
+def _summary(img: nib.Nifti1Image, mask: np.ndarray, t0: float) -> dict:
+    """Build the result record. naive_volume_ml uses the identity affine
+    that the V2/V3 predict() functions write to disk; true_volume_ml uses
+    the original affine the researcher should have preserved."""
+    runtime = time.time() - t0
+    if torch.cuda.is_available():
+        peak = torch.cuda.max_memory_allocated() / (1024 ** 3)
+    else:
+        peak = 0.0
+    voxels = int(mask.sum())
+    naive_ml = voxels / 1000.0
+    true_voxel_mm3 = abs(float(np.linalg.det(img.affine[:3, :3])))
+    true_ml = voxels * true_voxel_mm3 / 1000.0
+    return {
+        "status": "OK",
+        "runtime_s": runtime,
+        "peak_vram_gb": peak,
+        "voxel_count": voxels,
+        "naive_volume_ml": naive_ml,
+        "true_volume_ml": true_ml,
+    }
+
+
+def predict_v2(nifti_path: str, modality: str = "T1") -> dict:
+    """V2: gr.File + nibabel + single-shot full-volume forward pass.
+
+    Demonstrates failure mode 3 (CUDA OOM on full volumes) and, when the
+    forward pass does fit, failure mode 2 (output mask written with
+    identity affine, losing voxel spacing)."""
+    t0 = time.time()
+    if torch.cuda.is_available():
+        torch.cuda.reset_peak_memory_stats()
+        torch.cuda.empty_cache()
+
+    img = nib.load(nifti_path)
+    vol = np.asarray(img.get_fdata(dtype=np.float32))
+    norm = _normalize(vol)
+    x = torch.from_numpy(norm)[None, None].contiguous()
+
+    model = _get_model(modality)
+    device = next(model.parameters()).device
+    x = x.to(device)
+
+    with torch.no_grad():
+        if device.type == "cuda":
+            from torch.amp import autocast
+            with autocast(device_type="cuda"):
+                y_tuple = model(x)
+        else:
+            y_tuple = model(x)
+
+    y1 = y_tuple[0] if isinstance(y_tuple, (list, tuple)) else y_tuple
+    pred = torch.sigmoid(y1)[0, 0]
+    mask = (pred > _threshold_for(modality)).to(torch.uint8).cpu().numpy()
+
+    out_path = os.path.join(
+        os.path.dirname(nifti_path) or ".", "v2_pred.nii.gz"
+    )
+    nib.Nifti1Image(mask, affine=np.eye(4)).to_filename(out_path)
+
+    res = _summary(img, mask, t0)
+    res["out_path"] = out_path
+    return res
+
+
+def predict_v3(nifti_path: str, modality: str = "T1") -> dict:
+    """V3: gr.File + nibabel + manually-wired MONAI sliding window.
+
+    Inference succeeds even on full volumes, but the output is still
+    written with affine = identity, demonstrating failure mode 2."""
+    from monai.inferers import SlidingWindowInferer
+
+    t0 = time.time()
+    if torch.cuda.is_available():
+        torch.cuda.reset_peak_memory_stats()
+        torch.cuda.empty_cache()
+
+    img = nib.load(nifti_path)
+    vol = np.asarray(img.get_fdata(dtype=np.float32))
+    norm = _normalize(vol)
+    x = torch.from_numpy(norm)[None, None].contiguous()
+
+    model = _get_model(modality)
+    device = next(model.parameters()).device
+    x = x.to(device)
+
+    inferer = SlidingWindowInferer(
+        roi_size=[224, 224, 64],
+        sw_batch_size=1,
+        overlap=0.1,
+    )
+
+    def predictor(inp: torch.Tensor) -> torch.Tensor:
+        out = model(inp)
+        return out[0] if isinstance(out, (list, tuple)) else out
+
+    with torch.no_grad():
+        if device.type == "cuda":
+            from torch.amp import autocast
+            with autocast(device_type="cuda"):
+                y = inferer(x, predictor)
+        else:
+            y = inferer(x, predictor)
+
+    pred = torch.sigmoid(y)[0, 0]
+    mask = (pred > _threshold_for(modality)).to(torch.uint8).cpu().numpy()
+
+    out_path = os.path.join(
+        os.path.dirname(nifti_path) or ".", "v3_pred.nii.gz"
+    )
+    nib.Nifti1Image(mask, affine=np.eye(4)).to_filename(out_path)
+
+    res = _summary(img, mask, t0)
+    res["out_path"] = out_path
+    return res
+
+
+def _format_log(res: dict) -> str:
+    return (
+        f"voxels:                              {res['voxel_count']:,}\n"
+        f"naive volume (ml, identity affine):  {res['naive_volume_ml']:.2f}\n"
+        f"true  volume (ml, original affine):  {res['true_volume_ml']:.2f}\n"
+        f"peak VRAM (GB):                      {res['peak_vram_gb']:.2f}\n"
+        f"runtime (s):                         {res['runtime_s']:.2f}"
+    )
+
+
+def _wrap_v2(file_obj):
+    if file_obj is None:
+        return None, "Please upload a NIfTI file."
+    res = predict_v2(file_obj.name)
+    return res["out_path"], _format_log(res)
+
+
+def _wrap_v3(file_obj):
+    if file_obj is None:
+        return None, "Please upload a NIfTI file."
+    res = predict_v3(file_obj.name)
+    return res["out_path"], _format_log(res)
+
+
+def build_v1_demo() -> gr.Interface:
+    """V1: gr.Image. The component does not accept .nii / .nii.gz; the
+    upload is rejected before predict() is ever invoked. This is the
+    exact failure observed when a researcher reaches for the default
+    image component for a volumetric workflow."""
+
+    def _identity(image):
+        return image
+
+    return gr.Interface(
+        fn=_identity,
+        inputs=gr.Image(label="Upload an image (will not accept .nii.gz)"),
+        outputs=gr.Image(label="Output"),
+        title="V1: Idiomatic Gradio (gr.Image)",
+        description=(
+            "gr.Image only accepts standard 2D image formats (PNG, JPG, "
+            "TIFF). Uploading a NIfTI volume (.nii / .nii.gz) is rejected "
+            "at the upload step. This is failure mode 1 in the paper: "
+            "native NIfTI ingestion is not supported by Gradio's image "
+            "components."
+        ),
+    )
+
+
+def build_v2_demo() -> gr.Interface:
+    return gr.Interface(
+        fn=_wrap_v2,
+        inputs=gr.File(label="Upload .nii / .nii.gz"),
+        outputs=[
+            gr.File(label="Predicted mask (.nii.gz)"),
+            gr.Textbox(label="Log", lines=6),
+        ],
+        title="V2: gr.File + naive single-shot full-volume inference",
+        description=(
+            "Loads the NIfTI manually with nibabel and runs a single "
+            "forward pass on the full 3D volume. Expect CUDA OOM on "
+            "standard scans on most GPUs (failure mode 3). When inference "
+            "does succeed, the mask is written with affine=identity, so "
+            "the reported liver volume in ml has identity-affine bias "
+            "(failure mode 2)."
+        ),
+    )
+
+
+def build_v3_demo() -> gr.Interface:
+    return gr.Interface(
+        fn=_wrap_v3,
+        inputs=gr.File(label="Upload .nii / .nii.gz"),
+        outputs=[
+            gr.File(label="Predicted mask (.nii.gz)"),
+            gr.Textbox(label="Log", lines=6),
+        ],
+        title="V3: gr.File + manually-wired MONAI sliding window",
+        description=(
+            "Adds MONAI SlidingWindowInferer manually to avoid OOM. "
+            "Inference now succeeds on full volumes, but the mask is "
+            "still written with affine=identity because Gradio's I/O "
+            "contract does not preserve spatial metadata (failure mode 2)."
+        ),
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Head-to-head Gradio baseline (paper Section V)."
+    )
+    parser.add_argument(
+        "--variant", choices=["v1", "v2", "v3"], required=True,
+        help="Which baseline variant to launch.",
+    )
+    parser.add_argument("--port", type=int, default=7861)
+    parser.add_argument("--share", action="store_true")
+    args = parser.parse_args()
+
+    if args.variant == "v1":
+        demo = build_v1_demo()
+    elif args.variant == "v2":
+        demo = build_v2_demo()
+    else:
+        demo = build_v3_demo()
+
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=args.port,
+        share=args.share,
+    )
+
+
+if __name__ == "__main__":
+    main()

bench_gradio_baseline.py

@@ -0,0 +1,221 @@
+"""
+Headless benchmark for the head-to-head comparison in the VoxPixel paper
+(Section V). Runs the same nine-call protocol used for VoxPixel
+(Table III in the paper) for each of V1, V2, V3 and writes one CSV row
+per call, plus a printed summary suitable for direct inclusion in the
+paper.
+
+Usage (single command):
+
+    python bench_gradio_baseline.py \
+        --volumes ./test_volumes/56.nii.gz \
+                  ./test_volumes/58.nii.gz \
+                  ./test_volumes/60.nii.gz \
+        --trials 3 \
+        --modality T1 \
+        --out gradio_baseline_results.csv
+
+The 9 runs match the 9 VoxPixel runs in Table III. Use the same
+GPU and same checkpoints when reporting numbers.
+"""
+
+import argparse
+import csv
+import gc
+import os
+import time
+from pathlib import Path
+
+import torch
+
+# Keep this import local so the script can still print V1's deterministic
+# UI_REJECT row even if the model dependencies fail to load.
+def _load_predict_fns():
+    from app_gradio_baseline import predict_v2, predict_v3
+    return predict_v2, predict_v3
+
+
+# Reference numbers from the existing VoxPixel runs (Table III in paper).
+# Used to compute the affine-loss bias ("Δ vs. VoxPixel") in the report.
+VOXPIXEL_TRUTH_ML = {
+    "56.nii.gz": 1156.13,
+    "58.nii.gz": 896.77,
+    "60.nii.gz": 904.30,
+}
+
+
+def _classify_error(exc: BaseException) -> tuple[str, str]:
+    msg = str(exc)
+    if isinstance(exc, getattr(torch.cuda, "OutOfMemoryError", RuntimeError)):
+        if "out of memory" in msg.lower():
+            return "OOM", msg[:200]
+    if isinstance(exc, RuntimeError) and "out of memory" in msg.lower():
+        return "OOM", msg[:200]
+    return "ERROR", msg[:200]
+
+
+def run_v1(volume_path: str, modality: str) -> dict:
+    """gr.Image rejects .nii.gz before predict() is ever called.
+    Recorded deterministically without launching the UI so the row
+    is reproducible in CI."""
+    return {
+        "status": "UI_REJECT",
+        "runtime_s": 0.0,
+        "peak_vram_gb": 0.0,
+        "voxel_count": 0,
+        "naive_volume_ml": float("nan"),
+        "true_volume_ml": float("nan"),
+        "error": "gr.Image does not accept .nii / .nii.gz uploads",
+    }
+
+
+def run_with_safety(fn, volume_path: str, modality: str) -> dict:
+    try:
+        return fn(volume_path, modality=modality)
+    except BaseException as exc:
+        status, msg = _classify_error(exc)
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        gc.collect()
+        return {"status": status, "error": msg}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--volumes", nargs="+", required=True,
+                        help="Paths to NIfTI test volumes.")
+    parser.add_argument("--trials", type=int, default=3,
+                        help="Trials per (variant, volume). 3 reproduces "
+                             "the 9-call protocol in Table III.")
+    parser.add_argument("--modality", default="T1")
+    parser.add_argument("--out", default="gradio_baseline_results.csv")
+    parser.add_argument("--variants", nargs="+", default=["V1", "V2", "V3"],
+                        choices=["V1", "V2", "V3"])
+    args = parser.parse_args()
+
+    for v in args.volumes:
+        if not os.path.exists(v):
+            raise FileNotFoundError(f"Volume not found: {v}")
+
+    predict_v2 = predict_v3 = None
+    if any(v in ("V2", "V3") for v in args.variants):
+        predict_v2, predict_v3 = _load_predict_fns()
+
+    runners = {
+        "V1": lambda p, m: run_v1(p, m),
+        "V2": lambda p, m: run_with_safety(predict_v2, p, m),
+        "V3": lambda p, m: run_with_safety(predict_v3, p, m),
+    }
+
+    fields = [
+        "variant", "trial", "volume", "size_mb",
+        "status", "runtime_s", "peak_vram_gb",
+        "voxel_count", "naive_volume_ml", "true_volume_ml",
+        "voxpixel_volume_ml", "abs_err_naive_vs_voxpixel_ml",
+        "abs_err_true_vs_voxpixel_ml",
+        "error",
+    ]
+    rows: list[dict] = []
+
+    for variant in args.variants:
+        runner = runners[variant]
+        for vol_path in args.volumes:
+            vol_name = Path(vol_path).name
+            size_mb = round(os.path.getsize(vol_path) / (1024 ** 2), 2)
+            for trial in range(1, args.trials + 1):
+                print(f"[{variant}] trial {trial}/{args.trials} on {vol_name} "
+                      f"({size_mb} MB)...")
+                t0 = time.time()
+                result = runner(vol_path, args.modality)
+                elapsed = time.time() - t0
+
+                naive_ml = result.get("naive_volume_ml")
+                true_ml = result.get("true_volume_ml")
+                voxpixel = VOXPIXEL_TRUTH_ML.get(vol_name)
+
+                def _abs_err(estimate):
+                    if (voxpixel is None or estimate is None
+                            or estimate != estimate):  # NaN check
+                        return float("nan")
+                    return abs(estimate - voxpixel)
+
+                row = {
+                    "variant": variant,
+                    "trial": trial,
+                    "volume": vol_name,
+                    "size_mb": size_mb,
+                    "status": result.get("status", "?"),
+                    "runtime_s": round(result.get("runtime_s", elapsed), 3),
+                    "peak_vram_gb": round(result.get("peak_vram_gb", 0.0), 2),
+                    "voxel_count": result.get("voxel_count", 0),
+                    "naive_volume_ml": naive_ml,
+                    "true_volume_ml": true_ml,
+                    "voxpixel_volume_ml": voxpixel,
+                    "abs_err_naive_vs_voxpixel_ml": _abs_err(naive_ml),
+                    "abs_err_true_vs_voxpixel_ml": _abs_err(true_ml),
+                    "error": result.get("error", ""),
+                }
+                rows.append(row)
+                print(f"    -> status={row['status']}  "
+                      f"runtime={row['runtime_s']}s  "
+                      f"peak_vram={row['peak_vram_gb']}GB")
+
+                if torch.cuda.is_available():
+                    torch.cuda.empty_cache()
+                gc.collect()
+
+    with open(args.out, "w", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=fields)
+        writer.writeheader()
+        writer.writerows(rows)
+    print(f"\nWrote {len(rows)} rows to {args.out}")
+
+    print("\n=== Per-variant summary (paper Table) ===")
+    by_variant: dict[str, dict] = {}
+    for r in rows:
+        v = r["variant"]
+        d = by_variant.setdefault(v, {
+            "n": 0, "ok": 0, "oom": 0, "ui_reject": 0, "err": 0,
+            "runtime_sum": 0.0, "vram_max": 0.0,
+            "naive_err_sum": 0.0, "naive_err_n": 0,
+        })
+        d["n"] += 1
+        s = r["status"]
+        if s == "OK":
+            d["ok"] += 1
+            d["runtime_sum"] += r["runtime_s"]
+            d["vram_max"] = max(d["vram_max"], r["peak_vram_gb"])
+            err = r["abs_err_naive_vs_voxpixel_ml"]
+            if err == err:  # not NaN
+                d["naive_err_sum"] += err
+                d["naive_err_n"] += 1
+        elif s == "OOM":
+            d["oom"] += 1
+        elif s == "UI_REJECT":
+            d["ui_reject"] += 1
+        else:
+            d["err"] += 1
+
+    header = (
+        f"{'Variant':<6} {'Success':>10} {'OOM':>5} {'UI_REJ':>7} "
+        f"{'ERR':>5} {'mean_rt(s)':>11} {'peak_vram(GB)':>14} "
+        f"{'mean_|naive-voxpixel|(ml)':>26}"
+    )
+    print(header)
+    print("-" * len(header))
+    for v, d in by_variant.items():
+        mean_rt = (d["runtime_sum"] / d["ok"]) if d["ok"] else float("nan")
+        mean_err = (
+            (d["naive_err_sum"] / d["naive_err_n"])
+            if d["naive_err_n"] else float("nan")
+        )
+        print(
+            f"{v:<6} {d['ok']:>4}/{d['n']:<5} "
+            f"{d['oom']:>5} {d['ui_reject']:>7} {d['err']:>5} "
+            f"{mean_rt:>11.2f} {d['vram_max']:>14.2f} "
+            f"{mean_err:>26.2f}"
+        )
+
+
+if __name__ == "__main__":
+    main()

prepare_runpod.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# One-shot bootstrap for the head-to-head Gradio benchmark on a RunPod
+# (or any Ubuntu 22.04 + CUDA 12.1 L40S box).
+#
+# Usage on the pod (after you've uploaded your three .nii.gz files into
+# /workspace/test_volumes/):
+#
+#   bash prepare_runpod.sh <hf_space_or_repo_url>
+#
+# Example:
+#   bash prepare_runpod.sh https://huggingface.co/spaces/HarshithReddy01/voxpixel
+#
+# What it does:
+#   1. Clones the VoxPixel repo into /workspace/voxpixel
+#   2. Installs system deps + Python deps + builds mamba_ssm and
+#      selective_scan_cuda_oflex (this is the slow step, ~10-15 min)
+#   3. Runs the 9-call x 3-variant benchmark
+#   4. Tars the CSV + log into /workspace/results.tar.gz so you can
+#      download it from the Jupyter file browser
+
+set -euo pipefail
+
+REPO_URL="${1:-https://huggingface.co/spaces/HarshithReddy01/voxpixel}"
+WORKDIR="/workspace/voxpixel"
+VOLDIR="/workspace/test_volumes"
+RESULTS="/workspace/gradio_baseline_results.csv"
+LOG="/workspace/bench.log"
+
+echo "===> [1/5] Sanity checks"
+nvidia-smi | head -n 20
+test -d "$VOLDIR" || { echo "ERROR: $VOLDIR missing. Upload your .nii.gz volumes there first."; exit 1; }
+ls -lh "$VOLDIR"
+
+echo "===> [2/5] Cloning repo into $WORKDIR"
+if [ ! -d "$WORKDIR" ]; then
+    git clone "$REPO_URL" "$WORKDIR"
+fi
+cd "$WORKDIR"
+git pull --rebase || true
+
+echo "===> [3/5] Installing system + Python deps + CUDA extensions"
+apt-get update -qq
+apt-get install -y -qq build-essential ninja-build git libgl1 libglib2.0-0 >/dev/null
+
+python -m pip install --upgrade pip wheel setuptools packaging ninja >/dev/null
+
+if ! python -c "import torch" 2>/dev/null; then
+    pip install --index-url https://download.pytorch.org/whl/cu121 \
+        torch torchvision torchaudio
+fi
+
+pip install --no-cache-dir -r requirements.txt
+
+if ! python -c "import mamba_ssm" 2>/dev/null; then
+    echo "  -> Building mamba-ssm (~5-10 min)..."
+    pip install "mamba-ssm>=2.2.2" --no-build-isolation
+fi
+
+if ! python -c "import selective_scan_cuda_oflex" 2>/dev/null; then
+    echo "  -> Building selective_scan_cuda_oflex (~3-5 min)..."
+    cd SRMA-Mamba/selective_scan
+    pip install --no-build-isolation -e . -v
+    cd "$WORKDIR"
+fi
+
+echo "===> [4/5] Verifying the stack"
+python - <<'PY'
+import torch, mamba_ssm, selective_scan_cuda_oflex
+print("torch:", torch.__version__, "cuda:", torch.cuda.is_available(),
+      "device:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "cpu")
+print("mamba_ssm OK:", mamba_ssm.__file__)
+print("selective_scan_cuda_oflex OK:", selective_scan_cuda_oflex.__file__)
+PY
+
+echo "===> [5/5] Running 9-call benchmark across V1, V2, V3"
+VOLS=( "$VOLDIR"/56.nii.gz "$VOLDIR"/58.nii.gz "$VOLDIR"/60.nii.gz )
+for v in "${VOLS[@]}"; do
+    test -f "$v" || { echo "ERROR: missing volume $v"; exit 1; }
+done
+
+python bench_gradio_baseline.py \
+    --volumes "${VOLS[@]}" \
+    --trials 3 \
+    --modality T1 \
+    --out "$RESULTS" 2>&1 | tee "$LOG"
+
+echo "===> Done. Bundling results."
+tar -czf /workspace/results.tar.gz \
+    -C /workspace \
+    "$(basename "$RESULTS")" \
+    "$(basename "$LOG")"
+ls -lh /workspace/results.tar.gz "$RESULTS" "$LOG"
+echo
+echo "Download /workspace/results.tar.gz from the Jupyter file browser,"
+echo "then 'Stop' or 'Terminate' this pod from the RunPod dashboard."