A manipulation is a list of transformations that are 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.

Transformations all have 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

The TwicPics API strives to be as consistent as possible and, as such, transformations will use the same format for parameters that represent the same underlying concept.

TwicPics *numbers* can be JSON-encoded number literals or expressions that, when computed, result in an actual number. Expressions are embedded in parenthesis. Operators `+`

, `-`

, `*`

and `/`

are supported for additions, subtractions, multiplications and divisions respectively. Classic algebraic precedence is respected and parenthesis can be used to circumvent it.

For instance, `50`

, `7.2`

, `(1/3)`

, `(5*(7+2)/3)`

are all valid *numbers*.

TwicPics *lengths* are equivalent to CSS length values. They consist of a *number* eventually followed by a *unit* specifier:

- when no
*unit*is specified, the*length*is in*pixels*, for instance`50`

is a*pixel length*that can be read as "50 pixels" - with the
*unit*specifier "s", the*length*is a*scale*, for instance`(1/3)s`

is a*scale length*that can be read as "one third" - with the
*unit*specifier "p", the*length*is a*percentage*, for instance`4.5p`

is a*percentage length*representing "4.5%"

*Coordinates* represent a point in an image, specified as a couple of **positive** *lengths* separated by the character `x`

:

- the first
*length*is the coordinate along the x-axis (following the width of the image) - the second
*length*is the coordinate along the y-axis (following the height of the image)

TwicPics uses the same coordinate system as CSS: zero-based, left-to-right and top-to-bottom.

If we take the example of an image that is 640 pixel-wide and 480 pixel-high:

`0x0`

points to the top-left corner pixel`639x479`

points to the bottom-right corner pixel.

It is perfectly fine to mix *lengths* of different *units* in the same *coordinates*. For instance, in the context of yet another 640 per 480 sample image, *coordinates* `100x50p`

actually translate to `100x240`

.

A *size* represents a 2D area, specified as a couple of **strictly positive** *lengths* separated by the character `x`

:

- the first
*length*is the width of the area - the second
*length*is the height of the area

For instance `640x480`

is 640 pixel-wide per 480 pixel-high.

It is possible to omit one of the dimensions using the character `-`

. In that case, TwicPics will automatically compute the missing dimension so that the size respects the aspect ratio of the source image. For instance, if the source image is 640 pixel-wide per 480 pixel-high, then *sizes* `320x-`

and `-x240`

are both equivalent to `320x240`

.

As a shortcut, it is possible to omit the height by specifying just a width. For instance, the *size* `320`

is equivalent to `320x-`

.

As for *coordinates*, it is totally fine to mix *lengths* of different *units* in the same *size*. For instance, `10px150`

is a perfectly valid size.

A *crop size* is a *size* where omitted dimensions are assumed to be the same as the input image.

For instance:

`320`

and`320x-`

are equivalent to`320x1s`

`-x240`

is equivalent to`1sx240`

A *ratio* represents the proportional relationship between a width and a height. It is specified as a couple of **strictly positive** *numbers* separated by the character `:`

:

- the first
*number*is the number of length units contained in the width - the second
*number*is the number of length units contained in the height

For instance, the *ratio* `9:3`

indicates that the width is 9-units long while the height is 3-units long. In terms of proportions, the width is (9/3=)3 times longer than the height.

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 `focus`

transformation.

The biggest extractable area of the image that has the *focus point* as its center is called the *focus window*. By default, since the *focus point* is right in the middle of the image, the *focus window* is actually the image itself.

Here is, delimited in red, the *focus window* of a 300 pixel-wide per 188 pixel-high cat face with the *focus point* set at `85x85`

:

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