CFace-infer/QUICKSTART.md

# Quick Setup & Usage Guide

## Step 1: Configure TruFor Model Path
Edit `config.json`:
```json
{
    "trufor_model": "/path/to/your/trufor/checkpoint.pth"
}
```

## Step 2: Run the API
```bash
python app.py
# API runs on http://0.0.0.0:8000
```

## Step 3: Send Requests
```bash
# Using curl with image file
curl -X POST "http://localhost:8000/faceswap-image" \
  -F "files=@test_image.jpg"

# Using Python
import requests
with open('test_image.jpg', 'rb') as f:
    files = {'files': f}
    response = requests.post('http://localhost:8000/faceswap-image', files=files)
    print(response.json())
```

## Step 4: Parse Response
```python
data = response.json()

for source in data['results']:
    print(f"Source: {source['source']}")
    print(f"Faces detected: {source['faces_detected']}")
    
    for face in source['predictions']:
        print(f"  Face {face['face_id']}: {face['prediction']}")
        print(f"  Confidence: {face['confidence']:.3f}")
        
        if face.get('visualization'):
            # Visualization image available as base64
            print(f"  Visualization: {face['visualization']['filename']}")
            
            # Save base64 image to file
            import base64
            img_data = base64.b64decode(face['visualization']['image_base64'])
            with open(face['visualization']['filename'], 'wb') as f:
                f.write(img_data)
```

## Response Structure
```json
{
  "success": true,
  "total_sources_processed": 1,
  "total_faces_processed": 2,
  "results": [
    {
      "source_type": "file",
      "source": "test.jpg",
      "success": true,
      "faces_detected": 2,
      "message": "Detected 2 face(s).",
      "image_info": {
        "width": 1920,
        "height": 1080,
        "channels": 3
      },
      "predictions": [
        {
          "face_id": 1,
          "bbox": [100, 50, 300, 250],
          "square_bbox_224": [88, 38, 312, 262],
          "detection_score": 0.98,
          "prediction": "fake",
          "confidence": 0.94,
          "raw_confidence": {
            "real": 0.06,
            "fake": 0.94
          },
          "visualization": {
            "filename": "test_plotted.jpg",
            "image_base64": "iVBORw0KGgoAAAA...",
            "mime_type": "image/jpeg"
          },
          "extra_info": {
            "bbox_dimensions": {"width": 200, "height": 200},
            "aspect_ratio": 1.0,
            "crop_size": [224, 224],
            "kps": []
          }
        }
      ]
    }
  ]
}
```

## Key Features

| Feature | Details |
|---------|---------|
| **Detection** | Real-time face detection using InsightFace |
| **Classification** | CFace CLIP model for real/fake classification |
| **Localization** | TruFor model for detailed deepfake localization maps |
| **Visualization** | Multi-panel matplotlib visualization with base64 encoding |
| **Response Format** | JSON with embedded base64 images (no file I/O) |
| **Batch Processing** | Single model pass for all faces in all images |
| **Error Handling** | Graceful fallbacks if TruFor model unavailable |

## Troubleshooting

### TruFor Model Not Loading
```
Warning: Model checkpoint not found at /path/to/trufor/checkpoint.pth
```
**Solution**: Check `config.json` and ensure the path exists

### CUDA Out of Memory
```
Error: CUDA Out of Memory during TruFor inference
```
**Solution**: 
- Reduce image size or use smaller batches
- Run on CPU: Set GPU to -1 in config
- Use lower resolution input

### No Visualization for Fake Detections
**Check**:
1. Is TruFor model loaded? Check logs
2. Is face actually predicted as "fake"?
3. Are there exceptions in logs?

### Visualization Quality Issues
**Adjust in `create_visualization_image()`**:
- Change `figsize=(cols*4, 4)` for larger/smaller images
- Change `dpi=100` for higher/lower resolution
- Modify colormaps: `cmap='RdBu_r'` → `'jet'`, `'viridis'`, etc.

## API Endpoints

### POST /faceswap-image
Analyze image(s) for face-swap deepfakes

**Parameters:**
- `files` (optional): List of image files
- `image_url` (optional): Single image URL
- `image_urls` (optional): Multiple image URLs

**Returns:** JSON with detection results and visualizations

### GET /
Health check endpoint

**Returns:** API status and model information

## Model Details

| Model | Purpose | Input | Output |
|-------|---------|-------|--------|
| **InsightFace** | Face detection | Image | Face bboxes, keypoints |
| **CFace CLIP** | Real/Fake classification | 224x224 face crops | Probability scores |
| **TruFor** | Deepfake localization | Full resolution image | Localization maps |

## Performance Metrics

- **Face Detection**: ~50-100ms per image
- **CFace Classification**: ~10-20ms per face
- **TruFor Localization**: ~100-500ms per face (GPU dependent)
- **Visualization Generation**: ~20-50ms per deepfake
- **Total**: ~200-800ms per deepfake detection (with visualization)

## Security Notes

- ✅ CORS enabled (configure as needed)
- ✅ No file storage (in-memory processing)
- ✅ Base64 encoding prevents binary issues
- ⚠️  Consider adding API authentication for production
- ⚠️  Validate image file sizes to prevent DoS