DEPLOYMENT.md

# Deployment Guide for Depth Pro Distance Estimation

This is a FastAPI-based Hugging Face Space that provides depth estimation and distance calculation using Apple's Depth Pro model via Transformers pipeline.

## 🚀 Quick Deployment to Hugging Face Spaces

1. **Create a New Space**
   - Go to https://huggingface.co/spaces
   - Click "Create new Space"
   - Choose a name (e.g., `depth-pro-estimation`)
   - Select SDK: **Docker**
   - Set to Public or Private as needed

2. **Upload Files**
   Upload all files from this directory:
   - `README.md` (contains Space configuration)
   - `Dockerfile` (Docker build instructions)
   - `requirements.txt` (Python dependencies)
   - `app.py` (main FastAPI application)

3. **Space Configuration**
   The Space will automatically use:
   - **SDK**: Docker
   - **Port**: 7860 (defined in README.md as `app_port: 7860`)
   - **Hardware**: CPU Basic (suitable for this application)

4. **Build Process**
   - Hugging Face will automatically build the Docker image
   - The build takes ~10-15 minutes due to model download
   - Check the build logs for any issues

## 🔧 Local Development

### Prerequisites
- Python 3.10+
- pip

### Setup
```bash
# Clone or download this directory
cd path/to/pf-depth

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

### Access
- **Web Interface**: http://localhost:7860
- **API Documentation**: http://localhost:7860/docs
- **Health Check**: http://localhost:7860/health

## 🧪 Testing

Run the test suite:
```bash
python test_app.py
```

Test with example image:
```bash
python example_usage.py
```

## 📊 Features

- **FastAPI**: Modern Python web framework with automatic API docs
- **Transformers Pipeline**: Easy integration with Hugging Face models
- **Depth Estimation**: Uses Apple's Depth Pro model via pipeline
- **CPU Optimized**: Runs efficiently on CPU-only hardware
- **Docker Ready**: Containerized for easy deployment
- **Web Interface**: Simple HTML interface for testing
- **REST API**: Programmatic access via HTTP endpoints
- **Fallback Support**: Dummy pipeline when main model fails

## 🔌 API Endpoints

- `GET /` - Web interface
- `POST /estimate-depth` - Upload image for analysis
- `GET /docs` - API documentation (Swagger UI)
- `GET /redoc` - Alternative API documentation
- `GET /health` - Health check endpoint

## 📋 File Structure

```
pf-depth/
├── README.md           # Space configuration and documentation
├── Dockerfile          # Docker build instructions
├── requirements.txt    # Python dependencies
├── app.py             # Main FastAPI application
├── depth_pro/         # Depth Pro model module
│   ├── __init__.py
│   └── depth_pro.py
├── test_app.py        # Test suite
├── example_usage.py   # Usage examples
├── .dockerignore      # Docker ignore rules
└── DEPLOYMENT.md      # This file
```

## ⚠️ Important Notes

1. **Model Download**: The Depth Pro model (~2GB) downloads on first run
2. **CPU Performance**: Processing time is ~10-30 seconds per image
3. **Memory Usage**: Requires ~4GB RAM for model inference
4. **Image Size**: Automatically resizes large images to 1536px max dimension

## 🐛 Troubleshooting

### Build Issues
- Check that all files are uploaded correctly
- Verify the README.md has correct YAML frontmatter
- Look at build logs in the Space's settings

### Runtime Issues
- Check if the health endpoint responds: `/health`
- Verify model downloads in the logs
- Test with small, clear images first

### Performance Issues
- Use JPEG format for faster upload
- Resize very large images before upload
- CPU processing is inherently slower than GPU

## 📞 Support

For issues:
1. Check the Space build logs
2. Test locally using the development setup
3. Verify all dependencies are correctly specified
4. Ensure Docker environment has sufficient resources

## 🎯 Expected Results

- **Distance Accuracy**: ±20% for typical outdoor scenes
- **Processing Time**: 10-30 seconds per image on CPU
- **Best Performance**: Clear, well-lit images with visible edges
- **Supported Formats**: JPEG, PNG, WebP, and other PIL-supported formats