Face Detection

Tuzzle provides AI-powered face detection for smart cropping that keeps faces in frame.

Triggering Face Detection

Face detection is triggered by using facial gravity values:

?w=400&h=400&r=crop&g=face
?w=200&h=200&r=thumb&g=faces
?w=300&h=300&r=crop&g=eyes
?w=400&h=400&r=crop&g=auto

How It Works

1. Detection: The image is analyzed and face bounding boxes are returned
2. Sorting: Detected faces are sorted by area, largest first
3. Crop calculation: The crop region is centered on the largest face's bounding box
4. Fallback: If no faces are detected, the crop falls back to center gravity

Caching

Face detection results are cached after the first request. Subsequent requests for the same image use cached data, so there is no additional latency after the initial detection.

Crop Mode vs Thumb Mode

Crop with Face Detection

Centers the requested crop area on the largest face:

?w=600&h=400&r=crop&g=face

The crop region is positioned so the face is centered, with boundaries clamped to the image edges.

Thumb with Face Detection

Applies smart zoom for tighter, portrait-style results:

?w=200&h=200&r=thumb&g=face

1. Detects the face bounding box
2. Applies a 2x zoom factor around the face
3. Adjusts the crop to keep the face centered within the zoomed region
4. Resizes to the requested dimensions

Thumb mode produces more focused results, ideal for avatar-style images.

Best Practices

• Use r=thumb&g=face for profile pictures and avatars
• Use r=crop&g=face for editorial crops that need more context around the face
• Use r=fill with compass gravity when you know faces aren't the focus
• Face detection adds latency on the first request (subsequent requests use cached results)
• Images without detected faces fall back gracefully to center cropping