HF_PRO_DEPLOYMENT.md

Deploying Your NeRF App on Hugging Face Pro

Prerequisites

✅ Hugging Face Pro account ($9/month) ✅ Git installed locally ✅ Understanding that GPU usage incurs additional costs

---

Step 1: Create Your Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in details:
   • Space name: nerf-3d-reconstruction (or your choice)
   • License: Choose appropriate (MIT recommended)
   • SDK: Gradio
   • Hardware: Start with "CPU basic" (we'll upgrade after upload)
   • Visibility: 🔒 PRIVATE (recommended to avoid unexpected costs)

---

Step 2: Upload Your Files

Required Files in Root Directory:

your-space/
├── app.py              # Your app-10.py (rename to app.py)
├── requirements.txt    # Python dependencies
├── packages.txt        # System dependencies (COLMAP)
└── README.md          # Space description

app.py

Rename app-10.py to app.py (HF Spaces looks for this name)

requirements.txt

gradio>=4.0.0
opencv-python-headless>=4.8.0
numpy>=1.24.0
Pillow>=10.0.0
nerfstudio>=1.0.0
torch>=2.0.0
torchvision>=0.15.0

packages.txt

colmap

README.md

---
title: NeRF 3D Reconstruction
emoji: 🎥
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
---

# NeRF 3D Reconstruction from 360° Video

Transform Insta360 videos into detailed 3D models using Neural Radiance Fields.

**⚠️ Processing Time:** 20-45 minutes per video
**🎮 GPU Required:** This Space uses GPU hardware

---

Step 3: Upload Files

Option A: Git (Recommended)

# Clone your Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/nerf-3d-reconstruction
cd nerf-3d-reconstruction

# Add your files
cp /path/to/app-10.py app.py
cp /path/to/requirements.txt .
cp /path/to/packages.txt .

# Commit and push
git add .
git commit -m "Initial commit: NeRF reconstruction app"
git push

Option B: Web Interface

1. Go to your Space's "Files" tab
2. Click "Add file" → "Upload files"
3. Drag and drop all files
4. Commit changes

---

Step 4: Configure Hardware (CRITICAL)

1. Go to Space Settings (⚙️ icon)
2. Scroll to "Hardware" section
3. Choose GPU:

For Pro Users - Recommended Options:

Budget Option: T4 Small

• Cost: ~$0.60/hour
• Good for: Testing, light usage
• Processing: 30-60 min per reconstruction

Best Value: A10G Small ⭐

• Cost: ~$1.05/hour
• Good for: Regular use, best price/performance
• Processing: 20-45 min per reconstruction

High Performance: A10G Large

• Cost: ~$1.30/hour
• Good for: Faster processing
• Processing: 15-30 min per reconstruction

Maximum Speed: A100

• Cost: ~$3-4/hour
• Good for: Production, many users
• Processing: 15-25 min per reconstruction

4. Click "Save"
5. Space will rebuild with GPU

---

Step 5: Wait for Build

Your Space will now:

1. ⏳ Install system packages (COLMAP) - 2-3 minutes
2. ⏳ Install Python packages - 3-5 minutes
3. ⏳ Download CUDA/PyTorch - 2-3 minutes
4. ✅ Launch app - 30 seconds

Total build time: 8-12 minutes

Check Build Logs:

• Click "Logs" tab to monitor progress
• Look for: Running on local URL: http://0.0.0.0:7860
• ✅ Success! Your Space is live

---

Step 6: Test Your Space

1. Click on your Space's "App" tab
2. Upload a test video
3. Start reconstruction
4. ⏰ Wait 20-45 minutes (grab coffee!)
5. Download your 3D model

If It Fails:

• Check logs for errors
• Common issues:
  • COLMAP not found → Check packages.txt uploaded
  • CUDA out of memory → Upgrade GPU hardware
  • Timeout → Shouldn't happen on Pro with GPU

---

Step 7: Cost Management

Track Your Usage:

1. Go to Billing → Usage in your HF account
2. Monitor GPU hours consumed
3. Set up billing alerts (recommended)

Cost Estimates:

Personal Use (10 reconstructions/month):

• Pro subscription: $9/month
• GPU time (A10G): ~$10-15/month
• Total: ~$20-25/month

Heavy Use (50 reconstructions/month):

• Pro subscription: $9/month
• GPU time (A10G): ~$45-75/month
• Total: ~$55-85/month

Cost-Saving Tips:

1. Use Sleep/Pause

HF Spaces auto-pause when inactive:

• Set Sleep timeout: 15 minutes
• Space sleeps when not in use
• ✅ No GPU charges when sleeping

2. Keep Private

• Public Spaces = anyone can use (expensive!)
• Private Spaces = only you + invited users
• Set to PRIVATE in settings

3. Downgrade When Not Using

• Use T4 for testing
• Upgrade to A10G only when needed
• Downgrade back to CPU if not using for days

4. Process in Batches

• Do multiple reconstructions in one session
• Minimize GPU startup time
• More efficient billing

---

Step 8: Share Access (Optional)

If You Want Collaborators:

1. Go to Space Settings
2. Click "Collaborators"
3. Add users by username
4. They can access without making it public

If You Want Public (⚠️ Risky):

1. Change visibility to "Public"
2. ⚠️ Add usage warnings in your README
3. Consider adding:
   • Rate limiting
   • Authentication
   • Max processing queue
4. 💸 Monitor costs CLOSELY

---

Important Limitations

Timeout Considerations:

• HF Pro: Longer timeouts than free tier
• Your app: 20-45 minutes processing
• ✅ Should work fine on Pro with GPU

Storage Limitations:

• Temporary files: Auto-cleaned
• Uploads: Limited by Space storage
• Downloads: User downloads directly
• Consider cleaning up temp files aggressively

Concurrent Users:

• Single GPU: One user at a time
• Multiple requests: Queue up
• Consider adding queue management UI

---

Recommended Space Settings

# In your Space settings:

Hardware: A10G Small (or T4 Small for testing)
Visibility: Private
Sleep timeout: 15 minutes
Environment secrets: None needed
Persistent storage: Not needed (temp files only)

---

Alternative: Serverless GPU

If you want pay-only-when-processing:

Use HF Inference Endpoints Instead:

1. Package your model as API
2. Deploy as Inference Endpoint
3. Pay only when API called
4. More complex setup but better for sporadic use

---

Troubleshooting

Build Fails:

Error: colmap not found
→ Check packages.txt exists and contains "colmap"

GPU Out of Memory:

CUDA out of memory
→ Upgrade to larger GPU (A10G Large or A100)
→ Or reduce max_frames in UI (try 50 instead of 100)

Processing Times Out:

Timeout after 1 hour
→ Shouldn't happen on Pro + GPU
→ If it does, contact HF support

Costs Too High:

Unexpected charges
→ Check if Space is Public (anyone can use!)
→ Set to Private
→ Check for hung processes

---

Best Practices

✅ DO:

• Keep Space Private initially
• Start with T4 for testing
• Monitor costs weekly
• Set billing alerts
• Clean up temp files
• Add clear UI warnings about processing time

❌ DON'T:

• Make it Public without rate limiting
• Leave expensive GPU running 24/7
• Forget to set sleep timeout
• Process 100+ frames without GPU
• Upload 4K videos (too large)

---

Expected Monthly Costs

Light Personal Use:

• Subscription: $9/month (HF Pro)
• GPU: ~$5-10/month
• Total: ~$15-20/month

Regular Personal Use:

• Subscription: $9/month
• GPU: ~$15-30/month
• Total: ~$25-40/month

Heavy Use / Small Team:

• Subscription: $9/month
• GPU: ~$50-100/month
• Total: ~$60-110/month

---

Summary Checklist

• Created Hugging Face Space
• Uploaded app.py, requirements.txt, packages.txt
• Set Hardware to GPU (A10G Small recommended)
• Set Visibility to Private
• Set Sleep timeout to 15 minutes
• Waited for build to complete (~10 min)
• Tested with sample video
• Verified 3D model export works
• Set up billing alerts
• Documented usage for team (if applicable)

---

Next Steps

1. Test thoroughly with Private Space
2. Monitor costs for first week
3. Optimize settings based on usage
4. Consider public only if needed + rate limiting
5. Share with team via collaborators

---

Support

• HF Pro Support: https://huggingface.co/support
• Billing Questions: Check HF billing dashboard
• Technical Issues: HF Community forums

---

🎉 You're ready to deploy! With HF Pro, you have the resources to run this computationally intensive app. Just be mindful of costs and keep it Private initially.