Manipulations
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 ratioresize=640x480
will resize the image to exactly 640 pixels in width per 480 pixels in height, potentially altering its aspect ratio
Types of parameters
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.
boolean
A boolean represents... a boolean value (true
or false
).
The following literals are accepted:
- for
true
:true
,on
,yes
- for
false
:false
,off
,no
color
A color represents... a color! It can be specified as:
- a color name like
red
orgreen
(see the comprehensive list further down this section) - a three character hexadecimal value like
76E
for RGB colors with no alpha, - a four character hexadecimal value like
76E8
for RGB colors with alpha, - a six character hexadecimal value like
A68040
for RGB colors with no alpha, - a eight character hexadecimal value like
A6804080
for RGB colors with alpha, - a CSS-like RGB expression:
rgb(<red>,<green>,<blue>)
, - a CSS-like RGBA expression:
rgba(<red>,<green>,<blue>,<alpha>)
, - a CSS-like HSL expression:
hsl(<hue>,<saturation>,<lightness>)
, - a CSS like HSLA expression:
hsla(<hue>,<saturation>,<lightness>,<alpha>)
.
TwicPics also adds transparent
so that you can easily create an invisible placeholder using placeholder:transparent
.
Finally, you also have the possibility to add an alpha value to color names, three character hexadecimal colors, and six character hexadecimal color. Simply append the decimal part of the alpha component to the color expression.
Example | Result |
---|---|
violet.25 | |
008.75 | |
808080.3 |
Finally, here is the list of all supported color names:
Name | Preview |
---|---|
alice-blue | |
antique-white | |
aqua | |
aquamarine | |
azure | |
beige | |
bisque | |
black | |
blanched-almond | |
blue | |
blue-violet | |
brown | |
burlywood | |
cadet-blue | |
chartreuse | |
chocolate | |
coral | |
cornflower-blue | |
cornsilk | |
crimson | |
cyan | |
dark-blue | |
dark-cyan | |
dark-goldenrod | |
dark-gray | |
dark-green | |
dark-khaki | |
dark-magenta | |
dark-olive-green | |
dark-orange | |
dark-orchid | |
dark-red | |
dark-salmon | |
dark-sea-green | |
dark-slate-blue | |
dark-slate-gray | |
dark-turquoise | |
dark-violet | |
deep-pink | |
deep-sky-blue | |
dim-gray | |
dodger-blue | |
firebrick | |
floral-white | |
forest-green | |
fuchsia | |
gainsboro | |
ghost-white | |
gold | |
goldenrod | |
gray | |
green | |
green-yellow | |
honeydew | |
hot-pink | |
indian-red | |
indigo | |
ivory | |
khaki | |
lavender | |
lavender-blush | |
lawn-green | |
lemon-chiffon | |
light-blue | |
light-coral | |
light-cyan | |
light-goldenrod-yellow | |
light-gray | |
light-green | |
light-pink | |
light-salmon | |
light-sea-green | |
light-sky-blue | |
light-slate-gray | |
light-steel-blue | |
light-yellow | |
lime | |
lime-green | |
linen | |
magenta | |
maroon | |
medium-aquamarine | |
medium-blue | |
medium-orchid | |
medium-purple | |
medium-sea-green | |
medium-slate-blue | |
medium-spring-green | |
medium-turquoise | |
medium-violet-red | |
midnight-blue | |
mint-cream | |
misty-rose | |
moccasin | |
navajo-white | |
navy | |
old-lace | |
olive | |
olive-drab | |
orange | |
orange-red | |
orchid | |
pale-goldenrod | |
pale-green | |
pale-turquoise | |
pale-violet-red | |
papaya-whip | |
peach-puff | |
peru | |
pink | |
plum | |
powder-blue | |
purple | |
rebecca-purple | |
red | |
rosy-brown | |
royal-blue | |
saddle-brown | |
salmon | |
sandy-brown | |
sea-green | |
seashell | |
sienna | |
silver | |
sky-blue | |
slate-blue | |
slate-gray | |
snow | |
spring-green | |
steel-blue | |
tan | |
teal | |
thistle | |
tomato | |
turquoise | |
violet | |
wheat | |
white | |
white-smoke | |
yellow | |
yellow-green |
coordinates
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 pixel639x479
points to the bottom-right corner pixel.
100x50p
actually translate to
100x240
.
crop size
A crop size is a size where omitted dimensions are assumed to be the same as the input image.
For instance:
320
and320x-
are equivalent to320x1s
-x240
is equivalent to1sx240
length
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%"
number
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.
ratio
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.
size
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-
.
10px150
is a perfectly valid size.
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 focus 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-wideresize=50p/focus=20x10
will put the focus point at coordinates40x20
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.