README_SETUP.md

# FoundationPose Setup Guide

**Quick navigation to setup instructions:**

## 🎯 Choose Your Path

### Path 1: Test Without Weights (5 minutes)

Just want to test the API structure?

```bash
cd foundationpose
pip install -r requirements.txt
python app.py
```

✅ Works immediately
✅ No GPU needed
✅ Returns valid API responses (empty results)
✅ Perfect for developing client integrations

→ **No additional setup needed!**

---

### Path 2: Deploy with Real Weights (30 minutes)

Want actual 6D pose estimation?

**Step 1: Get Model Weights**

Option A: **Create HF Model Repo** (Recommended)
📖 **Guide:** [HF_MODEL_SETUP.md](HF_MODEL_SETUP.md) (Quick 5-min guide)
📖 **Detailed:** [UPLOAD_WEIGHTS.md](UPLOAD_WEIGHTS.md) (Full instructions)

```bash
# Quick version:
huggingface-cli login
huggingface-cli repo create foundationpose-weights --type model
huggingface-cli upload YOUR_USER/foundationpose-weights ./weights .
```

Option B: Manual Download (Not recommended)
- Download from Google Drive
- Use git-lfs to add to Space repo
- More complex, slower

**Step 2: Configure Space**

Add environment variables in Space settings:
```
FOUNDATIONPOSE_MODEL_REPO=YOUR_USER/foundationpose-weights
USE_HF_WEIGHTS=true
USE_REAL_MODEL=true
```

**Step 3: Deploy**

```bash
git push origin main
```

Done! Space will auto-download weights on first run.

---

## 📚 Documentation Index

| Document | Purpose | Read When |
|----------|---------|-----------|
| [HF_MODEL_SETUP.md](HF_MODEL_SETUP.md) | **Quick HF model repo setup** | Setting up weights (recommended way) |
| [UPLOAD_WEIGHTS.md](UPLOAD_WEIGHTS.md) | Detailed weight upload guide | Need step-by-step instructions |
| [QUICKSTART.md](QUICKSTART.md) | API usage & integration | Ready to use the API |
| [DEPLOYMENT.md](DEPLOYMENT.md) | Full deployment options | Want all the details |
| [STATUS.md](STATUS.md) | Complete project status | Want to know what's done/missing |
| [README.md](README.md) | Space homepage | First-time visitors |

---

## 🚀 Deployment Options Summary

### A. Placeholder Mode (Default)

```bash
# No setup needed
git push origin main
```

- Returns empty results
- Tests API structure
- No GPU costs
- Perfect for development

### B. Real Mode (Automatic Download)

```bash
# 1. Upload weights to HF model repo (see HF_MODEL_SETUP.md)
# 2. Set Space environment variables:
#    FOUNDATIONPOSE_MODEL_REPO=YOUR_USER/foundationpose-weights
#    USE_HF_WEIGHTS=true
#    USE_REAL_MODEL=true
# 3. Deploy
git push origin main
```

- Automatic weight download
- Real pose estimation
- ZeroGPU inference
- Production-ready

### C. Real Mode (Manual Weights)

```bash
# 1. Download weights manually
# 2. Add with git-lfs
git lfs track "weights/**"
git add weights/
git commit -m "Add weights"
# 3. Set USE_REAL_MODEL=true
git push origin main
```

- Weights included in Space
- Slower deployments
- Larger Space size
- Not recommended

---

## 🔗 Integration with robot-ml

Once your Space is running:

**1. Update wrapper:**
```python
from foundationpose.client import FoundationPoseClient

client = FoundationPoseClient("https://YOUR_USER-foundationpose.hf.space")
```

**2. Update config:**
```yaml
perception:
  enabled: true
  model: foundation_pose
  api_url: https://YOUR_USER-foundationpose.hf.space
```

**Full integration code:** See [QUICKSTART.md](QUICKSTART.md#integration-with-robot-ml)

---

## ❓ FAQ

**Q: Do I need a GPU?**
A: No. ZeroGPU allocates GPU on-demand when needed.

**Q: How much does it cost?**
A: ZeroGPU is free with usage limits. Placeholder mode uses no GPU.

**Q: Can I use someone else's weights?**
A: Yes! If someone has a public model repo: `FOUNDATIONPOSE_MODEL_REPO=their-username/foundationpose-weights`

**Q: How big are the weights?**
A: ~1.8GB total (900MB refiner + 900MB scorer)

**Q: Where do I get the weights?**
A: Download from [Google Drive](https://drive.google.com/drive/folders/1GCyGE-LbFGgRC-FuGsF3a1zeBuzsQ1Da) then upload to HF model repo.

**Q: Can I test locally?**
A: Yes! `python test_local.py` tests everything locally first.

**Q: What if weight download fails?**
A: Space will run in placeholder mode automatically. Check logs for errors.

---

## 🎯 Recommended Workflow

```
1. Test locally first
   → python test_local.py

2. Deploy placeholder mode
   → Test Space works

3. Create HF model repo
   → Upload weights
   → See HF_MODEL_SETUP.md

4. Enable real mode
   → Set environment variables
   → Space auto-downloads weights

5. Integrate with robot-ml
   → See QUICKSTART.md
```

---

## 🆘 Getting Help

- **General questions:** See [QUICKSTART.md](QUICKSTART.md)
- **Deployment issues:** See [DEPLOYMENT.md](DEPLOYMENT.md)
- **Weight upload:** See [UPLOAD_WEIGHTS.md](UPLOAD_WEIGHTS.md) or [HF_MODEL_SETUP.md](HF_MODEL_SETUP.md)
- **Project status:** See [STATUS.md](STATUS.md)
- **API usage:** See [QUICKSTART.md](QUICKSTART.md)

---

**Start here:**
→ Test locally: `python test_local.py`
→ Want real weights: [HF_MODEL_SETUP.md](HF_MODEL_SETUP.md)
→ Deploy: `git push origin main`

That's it! 🎉