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?

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 (Quick 5-min guide) 📖 Detailed: UPLOAD_WEIGHTS.md (Full instructions)

# 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

git push origin main

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

---

📚 Documentation Index

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

---

🚀 Deployment Options Summary

A. Placeholder Mode (Default)

# No setup needed
git push origin main

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

B. Real Mode (Automatic Download)

# 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)

# 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:

from foundationpose.client import FoundationPoseClient

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

2. Update config:

perception:
  enabled: true
  model: foundation_pose
  api_url: https://YOUR_USER-foundationpose.hf.space

Full integration code: See QUICKSTART.md

---

❓ 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 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
• Deployment issues: See DEPLOYMENT.md
• Weight upload: See UPLOAD_WEIGHTS.md or HF_MODEL_SETUP.md
• Project status: See STATUS.md
• API usage: See QUICKSTART.md

---

Start here: → Test locally: python test_local.py → Want real weights: HF_MODEL_SETUP.md → Deploy: git push origin main

That's it! 🎉