crop

Removes pixels from an image.

When specifying a crop parameter, the value starts with the desired width and height, either as measurements of pixels, separated with a comma, or as a ratio, separated with a colon (for example, crop=4:3 or crop=640,480 or crop=0.8,0.4).

The remaining parameters determine the position of the cropped region. On each dimension, placement can be made either with a position coordinate (x or y, which are relative to the top left of the uncropped image) or as a percentage offset from the center of the image using offset-x and offset-y. These can be mixed and matched, but only one method can be used for each dimension (i.e., x can be combined with offset-y but x cannot be combined with offset-x).

Offset positioning acts to distribute the remaining space according to the specified offset proportions. If an image is 2000 pixels wide and is being cropped to 1000 pixels wide, offset-x10 would crop 10% (100 pixels) from the left of the image and 90% (900 pixels) from the right. An offset of 50 centers the crop in the middle of the image.

Appending ,smart to the parameter value enables content-aware algorithms to attempt to crop the image to the desired aspect ratio while intelligently focusing on the most important visual content, including the detection of faces.

If the specified cropped region is outside the bounds of the image, the transformation will fail with the error "Invalid transformation for requested image: Invalid crop, region out of bounds". Append ,safe to the parameter value to override this. In safe mode, the image gets delivered as an intersection of the origin image and the specified cropped region. This avoids the error, but the resulting image may not be of the specified dimensions.

Syntax

crop={SIZE}
crop={SIZE},safe
crop={SIZE},smart
crop={SIZE},{POSITION}
crop={SIZE},{POSITION},safe
crop={SIZE},{POSITION},smart

SIZE can be:

{width},{height}
{width-ratio}:{height-ratio}

POSITION can be:

x{x},y{y}
offset-x{offset-x},offset-y{offset-y}
x{x},offset-y{offset-y}
offset-x{offset-x},y{y}

Sub-parameters

ParamUnits
widthPixels or Percentage
heightPixels or Percentage
width-ratioNumber
height-ratioNumber
xPixels or Percentage
yPixels or Percentage
offset-xPercentage
offset-yPercentage
smartnone
safenone

Notes

  1. x and y can be set as a value in pixels (e.g., 40 is 40 pixels) or as a percentage suffixed with p (e.g., 50p is 50%).
  2. offset-x and offset-y are always interpreted as percentages of the image size (e.g., 25 is 25%).
  3. When using aspect ratio cropping, crop must be used in conjunction with a width or height parameter (or both) to return the correct output image size. If no width or height are supplied, the largest area of the requested aspect ratio will be returned based on the dimensions of the source image.
  4. If any dimension ends up at a fraction of a pixel, it is rounded to the nearest whole pixel.

Examples

Click the links to view the transformed image using a demo Fastly IO service.

Example usageDescription
?crop=1000,500Crop the image to 1000px by 500px
?crop=16:9Crop the image to an aspect ratio of 16:9
?crop=1000,500,x400,y50Crop the image to 1000px by 500px and select the starting sub region x coordinate to be 400px and the y sub region to be 50px
?crop=1:1,offset-x90,offset-y10Crop the image square and offset the crop on the x-axis such that 90% of the cropped content is removed from the left and 10% from the right
?crop=3000,600,x100,y100,safeFail-safe crop the image to 3000x600 and select the starting sub region x coordinate to be 100px and the y sub region to be 100px
?crop=1:1&width=200Crop the image square and resize the width to 200px
?trim=0.30&width=200&crop=1:1,smartTrim 30% of the image, resize the width to 200px and crop the image square using content-aware image cropping