Resize and Crop

Resizing and cropping images are the two basic geometry transformations. Like other Uploadcare image transformations, they're non-destructive and applied at the CDN delivery stage.

The order of operations is important. For example, when you resize an image first, the following crop operation will use the coordinates of the resized image.

Preview

-/preview/
-/preview/:two_dimensions/

Downscales an image proportionally to fit the given width and height in pixels. If the dimensions are not specified, it'll be 2048x2048.

/:uuid/-/preview/
/:uuid/-/preview/300x500/

Resize

-/resize/:one_or_two_dimensions/

Resizes an image to one or two dimensions. When you set both width and height explicitly, it may result in a distorted image. If you specify either side, this operation will preserve the original aspect ratio and resize the image accordingly.

/:uuid/-/resize/200x200/
/:uuid/-/resize/200x/
/:uuid/-/resize/x200/

Change resize behavior

-/stretch/:mode/

Sets the resize and scale_crop behavior when a source image is smaller than the requested dimensions. The order is important: a stretch operation applies to its following resize or scale_crop. You can use multiple resizing operations with individual stretch behavior for each one.

  • on — an image can be scaled up (default).
  • off — an image won't be scaled up.
  • fill — no image scaling up. The background color fills the remaining parts.
Resized image but stretched
/preview/160x160/-
/resize/220x/		Resized image, same dimensions
/preview/160x160/-
/stretch/off/-
/resize/220x/		Resized image, same placeholder size with a background fill
/preview/160x160/-
/stretch/fill/-
/resize/220x/

Smart resize

-/smart_resize/:two_dimensions/

Content-aware resize helps retaining original proportions of faces and other visually sensible objects while resizing the rest of the image using intelligent algorithms.


Original image, 440x500

/smart_resize/440x600/

/smart_resize/440x300/

Smart resize works best for solid, gradient, and homogenous backgrounds that'll be expanded. If background stretching can't be done without artifacts, a solid fill with a matching color will be applied instead.

Note: We are working on improving Smart resize and behaviour may change. Contact us if you found out regression.

Crop

-/crop/:two_dimensions/
-/crop/:two_dimensions/:two_coords/
-/crop/:two_dimensions/:alignment/

Crops an image by using specified dimensions and offsets. You can set offset in pixels and percent. :alignment values: center, top, right, bottom, left. If no values are set, the top-left image corner is used.

In URLs, % is an escape character; it can’t be used as-is. Use a %25 escape sequence or a p shortcut for percent.

Original image
Original image.		Crop to center
/crop/2000x1325/center/		Crop to coordinates
/crop/960x636/2400,700/

If given dimensions are greater than the ones of the original image, the image is rendered inside a color-filled box. The color of that box can be changed via the setfill operation.

Scale Crop

-/scale_crop/:two_dimensions/
-/scale_crop/:two_dimensions/:offsets/

Scales an image until it fully covers the specified dimensions; the rest gets cropped. Mostly used to place images with various dimensions into placeholders (e.g., square shaped).

Here's an example that shows the difference between three operations:

Resize image to a size, stretched
/resize/1024x1024/
Requested size.
Distorted.		Adjust size, keep dimensions
/preview/1024x1024/
Adjusted size.
No distortion.		Resize image to a placeholder, zoom and crop
/scale_crop/1024x1024/
Requested size.
No distortion.
  • :offsets — string, format: M%,N%, where M and N are the optional offsets along one or both of the axes in percentages; other possible values include:
  • center — a keyword responsible for centering the crop focus.

Smart Crop

When smart :type is specified.

Switching the crop type to one of the smart modes enables the content-aware mechanics. Uploadcare applies AI-based algorithms to detect faces and other visually sensible objects to crop the background and not the main object.

Example:

Smart crop to an object
/scale_crop/1024x1024/smart/
Smart cropping.

Content-aware mechanics of the smart crop are based on the following methods of image analysis:

  • Face Detection, :type is set to smart_faces. Face detection identifies and locates human faces in digital images.
  • Object Detection, :type is set to smart_object. Object detection identifies and locates most visually important regions in the image.
  • Corner Points Detection, :type is set to smart_points. This method analyses image pixels to find the high contrast corners in the image, useful for abstract, landscape, and art images. The corner points have much less semantic information than other methods and designed to be used as a fallback.

The methods you include separating by underscore are applied sequentially. The algorithm switches to the next method only if no regions were found by the previous one. For example smart_faces_objects_points applies face detection initially as the first step. Only when no faces are found on an image, the object detection will be used. Finally, when no objects are found, the corner points will be detected.

If specified methods were unable to find regions or points of interest, the :offset setting will be used to crop an image. When no :offsets are specified, images get center-cropped.

Smart crop always tries to save the maximum amount of pixels from the original image. It first applies scale operation and then cuts horizontal or vertical excesses.

Cropped image, auto centered on a face
smart_faces_objects
Centering on faces or objects
when no faces found.
Cropped image, auto centered on objects and faces
smart_objects_faces
Centering on objects or faces
when no objects found.
Image centering on hard edges
smart_points
Centering on corner points.

Possible :type values:

  • smart (alias for smart_faces_objects_points)
  • smart_faces_objects
  • smart_faces_points
  • smart_objects_faces_points
  • smart_objects_faces
  • smart_objects_points
  • smart_points
  • smart_objects
  • smart_faces

Set fill color

-/setfill/:color/

Sets the fill color used with crop, stretch or when converting an alpha channel enabled image to JPEG. The operation uses hexadecimal notation to define colors.

Image, cropped to center, resized on a white background
/preview/440x380/-
/crop/440x380/center/		Image, cropped to center, resized with a color filled background
/preview/440x380/-
/setfill/ece3d2/-
/crop/440x380/center/		PNG image with alpha channel converted to JPEG with a background fill
/setfill/ece3d2/-
/format/jpeg/

Zoom objects

-/zoom_objects/:zoom/

:zoom - sets the object's size in the image from 1 to 100.

Zoom objects operation is best suited for images with solid or uniform backgrounds.

As a result of the operation, the object's size in the image will change. The resolution of the image after the operation will remain the same. For example, an object in an image with applied operation -/zoom_objects/100/ is the object that occupies the maximum area of this image.


/zoom_objects/20/

/zoom_objects/50/

/zoom_objects/100/