README.md

---
title: RefDiffNet
emoji: 🔬
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: "5.23.0"
python_version: "3.10"
app_file: app.py
pinned: false
license: agpl-3.0
---

# RefDiffNet — PCB Reference–Defect Enrichment (A11_CA)

**Space:** [vinayedula/RefDiffNet](https://huggingface.co/spaces/vinayedula/RefDiffNet)

Standalone Gradio demo for the **A11_CA** prebackbone (no Ultralytics at runtime).

- **Inputs:** defect PCB image + golden reference image  
- **Output:** enriched image (`enriched = defect + α · gate · delta`)

Weights: `weights/prebackbone_a11_ca.pt` (~few MB)

## Deploy to Hugging Face Spaces

### 1. Prepare the Space folder locally

From the VYOLO repo root:

```bash
cd /mnt/data/vinay/work/VYOLO
bash hf_prebackbone_demo/prepare_space.sh
```

This will:

- Extract `prebackbone_a11_ca.pt` from `best.pt` (uses the VYOLO ultralytics fork **once** on your machine)
- Copy example image pairs into `examples/`
- Remove legacy `vendor/` if present

### 2. Push to [vinayedula/RefDiffNet](https://huggingface.co/spaces/vinayedula/RefDiffNet)

```bash
cd hf_prebackbone_demo
bash deploy_to_refdiffnet.sh
```

> **Note:** The Space ships only `a11_ca.py`, `prebackbone_infer.py`, and `prebackbone_a11_ca.pt` — not the full ultralytics tree.

### 3. Space settings (recommended)

| Setting | Value |
|---------|--------|
| Hardware | CPU Basic (works) or **GPU** for faster inference |
| Secrets | Optional: `HF_TOKEN` if weights are in a private model repo |

### Alternative: host weights on the Hub

```
HF_MODEL_REPO=YOUR_USER/YOUR_MODEL
```

The app downloads `prebackbone_a11_ca.pt` from that repo.

## Run locally

```bash
cd hf_prebackbone_demo
# Clean broken Gradio 4.x + starlette 1.x mix if you hit jinja2 / localhost errors:
pip uninstall -y gradio gradio-client starlette fastapi uvicorn 2>/dev/null || true
pip install -r requirements.txt
pip install --force-reinstall "numpy>=1.23.0,<2"
export PREBACKBONE_ONLY_WEIGHTS=weights/prebackbone_a11_ca.pt
python app.py
```

Open **http://127.0.0.1:7860** (default bind). Remote server: `GRADIO_SERVER_NAME=0.0.0.0 python app.py` or SSH port-forward.

### One-time weight extraction (from full `best.pt`)

Only needed if you do not already have `prebackbone_a11_ca.pt`:

```bash
ULTRALYTICS_ROOT=../ultralytics python extract_prebackbone_weights.py \
  --ckpt ../ultralytics/Proposed/yolo12_training/HRIPCB_Results/yolo12n_hripcb_200epochs_batch16/weights/best.pt
```

## Layout

| File | Role |
|------|------|
| `a11_ca.py` | Standalone A11_CA module definition |
| `prebackbone_infer.py` | Load weights, run enrichment (same H×W inputs) |
| `gradio_patch.py` | Gradio 5.16 / client 1.7 compatibility patch |
| `app.py` | Gradio UI |
| `weights/prebackbone_a11_ca.pt` | Prebackbone weights only |

## Environment variables

| Variable | Description |
|----------|-------------|
| `PREBACKBONE_ONLY_WEIGHTS` | Path to `prebackbone_a11_ca.pt` |
| `HF_MODEL_REPO` | Hub repo with `prebackbone_a11_ca.pt` |
| `PREBACKBONE_DEVICE` | `cpu` or `cuda` (default: auto) |
| `PORT` | Gradio port (default `7860`) |