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

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

python test_app.py

Test with example image:

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