Add local install bootstrap and GitHub links

.gitignore

@@ -1,3 +1,6 @@
 __pycache__/
 *.pyc
 *.log
+.venv/
+models/*.pt
+!models/.gitkeep

README.md

@@ -11,9 +11,15 @@ license: mit
 
 Gradio Space for detecting vessels in satellite imagery with a fine-tuned YOLOv8 model.
 
-## Included Model
+## Links
 
-- File: `models/best.pt`
+- Live Space: https://huggingface.co/spaces/DefendIntelligence/vessel-detection
+- Model repository: https://huggingface.co/DefendIntelligence/vessel-detection
+- Direct model download: https://huggingface.co/DefendIntelligence/vessel-detection/resolve/main/models/best.pt
+
+## Model
+
+- Local file expected by the app: `models/best.pt`
 - Checkpoint source: `train-20260417T124314Z-fad9d3ed_best.pt`
 - Run source: `infer-b88a2887`
 - Training name: `super-visible-y8s-newlabels-focuslite-e45`
@@ -21,7 +27,39 @@ Gradio Space for detecting vessels in satellite imagery with a fine-tuned YOLOv8
 - Main dataset: `sentinel-2-rgb`
 - Local index mAP50: `0.7912`
 
-## Usage
+The GitHub repository does not store `best.pt`. Use the bootstrap command below and it will download the model from Hugging Face.
+
+## Run Locally
+
+```bash
+git clone https://github.com/anisayari/vessel-detection.git
+cd vessel-detection
+python run_local.py
+```
+
+Windows shortcut:
+
+```powershell
+.\start.ps1
+```
+
+macOS/Linux shortcut:
+
+```bash
+bash start.sh
+```
+
+The script creates a local `.venv`, installs `requirements.txt`, downloads `models/best.pt` from Hugging Face, then starts Gradio at `http://127.0.0.1:7860`.
+
+Useful options:
+
+```bash
+python run_local.py --download-only
+python run_local.py --skip-install
+python run_local.py --host 0.0.0.0 --port 7860
+```
+
+## Use The App
 
 1. Upload an RGB satellite image or select an example.
 2. Adjust the confidence threshold if needed.
@@ -31,8 +69,6 @@ The app tiles large images before inference so small vessels remain visible to t
 
 ## Hugging Face Deployment
 
-Depuis ce dossier:
-
 ```bash
 git init
 git lfs install

app.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from functools import lru_cache
 from pathlib import Path
 
@@ -10,6 +11,7 @@ from ultralytics import YOLO
 
 ROOT = Path(__file__).resolve().parent
 MODEL_PATH = ROOT / "models" / "best.pt"
+MODEL_URL = "https://huggingface.co/DefendIntelligence/vessel-detection/resolve/main/models/best.pt"
 EXAMPLES_DIR = ROOT / "examples"
 MAX_TILES = 196
 BATCH_SIZE = 8
@@ -18,7 +20,9 @@ BATCH_SIZE = 8
 @lru_cache(maxsize=1)
 def load_model() -> YOLO:
     if not MODEL_PATH.exists():
-        raise FileNotFoundError(f"Model not found: {MODEL_PATH}")
+        raise FileNotFoundError(
+            f"Model not found: {MODEL_PATH}. Run `python run_local.py` or download it from {MODEL_URL}."
+        )
     return YOLO(str(MODEL_PATH))
 
 
@@ -266,4 +270,9 @@ with gr.Blocks(title="Vessel Detection") as demo:
 
 
 if __name__ == "__main__":
-    demo.launch()
+    launch_kwargs = {}
+    if os.environ.get("GRADIO_SERVER_NAME"):
+        launch_kwargs["server_name"] = os.environ["GRADIO_SERVER_NAME"]
+    if os.environ.get("GRADIO_SERVER_PORT"):
+        launch_kwargs["server_port"] = int(os.environ["GRADIO_SERVER_PORT"])
+    demo.launch(**launch_kwargs)

models/.gitkeep

@@ -0,0 +1 @@
+

run_local.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import urllib.request
+import venv
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent
+VENV_DIR = ROOT / ".venv"
+MODEL_DIR = ROOT / "models"
+MODEL_PATH = MODEL_DIR / "best.pt"
+MODEL_URL = "https://huggingface.co/DefendIntelligence/vessel-detection/resolve/main/models/best.pt"
+
+
+def _venv_python() -> Path:
+    if os.name == "nt":
+        return VENV_DIR / "Scripts" / "python.exe"
+    return VENV_DIR / "bin" / "python"
+
+
+def _run(command: list[str | os.PathLike[str]], env: dict[str, str] | None = None) -> None:
+    printable = " ".join(str(part) for part in command)
+    print(f"\n$ {printable}", flush=True)
+    subprocess.check_call([str(part) for part in command], cwd=ROOT, env=env)
+
+
+def _ensure_venv() -> Path:
+    python_path = _venv_python()
+    if not python_path.exists():
+        print(f"Creating virtual environment: {VENV_DIR}", flush=True)
+        venv.EnvBuilder(with_pip=True).create(VENV_DIR)
+    return python_path
+
+
+def _install_dependencies(python_path: Path) -> None:
+    _run([python_path, "-m", "pip", "install", "--upgrade", "pip"])
+    _run([python_path, "-m", "pip", "install", "-r", "requirements.txt"])
+
+
+def _download_model() -> None:
+    MODEL_DIR.mkdir(parents=True, exist_ok=True)
+    if MODEL_PATH.exists() and MODEL_PATH.stat().st_size > 0:
+        print(f"Model already present: {MODEL_PATH}", flush=True)
+        return
+
+    tmp_path = MODEL_PATH.with_suffix(".pt.tmp")
+    print(f"Downloading model from Hugging Face:\n{MODEL_URL}", flush=True)
+    with urllib.request.urlopen(MODEL_URL) as response, tmp_path.open("wb") as handle:
+        total = int(response.headers.get("Content-Length") or 0)
+        downloaded = 0
+        while True:
+            chunk = response.read(1024 * 1024)
+            if not chunk:
+                break
+            handle.write(chunk)
+            downloaded += len(chunk)
+            if total:
+                percent = downloaded * 100 / total
+                print(f"\r{downloaded / 1_000_000:.1f} MB / {total / 1_000_000:.1f} MB ({percent:.0f}%)", end="")
+            else:
+                print(f"\r{downloaded / 1_000_000:.1f} MB", end="")
+        print()
+    tmp_path.replace(MODEL_PATH)
+    print(f"Saved model to: {MODEL_PATH}", flush=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Install and run the Vessel Detection Gradio demo locally.")
+    parser.add_argument("--skip-install", action="store_true", help="Do not install Python dependencies.")
+    parser.add_argument("--download-only", action="store_true", help="Download the model and exit.")
+    parser.add_argument("--host", default="127.0.0.1", help="Gradio server host.")
+    parser.add_argument("--port", default="7860", help="Gradio server port.")
+    args = parser.parse_args()
+
+    python_path = None
+    if not (args.download_only and args.skip_install):
+        python_path = _ensure_venv()
+    if not args.skip_install:
+        if python_path is None:
+            python_path = _ensure_venv()
+        _install_dependencies(python_path)
+    _download_model()
+
+    if args.download_only:
+        return
+
+    if python_path is None:
+        python_path = _ensure_venv()
+    env = os.environ.copy()
+    env["GRADIO_SERVER_NAME"] = args.host
+    env["GRADIO_SERVER_PORT"] = args.port
+    print(f"\nStarting Gradio at http://{args.host}:{args.port}", flush=True)
+    _run([python_path, "app.py"], env=env)
+
+
+if __name__ == "__main__":
+    main()

start.ps1

@@ -0,0 +1,7 @@
+$ErrorActionPreference = "Stop"
+
+if (Get-Command py -ErrorAction SilentlyContinue) {
+    py -3 run_local.py
+} else {
+    python run_local.py
+}

start.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v python3 >/dev/null 2>&1; then
+  python3 run_local.py
+else
+  python run_local.py
+fi