ImageKit allows use of arithmetic expressions in certain dimension and position-related parameters, making media transformations more flexible and dynamic. They allow for more flexible and complex transformations without the need to hard code specific values in scenarios where the exact dimensions or positions may not be known beforehand or when they need to be adjusted based on other parameters.
Example use cases:
- Dynamic resizing: You can use arithmetic expressions to set the dimensions of an image relative to its original dimensions or other parameters. For instance, making the width of an image half of its original size using
w-iw_div_2. - Positioning overlays: Arithmetic expressions can be used to calculate the position of overlays or watermarks based on the dimensions of the original image. For instance, placing a watermark at a position that is 10% from the top and right edges of the image using the transformation
lx-bw_mul_0.9,ly-bh_mul_0.1. - Adjusting border in image: Arithmetic expressions can be used to calculate these values based on other parameters like the image's dimensions or aspect ratio using
b-ch_mod_5_yellow.
You can create arithmetic expressions by using arithmetic operators with expression variables or positive numbers. A simple expression follows the {value}_{operator}_{value} syntax, where the value can be expression variables, positive integers, or positive decimal numbers. You can also directly assign expression variables like ih, or bw to supported parameters. For example, you can use expressions like bh_div_2 or ch_mul_0.25. Furthermore, you can combine multiple operators and values to create complex expressions, such as ih_mul_0.8_add_iw_mul_0.4.
Supported expression variables
| Property | Description |
|---|---|
ih | Initial height of the asset. Inside a layer transformation, it indicates the initial height of the asset being overlaid. |
iw | Initial width of the asset. Inside a layer transformation, it indicates the initial width of the asset being overlaid. |
iar | Initial aspect ratio of the asset. Inside a layer transformation, it indicates the initial aspect ratio of the asset being overlaid. |
idu | It represents the original duration of the asset. Inside a layer transformation, it indicates the original duration of the asset being overlaid. It can only be used with durational parameters so, eo, du, lso, ldu, and leo. |
ch | It represents the height resulting from the last applied transformation in a chain of transformations. Similarly, inside a layer transformation, it indicates the current height of the asset being overlaid. |
cw | It represents the width resulting from the last applied transformation in a chain of transformations. Similarly, inside a layer transformation, it indicates the current width of the asset being overlaid. |
car | It represents the aspect ratio resulting from the last applied transformation in a chain of transformations. Similarly, inside a layer transformation, it indicates the current aspect ratio of the asset being overlaid. |
bh | It represents the current height of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation. |
bw | It represents the current width of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation. |
bar | It represents the current aspect ratio of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation. |
bdu | It represents the current duration of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation and with durational parameters so, eo, du, lso, ldu, and leo. |
Supported operators
| Operator name | Operation |
|---|---|
| add | add |
| sub | sub |
| mul | mul |
| div | div |
| mod | mod (remainder) |
| pow | pow |
Parameter supporting arithmetic expressions
| Parameter | Examples | Remarks |
|---|---|---|
h | h-ih_add_10 h-ch_mul_0.8_add_bh_mul_0.6 | |
w | w-ih_add_10 w-ch_mul_0.8_add_bh_mul_0.6 | |
ar | ar-car_mul_0.5 ar-bar | The calculated value of the expression will represent the |
x, y | x-iw_sub_cw y-ih_sub_ch | |
xc, yc | xc-cw_mul_0.25 yc-ch_mul_0.25 | |
b | b-ih_mul_0.05_red b-cw_mod_5_AAAA54 | The border follows the |
lx, ly | lx-bw_div_2 ly-bh_div_2 lx-cw_div_2_add_iw_div_2 ly-ch_div_2_add_cw_div_2 | These are layer positional parameters that can be placed in any order within a chain of transformations inside a layer transformation but are always executed last. Hence |
so, du, eo | so-bdu_sub_idu du-bdu_div_2 eo-idu_div_2 | Valid expression variables are only |
lso, ldu, leo | lso-bdu_mul_0.2 ldu-bdu_mul_0.5 leo-idu_sub_2 | Valid expression variables are only |
| pa | pa-bh_mul_0.05 pa-bw_mod_5 | The calculated expression value will be applied as uniform padding along all four edges of the text. |
fs | fs-bh_mul_0.1 fs-bw_div_50 | |
sp (inside e-gradient) | sp-bh_mul_0.75 sp-bh_div_2 |
Calculation Sequence for multiple operators
- Multiplication and Division: Multiplication and division are evaluated first from left to right.
- Addition and Subtraction: Addition and subtraction are evaluated next from left to right.
- Modulus: Modulus is evaluated then from left to right.
- Power: Power is evaluated last from left to right.
If you're using expressions inside a layer, then the layer should be a separate chain transformation.
Only the
bw,bh, andbarexpression variables are allowed inside text layers, solid image layers, and gradient block layers.
Examples
Resizing
To resize the height to half of the original, the width to one-fourth of the original, and then add a yellow color border that's 5% of the current width, you can use the following URL.
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-iw_div_4,h-ih_div_2:b-cw_mul_0.05_yellow
To crop the image with half height and width while extracting from a position that is 20% from top and left edges, you can use the following URL.
Image overlay
You can also resize and position the image layer relative to the base asset. For example, to first resize the image being overlaid to half of the base image dimensions and then place it one-eight from the top and left edges, you can use the following URL.
Expressions can also conveniently be used to resize and position nested layers in relation to their outer layers. In this example, we overlay the resized women-dress.jpeg with a red border, positioning it 10% from the top and left edges of medium_cafe_B1iTdD0C.jpg, and then add the imagekit.io logo, positioning it at 10% from the top and left edges of women-dress.jpeg.
Text overlay
To control the text layer's width and font size with respect to the base layer, you can use the following URL.
To add padding to a text layer with a background color, you can use the following URL.
Video overlay
Expressions can also be used inside video layers for resizing and positioning in parameters that allow arithmetic expressions.
To overlay the video at half its original width and height, we can use the following URL.
Trimming the video
We can also use expressions with trim parameters so, du, eo and positional parameters lso, ldu, leo to trim the video smartly.
Trim parameters so, du and eo can only be used once in a chain transformation if any of them is using expression variable. For ex. tr:so-idu_mul_0.2,du-idu_mul_0.4 is a valid transformation, but tr:so-idu_mul_0.2,du-idu_mul_0.4:so-idu_mul_0.2 is invalid and result in an error.
To trim the video 10 sec from the the end we can use the below URL.
URL - https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-idu_sub_10
To overlay the video at half the duration of the base video, we can use the below URL.