Search Documentation

fit Resize Fit Mode

The fit parameter controls how the output image is fit to its target dimensions after resizing, and how any background areas will be filled

Valid values are clamp, clip, crop, facearea, fill, fillmax, max, min, and scale. The default value is clip.

fit=clamp

Resizes the image to fit within the width and height dimensions without cropping or distorting the image, and the remaining space is filled with extended pixels from the edge of the image. The resulting image will match the constraining dimensions. The pixel extension is called an affine clamp, hence the value name, “clamp”.

Example of how clamp works

fit=clip

Default. Resizes the image to fit within the width and height boundaries without cropping or distorting the image. The resulting image will match one of the constraining dimensions, while the other dimension is altered to maintain the same aspect ratio of the input image.

Example of how clip works

  • Unset: This is the original image at 300×200 with no parameters applied. clip is the default, so is not necessary.

    original image

  • fit=clip&w=100&h=100: Attempting to resize this image to be 100×100 with a fit mode of clip will result in an image that is 100×67 because the aspect ratio of the original image is maintained.

    Clipped image

fit=crop

Resizes the image to fill the width and height dimensions and crops any excess image data. The resulting image will match the width and height constraints without distorting the image. It’s used in conjunction with the the crop parameter, which controls how the image is cropped. Both the w and h parameters will also need to be set.

Example of how crop works

  • Unset: Default. This is the original image at 300×200 size with no parameters applied.

    original image

  • fit=crop&w=300&h=100: Resizing the image to 300×100 with fit=crop will fit the image exactly to those dimensions.

    Cropped image

  • fit=crop&w=200&h=200: Setting an equal value for width and height along with fit=crop will always result in a square image. To adjust the position of the content in a cropped image, please review the crop mode parameter.

    Image cropped to square

fit=facearea

Finds the area containing all faces, or a specific face in an image, and scales it to specified width and height dimensions. Can be used in conjunction with faceindex to identify a specific face, as well as facepad to include additional padded area around the face to zoom out from the immediate area around the faces.

Example of how facearea works

  • Unset: Default. This is the entire image, with no face area cropping, resized to 300×200.

    Original image

  • fit=facearea&w=300&h=200: Crops and resizes the image to 300×200, with the faces centered as closely as possible. The output is the correct requested size, depending on the output aspect ratio and face area availability.

    Cropped image, with faces centered

  • fit=facearea&faceindex=2&facepad=1.5&w=300&h=300: Crops and resizes the image to 300×300, making use of the faceindex and facepad parameters to select a face within the image and zoom in.

    Image with one face selected

fit=fill

Resizes the image to fit within the width and height dimensions without cropping or distorting the image, and fills the remaining space with a solid color. The resulting image will match the constraining dimensions. The bg parameter must be set to the color desired to fill the space.

Example of how fill works Fill legend

  • Unset: Default. Original image sized to 400×200, with no fit mode applied.

    Original image

  • fit=fill&bg=cc: Original image sized to 400×200, with fit=fill and bg=ccc

    Resized with fill

fit=fillmax

Resizes the image to fit within the width and height dimensions without cropping or distorting the image, and fills the remaining space with a solid color. If the width or height of the specified dimensions exceeds that of the original, the original will remain the same size, and the remaining space will be filled with the set background color. The resulting image will match the constraining dimensions. The bg parameter must be set to the color desired to fill the space.

Example of how fillmax works Fill legend

  • Unset: Default. Original image sized to 500×200, with no fit mode applied.

    Original image

  • fit=fillmax&w=500&h=200&bg=F0A56A: Resizing the image to 500×200, wider than the original. The image is centered and the background fills the remaining space with a specified background color. bg must be set in order for fillmax to work properly.

    Image with fillmax

  • fit=fillmax&w=200&h=200&bg=F0A56A&pad=60: Resizing the image to 200×200, and adding a pad value, will scale down the image to fit. The image is centered and scaled into place, while the extra area is filled with a specified background color. bg must be set in order for fill to work properly.

    Image with fillmax and padding

fit=max

Resizes the image to fit within the width and height dimensions without cropping or distorting the image, but will not increase the size of the image if it is smaller than the output size. The resulting image will maintain the same aspect ratio of the input image.

Example of how max works Max legend

  • Unset: Default. This is the original image at 300×200 with no parameters applied.

    Original image

  • fit=max&w=500&h=300: Attempting to resize to 500×300 will result in an image that is 300×200, the original dimensions of the image, applying max will not scale up the image.

    Image with fit=max

  • fit=max&w=200&h=400: Attempting to resize to 200×400 will result in a 200×133 image. This behavior is somewhat similar to clip.

    Image resized outside of bounds

fit=min

Resizes and crops the image to match the aspect ratio of the requested width and height. Will not exceed the original width and height of the image.

Example of how min works

  • Unset: This is the original image at 300×200 with no parameters applied.

    Original image

  • fit=min&w=500&h=200: Attempting to resize to 500×200 will result in an image that is 300×120, The requested aspect ratio is maintained and the image will be cropped, but the image will not exceed its original size.

    image with fit=min

  • fit=min&w=200&h=400: Attempting to resize to 200×400 will result in a 100×200 image. The requested aspect ratio is maintained and the image will be cropped, but the image will not exceed its original size.

    Image resized outside of bounds

fit=scale

Scales the image to fit the constraining dimensions exactly. The resulting image will fill the dimensions, and will not maintain the aspect ratio of the input image.

Example of how scale works

  • Unset: This is the original image at 300×200 with no parameters applied.

    Original image

  • fit=scale&w=500&h=200: Resizing the image to 500×100, wider than the original, the image is scaled and distorted horizontally to fit dimensions.

    Image scaled

  • fit=scale&w=100&h=300: Resizing the image to 100×300, taller than the original, the image is scaled and distorted vertically to fit dimensions.

    Image scaled