File size: 5,170 Bytes
4837bd5 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | # 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
|