The size parameters allow you to control all aspects of resizing, cropping, and the fit-to-crop behaviour of your image.
width (w)
This parameter sets width of output image. w
is an alias for this parameter.
If this parameter is omitted, and the height
parameter is set, the output width is set automatically such that aspect ratio is preserved. If both height
and width
parameters are set, the output image dimensions are set as per mode parameter.
If none of the height
and width
parameters are set, original aspect ratio is preserved and output dimensions depend on parameters like scale if provided.
Maximum value for this is 8192 and any output which has more than this width will be scaled down to this value.
width=250 | Original |
---|---|
height (h)
This parameter sets height of output image. h
is an alias for this parameter.
If this parameter is omitted, and the width
parameter is set, the output height is set automatically such that aspect ratio is preserved. If both height
and width
parameters are set, the output image dimensions are set as per mode setting.
If none of the height
and width
parameters are set, original aspect ratio is preserved and output dimensions depend on parameters like scale if provided.
Maximum value for this is 8192 and any output which has more than this height will be scaled down to this value.
height=250 | Original |
---|---|
dpr
Specifies device pixel ratio. Valid values are between 1.0
and 3.0
and floating point numbers are valid parameters. This acts as multiplier to both width and height. width=200&height=300&dpr=2
is equivalent to width=400&height=600
.
This makes it easy to specify image with correct resolution when using srcset
attribute of <img>
tag.
enlarge
This boolean parameter specifies whether the output image should be enlarged if input image dimensions are smaller than required dimensions.
For example, if input image width is 800px
wide and width=1000
is specified, the output image will still remain 800px
. If enlarge=true
is set then only the output image will have 1000px width
.
Default value of this parameter is false
if mode
is crop
or stretch
and true
otherwise. You can't override the default false
if mode
is set to crop
or stretch
mode
Specifies the resize behavior when width or height parameters are provided.
-
fit: Resize to fit within boundaries specified by
width
andheight
parameters. If ratio given differs from original aspect ratio, only one dimension will be set as per given value and other dimension will be smaller such that original aspect ratio is maintained. -
crop: Entire area defined is filled maintaining aspect ratio but might crop part of image. The type of cropping is determined by crop parameter.
-
stretch: Resize to fill area defined by height and width. It might not preserve aspect ratio and image might be distorted.
-
min: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to the
width
andheight
specified. -
max: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to the
width
andheight
specified. -
fill: Preserving aspect ratio, resize the image to the maximum
width
orheight
specified then embed on a background of the exact width and height as original image. You can fill excess space with fill parameter. -
fillmax: Resize the image by preserving the aspect ratio and without stretching the original image. If the requested width or height exceeds the original, it will fill the space with a solid color or blurred version of the image, based on fill parameter value.
Default mode is fit
.
mode=fit | mode=crop | mode=stretch |
---|---|---|
fill
This parameter specifies how to fill the extra space created by mode=fill
.
-
solid
Fills excess space with solid color specified by parameterfill-color
. Iffill-color
is not specified then access space will be filled withwhite
. -
blur
Fills excess space with the blurred original image. -
background
Fills excess space with top-left corner colour.
Default value of this parameter is solid
.
mode=fill&fill=background | mode=fill&fill=solid&fill-color=c0c0c0 | mode=fill&fill=blur |
---|---|---|
crop
Allows you to define crop position when using crop
as mode parameter.
Valid values are entropy
, smart
, top
, topleft
, left
, bottomleft
, bottom
, bottomright
, right
, topright
, faces
, center
and focalpoint
.
While other modes are self explanatory, let us describe first some special crop modes.
- faces: detects all faces in an image and tries to keep them in center in cropped image.
mode=crop&crop=faces | original |
---|---|
-
entropy: focus on region with highest Shanon Entropy.
-
smart: focus on region with highest luminance frequency and skin tones. Gumlet automatically finds person or other objects in image and keeps them in center while cropping.
-
focalpoint: focus on point given by you. It allows you to define the point of focus by
fp-x
andfp-y
. You can also define zoom usingfp-z
.fp-x
andfp-y
must be float value between0.0
to1.0
and default value will be0.5
.fp-z
can be in the range of1
to10
and default value is1
.
Default mode if no parameter is provided is center
.
mode=crop | mode=crop&crop=smart | mode=crop&crop=focalpoint |
---|---|---|
mask
It mask the image as per the given input. current supported mask shapes are ellipse
and corners
.
- ellipse Mask image into ellipse shape. When masked image is output as a PNG, masked area will be transparent otherwise it will be the default background. To get the circle shape with mask, the output image must have the same width and height otherwise it will be oval.
- cornersMask the corner of the image rounded. One can control it using the
rpixels
parameter by providing a pixel value that needs to be rounded.
mask=ellipse | mask=corners | original |
---|---|---|
extract (rect)
Extract a region from image. rect
is an alias for this parameter. This operation is always applied before resize
operation. Please give the parameters according to original image.
The value should be provided as comma separated list left,top,width,height
.
left
is zero-indexed offset from left edgetop
is zero-indexed offset from top edgewidth
of extracted imageheight
of extracted image
extract=0,0,300,300 | extract=300,300,200,200 | original |
---|---|---|
aspect ratio (ar)
Resize and crop the image to given aspect ratio. This parameter will work only with mode=crop
. ar
is proportional representation between width and height.
E.g. ar=3:4&mode=crop
will crop image in aspect ratio of 3:4. You can add one dimension (height or width) along with ar
and other dimension will be automatically calculated based on aspect ratio. height=400&ar=3:4&mode=crop
here width 300 will be automatically calculated.
height=400&ar=3:4&mode=crop | ar=1:1&mode=crop&crop=smart | original |
---|---|---|
pad
Pads/Extends the edges of the image with the color provided by the background
parameter. The value should either be integer which adds padding of same number of pixel to all edges or it should be comma separated list of 4 integers as top,right,bottom,left
.
E.g. pad=40,20,40,30
will add 40px
padding on top, 20px
on right, 40px
on bottom and 30px
on left. If you want to add same padding to all sides, you can provide just one number like pad=40
and it will add 40px
on all sides.
Please note this operation will add additional pixels and hence increase height and width of image. This operation is applied after resize
. Please provide padding parameters accordingly.
pad=30,30,30,30&bg=b03e5c | original |
---|---|
trim
Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel. The value of this parameter is number between 1
to 99
representing the percentage similarity.
This operation is applied after resize
.
trim=50 | original | |
---|---|---|
dpi
Dots per inch (DPI) specifies how should we convert SVG or PDF files which are vector images to raster images like JPEG. Higher the parameter, bigger the default output sizes will be.
Default value is 72
.