Desert segmentation Gradio Space

.gitattributes

@@ -0,0 +1,2 @@
+# Use Git LFS for checkpoints when pushing to Hugging Face (avoids hard size limits).
+*.pt filter=lfs diff=lfs merge=lfs -text

HUGGINGFACE_SPACES.md

@@ -0,0 +1,93 @@
+# Deploy this project to Hugging Face Spaces
+
+Your Space: `https://huggingface.co/spaces/webVishnu/code-wizards` (replace if yours differs).
+
+## 1. One-time: access token
+
+Create a token with **write** access: [Settings → Access Tokens](https://huggingface.co/settings/tokens).
+
+## 2. Connect git to the Space
+
+From **this repository root** (where `app.py` lives). If this folder is **already** a git repo, skip `git init`.
+
+```powershell
+git remote add space https://huggingface.co/spaces/webVishnu/code-wizards
+```
+
+If `git remote add` fails because `space` exists, use `git remote set-url space https://huggingface.co/spaces/webVishnu/code-wizards`.
+
+Stage what the Space needs (trim paths you do not want public):
+
+```powershell
+git add app.py requirements.txt packages.txt .gitattributes desert_segmentation scripts
+git add HUGGINGFACE_SPACES.md README_HF_SPACES.md
+```
+
+Optional: `git add eval_summary.json` (validation accuracy in the UI). Optional: `git add checkpoints/best.pt` (only with **Git LFS**; see step 3).
+
+- Add **`checkpoints/best.pt`** only if you use a file in the repo (use **Git LFS**; see below). Otherwise use Hub download (step 4).
+- Do **not** commit huge `training/` folders unless you intend to; the demo only needs code + weights + optional `eval_summary.json`.
+
+**Space README (card + Gradio metadata):** Hugging Face reads **`README.md`** at the Space repo root (YAML frontmatter + markdown).
+
+- **Easiest (does not touch your local GitHub README):** After the first successful push, open the Space → **Files** → `README.md` → **Edit**, delete the boilerplate, and **paste the full contents of `README_HF_SPACES.md`**, then commit on the Hub.
+- **If this folder is only for the Space:** you can `git add` a `README.md` that is a copy of `README_HF_SPACES.md` (rename the file to `README.md` before committing).
+- **If you use one git repo for both GitHub and HF:** do **not** overwrite your long `README.md`; use the Hub web editor for the Space card, or maintain a dedicated branch for the Space with a short `README.md`.
+
+## 3. Git LFS for `best.pt` (if the checkpoint lives in the repo)
+
+```powershell
+git lfs install
+git lfs track "*.pt"
+git add .gitattributes checkpoints/best.pt
+```
+
+## 4. Weights without committing the file (recommended for large checkpoints)
+
+1. Create a **Model** repository on the Hub and upload `best.pt` (with LFS).
+2. In the Space → **Settings → Repository secrets**, add nothing extra for public models.
+3. In the Space → **Settings → Variables** (or **Secrets**), add:
+   - **`HF_HUB_CHECKPOINT_REPO`** = your model repo id, e.g. `webVishnu/desert-seg-best`
+   - **`HF_HUB_CHECKPOINT_FILENAME`** = `best.pt` (optional if the filename is `best.pt`)
+
+`app.py` will download the file on startup. For a **private** model repo, add a read token as **`HF_TOKEN`** (secret).
+
+Alternatively set **`CHECKPOINT_PATH`** to an absolute path inside the container (rare).
+
+## 5. Optional: validation accuracy line in the UI
+
+Commit **`eval_summary.json`** at the repo root (same layout as local). The demo shows **Accuracy (val)** when `global_pixel_accuracy` is present.
+
+## 6. Hardware
+
+Space **Settings → Hardware**: start with **CPU** to verify the build; switch to **GPU** (e.g. T4) for usable speed. Update the `hardware:` field in the Space `README.md` YAML if you use a template that expects it.
+
+## 7. Push
+
+```powershell
+git commit -m "Add Gradio Space app and dependencies"
+git push space main
+```
+
+If the default branch on the Hub is `main`, use `main`. Use your **token** as the password when Git asks.
+
+## 8. Verify
+
+Open the **App** tab. When the container builds, you should see the demo (first load downloads weights if using Hub env vars).
+
+## Environment variables reference
+
+| Variable | Purpose |
+|----------|---------|
+| `CHECKPOINT_PATH` | Path to `.pt` if bundled or mounted |
+| `HF_HUB_CHECKPOINT_REPO` | Model repo id for `hf_hub_download` |
+| `HF_HUB_CHECKPOINT_FILENAME` | Filename in that repo (default `best.pt`) |
+| `HF_TOKEN` | Read token for private Hub weights |
+| `DEMO_MAX_SIDE` | Max image side (default `4096`) |
+| `DEMO_MAX_MEGAPIXELS` | Max megapixels (default `16`) |
+
+Local run still works:
+
+```powershell
+python scripts/demo_gradio.py --checkpoint checkpoints/best.pt
+```

README_HF_SPACES.md

@@ -0,0 +1,19 @@
+---
+title: Desert semantic segmentation
+emoji: 🏜️
+colorFrom: yellow
+colorTo: orange
+sdk: gradio
+app_file: app.py
+pinned: false
+license: apache-2.0
+short_description: Upload a desert/off-road RGB image and get a per-pixel class mask, overlay, and metrics.
+---
+
+# Desert semantic segmentation
+
+Interactive **semantic segmentation** demo: each pixel is classified into terrain / scene categories. Upload an RGB image, click **Run segmentation**, and view the colored mask, overlay, strip, timing, optional **validation accuracy**, and dominant classes.
+
+**Weights:** configure `CHECKPOINT_PATH`, or `HF_HUB_CHECKPOINT_REPO` (+ optional `HF_HUB_CHECKPOINT_FILENAME`), or commit `checkpoints/best.pt` (prefer **Git LFS**). See `HUGGINGFACE_SPACES.md` in the project repository.
+
+**Hardware:** CPU works but is slow; enable a **GPU** in Space settings for responsive inference.

app.py

@@ -0,0 +1,85 @@
+"""
+Hugging Face Spaces entrypoint: exposes ``demo`` for the Gradio SDK.
+
+Checkpoint resolution (first match wins):
+1. ``CHECKPOINT_PATH`` — absolute or relative to repo root, file must exist.
+2. ``HF_HUB_CHECKPOINT_REPO`` + optional ``HF_HUB_CHECKPOINT_FILENAME`` (default ``best.pt``)
+   — downloads from the Hub (use a Model repo; set Space secret ``HF_TOKEN`` if private).
+3. ``<repo_root>/checkpoints/best.pt``
+
+Optional: ``eval_summary.json`` at repo root enables **Accuracy (val)** in the UI.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+ROOT = Path(__file__).resolve().parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+
+logger = logging.getLogger("app")
+
+
+def _resolve_checkpoint(root: Path) -> Path:
+    env_path = os.environ.get("CHECKPOINT_PATH", "").strip()
+    if env_path:
+        p = Path(env_path)
+        if not p.is_absolute():
+            p = (root / p).resolve()
+        else:
+            p = p.resolve()
+        if p.is_file():
+            logger.info("Using checkpoint from CHECKPOINT_PATH=%s", p)
+            return p
+        logger.warning("CHECKPOINT_PATH set but not a file: %s", p)
+
+    hub_repo = os.environ.get("HF_HUB_CHECKPOINT_REPO", "").strip()
+    if hub_repo:
+        from huggingface_hub import hf_hub_download
+
+        fn = os.environ.get("HF_HUB_CHECKPOINT_FILENAME", "best.pt").strip() or "best.pt"
+        token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        path = hf_hub_download(repo_id=hub_repo, filename=fn, token=token)
+        p = Path(path).resolve()
+        logger.info("Downloaded checkpoint from Hub repo=%s file=%s -> %s", hub_repo, fn, p)
+        return p
+
+    cand = root / "checkpoints" / "best.pt"
+    if cand.is_file():
+        logger.info("Using bundled checkpoint %s", cand)
+        return cand.resolve()
+
+    raise FileNotFoundError(
+        "No weights found. Do one of: "
+        "(1) Set Space secret / env CHECKPOINT_PATH to your .pt file, "
+        "(2) Set HF_HUB_CHECKPOINT_REPO (and optional HF_HUB_CHECKPOINT_FILENAME) to a Model repo, "
+        f"(3) Add checkpoints/best.pt under {root} (use Git LFS for large files)."
+    )
+
+
+def _resolve_eval_summary(root: Path) -> Optional[Path]:
+    p = root / "eval_summary.json"
+    return p if p.is_file() else None
+
+
+_checkpoint = _resolve_checkpoint(ROOT)
+_eval_summary = _resolve_eval_summary(ROOT)
+
+from scripts.demo_gradio import create_demo  # noqa: E402
+
+_max_side = int(os.environ.get("DEMO_MAX_SIDE", "4096"))
+_max_mp = float(os.environ.get("DEMO_MAX_MEGAPIXELS", "16"))
+
+demo = create_demo(
+    _checkpoint,
+    _eval_summary,
+    max_side=_max_side,
+    max_megapixels=_max_mp,
+)

packages.txt

@@ -0,0 +1,5 @@
+# System packages for Spaces (OpenCV / headless image stack). Safe to ignore locally.
+libglib2.0-0
+libsm6
+libxext6
+libxrender1

requirements.txt

@@ -8,3 +8,5 @@ albumentations>=1.3.1,<1.5
 segmentation-models-pytorch>=0.3.3
 tqdm>=4.66.0
 pytest>=7.4.0
+gradio>=4.44.0,<6
+huggingface_hub>=0.20.0

scripts/demo_gradio.py

@@ -176,49 +176,20 @@ def _run(
     return rgb, colored, overlay, strip, stats, dominant
 
 
-def main() -> None:
-    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
-
-    parser = argparse.ArgumentParser(description="Gradio demo for desert semantic segmentation")
-    parser.add_argument("--root", type=str, default=os.environ.get("ROOT"), help="Workspace root (default: repo root or env ROOT)")
-    parser.add_argument(
-        "--checkpoint",
-        type=str,
-        default=os.environ.get("CHECKPOINT_PATH"),
-        help="Path to best.pt (default: env CHECKPOINT_PATH or <root>/checkpoints/best.pt)",
-    )
-    parser.add_argument("--host", type=str, default="127.0.0.1")
-    parser.add_argument("--port", type=int, default=7860)
-    parser.add_argument("--share", action="store_true", help="Create a temporary public Gradio link")
-    parser.add_argument("--max-side", type=int, default=4096)
-    parser.add_argument("--max-megapixels", type=float, default=16.0)
-    parser.add_argument(
-        "--eval-summary",
-        type=str,
-        default=None,
-        help="Optional path to eval_summary.json (default: <root>/eval_summary.json if that file exists)",
-    )
-    args = parser.parse_args()
-
-    root = Path(args.root or ROOT).resolve()
-    ckpt_arg = args.checkpoint or str(root / "checkpoints" / "best.pt")
-    ckpt = Path(ckpt_arg)
-    if not ckpt.is_absolute():
-        ckpt = (root / ckpt).resolve()
+def create_demo(
+    checkpoint: Path,
+    eval_summary: Optional[Path],
+    max_side: int = 4096,
+    max_megapixels: float = 16.0,
+    device: Optional[torch.device] = None,
+) -> gr.Blocks:
+    """Build the Gradio Blocks app (Hugging Face Spaces: assign ``demo = create_demo(...)``; do not call ``launch``)."""
+    ckpt = checkpoint.resolve()
     if not ckpt.is_file():
-        raise SystemExit(f"Checkpoint not found: {ckpt}")
-
-    eval_summary_arg = args.eval_summary
-    if eval_summary_arg:
-        eval_summary = Path(eval_summary_arg)
-        if not eval_summary.is_absolute():
-            eval_summary = (root / eval_summary).resolve()
-    else:
-        cand = root / "eval_summary.json"
-        eval_summary = cand if cand.is_file() else None
+        raise FileNotFoundError(f"Checkpoint not found: {ckpt}")
 
-    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-    _init_state(ckpt, device, eval_summary)
+    dev = device or torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    _init_state(ckpt, dev, eval_summary)
 
     icfg = _STATE["icfg"]
     def_tta = bool(icfg.get("tta_flip", True))
@@ -239,7 +210,7 @@ _Confidence heatmaps for full-resolution sliding windows are not in this demo (v
 """
 
     cpu_note = ""
-    if device.type == "cpu":
+    if dev.type == "cpu":
         cpu_note = "\n\n> Running on **CPU** — expect slower inference. Use a CUDA GPU for best speed.\n"
 
     with gr.Blocks(title="Desert segmentation", theme=gr.themes.Soft()) as demo:
@@ -261,8 +232,8 @@ _Confidence heatmaps for full-resolution sliding windows are not in this demo (v
         gr.Markdown("### Class legend (fixed palette)")
         gr.HTML(_STATE["legend_html_static"])
 
-        def _fn(img, tta, ov, ts):
-            return _run(img, tta, ov, ts, args.max_side, args.max_megapixels)
+        def _fn(img: Any, tta: bool, ov: float, ts: float) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, str, str]:
+            return _run(img, tta, ov, ts, max_side, max_megapixels)
 
         run_btn.click(
             fn=_fn,
@@ -270,6 +241,59 @@ _Confidence heatmaps for full-resolution sliding windows are not in this demo (v
             outputs=[out_orig, out_mask, out_overlay, out_strip, stats_md, dominant_md],
         )
 
+    return demo
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+
+    parser = argparse.ArgumentParser(description="Gradio demo for desert semantic segmentation")
+    parser.add_argument("--root", type=str, default=os.environ.get("ROOT"), help="Workspace root (default: repo root or env ROOT)")
+    parser.add_argument(
+        "--checkpoint",
+        type=str,
+        default=os.environ.get("CHECKPOINT_PATH"),
+        help="Path to best.pt (default: env CHECKPOINT_PATH or <root>/checkpoints/best.pt)",
+    )
+    parser.add_argument("--host", type=str, default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=7860)
+    parser.add_argument("--share", action="store_true", help="Create a temporary public Gradio link")
+    parser.add_argument("--max-side", type=int, default=4096)
+    parser.add_argument("--max-megapixels", type=float, default=16.0)
+    parser.add_argument(
+        "--eval-summary",
+        type=str,
+        default=None,
+        help="Optional path to eval_summary.json (default: <root>/eval_summary.json if that file exists)",
+    )
+    args = parser.parse_args()
+
+    root = Path(args.root or ROOT).resolve()
+    ckpt_arg = args.checkpoint or str(root / "checkpoints" / "best.pt")
+    ckpt = Path(ckpt_arg)
+    if not ckpt.is_absolute():
+        ckpt = (root / ckpt).resolve()
+    if not ckpt.is_file():
+        raise SystemExit(f"Checkpoint not found: {ckpt}")
+
+    eval_summary_arg = args.eval_summary
+    if eval_summary_arg:
+        eval_summary = Path(eval_summary_arg)
+        if not eval_summary.is_absolute():
+            eval_summary = (root / eval_summary).resolve()
+    else:
+        cand = root / "eval_summary.json"
+        eval_summary = cand if cand.is_file() else None
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    demo = create_demo(
+        ckpt,
+        eval_summary,
+        max_side=args.max_side,
+        max_megapixels=args.max_megapixels,
+        device=device,
+    )
+
     logger.info("Launching Gradio on http://%s:%s", args.host, args.port)
     demo.launch(server_name=args.host, server_port=args.port, share=args.share)