@imgproxy/imgproxy-js-core
Version:
imgproxy-js-core package is designed to be used as part of framework-specific packages and plugins.
1,325 lines (1,323 loc) • 128 kB
TypeScript
// Generated by dts-bundle-generator v9.5.1
/**
* *Brightness option*. **PRO feature.**
*
* When set, imgproxy will adjust brightness of the resulting image.
* `brightness` is an integer number ranging from -255 to 255.
*
* @example
* {brightness: 50} - increase brightness by 50
* {brightness: -50} - decrease brightness by 50
*
* @default 0
*/
export type Brightness = number;
/**
* *Brightness option*. **PRO feature.**
*
* To describe the Brightness option, you can use the keyword `brightness` or `br`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=brightness
*/
export interface BrightnessOptionsPartial {
brightness?: Brightness;
br?: Brightness;
}
/**
* *Contrast option*. **PRO feature.**
*
* When set, imgproxy will adjust the contrast of the resulting image.
* `contrast` is a positive floating point number, where a value of 1 leaves the contrast unchanged.
*
* @example
* {contrast: 0.5} - decrease contrast by 50%
* {contrast: 1.5} - increase contrast by 50%
* {contrast: 3} - increase contrast by 200%
*
* @default 1
*
* @see https://docs.imgproxy.net/generating_the_url?id=contrast
*/
export type Contrast = number;
/**
* *Contrast option*. **PRO feature.**
*
* To describe the Contrast option, you can use the keyword `contrast` or `co`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=contrast
*/
export interface ContrastOptionsPartial {
contrast?: Contrast;
co?: Contrast;
}
/**
* *Saturation option*. **PRO feature.**
*
* When set, imgproxy will adjust saturation of the resulting image.
* `saturation` is a positive floating-point number, where a value of 1 leaves the saturation unchanged.
*
* @example
* {saturation: 0.5} - decrease saturation by 50%
* {saturation: 1.5} - increase saturation by 50%
* {saturation: 5} - increase saturation by 400%
*
* @default 1
*
* @see https://docs.imgproxy.net/generating_the_url?id=saturation
*/
export type Saturation = number;
/**
* *Saturation option*. **PRO feature.**
*
* To describe the Saturation option, you can use the keyword `saturation` or `sa`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=saturation
*/
export interface SaturationOptionsPartial {
saturation?: Saturation;
sa?: Saturation;
}
/**
* *Adjust option*. **PRO feature.**
*
* This is a meta-option that defines the brightness, contrast, and saturation.
* All arguments are optional and can be omitted to use their default values.
*
* *Brightness*.
*
* When set, imgproxy will adjust brightness of the resulting image.
* `brightness` is an integer number ranging from -255 to 255.
*
* *Contrast*.
*
* When set, imgproxy will adjust the contrast of the resulting image.
* `contrast` is a positive floating point number, where a value of 1 leaves the contrast unchanged.
*
* *Saturation*.
*
* When set, imgproxy will adjust saturation of the resulting image.
* `saturation` is a positive floating-point number, where a value of 1 leaves the saturation unchanged.
*
* @example
* {adjust: {brightness: 50, contrast: 1.5, saturation: 0.5}} - increase brightness by 50, increase contrast by 50%, decrease saturation by 50%
* {adjust: {brightness: -50, contrast: 0.5, saturation: 5}} - decrease brightness by 50, decrease contrast by 50%, increase saturation by 400%
* {adjust: {brightness: 50}} - increase brightness by 50, leave contrast and saturation unchanged
* {adjust: {contrast: 2.5, saturation: 0.5}} - leave brightness unchanged, increase contrast by 150%, decrease saturation by 50%
*
* @default
* - brightness: 0
* - contrast: 1
* - saturation: 1
*
* @see
* - `adjust` https://docs.imgproxy.net/generating_the_url?id=adjust
* - `brightness` https://docs.imgproxy.net/generating_the_url?id=brightness
* - `contrast` https://docs.imgproxy.net/generating_the_url?id=contrast
* - `saturation` https://docs.imgproxy.net/generating_the_url?id=saturation
*/
export interface Adjust {
brightness?: Brightness;
contrast?: Contrast;
saturation?: Saturation;
}
/**
* *Adjust option*. **PRO feature.**
*
* To describe the Adjust option, you can use the keyword `adjust` or `a`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=adjust
*/
export interface AdjustOptionsPartial {
adjust?: Adjust;
a?: Adjust;
}
/**
* *Autoquality option*. **PRO feature**
*
* Redefines autoquality settings.
* All arguments are optional and can be omitted.
*
* @param {"none" | "size" | "dssim" | "ml"} [method="none"] - (optional) the method of quality calculation. Default: `none`.
*
* Available methods:
* - `none` - Disable the autoquality.
* - `size` - With this method, imgproxy will try to degrade the quality so your image fits the desired file size.
* With this method parameter `target` must be equal to the desired file size.
* - `dssim` - With this method imgproxy will try to select a level of quality so that the saved image
* will have the desired {@link https://en.wikipedia.org/wiki/Structural_similarity#Structural_Dissimilarity | DSSIM} value.
* With this method parameter `target` must be equal to the desired DSSIM value.
* - `ml` - This method is almost the same as autoquality with {@link https://docs.imgproxy.net/autoquality?id=autoquality-by-dssim | DSSIM}
* but imgproxy will try to predict the initial quality using neural networks.
* This requires neural networks to be configured (see the config examlpe or the config documentation).
* If a neural network for the resulting format is not provided,
* the {@link https://docs.imgproxy.net/autoquality?id=autoquality-by-dssim | DSSIM} method will be used instead.
* When this method is used, imgproxy will save JPEG images with the most optimal
* {@link https://docs.imgproxy.net/configuration?id=advanced-jpeg-compression | advanced JPEG compression}
* settings, ignoring config and processing options.
* With this method parameter `target` must be equal to the desired DSSIM value.
* If you trust your neural network’s autoquality, you may want to set `allowed_error` to `1`
* (the maximum possible DSSIM value). In this case, imgproxy will always use the quality predicted by the neural network.
*
* @param {number} [target=0.02] - (optional) desired value of the autoquality method metric.
* The value can be any positive number. Default: `0.02`
* @param {number} [min_quality=70] - (optional) the minimal quality imgproxy can use. Default: `70`
* @param {number} [max_quality=80] - (optional) the maximum quality imgproxy can use. Default: `80`
* @param {number} [allowed_error=0.001] - (optional) the allowed `target` error. Available range values from `0` to `1`.
* Applicable only to `dssim` and `ml` methods. Default: `0.001`
*
* @warning Autoquality requires the image to be saved several times.
* Use it only when you prefer the resulting size and quality over the speed.
*
* @example
* // Auquality with size method
* {autoquality: {method: "size", target: 10240, min_quality: 10, max_quality: 80}}
* // Auquality with dssim method, `allowed_error` - we're happy enough if the resulting DSSIM will differ from the desired by `0.001`
* {autoquality: {method: "dssim", target: 0.02, min_quality: 70, max_quality: 80, allowed_error: 0.001}}
* // Auquality with ml method
* {autoquality: {method: "ml", target: 0.02, min_quality: 70, max_quality: 80, allowed_error: 0.001}}
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=autoquality | autoquality option imgproxy docs}
* - {@link https://docs.imgproxy.net/autoquality | more info about autoquality option imgproxy docs}
* - {@link https://docs.imgproxy.net/autoquality?id=autoquality-by-file-size | autoquality by file size imgproxy docs}
* - {@link https://docs.imgproxy.net/autoquality?id=autoquality-by-dssim | autoquality by DSSIM imgproxy docs}
* - {@link https://docs.imgproxy.net/autoquality?id=autoquality-with-ml | autoquality with ML imgproxy docs}
*/
export interface Autoquality {
method?: "none" | "size" | "dssim" | "ml";
target?: number;
min_quality?: number;
max_quality?: number;
allowed_error?: number;
}
/**
* *Autoquality option*. **PRO feature**
*
* To describe the Autoquality option, you can use the keyword `autoquality` or `aq`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=autoquality
*/
export interface AutoqualityOptionsPartial {
autoquality?: Autoquality;
aq?: Autoquality;
}
/**
* *Auto rotate option*
*
* When set to `1`, `"t"` or `true`, imgproxy will automatically rotate images based on the EXIF Orientation parameter
* (if available in the image meta data). The orientation tag will be removed from the image in all cases.
* Normally this is controlled by the `IMGPROXY_AUTO_ROTATE` configuration
* but this procesing option allows the configuration to be set for each request.
*
* @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @see
* - `Auto rotate` https://docs.imgproxy.net/generating_the_url?id=auto-rotate
* - `IMGPROXY_AUTO_ROTATE` https://docs.imgproxy.net/configuration?id=miscellaneous
*/
export type AutoRotate = 1 | "t" | true | false | string;
/**
* *Auto rotate option*
*
* To describe the Auto rotate option, you can use the keyword `auto_rotate` or `ar`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=auto-rotate
*/
export interface AutoRotateOptionsPartial {
auto_rotate?: AutoRotate;
ar?: AutoRotate;
}
/**
* *Background option*
*
* When set, imgproxy will fill the resulting image background with the specified color.
* `r`, `g`, and `b` are the red, green and blue channel values of the background color (0-255).
* `hex_color` is a hex-coded value of the color. Useful when you convert an image with alpha-channel to JPEG.
*
* With no arguments provided, disables any background manipulations.
*
* @example
* {background: {r: 255, g: 255, b: 255}} - background in RGB format
* {background: "ff00ff"} - background in hex format
*
* @default disabled
*
* @see https://docs.imgproxy.net/generating_the_url?id=background
*/
export type Background = BackgroundRGB | string;
export interface BackgroundRGB {
r: number;
g: number;
b: number;
}
/**
* *Background option*
*
* To describe the Background option, you can use the keyword `background` or `bg`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=background
*/
export interface BackgroundOptionsPartial {
background?: Background;
bg?: Background;
}
/**
* *Background alpha option*. **PRO feature.**
*
* Adds an alpha channel to background. The value of alpha is a positive floating point number between 0 and 1.
*
* @example
* {background_alpha: 0.5} - background alpha 0.5
*
* @default 1
*
* @see https://docs.imgproxy.net/generating_the_url?id=background-alpha
*/
export type BackgroundAlpha = number;
/**
* *Background alpha option*. **PRO feature.**
*
* To describe the Background alpha option, you can use the keyword `background_alpha` or `bga`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=background-alpha
*/
export interface BackgroundAlphaOptionsPartial {
background_alpha?: BackgroundAlpha;
bga?: BackgroundAlpha;
}
/**
* *Blur detections*. **PRO feature**
*
* @param {number} sigma - The value of sigma defines the size of the mask imgproxy will use.
* @param {string[]} [class_names] - (optional) A list of class names to blur.
* If `class_names` are omitted, imgproxy blurs all the detected objects.
*
* @note imgproxy can detect objects on the image and use them for smart cropping,
* bluring the detections, or drawing the detections.
*
* For object detection purposes, imgproxy uses the {@link https://github.com/AlexeyAB/darknet | Darknet YOLO model}.
* We provide Docker images with a model trained for face detection,
* but you can use any Darknet YOLO model found in the {@link https://github.com/AlexeyAB/darknet/wiki/YOLOv4-model-zoo | zoo}
* or you can train your own model by following this {@link https://github.com/AlexeyAB/darknet#how-to-train-to-detect-your-custom-objects | guide}.
*
* @example
* // Blur all detected objects
* {blur_detections: {sigma: 5}}
*
* // Blur only detected faces
* {blur_detections: {sigma: 10, class_names: ["face"]}}
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=blur-detections | blur detections option imgproxy docs}
*/
export interface BlurDetections {
sigma: number;
class_names?: string[];
}
/**
* *Blur detections option*. **PRO feature**
*
* To describe the Blur detections option, you can use the keyword `blur_detections` or `bd`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=blur-detections
*/
export interface BlurDetectionsOptionsPartial {
blur_detections?: BlurDetections;
bd?: BlurDetections;
}
/**
* *Blur option*
*
* When set, imgproxy will apply a gaussian blur filter to the resulting image.
* The value defines the size of the mask imgproxy will use.
* The value can be an any positive number.
*
* @default disabled
*
* @see https://docs.imgproxy.net/generating_the_url?id=blur
*/
export type Blur = number;
/**
* *Blur option*
*
* To describe the Blur option, you can use the keyword `blur` or `bl`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=blur
*/
export interface BlurOptionsPartial {
blur?: Blur;
bl?: Blur;
}
/**
* *Cache buster option*
*
* Cache buster doesn’t affect image processing but its changing allows for bypassing the CDN,
* proxy server and browser cache. Useful when you have changed some things that are not reflected in the URL,
* like image quality settings, presets, or watermark data.
*
* It’s highly recommended to prefer the cachebuster option over a URL query string
* because that option can be properly signed.
*
* @default empty
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=cache-buster | cache buster option imgproxy docs}
*/
export type CacheBuster = string;
/**
* *Cache buster option*
*
* To describe the Cache Buster option, you can use the keyword `cachebuster` or `cb`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=cache-buster
*/
export interface CacheBusterOptionsPartial {
cachebuster?: CacheBuster;
cb?: CacheBuster;
}
/**
* *Color Profile option*
*
* When set, imgproxy will convert the image's colorspace to the specified color profile
* and embed the selected color profile in the output image.
*
* @note This is a Pro feature.
* @note Ignored if the output format doesn't support color profiles.
* @note Embedded profiles are not stripped by the standard color profile removal options.
*
* Available profiles:
* - `srgb`: Built-in compact sRGB profile
* - `cmyk`: Built-in "Chemical proof" CMYK profile
* - Custom color profile filename (located in IMGPROXY_COLOR_PROFILES_DIR)
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=color-profile | color profile option imgproxy docs}
*/
export type ColorProfile = string;
/**
* *Color Profile option*
*
* To describe the Color Profile option, you can use the keywords `color_profile`, `cp`, or `icc`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=color-profile
*/
export interface ColorProfileOptionsPartial {
color_profile?: ColorProfile;
cp?: ColorProfile;
icc?: ColorProfile;
}
/**
* *Colorize option*. **PRO feature**
*
* Places a color overlay on the processed image.
* @see
* - `colorize` https://docs.imgproxy.net/generating_the_url?id=colorize
*/
export interface Colorize {
/** Opacity of the color overlay (0-1). When set to 0, overlay is not applied */
opacity: number;
/** Optional hex-coded color value (default is black: 000) */
color?: string;
/** Optional flag to preserve the original image's alpha channel (default is false) */
keepAlpha?: boolean;
}
export interface ColorizeOptionsPartial {
colorize?: Colorize;
col?: Colorize;
}
/**
* Specifies the gravity type. Available values:
*
* - `no`: north (top edge)
* - `so`: south (bottom edge)
* - `ea`: east (right edge)
* - `we`: west (left edge)
* - `noea`: north-east (top-right corner)
* - `nowe`: north-west (top-left corner)
* - `soea`: south-east (bottom-right corner)
* - `sowe`: south-west (bottom-left corner)
* - `ce`: center
*/
export type GravityType = "no" | "so" | "ea" | "we" | "noea" | "nowe" | "soea" | "sowe" | "ce";
/**
* BaseGravity. When imgproxy needs to cut some parts of the image, it is guided by the gravity option.
*
*
* @param {GravityType} type - Must be one of the following values: `no`, `so`, `ea`, `we`, `noea`, `nowe`, `soea`, `sowe`, `ce`.
* @param {number} [x_offset] - The horizontal offset of the focal point from the type value.
* @param {number} [y_offset] - The vertical offset of the focal point from the type value.
*
* @example
* // In this case we set the image's focal point to be in the middle of its top edge.
* {gravity: {type: "no"}}
*
* // In this case we set the image's focal point to be in the middle of its top edge and shift this point 10px to the right and 10px down. This way, when resizing with imgproxy, it will be based on this specified point.
* {gravity: {type: "no", x_offset: 10, y_offset: 10}}
*
* // In this case we set the image's focal point to be in the bottom right corner and shift this point 10px to the left and 20px to the up.
* {gravity: {type: "soea", x_offset: -10, y_offset: -20}}
*
* @see https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface BaseGravity {
type: GravityType;
x_offset?: number;
y_offset?: number;
}
/**
* Smart gravity. libvips detects the most “interesting” section of the image and considers it as the center of the resulting image.
*
* Offsets are not applicable here.
*
* @param {string} type - Must be `sm`.
*
* @example
* {gravity: {type: "sm"}}
*
* @see https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface SmartGravity {
type: "sm";
}
/**
* The gravity focus point.
*
* `x` and `y` are floating point numbers between `0` and `1` that define the coordinates of the center of the resulting image.
*
* Treat `0` and `1` as right/left for `x` and top/bottom for `y`.
*
* @param {string} type - Must be `fp`.
* @param {number} x - The horizontal offset of the focal point from the type value.
* @param {number} y - The vertical offset of the focal point from the type value.
*
* @example
* {gravity: {type: "fp", x: 0.5, y: 0.5}}
*
* @see https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface FPGravity {
type: "fp";
x: number;
y: number;
}
/**
* **PRO feature.**
*
* Object-oriented gravity. imgproxy detects objects of provided classes on the image and calculates the resulting image center using their positions.
*
* If class names are omited, imgproxy will use all the detected objects.
*
* @param {string} type - Must be `obj`.
* @param {string[]} class_names - Array of class names.
*
* @example
* {gravity: {type: "obj", class_names: ["face", "person"]}}
*
* @see https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface ObjGravity {
type: "obj";
class_names: string[];
}
/**
* **PRO feature.**
*
* Object-weighted gravity. imgproxy detects objects of provided classes on the image, calculates the resulting image center using their positions, and adds weights to these positions.
*
* If class weights are omited, imgproxy will use all the detected objects with equal weights.
*
* @param {string} type - Must be `objw`.
* @param {Array<{class: string, weight: number}>} class_weights - Array of objects with class names and their weights.
*
* @example
* {gravity: {type: "objw", class_weights: [{class: "face", weight: 1}, {class: "person", weight: 0.5}]}}
*
* @see https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface ObjwGravity {
type: "objw";
class_weights: Array<{
class: string;
weight: number;
}>;
}
/**
* *Gravity option*
*
* When imgproxy needs to cut some parts of the image, it is guided by the gravity option.
*
* *Base gravity*.
* @param {GravityType} type - Must be one of the following values: `no`, `so`, `ea`, `we`, `noea`, `nowe`, `soea`, `sowe`, `ce`.
* @param {number} [x_offset] - The horizontal offset of the focal point from the type value.
* @param {number} [y_offset] - The vertical offset of the focal point from the type value.fset` (optional). The vertical offset of the focal point from the type value.
*
* Available type values:
* - `no`: north (top edge)
* - `so`: south (bottom edge)
* - `ea`: east (right edge)
* - `we`: west (left edge)
* - `noea`: north-east (top-right corner)
* - `nowe`: north-west (top-left corner)
* - `soea`: south-east (bottom-right corner)
* - `sowe`: south-west (bottom-left corner)
* - `ce`: center (default value)
*
* *Smart gravity*.
* libvips detects the most “interesting” section of the image and considers it as the center of the resulting image.
* Offsets are not applicable here.
* @param {string} type - Must be `sm`.
*
* *Object-oriented gravity*. **PRO feature.**
* imgproxy detects objects of provided classes on the image and calculates the resulting image center using their positions.
* If class names are omited, imgproxy will use all the detected objects.
* @param {string} type - Must be `obj`.
* @param {string[]} class_names - Array of class names.
*
* *Object-weighted gravity*. **PRO feature.**
* imgproxy detects objects of provided classes on the image, calculates the resulting image center using their positions, and adds weights to these positions.
* If class weights are omited, imgproxy will use all the detected objects with equal weights.
* @param {string} type - Must be `objw`.
* @param {Array<{class: string, weight: number}>} class_weights - Array of objects with class names and their weights.
*
* *FP gravity*.
* The gravity focus point.
* `x` and `y` are floating point numbers between `0` and `1` that define the coordinates of the center of the resulting image.
* Treat `0` and `1` as right/left for `x` and top/bottom for `y`.
* @param {string} type - Must be `fp`.
* @param {number} x - The horizontal offset of the focal point from the type value.
* @param {number} y - The vertical offset of the focal point from the type value.
*
* @default {gravity: {type: "ce", x_offset: 0, y_offset: 0}}
*
* @example <caption>Base gravity</caption>
* // In this case we set the image's focal point to be in the middle of its top edge.
* {gravity: {type: "no"}}
*
* // In this case we set the image's focal point to be in the middle of its top edge and shift this point 10px to the right and 10px down. This way, when resizing with imgproxy, it will be based on this specified point.
* {gravity: {type: "no", x_offset: 10, y_offset: 10}}
*
* // In this case we set the image's focal point to be in the bottom right corner and shift this point 10px to the left and 20px to the up.
* {gravity: {type: "soea", x_offset: -10, y_offset: -20}}
*
* @example <caption>Smart gravity</caption>
* {gravity: {type: "sm"}}
*
* @example <caption>Object-oriented gravity</caption>
* {gravity: {type: "obj", class_names: ["face", "person"]}}
*
* @example <caption>Object-weighted gravity</caption>
* {gravity: {type: "objw", class_weights: [{class: "face", weight: 1}, {class: "person", weight: 0.5}]}}
*
* @example <caption>FP gravity</caption>
* {gravity: {type: "fp", x: 0.5, y: 0.5}}
*
* @see https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export type Gravity = BaseGravity | SmartGravity | ObjGravity | ObjwGravity | FPGravity;
/**
* *Gravity option*
*
* To describe the Gravity option, you can use the keyword `gravity` or `g`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface GravityOptionsPartial {
gravity?: Gravity;
g?: Gravity;
}
/**
* *Crop option*
*
* **Description to the generateUrl method**
*
* Defines an area of the image to be processed (crop before resize).
*
* `width` and `height` define the size of the area:
* - When `width` or `height` is greater than or equal to `1`, imgproxy treats it as an absolute value.
* - When `width` or `height` is less than `1`, imgproxy treats it as a relative value.
* - When `width` or `height` is set to `0`, imgproxy will use the full width/height of the source image.
*
* `gravity` (optional) accepts the same values as the `gravity` option.
*
* *Base gravity*.
* - `type`.
* - `x_offset` (optional). The horizontal offset of the focal point from the type value.
* - `y_offset` (optional). The vertical offset of the focal point from the type value.
*
* Available type values:
* - `no`: north (top edge)
* - `so`: south (bottom edge)
* - `ea`: east (right edge)
* - `we`: west (left edge)
* - `noea`: north-east (top-right corner)
* - `nowe`: north-west (top-left corner)
* - `soea`: south-east (bottom-right corner)
* - `sowe`: south-west (bottom-left corner)
* - `ce`: center (default value)
*
* *Smart gravity*.
* libvips detects the most “interesting” section of the image and considers it as the center of the resulting image.
* Offsets are not applicable here.
* - `type`: `sm`
*
* *Object-oriented gravity*. **PRO feature.**
* imgproxy detects objects of provided classes on the image and calculates the resulting image center using their positions.
* If class names are omited, imgproxy will use all the detected objects.
* - `type`: `obj`
* - `class_names`: array of strings
*
* *FP gravity*.
* The gravity focus point.
* - type: `fp`
* - `x` is floating point numbers between `0` and `1` that define the right/left coordinates of the center of the resulting image.
* - `y` is floating point numbers between `0` and `1` that define the top/bottom coordinates of the center of the resulting image.
*
* @example
* // crop 100x100px from the center of the image, default gravity is `gravity: {type: "ce", offset_x: 0, offset_y: 0}`
* {crop: {width: 100, height: 100}}
*
* // crop 100x100px from the top edge of the image
* {crop: {width: 100, height: 100, gravity: {type: "no"}}}
*
* // crop 100x100px from top right corner of the image and moved focal point 10px to the left and 20px down
* {crop: {width: 100, height: 100, gravity: {type: "noea", offset_x: -10, offset_y: 20}}}
*
* // crop 100x100px from the center of the image using smart gravity
* {crop: {width: 100, height: 100, gravity: {type: "sm"}}}
*
* // crop 100x100px from the center of the image using object-oriented gravity
* {crop: {width: 100, height: 100, gravity: {type: "obj", class_names: ["face", "person"]}}}
*
* // crop 100x100px from the center of the image using FP gravity
* {crop: {width: 100, height: 100, gravity: {type: "fp", x: 0.5, y: 0.5}}}
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=crop | crop imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=gravity | gravity imgproxy docs}
*
*
* **Description to the generateImageInfoUrl method**
*
* @warning **Slow**. This option requires the image to be fully downloaded and processed.
*
* When `width` and `height` are greater than zero, imgproxy will return the relative
* crop coordinates for the defined crop parameters.
*
* Response example:
*
* {
* "crop": {
* "left": 0.383203125,
* "top": 0.2603861907548274,
* "width": 0.1953125,
* "height": 0.3510825043885313
* }
* }
*
* @default: 0:0:ce.
*
* @see {@link https://docs.imgproxy.net/getting_the_image_info?id=crop | crop imgproxy docs}
*/
export interface Crop {
width: number;
height: number;
gravity?: Gravity;
}
/**
* *Crop option*
*
* To describe the Crop option, you can use the keyword `crop` or `c`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=crop
*/
export interface CropOptionsPartial {
crop?: Crop;
c?: Crop;
}
/**
* *Crop aspect ratio option*. **PRO feature**
*
* **Description to the generateUrl method**
*
* Defines the aspect ratio to match the crop area. This is a Pro feature.
*
* @param {number} `aspect_ratio` defines the desired aspect ratio for the crop area:
* - When set to `0`, no aspect ratio correction is applied.
* - Any positive number defines the aspect ratio (width/height).
*
* @param `enlarge` {1 | "t" | true} - (optional) controls crop area sizing:
* - When set to `true`, `1`, or `"t"`, imgproxy will enlarge the crop area if needed.
* - If the enlarged crop area exceeds the image size, imgproxy will reduce the area to fit while maintaining the requested aspect ratio.
*
* @see {@link https://docs.imgproxy.net/latest/usage/processing#crop-aspect-ratio | crop aspect ratio imgproxy docs}
*/
export interface CropAspectRatio {
aspect_ratio: number;
enlarge?: boolean | 1 | 0 | "t" | "f";
}
/**
* *Crop aspect ratio option*
*
* To describe the crop aspect ratio option, you can use the keyword `crop_aspect_ratio`, `crop_ar`, or `car`.
*
* @see https://docs.imgproxy.net/latest/usage/processing#crop-aspect-ratio
*/
export interface CropAspectRatioOptionsPartial {
crop_aspect_ratio?: CropAspectRatio;
crop_ar?: CropAspectRatio;
car?: CropAspectRatio;
}
/**
* *Disable animation option*. **PRO feature**
*
* When set to `1`, `"t"` or `true`, imgproxy will treat all images as not animated.
* Use the `page` and the `pages` options to specify which frames imgproxy should use.
*
* @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @default false
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=disable-animation | disable animation option imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=page | page option imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=pages | pages option imgproxy docs}
*/
export type DisableAnimation = 1 | "t" | true | false | string;
/**
* *Disable animation option*. **PRO feature**
*
* To describe the Disable Animation option, you can use the keyword `disable_animation` or `da`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=disable-animation
*/
export interface DisableAnimationOptionsPartial {
disable_animation?: DisableAnimation;
da?: DisableAnimation;
}
/**
* *Duotone option*. **PRO feature**
*
* When intensity is greater than zero, imgproxy will convert the resulting image to duotone.
*/
export interface Duotone {
/** Floating-point number between 0-1 defining effect strength */
intensity: number;
/** Hex color for dark areas */
color1?: string;
/** Hex color for light areas */
color2?: string;
}
export interface DuotoneOptionsPartial {
duotone?: Duotone;
dt?: Duotone;
}
/**
* *DPI option*. **PRO feature**
*
* When set, imgproxy will replace the image’s DPI metadata with the provided value.
* When set to `0`, imgproxy won’t change the image’s DPI or will reset it to the default value
* if the image’s metadata should be stripped.
*
* @warning This processing option takes effect whether imgproxy should strip the image’s metadata or not.
*
* @default 0
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=dpi | DPI option imgproxy docs}
*/
export type DPI = number;
/**
* *DPI option*. **PRO feature**
*
* To describe the DPI option, you can use the keyword `dpi` or `d`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=dpi
*/
export interface DPIOptionsPartial {
dpi?: DPI;
}
/**
* *DPR option*
*
* When set, imgproxy will multiply the image dimensions according to this factor for HiDPI
* (Retina) devices. The value must be greater than `0`.
*
* @note The dpr option affects gravities offsets, watermark offsets, and paddings
* to make the resulting image structures with and without the dpr option applied match.
*
* @default 1
*
* @see https://docs.imgproxy.net/generating_the_url?id=dpr
*/
export type DPR = number;
/**
* *DPR option*
*
* To describe the DPR option, you can use the keyword `dpr`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=dpr
*/
export interface DPROptionsPartial {
dpr?: DPR;
}
/**
* *Draw detections option*. **PRO feature**
*
* @param {1 | "t" | true | false | string} draw - is set to `1`, `"t"` or `true`,
* imgproxy detects objects of the provided classes and draws their bounding boxes.
* If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
* @param {string[]} [class_names] - (optional) A list of class names to draw.
* If `class_names` are omitted, imgproxy draws the bounding boxes of all the detected objects.
*
* @note imgproxy can detect objects on the image and use them for smart cropping,
* bluring the detections, or drawing the detections.
*
* For object detection purposes, imgproxy uses the {@link https://github.com/AlexeyAB/darknet | Darknet YOLO model}.
* We provide Docker images with a model trained for face detection,
* but you can use any Darknet YOLO model found in the {@link https://github.com/AlexeyAB/darknet/wiki/YOLOv4-model-zoo | zoo}
* or you can train your own model by following this {@link https://github.com/AlexeyAB/darknet#how-to-train-to-detect-your-custom-objects | guide}.
*
* @example
* // Draw bounding boxes of all detected objects
* {draw_detections: {draw: 1}}
*
* // Draw bounding boxes of detected faces
* {draw_detections: {draw: 1, class_names: ["face"]}}
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=draw-detections | draw detections option imgproxy docs}
*/
export interface DrawDetections {
draw: 1 | "t" | true | false | string;
class_names?: string[];
}
/**
* *Draw detections option*. **PRO feature**
*
* To describe the Draw detections option, you can use the keyword `draw_detections` or `dd`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=draw-detections
*/
export interface DrawDetectionsOptionsPartial {
draw_detections?: DrawDetections;
dd?: DrawDetections;
}
/**
* *Enforce Thumbnail option*
*
* When set to `1`, `"t"` or `true` and the source image has an embedded thumbnail,
* imgproxy will always use the embedded thumbnail instead of the main image.
*
* This is normally controlled by the IMGPROXY_ENFORCE_THUMBNAIL configuration
* but this procesing option allows the configuration to be set for each request.
*
* @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @warning This option is only supported for images in AVIF (`.avif`) and HEIC (`.heic`) formats.
*
* @see {@link https://docs.imgproxy.net/generating_the_url_advanced#enforce-thumbnail-option | enforce thumbnail option imgproxy docs}
*/
export type EnforceThumbnail = 1 | "t" | true | false | string;
/**
* *Enforce Thumbnail option*
*
* To describe the Enforce Thumbnail option, you can use the keyword `enforce_thumbnail` or `eth`.
*
* @see https://docs.imgproxy.net/generating_the_url_advanced#enforce-thumbnail-option
*/
export interface EnforceThumbnailOptionsPartial {
enforce_thumbnail?: EnforceThumbnail;
eth?: EnforceThumbnail;
}
/**
* *Enlarge option*
*
* When set to `1`, `"t"` or `true`, imgproxy will enlarge the image if it is smaller than the given size.
*
* @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @warning The `enlarge` option will only work in conjunction with `width` or `height` options.
* If `width` or `height` options are not specified, the `enlarge` option will not have any effects.
*
* @default false
*
* @see https://docs.imgproxy.net/generating_the_url?id=enlarge
*/
export type Enlarge = 1 | "t" | true | false | string;
/**
* *Enlarge option*
*
* To describe the Enlarge option, you can use the keyword `enlarge` or `el`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=enlarge
*/
export interface EnlargeOptionsPartial {
enlarge?: Enlarge;
el?: Enlarge;
}
/**
* *Expires option*
*
* When set, imgproxy will check the provided unix timestamp and return 404 when expired.
*
* @default empty
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=expires | expires option imgproxy docs}
* @see {@link https://www.unixtimestamp.com | unix timestamp converter}
*/
export type Expires = number;
/**
* *Expires option*
*
* To describe the Expires option, you can use the keyword `expires` or `exp`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=expires
*/
export interface ExpiresOptionsPartial {
expires?: Expires;
exp?: Expires;
}
/**
* *Extend aspect ratio option*
*
* imgproxy will extend the image to the aspect ratio calculated based on the dimensions specified
* in the `width` or `height` options, adding a transparent background.
*
* @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @warning The `extendAspectRatio` option will only work in conjunction with `width` or `height` options.
* If `width` or `height` options are not specified, the `extendAspectRatio` option will not have any effects.
*
* `gravity` (optional) accepts values of types `Base gravity` or `FP Gravity`
*
* *Base gravity*.
* - `type`.
* - `x_offset` (optional). The horizontal offset of the focal point from the type value.
* - `y_offset` (optional). The vertical offset of the focal point from the type value.
*
* Available type values:
* - `no`: north (top edge)
* - `so`: south (bottom edge)
* - `ea`: east (right edge)
* - `we`: west (left edge)
* - `noea`: north-east (top-right corner)
* - `nowe`: north-west (top-left corner)
* - `soea`: south-east (bottom-right corner)
* - `sowe`: south-west (bottom-left corner)
* - `ce`: center (default value)
*
* *FP gravity*.
* The gravity focus point.
* - type: `fp`
* - `x` is floating point numbers between `0` and `1` that define the right/left coordinates of the center of the resulting image.
* - `y` is floating point numbers between `0` and `1` that define the top/bottom coordinates of the center of the resulting image.
*
* @default
* {
* extendAspectRatio: "false",
* gravity: {
* type: "ce",
* x_offset: 0,
* y_offset: 0,
* },
* }
*
* @example
* // extend the image (if `width` or `height` options are set and the original aspect ratio is smaller than calculated by the size)
* {extend_aspect_ratio: {exend: true}}
*
* // extend the image from the focal point in the middle of the top edge (if `width` or `height` options are set and the original aspect ratio is smaller than calculated by the size)
* {extend_aspect_ratio: {extend: 1, gravity: {type: "no"}}}
*
* @see
* - `extendAspectRatio` https://docs.imgproxy.net/generating_the_url?id=extend-aspect-ratio
* - `gravity` https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface ExtendAspectRatio {
extend: 1 | "t" | true | false | string;
gravity?: BaseGravity | FPGravity;
}
/**
* *Extend aspect ratio option*
*
* To describe the Extend aspect ratio option, you can use the keyword `extend_aspect_ratio`, `extend_ar`, or `exar`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=extend-aspect-ratio
*/
export interface ExtendAspectRatioOptionsPartial {
extend_aspect_ratio?: ExtendAspectRatio;
extend_ar?: ExtendAspectRatio;
exar?: ExtendAspectRatio;
}
/**
* *Extend option*
*
* imgproxy will extend the image to the size specified in `width` or `height` options by adding a transparent background.
* This feature can be useful when the final result is smaller than the size specified in `width` or `height` options
* due to other transformations.
* For example, when the original image is smaller than the size specified in `width` or `height` options,
* or when the proportions of the original image do not match the size specified in `width` or `height` options and you have
* set the `resize` option with the `fit` parameter, etc.
*
* @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @warning The `extend` option will only work in conjunction with `width` or `height` options.
* If `width` or `height` options are not specified, the `extend` option will not have any effects.
*
* `gravity` (optional) accepts values of types `Base gravity` or `FP Gravity`
*
* *Base gravity*.
* - `type`.
* - `x_offset` (optional). The horizontal offset of the focal point from the type value.
* - `y_offset` (optional). The vertical offset of the focal point from the type value.
*
* Available type values:
* - `no`: north (top edge)
* - `so`: south (bottom edge)
* - `ea`: east (right edge)
* - `we`: west (left edge)
* - `noea`: north-east (top-right corner)
* - `nowe`: north-west (top-left corner)
* - `soea`: south-east (bottom-right corner)
* - `sowe`: south-west (bottom-left corner)
* - `ce`: center (default value)
*
* *FP gravity*.
* The gravity focus point.
* - type: `fp`
* - `x` is floating point numbers between `0` and `1` that define the right/left coordinates of the center of the resulting image.
* - `y` is floating point numbers between `0` and `1` that define the top/bottom coordinates of the center of the resulting image.
*
* @default
* {
* extend: "false",
* gravity: {
* type: "ce",
* x_offset: 0,
* y_offset: 0,
* },
* }
*
* @example
* // extend the image (if `width` or `height` options are set and the original image size is smaller than specified in the size)
* {extend: 1}
*
* // extend the image from the focal point in the middle of the top edge (if `width` or `height` options are set and the original image size is smaller than specified in the size)
* {extend: "t", gravity: {type: "no"}}
*
*
* @see
* - `extend` https://docs.imgproxy.net/generating_the_url?id=extend
* - `gravity` https://docs.imgproxy.net/generating_the_url?id=gravity
*/
export interface Extend {
extend: 1 | "t" | true | false | string;
gravity?: BaseGravity | FPGravity;
}
/**
* *Extend option*
*
* To describe the Extend option, you can use the keyword `extend` or `ex`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=extend
*/
export interface ExtendOptionsPartial {
extend?: Extend;
ex?: Extend;
}
/**
* *Fallback image url option*. **PRO feature**
*
* Custom fallback image by specifying its URL. The value should be in the URL-safe Base64-encoded format.
*
* @default blank
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=fallback-image-url | fallback image url option imgproxy docs}
*/
export type FallbackImageUrl = string;
/**
* *Fallback image url option*. **PRO feature**
*
* To describe the Fallback Image Url option, you can use the keyword `fallback_image_url` or `fiu`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=fallback-image-url
*/
export interface FallbackImageUrlOptionsPartial {
fallback_image_url?: FallbackImageUrl;
fiu?: FallbackImageUrl;
}
/**
* *Filename option*
*
* Defines a filename for the Content-Disposition header.
* When not specified, imgproxy will get the filename from the source URL.
*
* @param {string} name - escaped or URL-safe Base64-encoded filename to be used in the `Content-Disposition` header
* @param {1 | "t" | true | false | string} [encoded] - (optional) identifies if filename is Base64-encoded.
* Set it to `1`, `"t"`, or `true` if you encoded the filename value with URL-safe Base64 encoding.
* If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @default empty
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=filename | filename option imgproxy docs}
*/
export interface Filename {
name: string;
encoded?: 1 | "t" | true | false | string;
}
/**
* *Filename option*
*
* To describe the Filename option, you can use the keyword `filename` or `fn`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=filename
*/
export interface FilenameOptionsPartial {
filename?: Filename;
fn?: Filename;
}
/**
* *Format option*
*
* Specifies the resulting image format. Alias for the extension part of the URL.
* At the moment, imgproxy supports only the most popular image formats.
* - `png` — Portable Network Graphics
* - `jpg` — Joint Photographic Experts Group
* - `jxl` — JPEG XL
* - `webp` — WebP
* - `avif` — AV1 Image File Format
* - `gif` — Graphics Interchange Format
* - `ico` — Microsoft icon
* - `svg` — Scalable Vector Graphics
* - `bmp` — Bitmap
* - `tiff` — Tagged Image File Format
* - `mp4` — **PRO feature** MPEG-4
* - `pdf` — **PRO feature** PDF document
* - `best` — **PRO feature** to make imgproxy pick the best format for the
* resultant image. Check out the {@link https://docs.imgproxy.net/best_format | Best format guide}
* to learn more.
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=format | format option imgproxy docs}
* - {@link https://docs.imgproxy.net/image_formats_support | image formats support imgproxy docs}
* - {@link https://docs.imgproxy.net/best_format | Best format guide}
*/
export type Format = "png" | "jpg" | "jxl" | "webp" | "avif" | "gif" | "ico" | "svg" | "bmp" | "tiff" | "mp4" | "pdf" | "best";
/**
* *Format option*
*
* To describe the Format option, you can use the keyword `format`, `f`, or `ext`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=format
*/
export interface FormatOptionsPartial {
format?: Format;
f?: Format;
ext?: Format;
}
export interface FormatQualityType {
format: "png" | "jpg" | "webp" | "avif" | "gif" | "ico" | "svg" | "bmp" | "tiff" | "heic" | "pdf" | "mp4";
quality: number;
}
/**
* *Format quality option*
*
* Adds or redefines `IMGPROXY_FORMAT_QUALITY` values.
*
* @param {"png" | "jpg" | "webp" | "avif" | "gif" | "ico" | "svg" | "bmp" | "tiff" | "heic" | "pdf" | "mp4"} format - image format
* @param {number} quality - quality of the resulting image, as a percentage (from `1` to `100`)
*
* @example
* {format_quality: [{format: "jpg", quality: 60}, {format: "webp", quality: 60}, {format: "png", quality: 75}]}
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=format-quality | format quality option imgproxy docs}
*/
export type FormatQuality = FormatQualityType[];
/**
* *Format quality option*
*
* To describe the Format quality option, you can use the keyword `format_quality` or `fq`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=format-quality
*/
export interface FormatQualityOptionsPartial {
format_quality?: FormatQuality;
fq?: FormatQuality;
}
/**
* *Gradient option*. **PRO feature**
*
* Places a gradient on the processed image. The placed gradient transitions from transparency to the specified color.
*
* @param {number} opacity - specifies gradient opacity. When set to 0, gradient is not applied. Value range: `0` - `1`.
* @param {string} [color="000"] - (optional) specifies gradient color. If omitted, the gradient is black. Default `"000"`.
* @param {"down" | "up" | "right" | "left" | number} [direction="down"] - (optional) specifies gradient direction. Default `"down"`.
*
* Available values:
* - `down` - the top side of the gradient is transparrent, the bottom side is opaque
* - `up` - the bottom side of the gradient is transparrent, the top side is opaque
* - `right` - the left side of the gradient is transparrent, the right side is opaque
* - `left` - the right side of the gradient is transparrent, the left side is opaque
* - `number` - angle in degrees (clockwise). `0` creates a gradient from top to bottom; `90` creates a gradient from right to left.
* @param {number} [start=0.0] - (optional) specifies the start point of the gradient. Value range: `0.0` - `1.0`. Default `0.0`.
* @param {number} [stop=1.0] - (optional) specifies the end point of the gradient. Value range: `0.0` - `1.0`. Default `1.0`.
*
* @example
* // Apply a black gradient with 0.5 opacity from the top to the bottom of the image
* {gradient: {opacity: 0.5}}
*
* // Apply a red gradient with 0.2 opacity from the top to the bottom of the image
* {gradient: {opacity: 0.2, color: "ff0000"}}
*
* // Apply a gray gradient with 0.3 opacity from the left to the right of the image with the start point at 0.2 and the end point at 0.8
* {gradient: {opacity: 0.3, direction: "right", color: "808080", start: 0.2, stop: 0.8}}
*
* // Apply a gray gradient with 0.3 opacity at a 45 degree angle
* {gradient: {opacity: 0.3, direction: 45, color: "808080"}}
*
* @see https://docs.imgproxy.net/generating_the_url?id=gradient
*/
export interface Gradient {
opacity: number;
color?: string;
direction?: "down" | "up" | "right" | "left" | number;
start?: number;
stop?: number;
}
/**
* *Gradient option*. **PRO feature**
*
* To describe the Gradient option, you can use the keyword `gradient` or `gr`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=gradient
*/
export interface GradientOptionsPartial {
gradient?: Gradient;
gr?: Gradient;
}
/**
* *Height option*
*
* Defines the height of the resulting image.
* When set to `0`, imgproxy will calculate resulting height using the defined width and source aspect ratio.
* When set to `0` and resizing type is `force`, imgproxy will keep the original height.
*
* @default 0
*
* @see https://docs.imgproxy.net/generating_the_url?id=height
*/
export type Height = number;
/**
* *Height option*
*
* To describe the Height option, you can use the keyword `height` or `h`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=height
*/
export interface HeightOptionsPartial {
height?: Height;
h?: Height;
}
/**
* *JPEG options*. **PRO feature**
*
* Allows redefining JPEG saving options. All arguments are optional and can be omitted.
*
* @param {boolean} [progressive=false] - (optional) enables progressive JPEG compression. Default: `false`.
* @param {boolean} [no_subsample=false] - (optional) disables chrominance subsampling.
* This will improve quality at the cost of larger file size. Default: `false`.