Crop Mode crop

Crop mode controls how the image is aligned when fit=crop is set. The w and h parameters should 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, which will crop to the top or left of an image depending on the image's aspect ratio.

  • 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. Other fallback methods include crop=faces,entropy, crop=faces,edges, crop=faces,center and crop=faces,focalpoint.

Default (crop from center)
crop=faces

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

fp-x=.825&fp-y=.35&fp-z=2

fp-x=.12&fp-y=.55&fp-z=2

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.

Please note:
Because they operate per frame, crop=entropy or crop=edges may cause unexpected results on animated images.

See the API specification for more information about this parameter's value ranges and format.