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

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)

# 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

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:

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

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

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:

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:

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

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

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

# 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. 🎉