Skip to content

Commit 2298a72

Browse files
committed
add transformation types for different type of overlays
1 parent 9769f40 commit 2298a72

File tree

1 file changed

+192
-43
lines changed

1 file changed

+192
-43
lines changed

src/interfaces/Transformation.ts

Lines changed: 192 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,15 @@ export interface Transformation {
1313
* Specifies the width of the output. If a value between 0 and 1 is provided, it is treated as a percentage
1414
* (e.g., `0.4` represents 40% of the original width). You can also supply arithmetic expressions (e.g., `iw_div_2`).
1515
*
16-
* {@link https://imagekit.io/docs/image-resize-and-crop#width---w|Image Resize and Crop - Width}
16+
* Width transformation - {@link https://imagekit.io/docs/image-resize-and-crop#width---w|Images} | {@link https://imagekit.io/docs/video-resize-and-crop#width---w|Videos}
1717
*/
1818
width?: number | string;
1919

2020
/**
2121
* Specifies the height of the output. If a value between 0 and 1 is provided, it is treated as a percentage
2222
* (e.g., `0.5` represents 50% of the original height). You can also supply arithmetic expressions (e.g., `ih_mul_0.5`).
2323
*
24-
* {@link https://imagekit.io/docs/image-resize-and-crop#height---h|Image Resize and Crop - Height}
24+
* Height transformation - {@link https://imagekit.io/docs/image-resize-and-crop#height---h|Images} | {@link https://imagekit.io/docs/video-resize-and-crop#height---h|Videos}
2525
*/
2626
height?: number | string;
2727

@@ -43,7 +43,7 @@ export interface Transformation {
4343
*
4444
* {@link https://imagekit.io/docs/effects-and-enhancements#blurred-background|Effects and Enhancements - Blurred Background}
4545
*
46-
* - Expand the image boundaries using generative fill: `genfill`. Optionally, control the background scene by passing a text prompt:
46+
* - Expand the image boundaries using generative fill: `genfill`. Not supported inside overlay. Optionally, control the background scene by passing a text prompt:
4747
* `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`.
4848
*
4949
* {@link https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill|AI Transformations - Generative Fill Background}
@@ -222,22 +222,22 @@ export interface Transformation {
222222
grayscale?: true;
223223

224224
/**
225-
* Upscales images beyond their original dimensions using AI.
225+
* Upscales images beyond their original dimensions using AI. Not supported inside overlay.
226226
*
227227
* {@link https://imagekit.io/docs/ai-transformations#upscale-e-upscale|AI Transformations - Upscale}
228228
*/
229229
aiUpscale?: true
230230

231231
/**
232-
* Performs AI-based retouching to improve faces or product shots.
232+
* Performs AI-based retouching to improve faces or product shots. Not supported inside overlay.
233233
*
234234
* {@link https://imagekit.io/docs/ai-transformations#retouch-e-retouch|AI Transformations - Retouch}
235235
*/
236236
aiRetouch?: true
237237

238238
/**
239239
* Generates a variation of an image using AI. This produces a new image with slight variations from the original,
240-
* such as changes in color, texture, and other visual elements, while preserving the structure and essence of the original image.
240+
* such as changes in color, texture, and other visual elements, while preserving the structure and essence of the original image. Not supported inside overlay.
241241
*
242242
* {@link https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar|AI Transformations - Generate Variations}
243243
*/
@@ -246,7 +246,8 @@ export interface Transformation {
246246
/**
247247
* Adds an AI-based drop shadow around a foreground object on a transparent or removed background.
248248
* Optionally, control the direction, elevation, and saturation of the light source (e.g., `az-45` to change light direction).
249-
* Pass true for the default drop shadow, or provide a string for a custom drop shadow.
249+
* Pass `true` for the default drop shadow, or provide a string for a custom drop shadow.
250+
* Supported inside overlay.
250251
*
251252
* {@link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow|AI Transformations - Drop Shadow}
252253
*/
@@ -255,13 +256,15 @@ export interface Transformation {
255256
/**
256257
* Uses AI to change the background. Provide a text prompt or a base64-encoded prompt,
257258
* e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`.
259+
* Not supported inside overlay.
258260
*
259261
* {@link https://imagekit.io/docs/ai-transformations#change-background-e-changebg|AI Transformations - Change Background}
260262
*/
261263
aiChangeBackground?: string;
262264

263265
/**
264266
* Applies ImageKit’s in-house background removal.
267+
* Supported inside overlay.
265268
*
266269
* {@link https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove|AI Transformations - Background Removal}
267270
*/
@@ -270,6 +273,7 @@ export interface Transformation {
270273
/**
271274
* Uses third-party background removal.
272275
* Note: It is recommended to use aiRemoveBackground, ImageKit’s in-house solution, which is more cost-effective.
276+
* Supported inside overlay.
273277
*
274278
* {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg|AI Transformations - External Background Removal}
275279
*/
@@ -285,30 +289,30 @@ export interface Transformation {
285289
/**
286290
* Adds a shadow beneath solid objects in an image with a transparent background.
287291
* For AI-based drop shadows, refer to aiDropShadow.
288-
* Pass true for a default shadow, or provide a string for a custom shadow.
292+
* Pass `true` for a default shadow, or provide a string for a custom shadow.
289293
*
290294
* {@link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow|Effects and Enhancements - Shadow}
291295
*/
292296
shadow?: true | string
293297

294298
/**
295299
* Sharpens the input image, highlighting edges and finer details.
296-
* Pass true for default sharpening, or provide a numeric value for custom sharpening.
300+
* Pass `true` for default sharpening, or provide a numeric value for custom sharpening.
297301
*
298302
* {@link https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen|Effects and Enhancements - Sharpen}
299303
*/
300304
sharpen?: true | number
301305

302306
/**
303307
* Applies Unsharp Masking (USM), an image sharpening technique.
304-
* Pass true for a default unsharp mask, or provide a string for a custom unsharp mask.
308+
* Pass `true` for a default unsharp mask, or provide a string for a custom unsharp mask.
305309
*
306310
* {@link https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm|Effects and Enhancements - Unsharp Mask}
307311
*/
308312
unsharpMask?: true | string;
309313

310314
/**
311-
* Creates a linear gradient with two colors. Pass true for a default gradient, or provide a string for a custom gradient.
315+
* Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient.
312316
*
313317
* {@link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient|Effects and Enhancements - Gradient}
314318
*/
@@ -428,6 +432,31 @@ export interface Transformation {
428432
overlay?: Overlay;
429433
}
430434

435+
export type Overlay =
436+
| TextOverlay
437+
| ImageOverlay
438+
| VideoOverlay
439+
| SubtitleOverlay
440+
| SolidColorOverlay
441+
442+
export interface BaseOverlay {
443+
/**
444+
* Specifies the overlay's position relative to the parent asset.
445+
* Accepts a JSON object with `x` and `y` (or `focus`) properties.
446+
*
447+
* {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer}
448+
*/
449+
position?: OverlayPosition;
450+
451+
/**
452+
* Specifies timing information for the overlay (only applicable if the base asset is a video).
453+
* Accepts a JSON object with `start` (`lso`), `end` (`leo`), and `duration` (`ldu`) properties.
454+
*
455+
* {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer}
456+
*/
457+
timing?: OverlayTiming;
458+
}
459+
431460
export interface OverlayPosition {
432461
/**
433462
* Specifies the x-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned.
@@ -485,32 +514,6 @@ export interface OverlayTiming {
485514
end?: number | string;
486515
}
487516

488-
489-
interface BaseOverlay {
490-
/**
491-
* Specifies the overlay's position relative to the parent asset.
492-
* Accepts a JSON object with `x` and `y` (or `focus`) properties.
493-
*
494-
* {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer}
495-
*/
496-
position?: OverlayPosition;
497-
498-
/**
499-
* Specifies timing information for the overlay (only applicable if the base asset is a video).
500-
* Accepts a JSON object with `start` (`lso`), `end` (`leo`), and `duration` (`ldu`) properties.
501-
*
502-
* {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer}
503-
*/
504-
timing?: OverlayTiming;
505-
506-
/**
507-
* An array of transformations to be applied to the overlay.
508-
* The supported transformations depend on the type of the base and overlay asset.
509-
*/
510-
transformations?: Transformation[];
511-
}
512-
513-
514517
export interface TextOverlay extends BaseOverlay {
515518
type: "text";
516519

@@ -519,6 +522,11 @@ export interface TextOverlay extends BaseOverlay {
519522
* The SDK automatically handles special characters and URL encoding.
520523
*/
521524
text: string;
525+
526+
/**
527+
* Control styling of the text overlay.
528+
*/
529+
transformations?: TextOverlayTransformation[];
522530
}
523531

524532
export interface ImageOverlay extends BaseOverlay {
@@ -528,6 +536,13 @@ export interface ImageOverlay extends BaseOverlay {
528536
* Specifies the relative path to the image used as an overlay.
529537
*/
530538
input: string;
539+
540+
/**
541+
* List of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset.
542+
*
543+
* {@link https://imagekit.io/docs/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay|Video}
544+
*/
545+
transformations?: Transformation[];
531546
}
532547

533548
export interface VideoOverlay extends BaseOverlay {
@@ -536,6 +551,13 @@ export interface VideoOverlay extends BaseOverlay {
536551
* Specifies the relative path to the video used as an overlay.
537552
*/
538553
input: string;
554+
555+
/**
556+
* List of transformations to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported.
557+
*
558+
* {@link https://imagekit.io/docs/video-transformation|Video Transformations}
559+
*/
560+
transformations?: Transformation[];
539561
}
540562

541563
export interface SubtitleOverlay extends BaseOverlay {
@@ -544,6 +566,13 @@ export interface SubtitleOverlay extends BaseOverlay {
544566
* Specifies the relative path to the subtitle file used as an overlay.
545567
*/
546568
input: string;
569+
570+
/**
571+
* Control styling of the subtitle.
572+
*
573+
* {@link https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer|Styling subtitles}
574+
*/
575+
transformations?: SubtitleOverlayTransformation[];
547576
}
548577

549578
export interface SolidColorOverlay extends BaseOverlay {
@@ -553,11 +582,131 @@ export interface SolidColorOverlay extends BaseOverlay {
553582
* If an 8-character value is provided, the last two characters represent the opacity level (from `00` for 0.00 to `99` for 0.99).
554583
*/
555584
color: string;
585+
586+
/**
587+
* Control width and height of the solid color overlay. Supported transformations depend on the base/parent asset.
588+
*
589+
* {@link https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay|Video}
590+
*/
591+
transformations?: SolidColorOverlayTransformation[];
556592
}
557593

558-
export type Overlay =
559-
| TextOverlay
560-
| ImageOverlay
561-
| VideoOverlay
562-
| SubtitleOverlay
563-
| SolidColorOverlay;
594+
export type TextOverlayTransformation = {
595+
/**
596+
* Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. Useful when used in conjunction with the `backgroundColor`.
597+
*/
598+
width?: number | string;
599+
600+
/**
601+
* Specifies the font size of the overlaid text. Accepts a numeric value, a percentage, or an arithmetic expression.
602+
*/
603+
fontSize?: number | string;
604+
605+
/**
606+
* Specifies the font family of the overlaid text. Choose from the [supported fonts list](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) or use a [custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay).
607+
*/
608+
fontFamily?: string;
609+
610+
/**
611+
* Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name.
612+
*/
613+
fontColor?: string;
614+
615+
/**
616+
* Specifies the inner alignment of the text when width is more than the text length.
617+
* Supported values: `left`, `right`, and `center` (default).
618+
*/
619+
innerAlignment?: "left" | "right" | "center";
620+
621+
/**
622+
* Specifies the padding around the overlaid text.
623+
* Can be provided as a single positive integer or multiple values separated by underscores (following CSS shorthand order).
624+
* Arithmetic expressions are also accepted.
625+
*/
626+
padding?: number | string;
627+
628+
/**
629+
* Specifies the transparency level of the text overlay. Accepts integers from `1` to `9`.
630+
*/
631+
alpha?: number;
632+
633+
/**
634+
* Specifies the typography style of the text.
635+
* Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.
636+
*/
637+
typography?: "b" | "i" | "b_i";
638+
639+
/**
640+
* Specifies the background color of the text overlay.
641+
* Accepts an RGB hex code, an RGBA code, or a color name.
642+
*/
643+
background?: string;
644+
645+
/**
646+
* Specifies the corner radius of the text overlay.
647+
* Set to `max` to achieve a circular or oval shape.
648+
*/
649+
radius?: number | "max";
650+
651+
/**
652+
* Specifies the rotation angle of the text overlay.
653+
* Accepts a numeric value for clockwise rotation or a string prefixed with "N" for counter-clockwise rotation.
654+
*/
655+
rotation?: number | string;
656+
657+
/**
658+
* Flip/mirror the text horizontally, vertically, or in both directions.
659+
* Acceptable values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or `v_h`.
660+
*/
661+
flip?: "h" | "v" | "h_v" | "v_h";
662+
663+
/**
664+
* Specifies the line height for multi-line text overlays. It will come into effect only if the text wraps over multiple lines.
665+
* Accepts either an integer value or an arithmetic expression.
666+
*/
667+
lineHeight?: number | string;
668+
}
669+
670+
export type SubtitleOverlayTransformation = {
671+
/**
672+
* Specifies the subtitle background color using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`).
673+
*/
674+
background?: string;
675+
/**
676+
* Sets the font size of subtitle text.
677+
*/
678+
fontSize?: number | string;
679+
/**
680+
* Sets the font family of subtitle text.
681+
* Refer to the [supported fonts documented](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) in the ImageKit transformations guide.
682+
*/
683+
fontFamily?: string;
684+
/**
685+
* Sets the font color of the subtitle text using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`).
686+
*/
687+
color?: string;
688+
/**
689+
* Sets the typography style of the subtitle text.
690+
* Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.
691+
*/
692+
typography?: "b" | "i" | "b_i";
693+
/**
694+
* Sets the font outline of the subtitle text.
695+
* Requires the outline width (an integer) and the outline color (as an RGB color code, RGBA color code, or standard web color name) separated by an underscore.
696+
* Examples: `2_blue`, `2_A1CCDD`, or `2_A1CCDD50`.
697+
*/
698+
fontOutline?: string;
699+
/**
700+
* Sets the font shadow for the subtitle text.
701+
* Requires the shadow color (as an RGB color code, RGBA color code, or standard web color name) and the shadow indent (an integer) separated by an underscore.
702+
* Examples: `blue_2`, `A1CCDD_3`, or `A1CCDD50_3`.
703+
*/
704+
fontShadow?: string;
705+
}
706+
707+
export type SolidColorOverlayTransformation = Pick<Transformation, "width" | "height" | "radius"> & {
708+
/**
709+
* Specifies the transparency level of the overlaid solid color layer. Supports integers from `1` to `9`.
710+
*/
711+
alpha?: number;
712+
}

0 commit comments

Comments
 (0)