CFace-infer/QUICKSTART.md

Quick Setup & Usage Guide

Step 1: Configure TruFor Model Path

Edit config.json:

{
    "trufor_model": "/path/to/your/trufor/checkpoint.pth"
}

Step 2: Run the API

python app.py
# API runs on http://0.0.0.0:8000

Step 3: Send Requests

# 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

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

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