File size: 4,222 Bytes
eae62a9 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 |
# 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
|