Precrop

      Last updated September 22, 2020

    The precrop parameter removes pixels from an image before any other transformations occur. When specifying a precrop parameter, the values always start with width followed by height (for example, precrop=4:3 or precrop=640,480 or precrop=0.8,0.4). When pre-cropping a region of interest from an image (a.k.a., "art direction"), the x and y parameters determine the position of the sub-region of the source image, whereas the offset-x and offset-y parameters move the horizontal or vertical offset of the pre-crop. When specifying smart cropping, content-aware algorithms attempt to crop an image to a fixed aspect ratio while intelligently focusing on the most important visual content, including the detection of faces.

    Features

    API Pattern

    Aspect Ratio Pre-crop
    Smart cropping
    Fail-safe cropping

    Appending the fail-safe mode parameter safe to the precrop API ensures an output image will never return an error due to the specified pre-cropped region being out of bounds. When appended, the image gets delivered as an intersection of the origin image and the specified pre-cropped region. This avoids the error entirely, but the image may not match the specified dimensions.

    Parameter

    Parameter Description
    precrop Remove pixels from an image before any other transformations occur.

    Parameter Values

    Value Units Description
    width Pixels or Percentage The width of the image.
    height Pixels or Percentage The height of the image.
    width-ratio float The width ratio of the image.
    height-ratio float The height ratio of the image.
    x{value} Pixels or Percentage The x coordinate sub-region of the source image.
    y{value} Pixels or Percentage The y coordinate sub-region of the source image.
    offset-x{value} Percentage The horizontal offset of the source image.
    offset-y{value} Percentage The vertical offset of the source image.
    smart none Content-aware image cropping.
    safe none Fail-safe crop mode.

    Notes

    1. The x and y or offset-x and offset-y parameters are optional.
    2. The optional x and y or offset-x and offset-y parameters can be supplied in any order after the width and height.
    3. If no x, y or offset-x,offset-y parameters are supplied the image is cropped form the center point.
    4. The x parameter can be supplied without y and visa versa.
    5. The offset-x parameter can be supplied without offset-y and vice versa.
    6. When using aspect ratio cropping, the crop parameter must be used in conjunction with a width or height parameter (or both) in order 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.
    7. Pixel rounding is performed on all calculations in a decimal format (with as much accuracy as possible). The final value is then rounded down.

    Examples

    Description HTML Demo
    Pre-crop - Pre-crop the image to 150px by 100px. <img src="image.jpg?precrop=150,100"/> Example
    Aspect Ratio Pre-crop - Pre-crop the image to an aspect ratio of 16:9. <img src="image.jpg?precrop=16:9"/> Example
    Pre-crop Sub Region - Pre-crop the image to 150px by 100px and select the starting sub region x coordinate to be 50px and the y sub region to be 50px. <img src="image.jpg?precrop=150,100,x50,y50"/> Example
    Aspect Ratio Pre-crop & Offset - Pre-crop the image square and offset the x-axis 25% and the y-axis 50% <img src="image.jpg?precrop=1:1,offset-x0.25,offset-y0.50"/> Example
    Fail-safe Pre-crop - Fail-safe pre-crop the image to 3000x600 and select the starting sub region x coordinate to be 100px and the y sub region to be 100px. <img src="image.jpg??precrop=3000,600,x100,x100,safe"/> Example
    Advanced Examples (Combining Additional Parameters)
    Description HTML Additional Param Demo
    Aspect ratio pre-crop (with width) - Pre-crop the image square and resize the width to 200px. <img src="image.jpg?precrop=1:1&width=200"/> width Example
    Smart cropping - Trim 30% of the image, resize the width to 200px and pre-crop the image square using content-aware image cropping. <img src="mountaineer.jpg?trim=0.30&width=200&precrop=1:1,smart"/> width, trim Example
    Back to Top