README.md

---
title: Depth Pro Distance Estimation
emoji: 📏
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# Depth Pro Distance Estimation

This Hugging Face Space uses Apple's Depth Pro model via Transformers pipeline to estimate depth and calculate distances in images. The application runs entirely on CPU and provides a FastAPI REST API with a simple web interface.

## Features

- **Depth Estimation**: Uses Apple's Depth Pro model via Transformers pipeline
- **Distance Calculation**: Estimates real-world distances between key points in images
- **CPU-Only**: Optimized to run on CPU hardware
- **Transformers Integration**: Simple pipeline-based implementation
- **FastAPI**: REST API with automatic documentation
- **Web Interface**: Simple HTML interface for easy testing
- **Real-time Processing**: Fast inference suitable for interactive use

## How it Works

1. **Upload Image**: Provide an image through the web interface or API
2. **Depth Estimation**: The Transformers pipeline uses Depth Pro to generate a depth map
3. **Pixel Detection**: Finds topmost and bottommost edge pixels
4. **Distance Calculation**: Calculates real-world distance using depth information
5. **Results**: Returns detailed measurements and statistics

## API Endpoints

### POST /estimate-depth
Upload an image to get depth estimation and distance calculation results.

**Parameters:**
- `file`: Image file (JPG, PNG, etc.)

**Response:**
```json
{
  "depth_map_shape": [384, 512],
  "focal_length_px": 614.4,
  "topmost_pixel": [50, 256],
  "bottommost_pixel": [300, 256],
  "distance_meters": 2.45,
  "depth_stats": {
    "min_depth": 1.2,
    "max_depth": 8.7,
    "mean_depth": 4.1
  }
}
```

## Technical Details

- **Model**: Apple Depth Pro via Transformers Pipeline
- **Framework**: FastAPI + Transformers
- **Processing**: CPU-only inference
- **Image Processing**: OpenCV, PIL
- **Precision**: Float32 for CPU compatibility
- **Pipeline**: `pipeline("depth-estimation", model="apple/DepthPro")`

## Usage Examples

### Web Interface

1. Visit the main page at your deployed Space URL
2. Upload an image using the file input
3. Click "Analyze Image" to get results
4. View detailed depth statistics and distance measurements

### API Usage

```python
import requests

files = {'file': open('image.jpg', 'rb')}
response = requests.post('https://your-space-url/estimate-depth', files=files)
result = response.json()
print(f"Distance: {result['distance_meters']:.2f} meters")
```

### cURL Example

```bash
curl -X POST https://your-space-url/estimate-depth \
  -F "file=@image.jpg" \
  -H "Content-Type: multipart/form-data"
```

## Limitations

- CPU-only processing may be slower than GPU
- Distance accuracy depends on image quality and scene structure
- Focal length estimation is heuristic-based
- Best results with clear, well-lit outdoor scenes

## Credits

- **Depth Pro Model**: Apple Inc.
- **Framework**: Gradio, FastAPI
- **Computer Vision**: OpenCV, PIL