Resize and Crop

Uploadcare Image Transformations allow you to adjust image size and crop options on the fly, adjust resizing behavior, and set a background fill color when cropping images.

Preview

-/preview/
-/preview/:two_dimensions/

Reduces an image proportionally for it to fit into the given dimensions in pixels. If dimensions are not specified, we use the default values of 2048x2048 pixels.

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

Resize

/resize/:one_or_two_dimensions/

Resizes an image to fit into the specified dimensions. With just a single linear dimension specified, preserves your original aspect ratio and resizes an image along one of its axes.

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

Change resize behavior

-/stretch/:mode/

Sets the resize behavior when a source image is smaller than the resulting dimensions. The following modes can apply:

  • on — stretches an image up, the default option.
  • off — forbids stretching an image along any dimension that exceeds image size along any of its axes.
  • fill — does not stretch an image, the color-filled frame is rendered around instead, the default fill color is used.

/preview/160x160/-
/resize/220x/

/preview/160x160/-
/stretch/off/-
/resize/220x/

/preview/160x160/-
/stretch/fill/-
/resize/220x/

Crop

-/crop/:two_dimensions/
-/crop/:two_dimensions/:two_coords/
-/crop/:two_dimensions/center/

Crops an image using specified dimensions and offsets. If no offset values are passed into the operation, the top-left image corner is used by default.


Original image.

/crop/2000x1325/center/

/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/:type/
-/scale_crop/:two_dimensions/:offsets/
-/scale_crop/:two_dimensions/:type/:offsets/

When :type is not specified.

Scales down an image until one of its dimensions gets equal to some of the specified ones; the rest is cropped. This proves useful when your want to fit as much of your image as possible into a box. Let us compare the two resizing methods:


/resize/1024x1024/
Requested size.
Distorted.

/preview/1024x1024/
Adjusted size.
No distortion.

/scale_crop/1024x1024/
Requested size.
No distortion.
  • :offsetsstring, 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 mechanic. Uploadcare applies AI-based algorithms to detect faces and other visually important objects or regions in images and crops the rest.

Example:


/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_faces_objects
Centering on faces or objects
when no faces found.

smart_objects_faces
Centering on objects or faces
when no objects found.

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.


/preview/440x380/-
/crop/440x380/center/

/preview/440x380/-
/setfill/ece3d2/-
/crop/440x380/center/

/setfill/ece3d2/-
/format/jpeg/