---
title: 'API Transformations'
description: 'The complete reference of media transformations supported by the TwicPics API.'
category: 'reference'
position: 2
---

# Transformations

<docs-page-description :description="description"></docs-page-description>

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.

## Syntax

All transformations follow the same structure: `<name>=<parameters>`

where:

- `<name>` is the name of the transformation
- `<parameters>` is an expression specifying the parameters for the transformation

For instance:

- `resize=400` will resize the image to 400 pixels in width while conserving the source image aspect ratio
- `resize=640x480` will resize the image to exactly 640 pixels in width per 480 pixels in height, potentially altering its aspect ratio

## Fundamentals

<doc-alert>We refer to a list of one or several transformations as **a manipulation**.</doc-alert>

Transformations can be chained together using the character `/`. There is no limit to the number of transformations you can chain, save for the limit in size of a URL as enforced by your browser. No matter how complex the manipulation, TwicPics will optimize it for speed and accuracy on the fly.

### Focus point

Transformations behave differently depending on which point in the image is the main focus. TwicPics will do its best to keep this _focus point_ as central as possible within the transformed image.

By default, the _focus point_ is in the middle of the image but you can change its coordinates by using the <span class="api">[focus](/docs/reference/transformations#focus)</span> transformation.

### Chaining transformations

When adding a transformation to the chain, the parameters given are interpreted as if previous transformations had already been performed (ie. as if the source image was the result of the previous transformations).

For instance:

- `resize=340/resize=50p` will result in an image that is 170 pixel-wide
- `resize=50p/focus=20x10` will put the _focus point_ at coordinates `40x20` of the source image

Since TwicPics will optimize the manipulation, be aware that a transformation may shadow what came before it. For instance `resize=50p/resize=340` will result in an image that is 340 pixel-wide: TwicPics will simply ignore the first _resize_.

## List of transformations

### <span class="experimental">achromatopsia</span>

_Syntax_:

- <span class="api">achromatopsia=<[number](/docs/reference/parameters#number)></span>
- <span class="api">achro=<[number](/docs/reference/parameters#number)></span>
- <span class="api">achromatopsia</span>
- <span class="api">achro</span>

Corrects the colors of the image for color-blind people suffering from achromatopsia.

The _[number](/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples            |                                                             |
| ------------------- | :---------------------------------------------------------: |
| _none_              | <DocSample src="colors.png"/>                               |
| `achromatopsia=0.5` | <DocSample src="colors.png" transform="achromatopsia=0.5"/> |
| `achromatopsia`     | <DocSample src="colors.png" transform="achromatopsia"/>     |

### background

_Syntax_: <span class="api">background=<[color](/docs/reference/parameters#color)[+[color](/docs/reference/parameters#color)]*></span>

_`background`_ specifies a color, or a series of colors, that will show through transparent and translucent parts of the image.

The final background color will also fill the borders created by an _[inside](#inside)_ transformation. This can be superseded by using the _[border](#border)_ transformation.

All types of [color values](/docs/reference/parameters#color) are accepted (i.e., `background=red`, `background=rgb(255,0,0)`, etc).

If multiple colors are specified and/or if multiple _`background`_ transformations are specified, they are applied in order using [alpha compositing](https://en.wikipedia.org/wiki/Alpha_compositing). As a consequence, if, at one point, a color is opaque, any color and or _`background`_ transformation thereafter will be ignored.

For instance, `background=red.5+white` will create a pinkish background and so will `background=red.5+white+black` and `background=red.5+white/background=black`: the final black color will be ignored because white is opaque.

Note that _background_, _[border](#border)_ and _[colorize](#colorize)_ are chainable, see [how chaining works with colors](/docs/reference/color-chaining) for more information.

In addition to color values, the keyword `remove` can also be used. When `remove` is found, all previous background colors will be canceled and TwicPics will remove the image background using artificial intelligence. Following that, you have a translucent image and you're free to specify a new background color.

| Examples                 |                                                                 |
| ------------------------ | :-------------------------------------------------------------: |
| _none_                   | <DocSample src="cake.png"/>                                     |
| `background=remove`      | <DocSample src="cake.png" transform="background=remove"/> |
| `background=remove+cyan` | <DocSample src="cake.png" transform="background=remove+cyan"/>  |

<doc-alert>Please note that `background=remove` is still experimental and results are subject to change.</doc-alert>

### border

_Syntax_: <span class="api">border=<[color](/docs/reference/parameters#color)></span>

_border_ specifies a color to fill borders eventually created by an _[inside](#inside)_ transformation. It supercedes _[background](#background)_ in that instance and it is notably possible to ensure both a solid background and translucent borders by using `border=transparent`. _border_ will have no effect on images that have no _[inside](#inside)_ applied to them.

If multiple _border_ transformations are specified, they are applied in order. If a _border_ uses an opaque color, any _border_ thereafter will be ignored.

Note that _[background](#background)_, _border_ and _[colorize](#colorize)_ are chainable, see [how chaining works with colors](/docs/reference/color-chaining) for more information.

### colorize

_Syntax_:

- <span class="api">colorize=<[color for black](/docs/reference/parameters#color)>[:<[color for white](/docs/reference/parameters#color)>]</span>
- <span class="api">colorize=&lt;color scheme&gt;</span>

Replaces colors in the image to create a gradient, replacing pure black with the first given color and pure white with the second given color.

| Examples              |                                                                |
| --------------------- | :------------------------------------------------------------: |
| _none_                | <DocSample src="colors.png"/>                                  |
| `colorize=black`      | <DocSample src="colors.png" transform="colorize=black"/>       |
| `colorize=black:cyan` | <DocSample src="colors.png" transform="colorize=black:cyan"/>  |
| `colorize=cyan:black` | <DocSample src="colors.png" transform="colorize=cyan:black"/>  |

There are also two available color schemes for your convenience:

- `monochrome` to create a black-and-white image
- `sepia` to create a sepia effect

| Examples              |                                                                |
| --------------------- | :------------------------------------------------------------: |
| `colorize=monochrome` | <DocSample src="colors.png" transform="colorize=monochrome"/>  |
| `colorize=sepia`      | <DocSample src="colors.png" transform="colorize=sepia"/>       |

Note that _[background](#background)_, _[border](#border)_ and _colorize_ are chainable, see [how chaining works with colors](/docs/reference/color-chaining) for more information.

### contain

_Syntax_: <span class="api">contain=<[size](/docs/reference/parameters#size)></span>

_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 a 300x188 close-up of a cat will result in the following 150x94 image:

<DocStaticSample src="cat-300.jpg" transform="contain=150x100" width="150" height="94"></DocStaticSample>

### contain-max

_Syntax_: <span class="api">contain-max=<[pixel size](/docs/reference/parameters#size)></span>

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_: <span class="api">contain-min=<[pixel size](/docs/reference/parameters#size)></span>

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

_Syntax_: <span class="api">cover=<[size](/docs/reference/parameters#size)|[ratio](/docs/reference/parameters#ratio)></span>

_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                         |
| ----------------------------------------------------------------------------------- | ------------------------------ |
| <DocStaticSample src="cat-300-cover-center-process.jpg" width="300" height="188" /> | <DocSample src="cat-300.jpg"/> |

_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                                                               |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| <DocStaticSample src="cat-300-cover-focus-process.jpg" width="300" height="188" /> | <DocSample src="cat-300.jpg" transform="focus=85x85/cover=100x100"/> |

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                                                           |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| <DocStaticSample src="cat-300-cover-ratio-process.jpg" width="300" height="188" /> | <DocSample src="cat-300.jpg" transform="focus=85x85/cover=1:1"/> |

### cover-max

_Syntax_: <span class="api">cover-max=<[pixel size](/docs/reference/parameters#size)></span>

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_: <span class="api">cover-min=<[pixel size](/docs/reference/parameters#size)></span>

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_: <span class="api">crop=<[crop size](/docs/reference/parameters#crop-size)>\[@<[coordinates](/docs/reference/parameters#coordinates)>\]</span>

_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.

| Examples             | Process                                                                             | Result             |
| -------------------- | ----------------------------------------------------------------------------------- | ------------------ |
| `crop=200x100`       | <DocStaticSample src="cat-300-crop-no-coord-process.jpg" width="300" height="188"/> | <DocStaticSample src="cat-300.jpg" transform="crop=200x100" width="200" height="100"/> |
| `crop=200x100@20x50` | <DocStaticSample src="cat-300-crop-coord-process.jpg" width="300" height="188"/>    | <DocStaticSample src="cat-300.jpg" transform="crop=200x100@20x50" width="200" height="100"/> |

### <span class="experimental">deuteranopia</span>

_Syntax_:

- <span class="api">deuteranopia=<[number](/docs/reference/parameters#number)></span>
- <span class="api">deut=<[number](/docs/reference/parameters#number)></span>
- <span class="api">deuteranopia</span>
- <span class="api">deut</span>

Corrects the colors of the image for color blind people suffering from deuteranopia.

The _[number](/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples           |                                                            |
| ------------------ | :--------------------------------------------------------: |
| _none_             | <DocSample src="colors.png"/>                              |
| `deuteranopia=0.5` | <DocSample src="colors.png" transform="deuteranopia=0.5"/> |
| `deuteranopia`     | <DocSample src="colors.png" transform="deuteranopia"/>     |

### download

_Syntax_:

- <span class="api">download</span>
- <span class="api">download=&lt;basename&gt;</span>
- <span class="api">download=&lt;basename&gt;.&lt;extension&gt;</span>

Forces media to be downloaded rather than displayed in the browser when the URL containing the transformation is used as a link `href` or entered in the address bar.

When no parameter is given, filename will have a _basename_ based on the type of media (`image` or `video`) and with an _extension_ corresponding to the output format of the media (`.mp4`, `.webp`, etc).

For instance:

- `image.webp`
- `video.mp4`

If only a _basename_ is given, then the _extension_ will still correspond to the output format of the media (`.jpeg`, `.webm`, etc).

| Examples         |              |
| ---------------- | :----------: |
| `download=birds` | `birds.webm` |
| `download=road`  | `road.jpeg`  |

If both a _basename_ and an _extension_ are given they will constitute the full filename. Only use this option when you know the actual output format of the media in order to use the correct file extension.

### duration

_Syntax_: <span class="api">duration=<[number](/docs/reference/parameters#number)></span>

If the source media is a video, _`duration`_ will extract the given duration from said source video.

Duration is a number of seconds that can be an integer as well as a real number (i.e., `duration=2`, `duration=11.2`, etc ).

By default, _`duration`_ is applied from the start of the source video. For instance, `duration=6` will effectively slice the video from the start up to second `6`. You can change this behavior by using the _[`from` transformation](#from)_.

You can find more information about _`duration`_ and its use-cases in the [video slicing](/docs/guides/video-optimization#video-slicing) chapter of our [video optimization best practices](/docs/guides/video-optimization).

### flip

_Syntax_: <span class="api">flip=<[axis](/docs/reference/parameters#axis)></span>

_flip_ will invert the image horizontally, vertically, or both, depending on the _axis_ provided.

| Expression | Axis                    |                                                      |
| ---------- | ----------------------- | :--------------------------------------------------: |
| `both`     | horizontal and vertical | <DocSample src="compass.png" transform="flip=both"/> |
| `x`        | horizontal              | <DocSample src="compass.png" transform="flip=x"/>    |
| `y`        | vertical                | <DocSample src="compass.png" transform="flip=y"/>    |

### focus

_Syntax_:

- <span class="api">focus=<[coordinates](/docs/reference/parameters#coordinates)></span><br>
- <span class="api">focus=<[anchor](/docs/reference/parameters#anchor)></span><br>
- <span class="api">focus=auto</span>

_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](#cover)_, _[crop](#crop)_ and _[zoom](#zoom)_).

If an _[anchor](/docs/reference/parameters#anchor)_ is provided, then the focus point will be the corresponding corner or the middle point of the corresponding border.

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.

### from

_Syntax_: <span class="api">from=<[number](/docs/reference/parameters#number)></span>

If the source media is a video, _`from`_ will slice it from the given mark.

Mark is a position in seconds that can be an integer as well as a real number (i.e., `from=1`, `from=5.75`, etc).

By default, the video will be sliced up to the end of the source video. For instance, `from=2` on a 10-second long source video will effectively slice the video from second `2` to second `10`. You can change this behavior by using the _[`duration` transformation](#duration)_ or the _[`to` transformation](#to)_.

You can find more information about _`from`_ and its use-cases in the [video slicing](/docs/guides/video-optimization#video-slicing) chapter of our [video optimization best practices](/docs/guides/video-optimization).

### inside

_Syntax_: <span class="api">inside=<[size](/docs/reference/parameters#size)|[ratio](/docs/reference/parameters#ratio)></span>

_inside_ behaves like the CSS background-size "contain". It will resize the image so that it completely fits inside the target area. Contrary to the _[contain](#contain)_ transformation, translucent borders will be added if the resulting aspect ratio is not the same as the aspect ratio of the input so that the resulting image has the exact, physical, size specified.

If the _[background](#background)_ transformation is used, then the background color will be used to fill the borders. If you wish to have a different color than the background color for the added borders, you can use the _[border](#border)_ transformation.

| Examples                                      |                                                                                   |
| --------------------------------------------- | :-------------------------------------------------------------------------------: |
| `inside=150x150`                              | <DocStaticSample src="cat-300.jpg" transform="inside=150x150" width="150" height="150"/>                           |
| `background=black/inside=150x150`             | <DocStaticSample src="cat-300.jpg" transform="background=black/inside=150x150" width="150" height="150"/> |
| `background=black/border=cyan/inside=150x150` | <DocStaticSample src="cat-300.jpg" transform="background=black/border=cyan/inside=150x150" width="150" height="150"/>  |

### max

_Syntax_: <span class="api">max=<[pixel size](/docs/reference/parameters#size)></span>

Alias of <span class="api">[contain-max](#contain-max)</span>.

### min

_Syntax_: <span class="api">min=<[pixel size](/docs/reference/parameters#size)></span>

Alias of <span class="api">[contain-min](#contain-min)</span>.

### noop

_Syntax_: <span class="api">noop</span>

Passes the media as is. TwicPics will not re-encode or apply any transformation be they provided through the API or through the path default manipulation.

<doc-alert type="warning">
By default, TwicPics will ignore `noop` since it makes your original media available to the outside world, and that may be an unintended side-effect. As a consequence, you need to explicitly allow `noop` in your path configuration.
</doc-alert>

### output

_Syntax_:

- <span class="api">output=&lt;format&gt;</span>
- <span class="api">output=&lt;preview type&gt;</span>
- <span class="api">output=auto</span>

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 issuing the request, but you can use _output_ to override this behavior.

Available _image formats_ are:

- `avif` for [AV1 Image File Format](<https://en.wikipedia.org/wiki/AV1#AV1_Image_File_Format_(AVIF)>)
- `heif` for [High Efficiency Image File Format](https://wikipedia.org/wiki/High_Efficiency_Image_File_Format)
- `image` (`jpeg` or `webp` depending on the browser, useful to extract the first frame of a video)
- `jpeg` for [Joint Photographic Experts Group](https://wikipedia.org/wiki/JPEG)
- `png` for [Portable Network Graphics](https://wikipedia.org/wiki/Portable_Network_Graphics)
- `webp` for [WebP](https://wikipedia.org/wiki/WebP)

Available _video formats_ are:

- `h264` for an [H.264](https://en.wikipedia.org/wiki/Advanced_Video_Coding) stream in an [MPEG-4 Part 14](https://en.wikipedia.org/wiki/MPEG-4_Part_14) container
- `h265` for an [H.265](https://en.wikipedia.org/wiki/High_Efficiency_Video_Coding) stream in an [MPEG-4 Part 14](https://en.wikipedia.org/wiki/MPEG-4_Part_14) container
- `vp9` for a [VP9](https://en.wikipedia.org/wiki/VP9) stream in a [WebM](https://en.wikipedia.org/wiki/WebM) container

Available _preview types_ are:

- `blank`: a blank, totally translucent version of the resulting image
- `blurhash`: a small text-based representation of the image (see [BlurHash](https://blurha.sh))
- `maincolor`: a solid color image containing the most important color in the resulting image
- `meancolor`: a solid color image containing the mean color of the resulting image
- `preview`: a blurry preview of the resulting image

For _videos_ and by default, _previews_ are based on the first frame of the resulting video. You can use the [`from`](#from) transformation to target a specific frame.

| Preview Formats    |                                                                                          |
| ------------------ | :--------------------------------------------------------------------------------------: |
| `output=blank`     | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=blank"/>     |
| `output=maincolor` | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=maincolor"/> |
| `output=meancolor` | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=meancolor"/> |
| `output=preview`   | <DocSample src="storm.jpeg" placeholder="none" transform="focus=auto/output=preview"/>   |
| _original image_   | <DocSample src="storm.jpeg" transform="focus=auto"/>                                     |

Please note that `blank`, `maincolor`, `meancolor` and `preview` are distributed with a `X-Robots-Tag: noindex` header so that they are not indexed by search engines.

In addition, you can use `output=auto` to ensure TwicPics' "smart-guess" of the output _format_ is used even if an output _format_ has already been specified by the [default manipulation](/docs/essentials/path-configuration#default-manipulation) of your path.

### <span class="experimental">protanopia</span>

_Syntax_:

- <span class="api">protanopia=<[number](/docs/reference/parameters#number)></span>
- <span class="api">prot=<[number](/docs/reference/parameters#number)></span>
- <span class="api">protanopia</span>
- <span class="api">prot</span>

Corrects the colors of the image for color-blind people suffering from protanopia.

The _[number](/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples         |                                                          |
| ---------------- | :------------------------------------------------------: |
| _none_           | <DocSample src="colors.png"/>                            |
| `protanopia=0.5` | <DocSample src="colors.png" transform="protanopia=0.5"/> |
| `protanopia`     | <DocSample src="colors.png" transform="protanopia"/>     |

### quality

_Syntax_: <span class="api">quality=<[number](/docs/reference/parameters#number)></span>

Specifies the output quality as a number between 1 and 100.

Note that `quality` will be ignored when:

- `output` is `png` and <span class="api">[truecolor](#truecolor)</span> is on
- `output` is a _preview format_

### quality-max

_Syntax_: <span class="api">quality-max=<[number](/docs/reference/parameters#number)></span>

A conditional version of _quality_ that will be applied only when given quality is below current quality.

| Examples                     | Resulting quality |
| ---------------------------- | ----------------- |
| `quality=100/quality-max=50` | `50`              |
| `quality=20/quality-max=50`  | `20`              |
| `quality-max=50/quality=100` | `100`             |

### quality-min

_Syntax_: <span class="api">quality-min=<[number](/docs/reference/parameters#number)></span>

A conditional version of _quality_ that will be applied only when given quality is above current quality.

| Examples                     | Resulting quality |
| ---------------------------- | ----------------- |
| `quality=100/quality-min=50` | `100`             |
| `quality=20/quality-min=50`  | `50`              |
| `quality-min=50/quality=20`  | `20`              |

### refit

_Syntax_: <span class="api">refit=<[size](/docs/reference/parameters#size)|[ratio](/docs/reference/parameters#ratio)>[@<[anchor](/docs/reference/parameters#anchor)>][([padding](/docs/reference/parameters#padding))]</span>

Alias of <span class="api">[refit-cover](#refit-cover)</span>.

### refit-cover

_Syntax_: <span class="api">refit-cover=<[size](/docs/reference/parameters#size)|[ratio](/docs/reference/parameters#ratio)>[@<[anchor](/docs/reference/parameters#anchor)>][([padding](/docs/reference/parameters#padding))]</span>

_refit-cover_ will resize the image to the specified _size_ while maximizing the area occupied by the main object (or objects) found within said image.

| Example           |                                                                                               |
| ----------------- | :-------------------------------------------------------------------------------------------: |
| original image    | <DocStaticSample src="woman-in-canyon.jpeg" transform="resize=376" width="188" height="125"/> |
| `refit-cover=1:1` | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1"/>                           |

By default, the subject will be placed at the center of the resulting image but it is possible to align the subject with a given border by specifying an [anchor](/docs/reference/parameters#anchor).

| Examples                |                                                                           |
| ----------------------- | :-----------------------------------------------------------------------: |
| `refit-cover=1:1@left`  | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1@left"/>  |
| `refit-cover=1:1@right` | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1@right"/> |

Also by default, the subject will touch the borders of the resulting image. This can be avoided by adding [padding](/docs/reference/parameters#padding).

It is generally easier to use padding values in percentage so that the added breathing room is independent of previous scalings.

| Examples                    |                                                                               |
| --------------------------- | :---------------------------------------------------------------------------: |
| `refit-cover=1:1`           | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1"/>           |
| `refit-cover=1:1(15p)`      | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1(15p)"/>      |
| `refit-cover=1:1(30p,0,5p)` | <DocSample src="woman-in-canyon.jpeg" transform="refit-cover=1:1(30p,0,5p)"/> |

<doc-alert type="warning">
Note that <i>refit-cover</i> will never create pixels that were not present in the original image.
<p>If there is not enough pixels in the original image to satisfy a given padding, as many pixels as available will be used and it may create a padding region that is smaller than expected.</p>
<p>If there is not enough pixels on the opposing side of the anchor point then the same best-effort approach will be used and the subject may be farther from the anchor point than expected.</p>
If placement is paramount to you, please use <em><i>refit-inside</i></em> instead.
</doc-alert>

### refit-inside

_Syntax_: <span class="api">refit-inside=<[size](/docs/reference/parameters#size)|[ratio](/docs/reference/parameters#ratio)>[@<[anchor](/docs/reference/parameters#anchor)>][([padding](/docs/reference/parameters#padding))]</span>

_refit-inside_ will resize the image to the specified _size_ while ensuring the main object (or objects) are perfectly centered, even if it means borders have to be created in the process.

| Example            |                                                                                       |
| ------------------ | :-----------------------------------------------------------------------------------: |
| original image     | <DocStaticSample src="football.jpg" transform="resize=376" width="208" height="139"/> |
| `refit-inside=1:1` | <DocSample src="football.jpg" transform="refit-inside=1:1/border=red"/>               |

By default, the subject will be placed at the center of the resulting image, but it is possible to align the subject with a given border by specifying an [anchor](/docs/reference/parameters#anchor).

| Examples                 |                                                                               |
| ------------------------ | :---------------------------------------------------------------------------: |
| `refit-inside=1:1@left`  | <DocSample src="football.jpg" transform="refit-inside=1:1@left/border=red"/>  |
| `refit-inside=1:1@right` | <DocSample src="football.jpg" transform="refit-inside=1:1@right/border=red"/> |

Also by default, the subject will touch the borders of the resulting image. This can be avoided by adding [padding](/docs/reference/parameters#padding).

It is generally easier to use padding values in percentage so that the added breathing room is independent of previous scalings.

| Examples                     |                                                                                   |
| ---------------------------- | :-------------------------------------------------------------------------------: |
| `refit-inside=1:1`           | <DocSample src="football.jpg" transform="refit-inside=1:1/border=red"/>           |
| `refit-inside=1:1(15p)`      | <DocSample src="football.jpg" transform="refit-inside=1:1(15p)/border=red"/>      |
| `refit-inside=1:1(30p,0,5p)` | <DocSample src="football.jpg" transform="refit-inside=1:1(30p,0,5p)/border=red"/> |

### resize

_Syntax_: <span class="api">resize=<[size](/docs/reference/parameters#size)|[ratio](/docs/reference/parameters#ratio)></span>

_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.

| Examples         |                                                                                          |
| ---------------- | :--------------------------------------------------------------------------------------: |
| `resize=150`     | <DocStaticSample src="cat-300.jpg" transform="resize=150" width="150" height="94"/>      |
| `resize=-x150`   | <DocStaticSample src="cat-300.jpg" transform="resize=-x150" width="239" height="150"/>   |
| `resize=150x150` | <DocStaticSample src="cat-300.jpg" transform="resize=150x150" width="150" height="150"/> |

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, `resize=4:3` will result in the following 274x206 image:

<DocStaticSample src="cat-300.jpg" transform="resize=4:3" width="274" height="206"></DocStaticSample>

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_: <span class="api">resize-max=<[pixel size](/docs/reference/parameters#size)></span>

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_: <span class="api">resize-min=<[pixel size](/docs/reference/parameters#size)></span>

A conditional version of _resize_ that will be applied only when one of the given _lengths_ is larger than the corresponding input image dimension.

### to

_Syntax_: <span class="api">to=<[number](/docs/reference/parameters#number)></span>

If the source media is a video, _`to`_ will slice it up to the given mark.

Mark is a position in seconds that can be an integer as well as a real number (i.e., `to=17`, `to=9.61`, etc ).

By default, the video will be sliced from the very start of the source video. For instance, `to=8` will effectively slice the video from the start up to second `8`. You can change this behaviour by using the _[`from` transformation](#from)_.

You can find more information about _`to`_ and its use-cases in the [video slicing](/docs/guides/video-optimization#video-slicing) chapter of our [video optimization best practices](/docs/guides/video-optimization).

### <span class="experimental">tritanopia</span>

_Syntax_:

- <span class="api">tritanopia=<[number](/docs/reference/parameters#number)></span>
- <span class="api">trit=<[number](/docs/reference/parameters#number)></span>
- <span class="api">tritanopia</span>
- <span class="api">trit</span>

Corrects the colors of the image for color-blind people suffering from protanopia.

The _[number](/docs/reference/parameters#number)_ provided must be between `0` and `1` and represents the degree of color blindness to correct for. If no _[number](/docs/reference/parameters#number)_ is provided then `1` (full-color blindness) is assumed.

| Examples         |                                                          |
| ---------------- | :------------------------------------------------------: |
| _none_           | <DocSample src="colors.png"/>                            |
| `tritanopia=0.5` | <DocSample src="colors.png" transform="tritanopia=0.5"/> |
| `tritanopia`     | <DocSample src="colors.png" transform="tritanopia"/>     |

### truecolor

_Syntax_:

- <span class="api">truecolor=<[boolean](/docs/reference/parameters#boolean)></span>
- <span class="api">truecolor</span>

_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 that do not support WebP.

### turn

_Syntax_: <span class="api">turn=<[angle](/docs/reference/parameters#angle)></span>

_turn_ will change the orientation of the image. It accepts an [angle](/docs/reference/parameters#angle). Angles will be rounded to the closest multiple of 90°.

| Expression   |   Angle   |                                                       |
| ------------ | :-------: | :---------------------------------------------------: |
| `turn=flip`  |   180°    | <DocSample src="compass.png" transform="turn=flip"/>  |
| `turn=left`  |   -90°    | <DocSample src="compass.png" transform="turn=left"/>  |
| `turn=right` |   90°     | <DocSample src="compass.png" transform="turn=right"/> |

### zoom

_Syntax_: <span class="api">zoom=<[number](/docs/reference/parameters#number)></span>

Zooms into the image by a factor equal or superior to 1 towards the _focus point_ while preserving the image size.

| Examples   |                                                                            |
| ---------- | :------------------------------------------------------------------------: |
| `zoom=1`   | <DocSample src="concert.jpeg" transform="focus=57px15p"/>                                  |
| `zoom=1.5` | <DocSample src="concert.jpeg" transform="focus=57px15p/zoom=1.5"/> |
| `zoom=2`   | <DocSample src="concert.jpeg" transform="focus=57px15p/zoom=2"/>   |
| `zoom=3`   | <DocSample src="concert.jpeg" transform="focus=57px15p/zoom=3"/>   |