UPLOAD_WEIGHTS.md

# How to Upload FoundationPose Weights to Hugging Face

This guide shows you how to host FoundationPose model weights in a Hugging Face model repository, which is much better than using git-lfs in your Space.

## Why Use a Model Repository?

✅ **Benefits:**
- Designed for large files (GB+)
- Fast CDN downloads
- Version control for weights
- Share weights across multiple Spaces
- No need for git-lfs in Space repo
- Better download performance

## Step-by-Step Guide

### 1. Download Official Weights

First, get the official FoundationPose weights from Google Drive:

**Download Link:** https://drive.google.com/drive/folders/1GCyGE-LbFGgRC-FuGsF3a1zeBuzsQ1Da

Download these two folders:
- `2023-10-28-18-33-37/` (refiner weights, ~900MB)
- `2024-01-11-20-02-45/` (scorer weights, ~900MB)

Save them locally in a directory structure like:
```
foundationpose-weights/
├── 2023-10-28-18-33-37/
│   ├── model.pth
│   └── ...
└── 2024-01-11-20-02-45/
    ├── model.pth
    └── ...
```

### 2. Create Hugging Face Model Repository

**Option A: Using the Web Interface**

1. Go to https://huggingface.co/new
2. Choose "Model" (not Space or Dataset)
3. Set owner to your username (e.g., `gpue`)
4. Set name: `foundationpose-weights`
5. Make it **Public** (so your Space can download it) or Private (requires token)
6. Click "Create model"

**Option B: Using the CLI**

```bash
pip install huggingface_hub
huggingface-cli login  # Enter your token

# Create repo
huggingface-cli repo create foundationpose-weights --type model
```

### 3. Upload Weights to Model Repository

**Option A: Using the Web Interface**

1. Go to your model repo: `https://huggingface.co/YOUR_USERNAME/foundationpose-weights`
2. Click "Files" → "Add file" → "Upload files"
3. Drag and drop the two weight folders
4. Click "Commit changes"

⚠️ **Note:** Web upload may be slow for large files. Use CLI for better experience.

**Option B: Using the CLI (Recommended)**

```bash
# From the directory containing your weight folders
huggingface-cli upload YOUR_USERNAME/foundationpose-weights ./2023-10-28-18-33-37 2023-10-28-18-33-37
huggingface-cli upload YOUR_USERNAME/foundationpose-weights ./2024-01-11-20-02-45 2024-01-11-20-02-45
```

**Option C: Using Python Script**

```python
from huggingface_hub import HfApi
from pathlib import Path

api = HfApi()
repo_id = "YOUR_USERNAME/foundationpose-weights"
weights_dir = Path("./foundationpose-weights")

print("Uploading weights to Hugging Face...")

# Upload entire directory
api.upload_folder(
    folder_path=str(weights_dir),
    repo_id=repo_id,
    repo_type="model"
)

print("✓ Upload complete!")
```

### 4. Add Model Card (README)

Create a `README.md` in your model repo to document the weights:

```markdown
---
license: cc-by-nc-4.0
tags:
  - computer-vision
  - 6d-pose-estimation
  - object-detection
  - robotics
---

# FoundationPose Model Weights

Pre-trained weights for [FoundationPose](https://github.com/NVlabs/FoundationPose) 6D object pose estimation model.

## Model Details

- **Refiner weights:** `2023-10-28-18-33-37/`
- **Scorer weights:** `2024-01-11-20-02-45/`
- **Source:** [Official FoundationPose release](https://github.com/NVlabs/FoundationPose)

## Usage

```python
from huggingface_hub import snapshot_download

# Download all weights
snapshot_download(
    repo_id="YOUR_USERNAME/foundationpose-weights",
    local_dir="./weights"
)
```

## Citation

```bibtex
@inproceedings{wen2023foundationpose,
  title={FoundationPose: Unified 6D Pose Estimation and Tracking of Novel Objects},
  author={Wen, Bowen and Yang, Wei and Kautz, Jan and Birchfield, Stan},
  booktitle={CVPR},
  year={2024}
}
```

## License

These weights are from the official FoundationPose release and subject to NVIDIA's license terms.
```

### 5. Configure Your Space to Use the Model Repo

Update your Space's environment variables (Settings → Variables and secrets):

```
FOUNDATIONPOSE_MODEL_REPO=YOUR_USERNAME/foundationpose-weights
USE_HF_WEIGHTS=true
USE_REAL_MODEL=true
```

Or set in your Space's Dockerfile/code:

```python
import os
os.environ["FOUNDATIONPOSE_MODEL_REPO"] = "gpue/foundationpose-weights"
os.environ["USE_HF_WEIGHTS"] = "true"
```

### 6. Test the Setup

**Test locally:**

```bash
cd foundationpose

# Set environment variables
export FOUNDATIONPOSE_MODEL_REPO="YOUR_USERNAME/foundationpose-weights"
export USE_HF_WEIGHTS="true"

# Download weights
python download_weights.py

# Should see:
# ✓ Download complete!
# ✓ Model weights found locally!
```

**Test in Space:**

After pushing to HF Spaces, check the build logs:
1. Go to your Space → Logs
2. Look for "Downloading from Hugging Face Model Repository"
3. Should see "✓ Download complete!"

### 7. Verify Weights Are Correct

Check that the downloaded structure matches:

```bash
ls -R weights/

# Should show:
# weights/2023-10-28-18-33-37/
# weights/2024-01-11-20-02-45/
```

## Troubleshooting

### "Repository not found"

- Check repo name matches exactly: `YOUR_USERNAME/foundationpose-weights`
- Make sure repo is Public, or provide HF token for private repos
- Verify you're logged in: `huggingface-cli whoami`

### "Upload failed"

- Check your internet connection
- Try uploading smaller chunks
- Use CLI instead of web interface for large files

### "Out of storage"

- HF free tier has storage limits (~50GB)
- Request more storage or use smaller model variants
- Host on your own S3/CDN as alternative

### Private Repository Access

If your model repo is private, set HF token in Space secrets:

1. Get token from https://huggingface.co/settings/tokens
2. Add to Space: Settings → Repository secrets → `HF_TOKEN`
3. Code will automatically use it:

```python
from huggingface_hub import snapshot_download
import os

snapshot_download(
    repo_id="YOUR_USERNAME/foundationpose-weights",
    local_dir="./weights",
    token=os.environ.get("HF_TOKEN")  # Uses secret
)
```

## Example: Complete Workflow

```bash
# 1. Download from Google Drive (manual)
# Save to: ~/Downloads/foundationpose-weights/

# 2. Install HF CLI
pip install huggingface_hub
huggingface-cli login

# 3. Create model repo
huggingface-cli repo create foundationpose-weights --type model

# 4. Upload weights
cd ~/Downloads/foundationpose-weights
huggingface-cli upload gpue/foundationpose-weights . .

# 5. Update your Space
cd /path/to/foundationpose
git add .
git commit -m "Use HF model repo for weights"
git push

# 6. Set Space secrets
# Go to: https://huggingface.co/spaces/gpue/foundationpose/settings
# Add: FOUNDATIONPOSE_MODEL_REPO=gpue/foundationpose-weights
# Add: USE_HF_WEIGHTS=true
# Add: USE_REAL_MODEL=true

# 7. Check Space logs
# Visit: https://huggingface.co/spaces/gpue/foundationpose/logs
# Should see weights downloading automatically
```

## Alternative: Public Model Repos

If someone else has already uploaded the weights, you can use their repo:

```bash
# Example (if available)
export FOUNDATIONPOSE_MODEL_REPO="some-user/foundationpose-weights"
```

Common public repos (check if they exist):
- `nvidia/foundationpose` (official, if available)
- Community uploads (search on HF)

## Cost

✅ **Free tier:**
- Unlimited model repos
- ~50GB storage per repo
- Unlimited downloads (public repos)
- No bandwidth costs

📈 **Pro tier ($9/month):**
- More storage
- Private repos with teams
- Priority support

---

**Quick Reference:**

```bash
# Create repo
huggingface-cli repo create foundationpose-weights --type model

# Upload
huggingface-cli upload YOUR_USERNAME/foundationpose-weights ./weights .

# Download in Space (automatic)
python download_weights.py

# Or download manually
from huggingface_hub import snapshot_download
snapshot_download("YOUR_USERNAME/foundationpose-weights", local_dir="./weights")
```

---

You're all set! Your FoundationPose Space will now automatically download weights from your model repository on first run. 🎉