Resize & Crop
Resizing and cropping images are the two basic geometry transformations. Like other Uploadcare image processing, 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/:dimensions/
Downscales an image proportionally to fit the given width and height in pixels.
:dimensions
— width and height in pixels separated byx
.
Example:320x240
.
If the dimensions are not specified, it'll be2048x2048
.
/: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.
:one_or_two_dimensions
— width and height in pixels separated byx
, one of the values can be omitted.
Examples:320x240
,320x
,x240
.
/:uuid/-/resize/320x240/
/:uuid/-/resize/320x/
/:uuid/-/resize/x240/
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.
:mode
— one of the following values: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.
Smart resize
-/smart_resize/: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.
:dimensions
— width and height in pixels separated byx
.
Example:320x240
.
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 that we are working on improving Smart resize and behaviour may change. Contact us if you found out regression.
Crop
-/crop/:dimensions/
-/crop/:dimensions/:alignment/
Crops an image by using specified dimensions and alignment.
:dimensions
— width and height in pixels or percents separated byx
.
Percent values are based on original size and should end with%
orp
char.
Examples:320x240
,50px240
,30%x25%
.:alignment
— horizontal and vertical offsets in pixels or percents separated by,
.
Offset in pixels is allowed to be negative. Percent values are a position of cropped area in full image canvas and should end with%
orp
char.
Examples:100,-50
,50p,240
,30%,25%
.
Also shortcuts as values are allowed:center
,top
,right
,bottom
,left
.
If the alignment is not specified, the0,0
is used.
In URLs, %
is an escape character and should be encoded with %25
escape
sequence, e.g. /crop/200x200/80%25,80%25/
. For convenience, you can use
the p
shortcut for percent which doesn't require encoding.
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.
Crop by ratio
-/crop/:ratio/
-/crop/:ratio/:alignment/
Crops the image to the specified aspect ratio, cutting off the rest of the image.
:ratio
— two numbers greater than zero separated by:
.
Ratio is the quotient from the division of these numbers.:alignment
— horizontal and vertical offsets in pixels or percents separated by,
.
Offset in pixels is allowed to be negative. Percent values are a position of cropped area in full image canvas and should end with%
orp
char.
Examples:100,-50
,50p,240
,30%,25%
.
Also shortcuts as values are allowed:center
,top
,right
,bottom
,left
.
If the alignment is not specified, the50%,50%
is used.
In URLs, %
is an escape character and should be encoded with %25
escape
sequence, e.g. /crop/4:3/80%25,80%25/
. For convenience, you can use
the p
shortcut for percent which doesn't require encoding.
Crop by objects
-/crop/:tag/
-/crop/:tag/:ratio/
-/crop/:tag/:ratio/:alignment/
-/crop/:tag/:dimensions/
-/crop/:tag/:dimensions/:alignment/
Crops the image to the object specified by the :tag
parameter.
:tag
— one of the following values:face
— the largest detected face in the image is used as a crop basis.image
— the whole image is used as a crop basis.
:ratio
— two numbers greater than zero separated by:
. Ratio is the quotient from the division of these numbers. The found object fits into the given aspect ratio.:dimensions
— width and height in percents separated byx
.
Percent values are based on the tag size and should end with%
orp
char.
Examples:150%x150%
,200%x100%
.:alignment
— horizontal and vertical offsets in percents separated by,
.
Percent values are a position of cropped area based on the selected tag location and should end with%
orp
char.
Examples:30%,25%
.
Also shortcuts as values are allowed:center
,top
,right
,bottom
,left
.
If the alignment is not specified, the50%,50%
is used.
In URLs, %
is an escape character and should be encoded with %25
escape
sequence, e.g. /crop/face/4:3/80%25,80%25/
. For convenience, you can use
the p
shortcut for percent which doesn't require encoding.
Scale crop
-/scale_crop/:dimensions/
-/scale_crop/:dimensions/:alignment/
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).
:dimensions
— width and height in pixels separated byx
.
Examples:320x240
,440x440
.:alignment
— horizontal and vertical offsets in percents separated by,
.
Percent values are a position of cropped area in full image canvas and should end with%
orp
char.
Examples:30%,25%
.
Also shortcuts as values are allowed:center
,top
,right
,bottom
,left
.
If the alignment is not specified, the0,0
is used.
In URLs, %
is an escape character and should be encoded with %25
escape
sequence, e.g. /scale_crop/440x440/80%25,80%25/
. For convenience, you can use
the p
shortcut for percent which doesn't require encoding.
Smart crop
-/scale_crop/:dimensions/:type/
-/scale_crop/:dimensions/:type/:alignment/
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.
:dimensions
— width and height in pixels separated byx
.
Examples:320x240
,440x440
.:type
- one of the following values:smart
(alias forsmart_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
:alignment
— horizontal and vertical offsets in percents separated by,
.
Percent values are a position of cropped area in full image canvas and should end with%
orp
char.
Examples:30%,25%
.
Also shortcuts as values are allowed:center
,top
,right
,bottom
,left
.
If the alignment is not specified, the0,0
is used.
In URLs, %
is an escape character and should be encoded with %25
escape
sequence, e.g. /scale_crop/440x440/smart/80%25,80%25/
. For convenience,
you can use the p
shortcut for percent which doesn't require encoding.
Content-aware mechanics of the smart crop are based on the following methods of image analysis:
- Face Detection,
:type
is set tosmart_faces
. Face detection identifies and locates human faces in digital images. - Object Detection,
:type
is set tosmart_object
. Object detection identifies and locates most visually important regions in the image. - Corner Points Detection,
:type
is set tosmart_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.
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 |
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.
Set fill color
-/setfill/:color/
Sets the fill color used with crop
,
stretch
or when converting an alpha channel enabled
image to JPEG.
:color
- color in hexadecimal notation with optional transparency.
Example:99ff99
,9f9
,99ff9920
.
Zoom objects
-/zoom_objects/:zoom/
Zoom objects operation is best suited for images with solid or uniform backgrounds.
:zoom
- sets the object's size in the image from 1 to 100.
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.