Documentation

crop Crop Mode

Crop mode controls how the image is aligned when fit=crop is set. The w and h parameters should be also be set, so that the crop behavior is defined within specific image dimensions.

Valid values are top, bottom, left, right, faces, focalpoint, edges, and entropy. Multiple values can be used by separating them with a comma ,. If no value is explicitly set, the default behavior is to crop from the center of the image.

Directional Cropping

The top, bottom, left, and right values allow you to specify the starting location of the crop. Image dimensions will be calculated from this starting point outward. These values can be combined by separating with commas, e.g. crop=top,left.

  • top: Crop from the top of the image, down.
  • bottom: Crop from the bottom of the image, up.
  • left: Crop from the left of the image, right.
  • right: Crop from the right of the image, left.

Face Cropping

The following example illustrates the difference between the default centered crop and one made with facial detection turned on. The source image in this example is being cropped to a square. If faces are detected in the image, attempts to center the crop to them. Otherwise, the cropping alignment will default to centered if no additional values are provided. For example, crop=faces,top,right will crop to faces, and if there are no faces, then crops to the top right corner.

Default (crop from center)
Woman
crop=faces
Woman

Focal Point Cropping

The following example illustrates the difference between the default centered crop and one made with focal point parameters to target and zoom to a portion of the image. The source image in this example is being cropped to a square. When set in combination with a relative horizontal (fp-x), vertical (fp-y), and/or zoom (fp-z) value, will center the image on those coordinates and crop from there.

Original
Walrus
fp-x=.825&fp-y=.35&fp-z=2
Walrus.jpg?h=320&w=320&fit=crop&crop=focalpoint&fp x=.825&fp y=
fp-x=.12&fp-y=.55&fp-z=2
Walrus.jpg?h=320&w=320&fit=crop&crop=focalpoint&fp x=.12&fp y=

Entropy and Edge Detection Cropping

The following example illustrates the difference between the entropy crop and edges automatic cropping methods. The source image in this example is being cropped to a wide rectangle. The entropy crop automatically finds and crops to an area of interest by looking for busy sections of the image. The edges crop automatically finds and crops to an area of interest by performing edge detection, looking for objects within the image.

Original
Kayak
crop=entropy
Kayak
crop=edges
Kayak