Crops out the topmost part of an image if it contains a face.

To control the margin when cropping the face out, you can use the face_margin=Y operation where Y is a percentage of the face height. Its default value is 20. You can also use negative numbers if you would like to keep part of the face.

func=facehide

Examples

Finds the most prominent face in the image and crops it to specified dimension provided with the width and height parameters. If you however provide only one dimension, the other dimension will be chosen automatically to keep the aspect ratio of the face.

func=face

Examples

Face margin

Sets margins around the face. You can set equal margins with face_margin=X or separate horizontal and vertical margins (face_margin=W,H).

face_margin=X|W,H

Examples

Crops the image to specified dimensions (width and height) while keeping proportions and delivers the resulting image via CDN.

func=crop

Examples

Gravity

Specifies which part of the image you wish to keep while cropping. If you omit the gravity option, central cropping is performed.

gravity=X

Available gravity values

Examples

Chooses the most important image features and objects and sets the focal point on them when cropping.

gravity=smart

gravity=auto

gravity=face

Smart gravity

Sets the crop focal point on the people in the image or on the most prominent featues if no faces are detected. Useful for creating thumbnails from images with different aspect ratios.

Examples

Automatic gravity (legacy)

If you prefer to use the legacy automatic crop, just set gravity operation to auto.

Examples

Face gravity

When using gravity=face, all images with one dominant face are focused on this face upon cropping. If there are many or no faces in the image, gravity falls back to auto.

Examples

Allows to crop an image by defining the coordinates of the crop focal point. It is useful when you want to crop images where the coordinates of the point of interest are already known.

To set the coordinates of the focal point, use the gravity=X,Y operation where X and Y are the coordinates of the focal point (in pixels). Alternatively, you can set the coordinates as a percentage of the original image - gravity=Xp,Yp or gravity=xc,yc, where X,Y=0..100 and x,y=0..1.

gravity=X,Y

gravity=Xp,Yp|xc,yc

Examples

Original image:

Allows to crop an image by providing the cropping area. It is useful when you want to crop a specific part of the image. To set the coordinates of the crop rectangle, use the tl_px and br_px operations.

tl_px=X1,Y1

br_px=X2,Y2

Examples

Original image: /docs/kids.jpg

Combining positionable crop with resize modes

Positionable crop can be combined with all available resize functions - width/height, crop, fit, bound or cover. This operation is performed after the positionable crop.

Examples

Sets target aspect ratio or aspect ratio range when cropping. Aspect ratios can be set as decimal values (1.778) or ratios (16:9).

aspect_ratio=AR | ar=AR

aspect_ratio=AR1,AR2 | ar=AR1,AR2

Crop and resize

If you provide only one dimension parameter (width or height) and aspect_ratio, the other dimension will be calcualted. If you include both width and height in the URL, aspect_ratio is ignored.

Examples

Crop without resize

If you provide only aspect_ratio and no dimensions (width or height), the image will be cropped without resizing.

Examples

Aspect ratio range

You can spcify a range of aspect ratio, for example aspect_ratio=4:3,16:9. Images which fall within this range, will not be cropped. Useful to avoid very wide ot very tall images by cropping them to the closest aspect ratio.

Examples