Crop and Gravity

The g (gravity) parameter controls where the image is anchored when cropping. It works with crop, thumb, and fill resize modes.

Compass Gravity

Position the crop using cardinal directions:

Examples

# Crop from the top
?w=800&h=400&r=crop&g=north

# Crop from the bottom-right
?w=800&h=400&r=crop&g=southeast

# Center crop (default)
?w=800&h=400&r=crop&g=center

Facial Gravity

Use face detection to position the crop around detected faces.

Examples

# Crop around the main face
?w=400&h=400&r=crop&g=face

# Face-focused thumbnail
?w=200&h=200&r=thumb&g=face

How Face Detection Works

1. The image is analyzed for face detection
2. Detected faces are returned as bounding boxes
3. Faces are sorted by area (largest first)
4. The crop is centered on the largest face
5. If no faces are detected, the crop falls back to center gravity

Face detection results are cached. Subsequent requests for the same image use cached results automatically.

Thumb Mode with Face Detection

When using r=thumb with facial gravity, Tuzzle applies smart zoom:

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

This produces tighter, portrait-style thumbnails focused on the subject's face.

Gravity with Different Resize Modes