DEPLOYMENT_GUIDE.md

# RetinaFace Face Detection API

A Gradio-based face detection service using RetinaFace models (MobileNet and ResNet backbones) deployed on Hugging Face Spaces.

## Features

- 🔥 **Dual Model Support**: MobileNet (fast) and ResNet (accurate) backbones
- 📱 **Thunkable Compatible**: API endpoints for mobile app integration
- ⚡ **Real-time Detection**: Web interface and API endpoints
- 🎨 **Interactive UI**: Gradio web interface for easy testing
- 🚀 **Serverless**: Deployed on Hugging Face Spaces for free

## Web Interface

Access the interactive web interface at your Hugging Face Space URL:
- Image upload and detection
- Model selection (MobileNet/ResNet)
- Confidence threshold adjustment
- Real-time results visualization
- API testing interface

## API Endpoints

### 1. Gradio API Endpoint
```
POST /api/predict
```
Main API endpoint compatible with Thunkable and other applications.

**Request Body:**
```json
{
  "data": [
    "base64_encoded_image_string",
    "mobilenet",
    0.5,
    0.4
  ]
}
```

**Response:**
```json
{
  "data": [
    {
      "faces": [
        {
          "bbox": {"x1": 100, "y1": 120, "x2": 200, "y2": 220},
          "confidence": 0.95,
          "landmarks": {
            "right_eye": [130, 150],
            "left_eye": [170, 150],
            "nose": [150, 170],
            "right_mouth": [135, 190],
            "left_mouth": [165, 190]
          }
        }
      ],
      "processing_time": 0.1,
      "model_used": "mobilenet",
      "total_faces": 1
    }
  ]
}
```

## Deployment Instructions

### 1. Hugging Face Spaces Deployment

1. **Create a new Space on Hugging Face:**
   - Go to https://huggingface.co/spaces
   - Click "Create new Space"
   - Choose "Gradio" as SDK
   - Set SDK version to 4.44.0
   - Set visibility to "Public"

2. **Upload your files:**
   ```
   ├── app.py                     # Main Gradio application
   ├── requirements.txt           # Python dependencies
   ├── README.md                  # HF Spaces configuration
   ├── mobilenet0.25_Final.pth    # MobileNet model weights
   ├── Resnet50_Final.pth         # ResNet model weights
   ├── models/
   │   └── retinaface.py         # RetinaFace model architecture
   └── utils/
       ├── box_utils.py          # Bounding box utilities
       ├── prior_box.py          # Anchor box generation
       └── py_cpu_nms.py         # Non-maximum suppression
   ```

3. **Your Space will automatically build and deploy!**

### 2. Local Testing

1. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

2. **Run locally:**
   ```bash
   python app.py
   ```

3. **Test the API:**
   ```bash
   python test_api.py
   ```

4. **Access the web interface:**
   Open http://localhost:7860 in your browser

## Thunkable Integration

### 1. Web API Component Setup
```
URL: https://your-username-retinaface-api.hf.space/api/predict
Method: POST
Headers: Content-Type: application/json
Body: {
  "data": [
    "{{base64_image}}",
    "mobilenet",
    0.5,
    0.4
  ]
}
```

### 2. Response Handling in Thunkable
```
When Web API receives data:
  Set app variable "apiResponse" to response body
  Set app variable "detectionData" to get property "data" of apiResponse
  Set app variable "faces" to get property "faces" of detectionData[0]
  Set app variable "faceCount" to get property "total_faces" of detectionData[0]
  
  If faceCount > 0:
    For each face in faces:
      // Process face data (bbox, confidence, landmarks)
```

### 3. Base64 Image Conversion
```
// In Thunkable, convert camera image to base64
Set app variable "imageBase64" to 
  call CloudinaryAPI.convertToBase64 
    mediaDB = Camera1.Picture
```

## Model Performance

| Model | Speed | Accuracy | Use Case |
|-------|-------|----------|----------|
| MobileNet | Fast | Good | Real-time mobile apps |
| ResNet50 | Slower | High | High-accuracy applications |

## API Testing

Use the built-in API testing interface in the Gradio app:
1. Go to the "📊 API Testing" tab
2. Paste your base64 encoded image
3. Select model and parameters
4. Click "🧪 Test API"
5. View the JSON response

## Error Handling

The API includes comprehensive error handling:
- Invalid image data validation
- Model loading verification
- Detailed error responses in JSON format

## Advantages of Gradio SDK

✅ **Web Interface**: Built-in UI for testing and demonstration
✅ **API Endpoints**: Automatic API generation at `/api/predict`
✅ **Easy Deployment**: No Docker configuration needed
✅ **Real-time Testing**: Interactive interface for immediate feedback
✅ **Documentation**: Built-in API documentation
✅ **Mobile Friendly**: Responsive web interface

## Limitations

- **File Size**: Max upload size determined by Hugging Face Spaces
- **Concurrent Requests**: Subject to Hugging Face Spaces limits
- **Cold Starts**: First request may take longer due to model loading
- **Processing Time**: Heavy models may timeout on free tier

## Example Integration Code

### JavaScript/Thunkable
```javascript
const response = await fetch('https://your-space.hf.space/api/predict', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    data: [base64Image, "mobilenet", 0.5, 0.4]
  })
});

const result = await response.json();
const faces = result.data[0].faces;
```

### Python
```python
import requests
import base64

# Convert image to base64
with open('image.jpg', 'rb') as f:
    image_b64 = base64.b64encode(f.read()).decode()

# Make API call
response = requests.post(
    'https://your-space.hf.space/api/predict',
    json={"data": [image_b64, "mobilenet", 0.5, 0.4]}
)

result = response.json()
faces = result["data"][0]["faces"]
```

## Support

For issues or questions:
1. Check the web interface at your Space URL
2. Test locally using the provided test script
3. Use the built-in API testing tab in Gradio
4. Verify model files are correctly uploaded

## License

Apache 2.0