commit 7d3c36050bc1ec02fc18bfa26d449b09912b3777 Author: ravi Date: Sat Apr 25 16:23:09 2026 +0530 first version diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..094034c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ + +| Principle | Addresses | +|-----------|-----------| +| **Think Before Coding** | Wrong assumptions, hidden confusion, missing tradeoffs | +| **Simplicity First** | Overcomplication, bloated abstractions | +| **Surgical Changes** | Orthogonal edits, touching code you shouldn't | +| **Goal-Driven Execution** | Leverage through tests-first, verifiable success criteria | diff --git a/README.md b/README.md new file mode 100644 index 0000000..9c14f99 --- /dev/null +++ b/README.md @@ -0,0 +1,213 @@ +# SAM-Tool + +Desktop video-frame extraction + image annotation tool, with optional +SAM 2 / SAM 3 segmentation backend. Built to replace an earlier +Python/Tkinter prototype (`sam_tool_v2.py`) for YOLO-style training +dataset prep. + +``` +┌──────────────────┐ HTTP ┌──────────────────┐ +│ sam-tool-tauri │ ◀───────────────▶ │ sam2-backend │ +│ (Tauri/Rust + UI)│ /predict, etc │ (FastAPI + GPU) │ +└──────────────────┘ └──────────────────┘ + │ │ + ▼ ▼ + local images + SAM 2.x / SAM 3 + sibling JSONs weights on disk +``` + +The two halves can run on the same machine or separate boxes — point the +desktop app at any reachable backend URL from **Settings**. + +--- + +## Layout + +``` +SAM-Tool/ +├── sam-tool-tauri/ # Desktop app (Tauri 2, React 18, TS, Vite) +│ ├── src/ # Frontend +│ ├── src-tauri/ # Rust commands (video, decoder, IPC) +│ └── package.json # `npm run tauri dev` / `tauri build` +│ +├── sam2-backend/ # FastAPI HTTP server (SAM 2 + SAM 3) +│ ├── server.py # /, /models, /predict +│ ├── registry.py # Lazy-load + single-resident cache +│ ├── adapters/ +│ │ ├── sam2_adapter.py +│ │ ├── sam3_adapter.py +│ │ └── utils.py # mask → polygon helper +│ ├── models.yaml # Model registry (paths + family) +│ ├── run.sh # Convenience launcher (env vars) +│ └── README.md # Install + run on the server side +│ +├── sam2/sam2/ # Meta SAM 2 source + checkpoints (vendored) +├── files/sam3_weights/ # SAM 3 weights (3.4 GB sam3.pt) +├── files/sam3_server.py # Reference SAM3 server (used as a guide) +│ +├── sam_tool_v2.py # Original Python/Tkinter tool (legacy) +├── sam_annotation_test/ # Sample data — dashcam MP4 + custom SAM JSON +│ +├── docs/ # ← you are here +│ ├── POLYGON_SMOOTHING.md How to tune mask→polygon output +│ ├── HF_DEPLOY_OFFLINE.md First-online-then-airgapped HF deploy +│ └── BUILD_RELEASE.md Building the Tauri app for release +│ +└── CLAUDE.md # Project rules (think → simplify → surgical) +``` + +--- + +## Quick start (single-machine dev) + +### 1. SAM backend + +```bash +cd sam2-backend +python3 -m venv .venv && source .venv/bin/activate +pip install --upgrade pip + +# Pick the right Torch wheel for your GPU (driver 570+ → cu128): +pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128 +# CPU-only fallback (slow): +# pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu + +# SAM 2 source + deps +pip install -e ../sam2/sam2 +pip install -r requirements.txt + +# Optional — SAM 3 support (needs HF account + accepted gating) +git clone https://github.com/facebookresearch/sam3.git .. +pip install -e ../sam3 +pip install "transformers>=4.57" +hf auth login # paste read token from https://huggingface.co/settings/tokens + +./run.sh # binds 0.0.0.0:9090, auto-picks cuda/cpu +``` + +Smoke-test: +```bash +curl http://localhost:9090/ # {"status":"ok",...} +curl http://localhost:9090/models # registered models +``` + +Full backend setup details: [`sam2-backend/README.md`](sam2-backend/README.md). + +### 2. Tauri desktop app + +```bash +cd sam-tool-tauri +npm install +npm run tauri dev # hot-reload dev mode + +# Or for a real build / installer: +npm run tauri build # see docs/BUILD_RELEASE.md +``` + +In the running app: +1. **Login** — pick or type a username (no password — used for annotation + author stamping). +2. **Extract mode** — Upload a video → optionally `Import annotations…` + (COCO / SAM JSON) → click `choose output folder…` (or just open a + video; the default `