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:

{
  "data": [
    "base64_encoded_image_string",
    "mobilenet",
    0.5,
    0.4
  ]
}

Response:

{
  "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:

   pip install -r requirements.txt
   

2. Run locally:

   python app.py
   

3. Test the API:

   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

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

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