// 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;
}
/**
* Available AVIF subsample values:
* - `"auto"` - (default) use subsampling when the image is saved with quality less than 90
* - `"on"` - always apply subsampling
* - `"off"` - never apply subsampling
*/
export type AvifSubsampleOptions = "auto" | "on" | "off";
/**
* *AVIF options*. **PRO feature**
*
* Allows redefining AVIF saving options.
*
* @default "auto"
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=avif-options | AVIF options imgproxy docs}
*/
export type AvifOptions = AvifSubsampleOptions | {
/**
* Controls when chroma subsampling is used. Default: `"auto"`
*/
subsample: AvifSubsampleOptions;
};
/**
* *AVIF options option*. **PRO feature**
*
* To describe the AVIF options option, you can use the keyword `avif_options` or `avifo`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=avif-options
*/
export interface AvifOptionsPartial {
avif_options?: AvifOptions;
avifo?: AvifOptions;
}
/**
* *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 area coordinates*. **PRO feature**
*
* @param {number} left - The left edge of the area, as a floating-point value between `0` and `1`, relative to the source image width.
* @param {number} top - The top edge of the area, as a floating-point value between `0` and `1`, relative to the source image height.
* @param {number} width - The width of the area, as a floating-point value between `0` and `1`, relative to the source image width.
* @param {number} height - The height of the area, as a floating-point value between `0` and `1`, relative to the source image height.
*
* @note The coordinates should be defined with respect to the source image EXIF orientation,
* as imgproxy doesn't rotate/flip them according to EXIF orientation.
* However, imgproxy rotates/flips the areas according to the `rotate` and `flip` options.
*/
export interface BlurArea {
left: number;
top: number;
width: number;
height: number;
}
/**
* *Blur areas*. **PRO feature**
*
* When `sigma` is greater than `0`, imgproxy will apply a Gaussian blur filter
* to the defined areas of the resulting image.
*
* @param {number} sigma - Defines the size of the mask imgproxy will use.
* @param {BlurArea[]} areas - The list of areas to be blurred.
*
* @example
* {blur_areas: {sigma: 5, areas: [{left: 0.1, top: 0.1, width: 0.2, height: 0.2}]}}
*
* @see {@link https://docs.imgproxy.net/usage/processing#blur-areas | blur areas option imgproxy docs}
*/
export interface BlurAreas {
sigma: number;
areas: BlurArea[];
}
/**
* *Blur areas option*. **PRO feature**
*
* To describe the Blur areas option, you can use the keyword `blur_areas` or `ba`.
*
* @see https://docs.imgproxy.net/usage/processing#blur-areas
*/
export interface BlurAreasOptionsPartial {
blur_areas?: BlurAreas;
ba?: BlurAreas;
}
/**
* *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 Base gravity
* // 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 Smart gravity
* {gravity: {type: "sm"}}
*
* @example Object-oriented gravity
* {gravity: {type: "obj", class_names: ["face", "person"]}}
*
* @example Object-weighted gravity
* {gravity: {type: "objw", class_weights: [{class: "face", weight: 1}, {class: "person", weight: 0.5}]}}
*
* @example FP gravity
* {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;
}
/**
* Boolean-like values for flip options
*
* @note Only `1`, `"t"`, or `true` are recognized as truthy values.
* Any other value (including `"true"` or `"1"` as strings) will be treated as false.
*/
export type FlipBooleanValue = boolean | 1 | 0 | "t" | "f";
/**
* *Flip option*
*
* When set, imgproxy will flip the image along the specified axes.
*
* @default false:false
*
* @see {@link https://docs.imgproxy.net/latest/usage/processing#flip | Flip imgproxy docs}
*/
export type FlipOptions = {
/**
* When set to `1`, `"t"`, or boolean `true`, imgproxy will flip the image horizontally.
* @default false
*/
horizontal?: FlipBooleanValue;
/**
* When set to `1`, `t`, or boolean `true`, imgproxy will flip the image vertically.
* @default false
*/
vertical?: FlipBooleanValue;
};
/**
* *Flip option*
*
* To describe the flip option, you can use the keyword `flip` or `fl`.
*
* @see https://docs.imgproxy.net/latest/usage/processing#flip
*/
export interface FlipOptionsPartial {
flip?: FlipOptions;
fl?: FlipOptions;
}
/**
* *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`.
* @param {boolean} [trellis_quant=false] - (optional) enables trellis quantisation for each 8x8 block.
* Reduces file size but increases compression time. Default: `false`.
* @param {boolean} [overshoot_deringing=false] - (optional)enables overshooting of samples with extreme values.
* Overshooting may reduce ringing artifacts from compression, in particular in areas where black text appears
* on a white background. Default: `false`.
* @param {boolean} [optimize_scans=false] - (optional) splits the spectrum of DCT coefficients into separate scans.
* Reduces file size but increases compression time. Requires parameter `progressive` to be set to `true`. Default: `false`.
* @param {0|1|2|3|4|5|6|7|8} [quant_table=0] - (optional) selects quantization table. Default: `0`.
*
* Available values:
* - `0` - Table from JPEG Annex K (default)
* - `1` - Flat table
* - `2` - Table tuned for MSSIM on Kodak image set
* - `3` - Table from ImageMagick by N. Robidoux
* - `4` - Table tuned for PSNR-HVS-M on Kodak image set
* - `5` - Table from Relevance of Human Vision to JPEG-DCT Compression (1992)
* - `6` - Table from DCTune Perceptual Optimization of Compressed Dental X-Rays (1997)
* - `7` - Table from A Visual Detection Model for DCT Coefficient Quantization (1993)
* - `8` - Table from An Improved Detection Model for DCT Coefficient Quantization (1993)
*
* @example
* // Disable chrominance subsampling
* {jpeg_options: {no_subsample: true}};
*
* // Enable progressive JPEG compression
* {jpeg_options: {progressive: true}};
*
* // Disable chrominance subsampling and enable trellis quantisation
* {jpeg_options: {no_subsample: true, trellis_quant: true}};
*
* // Enable overshooting of samples with extreme values and select quantization table 4
* {jpeg_options: {overshoot_deringing: true, quant_table: 4}};
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=jpeg-options | JPEG options imgproxy docs}
*/
export interface JPEGOptions {
progressive?: boolean;
no_subsample?: boolean;
trellis_quant?: boolean;
overshoot_deringing?: boolean;
optimize_scans?: boolean;
quant_table?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
}
/**
* *JPEG options option*. **PRO feature**
*
* To describe the JPEG options option, you can use the keyword `jpeg_options` or `jpgo`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=jpeg-options
*/
export interface JPEGOptionsPartial {
jpeg_options?: JPEGOptions;
jpgo?: JPEGOptions;
}
/**
* *Keep copyright option*
*
* When set to `1`, `"t"` or `true`, imgproxy will not remove copyright info while stripping metadata.
*
* This is normally controlled by the {@link https://docs.imgproxy.net/configuration?id=miscellaneous | IMGPROXY_KEEP_COPYRIGHT} 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 {@link https://docs.imgproxy.net/generating_the_url?id=keep-copyright | keep copyright option imgproxy docs}
*/
export type KeepCopyright = 1 | "t" | true | false | string;
/**
* *Keep metadata option*
*
* To describe the Keep metadata option, you can use the keyword `keep_copyright` or `kcr`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=keep-metadata
*/
export interface KeepCopyrightOptionsPartial {
keep_copyright?: KeepCopyright;
kcr?: KeepCopyright;
}
/**
* *Max animation frame resolution*
*
* This option redefining `IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION` config.
*
* The maximum resolution of the animated source image frame, in megapixels.
* Images with larger actual frame size will be rejected.
* When set to `0`, imgproxy will test the whole animated image resolution
* against `IMGPROXY_MAX_SRC_RESOLUTION` config summarising all the frames’ resolutions
*
* @warning Since this option allows redefining a security restriction, its usage
* is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
*
* @default 0
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=max-animation-frame-resolution | max animation frame resolution imgproxy docs}
*/
export type MaxAnimationFrameResolution = number;
/**
* *Max animation frame resolution*
*
* To describe the max animation frame resolution, you can use the keyword `max_animation_frame_resolution` or `mafr`.
*/
export interface MAFROptionsPartial {
max_animation_frame_resolution?: MaxAnimationFrameResolution;
mafr?: MaxAnimationFrameResolution;
}
/**
* *Max animation frames*
*
* imgproxy can process animated images (GIF, WebP), but since this operation
* is pretty memory heavy, only one frame is processed by default.
*
* You can increase the maximum number of animated image frames that may be processed.
*
* @default 1
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=max-animation-frames | max animation frames imgproxy docs}
*/
export type MaxAnimationFrames = number;
/**
* *Max animation frames*
*
* To describe the max animation frames, you can use the keyword `max_animation_frames` or `maf`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=max-animation-frames
*/
export interface MaxAnimationFramesOptionsPartial {
max_animation_frames?: MaxAnimationFrames;
maf?: MaxAnimationFrames;
}
/**
* *Max bytes option*
*
* When set, imgproxy automatically degrades the quality of the image until the image size
* is under the specified amount of bytes.
*
* @warning Applicable only to `jpg`, `webp`, `heic`, and `tiff` formats.
* When this option is set, imgproxy saves image multiple times to achieve the specified image size.
*
* @default 0
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=max-bytes | max bytes option imgproxy docs}
*/
export type MaxBytes = number;
/**
* *Max bytes option*
*
* To describe the Max bytes option, you can use the keyword `max_bytes` or `mb`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=max-bytes
*/
export interface MaxBytesOptionsPartial {
max_bytes?: MaxBytes;
mb?: MaxBytes;
}
/**
* *Max result dimension*
*
* Allows redefining the `IMGPROXY_MAX_RESULT_DIMENSION` configuration.
* Specifies the maximum allowed dimension for the resulting image.
*
* @warning Since this option allows redefining a security restriction,
* its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to true.
*
* @see {@link https://docs.imgproxy.net/latest/usage/processing#max-result-dimension | max result dimension imgproxy docs}
*/
export type MaxResultDimension = number;
/**
* *Max result dimension*
*
* To describe the max result dimension option, you can use the keyword `max_result_dimension` or `mrd`.
*/
export interface MaxResultDimensionOptionsPartial {
max_result_dimension?: MaxResultDimension;
mrd?: MaxResultDimension;
}
/**
* *Max src file size option*
*
* The maximum size of the source image, in bytes. Images with larger file size will be rejected.
* When set to `0`, file size check is disabled.
*
* @warning Since this option allows redefining a security restriction,
* its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to true.
*
* @default 0
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=max-src-file-size | max src file size option imgproxy docs}
*/
export type MaxSrcFileSize = number;
/**
* *Max src file size option*
*
* To describe the Max src file size option, you can use the keyword `max_src_file_size` or `msfs`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=max-src-file-size
*/
export interface MaxSrcFileSizeOptionsPartial {
max_src_file_size?: MaxSrcFileSize;
msfs?: MaxSrcFileSize;
}
/**
* *Max src resolution*
*
* The maximum resolution of the source image, in megapixels.
* Images with larger actual size will be rejected.
* Redefining `IMGPROXY_MAX_SRC_RESOLUTION` config.
*
* @warning Since this option allows redefining a security restriction,
* its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to true.
*
* @default: 16.8
*
* @see (@link https://docs.imgproxy.net/generating_the_url?id=max-src-resolution | max src resolution option imgproxy docs)
*/
export type MaxSrcResolution = number;
/**
* *Max src resolution*
*
* To describe the Max src resolution option, you can use the keyword `max_src_resolution` or `msr`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=max-src-resolution
*/
export interface MaxSrcResolutionOptionsPartial {
max_src_resolution?: MaxSrcResolution;
msr?: MaxSrcResolution;
}
/**
* *Min height option*
*
* Defines the minimum height of the resulting image.
*
* @warning When both `height` and `min-height` are set, the final image will be cropped according to `height`,
* so use this combination with care.
*
* @default 0
*
* @see https://docs.imgproxy.net/generating_the_url?id=min-height
*/
export type MinHeight = number;
/**
* *Min height option*
*
* To describe the Min height option, you can use the keyword `min_height` or `mh`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=min-height
*/
export interface MinHeightOptionsPartial {
min_height?: MinHeight;
mh?: MinHeight;
}
/**
* *Min width option*
*
* Defines the minimum width of the resulting image.
*
* @warning When both `width` and `min-width` are set, the final image will be cropped according to `width`,
* so use this combination with care.
*
* @default 0
*
* @see https://docs.imgproxy.net/generating_the_url?id=min-width
*/
export type MinWidth = number;
/**
* *Min width option*
*
* To describe the Min width option, you can use the keyword `min_width` or `mw`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=min-width
*/
export interface MinWidthOptionsPartial {
min_width?: MinWidth;
mw?: MinWidth;
}
/**
* *Monochrome option*. **PRO feature**
*
* When `intensity` is greater than zero, imgproxy will convert the resulting image to monochrome.
*/
export interface Monochrome {
/** Floating-point number between 0-1 defining effect strength */
intensity: number;
/** Optional hex color for monochrome palette base */
color?: string;
}
export interface MonochromeOptionsPartial {
monochrome?: Monochrome;
mc?: Monochrome;
}
declare const OBJECTS_POSITION_OPTIONS: readonly [
"no",
"so",
"ea",
"we",
"noea",
"nowe",
"soea",
"sowe",
"ce"
];
export type ObjectsPositionType = (typeof OBJECTS_POSITION_OPTIONS)[number];
export type ObjectsPositionNormalOptions = {
/**
* specifies the position type
*/
type: ObjectsPositionType;
/**
* (optional) specifies the position offset along the X axis.
*/
xOffset?: number;
/**
* (optional) specifies the position offset along the X axis.
*/
yOffset?: number;
};
export type ObjectsPositionFocusPointOptions = {
/**
* Focus point position
*/
type: "fp";
/**
* `x` is floating point number between 0 and 1 that define the coordinates of the center of the objects' area in the
* resulting image. Treat 0 and 1 as right/left
*/
x?: number;
/**
* `y` is floating point number between 0 and 1 that define the coordinates of the center of the objects' area in the
* resulting image. Treat 0 and 1 as top/bottom.
*/
y?: number;
};
export type ObjectctPositionProportionalOptions = {
type: "prop";
};
/**
* *Objcts position option*. **PRO feature.**
*
* When imgproxy needs to cut some parts of the image, and the obj/objw gravity is used, the objects_position option
* allows you to adjust the position of the detected objects on the resulting image.
*
* @default ce:0:0
*
* Special positions:
* - objects_position:fp:%x:%y: the focus point position. x and y are floating point numbers between 0 and 1 that define the coordinates of the center of the objects' area in the resulting image. Treat 0 and 1 as right/left for x and top/bottom for y.
* - objects_position:prop: the proportional position. imgproxy will try to set object offsets in the resulting image proportional to their offsets in the original image. This position type allows the picture scene to be maintained after cropping.
*
* @see https://docs.imgproxy.net/usage/processing#objects-position
*/
export type ObjectsPositionOptions = ObjectsPositionNormalOptions | ObjectsPositionFocusPointOptions | ObjectctPositionProportionalOptions;
export interface ObjectsPositionOptionsPartial {
objects_position?: ObjectsPositionOptions;
obj_pos?: ObjectsPositionOptions;
op?: ObjectsPositionOptions;
}
export interface PaddingDetails {
top?: number;
right?: number;
bottom?: number;
left?: number;
}
/**
* *Padding option*
*
* Defines padding size using CSS-style syntax.
* Padded space is filled according to the `background` option.
*
* - `top` (optional) - top padding (and for all other sides if they haven’t been explicitly st)
* - `right` (optional) - right padding (and left if it hasn’t been explicitly set)
* - `bottom` (optional) - bottom padding
* - `left` (optional) - left padding
*
*
* @note
* - Padding is applied after all image transformations (except watermarking) and enlarges the generated image.
* This means that if your resize dimensions were 100x200px and you applied the `padding:10` option,
* then you will end up with an image with dimensions of 120x220px.
* - Padding follows the `dpr` option so it will also be scaled if you’ve set it.
*
* @example
* {padding: 10} - 10px padding on all sides
* {padding: {top:10, right: 20}} - 10px top and bottom padding, 20px left and right padding
* {padding: {top: 10, right: 20, bottom: 30}} - 10px top padding, 20px left and right padding, 30px bottom padding
* {padding: {bottom: 30, left: 40}} - 0px top padding, 0px right padding, 30px bottom padding, 40px left padding
*
* @see
* - `padding` https://docs.imgproxy.net/generating_the_url?id=padding
* - `background` https://docs.imgproxy.net/generating_the_url?id=background
* - `dpr` https://docs.imgproxy.net/generating_the_url?id=dpr
*/
export type Padding = PaddingDetails | number;
/**
* *Padding option*
*
* To describe the Padding option, you can use the keyword `padding` or `pd`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=padding
*/
export interface PaddingOptionsPartial {
padding?: Padding;
pd?: Padding;
}
/**
* *Page option*. **PRO feature**
*
* When a source image supports pagination (`PDF`, `TIFF`) or animation (`GIF`, `WebP`),
* this option allows specifying the page to use. Page numeration starts from zero.
*
* The value can be any positive integer
*
* @warning If both the source and the resulting image formats supoprt animation,
* imgproxy will ignore this option and use all the source image pages.
* Use the `disable_animation` option to make imgproxy treat all images as not animated.
*
* @default 0
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=page | page option imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=disable-animation | disable animation option imgproxy docs}
*/
export type Page = number;
/**
* *Page option*. **PRO feature**
*
* To describe the Page option, you can use the keyword `page` or `pg`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=page
*/
export interface PageOptionsPartial {
page?: Page;
pg?: Page;
}
/**
* *Pages option*. **PRO feature**
*
* When a source image supports pagination (PDF, TIFF) or animation (GIF, WebP),
* this option allows specifying the number of pages to use. The pages will be stacked vertically and left-aligned.
* The value can be any positive integer starting with `1`.
*
* @warning If both the source and the resulting image formats supoprt animation,
* imgproxy will ignore this option and use all the source image pages.
* Use the `disable_animation` option to make imgproxy treat all images as not animated.
*
* @default 1
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=pages | pages option imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=disable-animation | disable animation option imgproxy docs}
*/
export type Pages = number;
/**
* *Pages option*. **PRO feature**
*
* To describe the Pages option, you can use the keyword `pages` or `pgs`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=pages
*/
export interface PagesOptionsPartial {
pages?: Pages;
pgs?: Pages;
}
/**
* *Pixelate option*
*
* When set, imgproxy will apply the pixelate filter to the resulting image. The value defines individual pixel size.
* The value can be an any positive number.
*
* @default disabled
*
* @see https://docs.imgproxy.net/generating_the_url?id=pixelate
*/
export type Pixelate = number;
/**
* *Pixelate option*
*
* To describe the Pixelate option, you can use the keyword `pixelate` or `pix`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=pixelate
*/
export interface PixelateOptionsPartial {
pixelate?: Pixelate;
pix?: Pixelate;
}
/**
* *PNG options*. **PRO feature**
*
* Allows redefining PNG saving options. All arguments are optional and can be omitted.
*
* @param {boolean} [interlaced=false] - (optional) enables interlaced PNG compression. Default: `false`.
* @param {boolean} [quantize=false] - (optional) enables PNG quantanization.
* libvips should be built with {@link https://github.com/DarthSim/quantizr | Quantizr} or libimagequant support.
* Default: `false`.
* @param {number} [quantization_colors=256] - (optional) maximum number of quantization palette entries.
* Should be between 2 and 256. Default: `256`.
*
* @example
* // Enable interlaced PNG compression
* {png_options: {interlaced: true}};
*
* // Enable PNG quantanization with 128 colors
* {png_options: {quantize: true, quantization_colors: 128}};
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=png-options | PNG options imgproxy docs}
*/
export interface PNGOptions {
interlaced?: boolean;
quantize?: boolean;
quantization_colors?: number;
}
/**
* *PNG options option*. **PRO feature**
*
* To describe the PNG options option, you can use the keyword `png_options` or `pngo`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=png-options
*/
export interface PNGOptionsPartial {
png_options?: PNGOptions;
pngo?: PNGOptions;
}
/**
* *Preset option*
*
* Defines a list of presets to be used by imgproxy. Feel free to use as many presets in a single URL as you need.
*
* Read more about presets in the {@link https://docs.imgproxy.net/presets | Presets} guide.
*
* @default empty
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=preset | preset option imgproxy docs}
*/
export type Preset = string[];
/**
* *Preset option*
*
* To describe the Preset option, you can use the keyword `preset` or `pr`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=preset
*/
export interface PresetOptionsPartial {
preset?: Preset;
pr?: Preset;
}
/**
* *Quality option*
*
* Redefines quality of the resulting image, as a percentage.
* When set to `0`, quality is assumed based on IMGPROXY_QUALITY and `format quality` option.
* Available range - from `1` to `100`.
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=quality | quality option imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=format-quality | format quality option imgproxy docs}
*/
export type Quality = number;
/**
* *Quality option*
*
* To describe the Quality option, you can use the keyword `quality` or `q`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=quality
*/
export interface QualityOptionsPartial {
quality?: Quality;
q?: Quality;
}
/**
* *Raw options*
*
* When set to `1`, `"t"` or `true`, imgproxy will respond with a raw unprocessed, and unchecked source image.
*
* @note If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* There are some differences between `raw` and `skip_processing` options:
* - While the `skip_processing` option has some conditions to skip the processing,
* the `raw` option allows to skip processing no matter what.
* - With the `raw` option set, imgproxy doesn’t check the source image’s type,
* resolution, and file size. Basically, the `raw` option allows streaming of any file type.
* - With the `raw` option set, imgproxy won’t download the whole image to the memory.
* Instead, it will stream the source image directly to the response lowering memory usage.
* - The requests with the `raw` option set are not limited by the `IMGPROXY_WORKERS` config
*
* @default false
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=raw | raw option imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=skip-processing | skip processing option imgproxy docs}
*/
export type Raw = 1 | "t" | true | false | string;
/**
* *Raw options*
*
* To describe the Raw option, you can use the keyword `raw`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=raw
*/
export interface RawOptionsPartial {
raw?: Raw;
}
/**
* *Resizing type option*
*
* Defines how imgproxy will resize the source image. Supported resizing types are:
*
* `fit`: resizes the image while keeping aspect ratio to fit a given size.
*
* `fill`: resizes the image while keeping aspect ratio to fill a given size and crops projecting parts.
*
* `fill-down`: the same as fill, but if the resized image is smaller than the requested size,
* imgproxy will crop the result to keep the requested aspect ratio.
*
* `force`: resizes the image without keeping the aspect ratio.
*
* `auto`: if both source and resulting dimensions have the same orientation (portrait or landscape),
* imgproxy will use fill. Otherwise, it will use fit.
*
* @default fit
*
* @see https://docs.imgproxy.net/generating_the_url?id=resizing-type
*/
export type ResizingType = "fit" | "fill" | "fill-down" | "force" | "auto";
/**
* *Resizing type option*
*
* To describe the Resizing type option, you can use the keyword `resizing_type` or `rt`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=resizing-type
*/
export interface ResizingTypeOptionsPartial {
resizing_type?: ResizingType;
rt?: ResizingType;
}
/**
* *Resize option*
* This is a meta-option that defines the `resizing_type`, `width`, `height`, `enlarge`, and `extend`.
*
* `resizing_type` (optional). Defines how imgproxy will resize the source image. Supported resizing types are:
*
* - `fit`: resizes the image while keeping aspect ratio to fit a given size. (**default value**)
* - `fill`: resizes the image while keeping aspect ratio to fill a given size and crops projecting parts.
* - `fill-down`: the same as fill, but if the resized image is smaller than the requested size,
* imgproxy will crop the result to keep the requested aspect ratio.
* - `force`: resizes the image without keeping the aspect ratio.
* - `auto`: if both source and resulting dimensions have the same orientation (portrait or landscape),
* imgproxy will use fill. Otherwise, it will use fit.
*
* `width` (optional). The width of the resulting image. If not specified,
* imgproxy will calculate it based on the `height` and the aspect ratio of the source image.
*
* `height` (optional). The height of the resulting image. If not specified,
* imgproxy will calculate it based on the `width` and the aspect ratio of the source image.
*
* `enlarge` (optional). If set to `1`, `"t"`, or `true`, imgproxy will enlarge the resulting
* image if the requested size is bigger than the size of the source image.
*
* `extend` (optional). imgproxy will extend the image to the size specified in `width` or `height` options by adding a transparent background.
* - `extend` - `1 | "t" | true | false | string`
* - `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.
*
* @example
* // resize the image to 300x200px using the fit resizing type
* {resize: {width: 300, height: 200}}
*
* // resize the image to 300x200px using the fill resizing type
* {resize: {width: 300, height: 200, resizing_type: "fill"}}
*
* // resize the image to 300x200px using the fill resizing type and enlarge it if the requested size is bigger than the size of the source image
* {resize: {width: 300, height: 200, resizing_type: "fill", enlarge: 1}}
*
* // resize the image to 300x200px using the fill resizing type and extend it if the requested size is bigger than the size of the source image
* {resize: {width: 300, height: 200, resizing_type: "fill", extend: {extend: 1}}}
*
* @see
* - `resize` https://docs.imgproxy.net/generating_the_url?id=resize
* - `resizing_type` https://docs.imgproxy.net/generating_the_url?id=resizing-type
* - `enlarge` https://docs.imgproxy.net/generating_the_url?id=enlarge
* - `extend` https://docs.imgproxy.net/generating_the_url?id=extend
*/
export interface Resize {
resizing_type?: ResizingType;
width?: number;
height?: number;
enlarge?: Enlarge;
extend?: Extend;
}
/**
* *Resize option*
*
* To describe the Resize option, you can use the keyword `resize` or `rs`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=resize
*/
export interface ResizeOptionsPartial {
resize?: Resize;
rs?: Resize;
}
/**
* *Resizing algorithm option.*
* **PRO feature.**
*
* Defines the algorithm that imgproxy will use for resizing.
* Supported algorithms are
* - `nearest` - The nearest neighbor algorithm is the simplest and fastest resizing technique.
* It works by selecting the nearest pixel from the original image and replicating its color to create the new pixels.
* - `linear` - Linear (or bilinear, in two dimensions) interpolation is typically good for changing the size of an image,
* but causes some undesirable softening of details and can still be somewhat jagged.
* - `cubic` - Bi-Cubic Interpolation is an extension of the Bi-Linear Interpolation technique,
* which estimates pixel values based on the nearest four pixels.
* Bi-Cubic Interpolation takes the surrounding sixteen pixels into account,
* resulting in smoother and more accurate image scaling.
* - `lanczos2` - Changes an image size using interpolation with the Lanczos filter.
* This function changes an image size using interpolation with the Lanczos filter.
* The image size may be either reduced or increased in each direction, depending on the destination image size.
* - `lanczos3` - The lanczos3 result (lower center) is sharper than the bicubic and lanczos2 results but exhibits
* a visible "ringing" artifact. The ringing artifact appears as a faint echo outside the gray boundary,
* or by looking just to the left and right of the thick black stripe running down the middle of the image
*
* @default lanczos3
*
* @see https://docs.imgproxy.net/generating_the_url?id=resizing-algorithm
*/
export type ResizingAlgorithm = "nearest" | "linear" | "cubic" | "lanczos2" | "lanczos3";
/** *Resizing algorithm option.*
* **PRO feature.**
*
* To describe the Resizing algorithm option, you can use the keyword `resizing_algorithm` or `ra`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=resizing-algorithm
*/
export interface ResizingAlgorithmOptionsPartial {
resizing_algorithm?: ResizingAlgorithm;
ra?: ResizingAlgorithm;
}
/**
* *Return attachment option*
*
* When set to `1`, `"t"` or `true`, imgproxy will return `attachment` in the `Content-Disposition` header,
* and the browser will open a ‘Save as’ dialog. This is normally controlled by the `IMGPROXY_RETURN_ATTACHMENT`
* configuration but this procesing option allows the configuration to be set for each request.
*
* If any value other than `1`, `"t"`, or `true` is passed, it will be recognized as `false`.
*
* @see {@link https://docs.imgproxy.net/generating_the_url?id=return-attachment | return attachment option imgproxy docs}
*/
export type ReturnAttachment = 1 | "t" | true | false | string;
/**
* *Return attachment option*
*
* To describe the Return attachment option, you can use the keyword `return_attachment` or `att`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=return-attachment
*/
export interface ReturnAttachmentOptionsPartial {
return_attachment?: ReturnAttachment;
att?: ReturnAttachment;
}
/**
* *Rotate option*
*
* Rotates the image on the specified angle.
* The orientation from the image metadata is applied before the rotation unless autorotation is disabled.
*
* Available values:
* - `0` - no rotation
* - `90` - rotate 90 degrees clockwise
* - `180` - rotate 180 degrees
* - `270` - rotate 90 degrees counterclockwise
*
* @default 0
*/
export type Rotate = 0 | 90 | 180 | 270;
/**
* *Rotate option*
*
* To describe the Rotate option, you can use the keyword `rotate` or `rot`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=rotate
*/
export interface RotateOptionsPartial {
rotate?: Rotate;
rot?: Rotate;
}
/**
* *Sharpen option*
*
* When set, imgproxy will apply the sharpen filter to the resulting image.
* The value of sigma defines the size of the mask imgproxy will use.
*
* As an approximate guideline, use
* - 0.5 for 4 pixels/mm (display resolution),
* - 1.0 for 12 pixels/mm,
* - 1.5 for 16 pixels/mm (300 dpi == 12 pixels/mm).
*
* @default disabled
*
* @see https://docs.imgproxy.net/generating_the_url?id=sharpen
*/
export type Sharpen = number;
/**
* *Sharpen option*
*
* To describe the Sharpen option, you can use the keyword `sharpen` or `sh`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=sharpen
*/
export interface SharpenOptionsPartial {
sharpen?: Sharpen;
sh?: Sharpen;
}
/**
* *Size option*
* This is a meta-option that defines the `width`, `height`, `enlarge`, and `extend`.
*
* `width` (optional). The width of the resulting image. If not specified,
* imgproxy will calculate it based on the `height` and the aspect ratio of the source image.
*
* `height` (optional). The height of the resulting image. If not specified,
* imgproxy will calculate it based on the `width` and the aspect ratio of the source image.
*
* `enlarge` (optional). If set to `1`, `"t"`, or `true`, imgproxy will enlarge the resulting
* image if the requested size is bigger than the size of the source image.
*
* `extend` (optional). imgproxy will extend the image to the size specified in `width` or `height` options by adding a transparent background.
* - `extend` - `1 | "t" | true | false | string`
* - `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.
*
* @example
* // change the size image to 300x200px
* {size: {width: 300, height: 200}}
*
* // change the size image to 300x200px and enlarge it if the requested size is bigger than the size of the source image
* {size: {width: 300, height: 200, enlarge: 1}}
*
* // change the size image to 300x200px and extend it if the requested size is bigger than the size of the source image
* {size: {width: 300, height: 200, extend: 1}}
*
* // change the size image to 300x200px and 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
* {size: {width: 300, height: 200, extend: {extend: 1, gravity: {type: "no"}}}}
*
* @see
* - `size` https://docs.imgproxy.net/generating_the_url?id=size
* - `width` https://docs.imgproxy.net/generating_the_url?id=width
* - `height` https://docs.imgproxy.net/generating_the_url?id=height
* - `enlarge` https://docs.imgproxy.net/generating_the_url?id=enlarge
* - `extend` https://docs.imgproxy.net/generating_the_url?id=extend
*/
export interface Size {
width?: number;
height?: number;
enlarge?: Enlarge;
extend?: Extend;
}
/**
* *Size option*
*
* To describe the Size option, you can use the keyword `size` or `s`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=size
*/
export interface SizeOptionsPartial {
size?: Size;
s?: Size;
}
/**
* *Skip processing option*
*
* A list of formats that imgproxy shouldn’t process.
*
* @warning Processing can only be skipped when the requested format is the same as the source format.
* Video thumbnail processing can’t be skipped.
*
* There are some differences between `raw` and `skip_processing` options:
* - While the `skip_processing` option has some conditions to skip the processing,
* the `raw` option allows to skip processing no matter what.
* - With the `raw` option set, imgproxy doesn’t check the source image’s type,
* resolution, and file size. Basically, the `raw` option allows streaming of any file type.
* - With the `raw` option set, imgproxy won’t download the whole image to the memory.
* Instead, it will stream the source image directly to the response lowering memory usage.
* - The requests with the `raw` option set are not limited by the `IMGPROXY_WORKERS` config
*
* @default empty
*
* @see
* - {@link https://docs.imgproxy.net/generating_the_url?id=skip-processing | skip processing option imgproxy docs}
* - {@link https://docs.imgproxy.net/generating_the_url?id=raw | raw option imgproxy docs}
*/
export type SkipProcessing = Array<"jpg" | "jxl" | "png" | "webp" | "avif" | "gif" | "ico" | "svg" | "heic" | "bmp" | "tiff" | "pdf" | "mp4">;
/**
* *Skip processing option*
*
* To describe the Skip Processing option, you can use the keyword `skip_processing` or `sp`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=skip-processing
*/
export interface SkipProcessingOptionsPartial {
skip_processing?: SkipProcessing;
sp?: SkipProcessing;
}
/**
* *Strip Color option*
*
* When set to `1`, `"t"` or `true`, imgproxy will transform the embedded color profile (ICC) to sRGB
* and remove it from the image.
* Otherwise, imgproxy will try to keep it as is.
*
* This is normally controlled by the {@link https://docs.imgproxy.net/configuration?id=miscellaneous | IMGPROXY_STRIP_COLOR_PROFILE}
* 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 {@link https://docs.imgproxy.net/generating_the_url?id=strip-color-profile | strip color profile option imgproxy docs}
*/
export type StripColorProfile = 1 | "t" | true | false | string;
/**
* *Strip Color option*
*
* To describe the Strip Color option, you can use the keyword `strip_color_profile` or `scp`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=strip-color-profile
*/
export interface StripColorProfileOptionsPartial {
strip_color_profile?: StripColorProfile;
scp?: StripColorProfile;
}
/**
* *Strip metadata option*.
*
* When set to `1`, `"t"` or `true`, imgproxy will strip the metadata (EXIF, IPTC, etc.) on JPEG and WebP output images.
*
* This is normally controlled by the {@link https://docs.imgproxy.net/configuration?id=miscellaneous | IMGPROXY_STRIP_METADATA}
* 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 {@link https://docs.imgproxy.net/generating_the_url?id=strip-metadata | strip metadata option imgproxy docs}
*/
export type StripMetadata = 1 | "t" | true | false | string;
/**
* *Strip metadata option*.
*
* To describe the Strip metadata option, you can use the keyword `strip_metadata` or `sm`.
*
* @see https://docs.imgproxy.net/generating_the_url?id=strip-metadata
*/
export interface StripMetadataOptionsPartial {
strip_metadata?: StripMetadata;
sm?: StripMetadata;
}
/**
* *Style option*. **PRO feature**.
*
* When set, imgproxy will prepend a `