# 🚀 Deployment Guide for Smart Object Size Estimator

This guide explains how to deploy the Smart Object Size Estimator to Hugging Face Spaces.

## 📁 Required Files

Make sure you have all these files in your HuggingFace Space:

```
├── app.py                 # Main Gradio application
├── requirements.txt       # Python dependencies
├── config.yaml           # HuggingFace Space configuration
├── README.md             # Project documentation
├── DEPLOYMENT.md         # This deployment guide
└── goal2/                # Source code directory
    └── src/
        └── agent/
            ├── __init__.py
            ├── models.py      # AI model loading
            ├── geometry.py    # Size calculations
            └── io.py         # Image processing utilities
```

## 🔧 Step-by-Step Deployment

### 1. Create a New HuggingFace Space

1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Choose:
   - **Space name**: `smart-object-size-estimator` (or your preference)
   - **License**: MIT
   - **SDK**: Gradio
   - **Hardware**: CPU Basic (free tier) or GPU if available

### 2. Upload Files

Upload all the files listed above to your Space. You can either:

- Use the web interface to drag & drop files
- Use git to clone and push files
- Use the HuggingFace CLI

### 3. Model Weight Configuration

The app automatically downloads model weights:

- **Depth Anything V2**: Downloaded from HuggingFace Hub
- **SAM**: Downloaded from Facebook's repository

No manual model upload required!

### 4. Environment Configuration

The `config.yaml` file configures:

- Python version: 3.9+
- Gradio SDK version: 4.44.0
- Hardware requirements: CPU (upgradeable to GPU)

### 5. Dependencies Installation

All dependencies are listed in `requirements.txt`:

- Core ML: PyTorch, transformers
- Image processing: OpenCV, PIL, matplotlib
- Web interface: Gradio
- Utilities: NumPy, scikit-image

## 🚦 Launch Process

1. **Upload files** → Space shows "Building..."
2. **Install dependencies** → Takes ~2-3 minutes
3. **Download models** → First run takes ~1-2 minutes
4. **Ready!** → App accessible at your Space URL

## 📊 Expected Resource Usage

### CPU Version (Free Tier)

- **RAM**: ~2-4 GB during inference
- **Storage**: ~3 GB (models + dependencies)
- **Speed**: 10-30 seconds per image

### GPU Version (Paid Tier)

- **RAM**: ~4-6 GB during inference
- **Speed**: 3-8 seconds per image
- **Cost**: Variable based on usage

## 🔍 Troubleshooting

### Common Issues

1. **"Model download failed"**

   - Solution: Check internet connectivity, retry after a few minutes
   - Models are large (1-2 GB total)

2. **"Out of memory" errors**

   - Solution: Upgrade to GPU hardware or reduce image sizes
   - The app automatically resizes very large images

3. **"Import errors"**

   - Solution: Check `requirements.txt` versions
   - Ensure all dependencies are properly listed

4. **Slow processing**
   - Solution: Consider upgrading to GPU hardware
   - CPU processing is slower but works fine

### Debug Mode

To enable debugging, set `debug=True` in the `demo.launch()` call:

```python
demo.launch(share=True, debug=True)
```

## 🎯 Performance Optimization

### For Better Speed:

1. Upgrade to GPU hardware
2. Use smaller input images when possible
3. Consider caching models if using persistent storage

### For Better Accuracy:

1. Use camera-specific presets when available
2. Ensure good lighting in input images
3. Choose reference objects with known precise dimensions

## 🔐 Privacy & Security

- **No data storage**: Images are processed in memory only
- **No user tracking**: No personal data collected
- **Model privacy**: All processing happens on HuggingFace servers
- **Open source**: All code is publicly available

## 📈 Monitoring & Analytics

HuggingFace Spaces provides built-in analytics:

- Usage statistics
- Performance metrics
- Error logs
- Resource consumption

Access these through your Space settings panel.

## 📞 Support

If you encounter issues:

1. **Check the Space logs** in the HuggingFace interface
2. **Review the README.md** for usage instructions
3. **Test with example images** to isolate problems
4. **Consider hardware upgrades** for performance issues

## 🔄 Updates & Maintenance

To update the app:

1. Modify files in your local copy
2. Push changes to the Space repository
3. Space will automatically rebuild
4. Test thoroughly after updates

## 📋 Pre-Launch Checklist

- [ ] All required files uploaded
- [ ] `config.yaml` properly configured
- [ ] `requirements.txt` includes all dependencies
- [ ] Test with sample images
- [ ] Verify camera presets work
- [ ] Check reference object system
- [ ] Ensure error handling works
- [ ] Documentation is complete

## 🎉 Launch!

Once everything is set up, your Space will be live at:
`https://huggingface.co/spaces/[your-username]/[space-name]`

Share this URL with users and enjoy your deployed AI-powered size estimation tool!