Version: next


Resize can be a very complex task in Caravaggio. There are plenty of ways of resizing, cropping and extract portion of your images.
In general a resize command take this shape

rs,s:<size>,m:<mode>,iar:<true|false>,b:<background color>,g:<gravity>

rs means you want change the final dimension of your image.
s is the new size (it can be expressed in several ways as explaned here).
m define how to resize. Maybe you want to stretch the image, or take just a portion. See below;
Some parameters apply to some modes only
b background color, in case the new image won't fit the entire viewport g is the gravity to decide the new position iar mean Ignore Aspect Ratio. Some transformations let you stretch the image without keeping the original proportions

Resize methods


In scale mode the image will have the dimension of the size you specified. The aspect ratio is kept unless you pass iar (ignore aspect ratio) as additional parameter.
Since scale is the default resize mode, you can avoid specifiying it.

Scale the image to 200x300 px keeping the aspect ratio


Scale the image to 200 px width keeping the aspect ratio. The height is calculated automatically


Scale the image to 200x300 px width ignoring the aspect ratio.


Two girls

Smaller image of two girls


The image will take the maximum available space up to the specified size, keeping the aspect ratio.
For example this will resize the image up to 300x300 pixels and all the image will be visible.


Two girls, the image is fitted

NOTE: both width and height must be passed. Nonetheless they can be expressed in percentage

Down fit

Like fit but only if the image is larger than the desired size (width or height), otherwise it will be left untouched.


NOTE: both width and height must be passed. Nonetheless they can be expressed in percentage

Up fit

Like fit but only if the image is smaller than the desired size (both the width and height must be smaller), otherwise it will be left untouched.


NOTE: both width and height must be passed. Nonetheless they can be expressed in percentage


Produce a new image of specified width and height. The original image is then filled inside those dimensions. The excess part will be excluded.
You can specify a gravity to decide which part of the original image should be excluded. If nothing is specified the default gravity is center.

In this example we fill the image in a 300x300 px space, with gravity on the center


Two girls, image is filled. Gravity is on the center

Here instead we change the gravity to north-east


Two girls, image is filled with north east gravity

Fill also accept a special gravity parameter: auto. This let you automatically select a meaningfull region of the image.
Here an example


One girl. She is on the left side of the picture. The rest of the image has no particulars

Gravity on center (rs_200x300_fill_center)

One girl, filled with gravity on the center

Gravity auto (rs_200x300_fill_auto)

One girl, filled auto, the girl is now centered in the image

Down fill

Same as fill but only if the image is larger than the target size (width and height).



This embeds the image in the specified dimensions. The entire image is taken and aspect ratio is kept. If the image doesn't fit well in the dimension the output will be padded with a color of your choice (or black by default). A gravity can be specified to decide how to embed the image. Both gravity and background color are optional


Two girls. The picture is embedded and the remaining space is black

You can specify the color in RGB (red: 105, green: 72, blue: 200). Each number must have 3 digits, you have to pad them (so 72 must be written as 072).


Two girls. The picture is embedded and the remaining space is purple

The color can be specified in RGBA. To add the alpha channel value append .n at the end. To have full transparency put .0, to have full opacity put nothing, just the color.


The color can be specified in hexadecimal code (6 digit). Alpha can be specified as well


You can spcify the gravity


Two girls. The picture is embedded with gravity on north


The size parameter can be specified in several format in each resize mode.


rs,s:200x300 is 200 x 300 px
rs,s:200 is 200 px width, height auto
rs,s:x300 is 200 px height, width auto


You can specify the width and height as percentage value of the input image

rs,s:0.2x0.3 is 20% of the width and 30% of the height
rs,s:0.2 is 20% of the width
rs,s:x0.3 is 30% of the height


Pixel and percentage can be mixed.

rs,s:200x0.3 is 200px of width and 30% of height


For those operations which support gravity, those value can be specified

center, north, northeast, northwest, east, west, south, southeast, southwest

and can be abbreviated in

c, n, ne, nw, e, w, s, se, sw.

Some operations, such as fill and downfill, accept the auto gravity. This automatically focus on the most important region of the image. Look here for an example.


The colors accepetd by some operations can be expressed as:

RGB 120230007 in this case the rgb(120, 230, 7)

The three values of red, green and blue must be put together and each must be of three digits, so 7 becomes 007 and 45 becomes 045.

Hexadecimal FF00AB is in the hex format. The short notation (3 digits only) is not accepted yet and # at the beginning must be removed.

To specify the opacity you can add .N at the end. So to set an opacity of 0.4 the previouses become 120230007.4 and FF00AB.4
Omitting the opacity means it is 1, full opaque, while .0 means full transparent.