Transformations
There are two kinds of transformations: ones that actually modify the image (or video) and others that change the context of further transformations down the manipulation chain. You'll find both types listed here, in alphabetical order, each with a short description of its specific syntax and behavior.
background
Syntax: background=<color>
background specifies a color that will show through transparent and translucent parts of the image. This will have no effect on images with no transparency nor translucency.
If multiple background
transformations are specified, they are applied in order. If a background
uses an opaque color, any background
coming after will be ignored.
contain
Syntax: contain=<size>
contain behaves like the CSS background size "contain". It will resize the image so that it completely fits inside the target area while conserving the original aspect ratio. The resulting image will be smaller than a target size which aspect ratio is not the same as the aspect ratio of the input.
For instance, applying contain=150x100
to our beloved face of a cat will result in the following 150x94 image:
Result |
---|
![]() |
contain-max
Syntax: contain-max=<pixel size>
A conditional version of contain that will be applied only when one of the given lengths is smaller than the corresponding input image dimension.
contain-min
Syntax: contain-min=<pixel size>
A conditional version of contain that will be applied only when one of the given lengths is larger than the corresponding input image dimension.
cover
cover behaves like the CSS background size "cover". It will resize the image so that it completely fills the target area while conserving the original aspect ratio. If some parts of the image end up outside of the covered area, they are cropped.
So, a cover=100x100
of a 300x188 image would first scale the image down to a height of 100 pixels and then crop along the x-axis as demonstrated below:
Process | Result |
---|---|
![]() | ![]() |
cover will use the focus point as a guide and will crop the image so that the focus point is as central as possible in the resulting image. For instance, focus=85x85/cover=100x100
will behave as follows:
Process | Result |
---|---|
![]() | ![]() |
When a ratio is provided, cover will extract the biggest possible area that satisfies the ratio and is as centered on the focus point as possible. For instance, focus=85x85/cover=1:1
will behave as follows:
Process | Result |
---|---|
![]() | ![]() |
cover-max
Syntax: cover-max=<pixel size>
A conditional version of cover that will be applied only when one of the given lengths is smaller than the corresponding input image dimension.
cover-min
Syntax: cover-min=<pixel size>
A conditional version of cover that will be applied only when one of the given lengths is larger than the corresponding input image dimension.
crop
Syntax: crop=<crop size>[@<coordinates>]
crop will extract a zone from the image which size is the given crop size. If no coordinates are given, the focus point will be used as a guide to determine where to start the extraction. If coordinates are given, they will be used to determine the top-left pixel from which to start the extraction and the focus point will be reset to the center of the resulting image.
Here are two examples:
Manipulation | Process | Result |
---|---|---|
crop=200x100 | ![]() | ![]() |
crop=200x100@20x50 | ![]() | ![]() |
flip
Syntax: flip=<expression>
flip will invert the image horizontally, vertically or both depending on the expression provided.
Expression | Axis | Result |
---|---|---|
both | horizontal and vertical | ![]() |
x | horizontal | ![]() |
y | vertical | ![]() |
focus
Syntax: focus=<coordinates> or focus=auto
focus will set the focus point coordinates. It doesn't modify the output image in any way but will change the behavior of further transformations that take the focus point into account (namely cover, crop and resize).
If auto
is used in place of actual coordinates, the focus point will be chosen automagically for you! Note that auto
is not implemented for videos yet.
max
Syntax: max=<pixel size>
Alias of contain-max.
min
Syntax: min=<pixel size>
Alias of contain-min.
output
Syntax: output=<format>
Specifies the output format. It can be an image format, a video format or a preview format. Only the last output in the manipulation expression is taken into account. By default, TwicPics will "smart-guess" the best output format for the browser currently issueing the request but you can use output to override this behavior.
Available image formats are:
avif
for AV1 Image File Formatheif
for High Efficiency Image File Formatimage
(jpeg
orwebp
depending on the browser, useful to extract the first frame of a video)jpeg
for Joint Photographic Experts Grouppng
for Portable Network Graphicswebp
for WebP
Available video formats are:
h264
for an H.264 stream in an MPEG-4 Part 14 containerh265
for an H.265 stream in an MPEG-4 Part 14 containervp9
for a VP9 stream in a WebM container
Available preview formats are:
blank
: a blank, totally translucent version of the resulting imagemaincolor
: a solid color image containing the most represented color in the resulting imagemeancolor
: a solid color image containing the mean color of the resulting imagepreview
: a blurry preview of the resulting image
For videos, preview formats are based on the first frame of the resulting video.
Preview Format | Result |
---|---|
output=blank | |
output=maincolor | |
output=meancolor | |
output=preview |
In addition, you can use output=auto
to ensure TwicPics' "smart-guess" of the output image format is used even if an output format has already been specified by the default manipulation of your path.
quality
Syntax: quality=<number>
Specifies the output quality as a number between 1 and 100.
Note that quality
will be ignored when:
output
ispng
and truecolor is onoutput
is a preview format
quality-max
Syntax: quality-max=<number>
A conditional version of quality that will be applied only when given quality is below current quality.
Manipulation | Resulting quality |
---|---|
quality=100/quality-max=50 | 50 |
quality=20/quality-max=50 | 20 |
quality-max=50/quality=100 | 100 |
quality-min
Syntax: quality-min=<number>
A conditional version of quality that will be applied only when given quality is above current quality.
Manipulation | Resulting quality |
---|---|
quality=100/quality-min=50 | 100 |
quality=20/quality-min=50 | 50 |
quality-min=50/quality=20 | 20 |
resize
resize will resize the image to the specified size. If only one length is provided, the other dimension will be determined so as to respect the aspect ratio of the input image. If both lengths are provided, the aspect ratio may not be respected.
Here are three resize operations on the same source image:
Manipulation | Result |
---|---|
resize=100 | ![]() |
resize=-x100 | ![]() |
resize=100x100 | ![]() |
If a ratio is provided, the image will be resized so that it stays as close as possible to its current surface (i.e number of pixels) while respecting the given aspect ratio as closely as possible.
For instance, focus=85x85/resize=4:3
will result in the following 274x206 image:
Result |
---|
![]() |
The 300x188 image was resized to a 274x206 image (respecting the 4:3 ratio as best as possible). The initial surface was (300x188=) 56,400 pixels. The final surface is (274x206=) 56,444 pixels.
resize-max
Syntax: resize-max=<pixel size>
A conditional version of resize that will be applied only when one of the given lengths is smaller than the corresponding input image dimension.
resize-min
Syntax: resize-min=<pixel size>
A conditional version of resize that will be applied only when one of the given lengths is larger than the corresponding input image dimension.
truecolor
Syntax: truecolor=<boolean> or true-color=<boolean>
truecolor can be used to prevent color quantization. If no boolean is provided, true
is assumed. By default, quantization is allowed (truecolor=false
).
When may quantization occur? Whenever the output format is png
. By default, TwicPics will quantize colors to reduce the size of the output image. It is possible to prevent this behaviour by setting truecolor
to true
.
Be aware that TwicPics will automatically output PNG images when:
- no output format is specified,
- the source image has an alpha channel,
- and, target browser does not support WebP.
As such, use truecolor
if you want to distribute substantially larger but more accurate images with translucency to users on browsers with no WebP support.
turn
Syntax: turn=<number> or turn=<expression>
turn will change the orientation of the image. It accepts an angle in degrees or an expression. Angles will be rounded to the closest multiple of 90°.
Expression | Angle | Result |
---|---|---|
flip | 180° | ![]() |
left | -90° | ![]() |
right | 90° | ![]() |
zoom
Syntax: zoom=<number>`
Zooms into the image by a factor equal or superior to 1 towards the focus point while preserving the image size.
Factor | Result |
---|---|
1 | ![]() |
1.5 | ![]() |
2 | ![]() |
3 | ![]() |