Update docs and CHANGELOG

CHANGELOG.md

@@ -2,10 +2,14 @@
 
 ## [Unreleased]
 ### Add
-- Add video streams info to the `/info` response.
+- (pro) Add [info options](https://docs.imgproxy.net/latest/getting_the_image_info?id=info-options) support to the `/info` endpoint.
+- (pro) Add video streams info to the `/info` endpoint response.
 
 ### Change
 - Limit vector image sizes to `IMGPROXY_MAX_SRC_RESOLUTION`.
+- (pro) Respect image orientation when extracting image dimensions for the `/info` endpoint response.
+- (pro) Respect `IMGPROXY_WORKERS` and `IMGPROXY_REQUESTS_QUEUE_SIZE` configs in the `/info` endpoint.
+- (pro) Collect detailed metrics for the `/info` endpoint.
 
 ### Fix
 - Fix parsing of HEIF files with large boxes.

docs/assets/docsify-init.js

@@ -135,7 +135,8 @@ const configureDocsify = (additionalVersions, latestVersion, latestTag) => {
             .replaceAll("📝", '<i class="icon icon-note"></i>')
             .replaceAll("⚠️", '<i class="icon icon-warn"></i>')
             .replaceAll("✅", '<i class="icon icon-check"></i>')
-            .replaceAll("❌", '<i class="icon icon-cross"></i>');
+            .replaceAll("❌", '<i class="icon icon-cross"></i>')
+            .replaceAll("⏳", '<i class="icon icon-hourglass"></i>');
 
           if (vm.route.path.endsWith('/configuration'))
             content = content.replaceAll(configRegex, '* <code id="$1">$1</code>:');

docs/assets/hourglass.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="1em" viewBox="0 0 384 512"><!--! Font Awesome Free 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#f6c744" d="M32 0C14.3 0 0 14.3 0 32S14.3 64 32 64V75c0 42.4 16.9 83.1 46.9 113.1L146.7 256 78.9 323.9C48.9 353.9 32 394.6 32 437v11c-17.7 0-32 14.3-32 32s14.3 32 32 32H64 320h32c17.7 0 32-14.3 32-32s-14.3-32-32-32V437c0-42.4-16.9-83.1-46.9-113.1L237.3 256l67.9-67.9c30-30 46.9-70.7 46.9-113.1V64c17.7 0 32-14.3 32-32s-14.3-32-32-32H320 64 32zM96 75V64H288V75c0 19-5.6 37.4-16 53H112c-10.3-15.6-16-34-16-53zm16 309c3.5-5.3 7.6-10.3 12.1-14.9L192 301.3l67.9 67.9c4.6 4.6 8.6 9.6 12.1 14.9H112z"/></svg>

docs/assets/style.css

@@ -233,6 +233,9 @@ i.icon-check::after {
 i.icon-cross::after {
   background-image: url(/assets/cross.svg);
 }
+i.icon-hourglass::after {
+  background-image: url(/assets/hourglass.svg);
+}
 
 .github-edit-btn {
   display: block;

docs/configuration.md

@@ -325,12 +325,13 @@ There are two ways to define presets:
 
 #### Using an environment variable
 
-* `IMGPROXY_PRESETS`: a set of preset definitions, comma divided. Example: `default=resizing_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2`. Default: blank
+* `IMGPROXY_PRESETS`: a set of processing preset definitions, comma divided. Example: `default=resizing_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2`. Default: blank
+* `IMGPROXY_INFO_PRESETS`: ![pro](./assets/pro.svg) a set of info preset definitions, comma divided. Example: `default=xmp:0/blurhash:4:3`. Default: blank
 
 #### Using a command line argument
 
 ```bash
-imgproxy -presets /path/to/file/with/presets
+imgproxy -presets /path/to/file/with/presets -info-presets /path/to/file/with/info-presets
 ```
 
 This file should contain preset definitions, one per line. Lines starting with `#` are treated as comments. Example:
@@ -349,7 +350,8 @@ blurry=blur:2
 
 imgproxy can be switched into "presets-only mode". In this mode, imgproxy accepts only `preset` option arguments as processing options. Example: `http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png`
 
-* `IMGPROXY_ONLY_PRESETS`: disables all URL formats and enables presets-only mode.
+* `IMGPROXY_ONLY_PRESETS`: when `true`, enables presets-only mode. Default: `false`
+* `IMGPROXY_INFO_ONLY_PRESETS`: when `true`, enables presets-only mode for the [info](getting_the_image_info.md) endpoint. Default: `IMGPROXY_ONLY_PRESETS` value
 
 ## Image sources
 

docs/getting_the_image_info.md

@@ -7,81 +7,155 @@ imgproxy can fetch and return a source image info without downloading the whole
 To get the image info, use the following URL format:
 
 ```
-/info/%signature/plain/%source_url
-/info/%signature/%encoded_source_url
+/info/%signature/%info_options/plain/%source_url
+/info/%signature/%info_options/%encoded_source_url
 ```
 
-### Signature
+## Signature
 
 A signature protects your URL from being modified by an attacker. It is highly recommended to sign imgproxy URLs in a production environment.
 
 Once you set up your [URL signature](configuration.md#url-signature), check out the [Signing the URL](signing_the_url.md) guide to learn about how to sign your URLs. Otherwise, since the signature is required, feel free to use any string here.
 
-### Source URL
-#### Plain
+## Info options
 
-The source URL can be provided as is, prepended by `/plain/` part:
+Info options should be specified as URL parts divided by slashes (`/`). An info option has the following format:
 
 ```
-/plain/http://example.com/images/curiosity.jpg
+%option_name:%argument1:%argument2:...:argumentN
 ```
 
-**📝 Note:** If the source URL contains a query string or `@`, you'll need to escape it.
+### Size
 
-#### Base64 encoded
+```
+size:%size
+s:%size
+```
 
-The source URL can be encoded with URL-safe Base64. The encoded URL can be split with `/` as desired:
+When set to `1`, `t`, or `true`, imgproxy will return the size of the image file. If the source URL is an HTTP(s) URL, imgproxy will determine the file size based on the `Content-Length` HTTP header.
+
+Default: `true`.
 
+**Response example:**
+
+```json
+{
+  "size": 123456
+}
 ```
-/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn
+
+### Format
+
+```
+format:%format
+f:%format
 ```
 
-#### Encrypted with AES-CBC![pro](./assets/pro.svg) :id=encrypted-with-aes-cbc
+When set to `1`, `t`, or `true`, imgproxy will return the image format.
 
-The source URL can be encrypted with the AES-CBC algorithm, prepended by the `/enc/` segment. The encrypted URL can be split with `/` as desired:
+**📝 Note:** For video files, imgproxy returns a list of predicted formats divided by comma.
 
-```
-/enc/jwV3wUD9r4VBIzgv/ang3Hbh0vPpcm5cc/VO5rHxzonpvZjppG/2VhDnX2aariBYegH/jlhw_-dqjXDMm4af/ZDU6y5sBog
+Default: `true`.
+
+**Response example:**
+
+```json
+{
+  "format": "jpeg"
+}
 ```
 
-## Response format
+### Dimensions
 
-imgproxy responses with a JSON body and returns the following info:
+```
+dimensions:%dimensions
+d:%dimensions
+```
 
-* `format`: source image/video format. In case of video - list of predicted formats divided by comma
-* `width`: image/video width
-* `height`: image/video height
-* `size`: file size. Can be zero if the image source doesn't set `Content-Length` header properly
-* `exif`: Exif data
-* `iptc`: IPTC data
-* `xmp`: XMP data
-* `photoshop`: Photoshop metadata (currently, only the resolution data)
-* `video_streams`: info about the video streams (maximum 20 streams)
-* `video_meta`: metadata from the video
+When set to `1`, `t`, or `true`, imgproxy will return the image dimensions.
 
-**📝 Note:** There are lots of IPTC tags in the spec, but imgproxy supports only a few of them. If you need some tags to be supported, just contact us.
+Default: `true`.
 
-#### Example (JPEG)
+**Response example:**
 
 ```json
 {
-  "format": "jpeg",
   "width": 7360,
-  "height": 4912,
-  "size": 28993664,
+  "height": 4912
+}
+```
+
+### EXIF
+
+```
+exif:%exif
+```
+
+When set to `1`, `t`, or `true`, imgproxy will return the image's EXIF metadata.
+
+Default: `true`.
+
+**Response example:**
+
+```json
+{
   "exif": {
     "Aperture": "8.00 EV (f/16.0)",
     "Contrast": "Normal",
     "Date and Time": "2016:09:11 22:15:03",
     "Model": "NIKON D810",
     "Software": "Adobe Photoshop Lightroom 6.1 (Windows)"
-  },
+  }
+}
+```
+
+### IPTC
+
+```
+iptc:%iptc
+```
+
+When set to `1`, `t`, or `true`, imgproxy will return the image's IPTC (IPTC-IIM) metadata and Photoshop metadata (currently, only the resolution data).
+
+Default: `true`.
+
+**Response example:**
+
+```json
+{
   "iptc": {
     "Name": "Spider-Man",
     "Caption": "Spider-Man swings on the web",
     "Copyright Notice": "Daily Bugle",
     "Keywords": ["spider-man", "menance", "offender"]
   },
+  "photoshop": {
+    "resolution": {
+      "XResolution": 240,
+      "XResolutionUnit": "inches",
+      "WidthUnit": "inches",
+      "YResolution": 240,
+      "YResolutionUnit": "inches",
+      "HeightUnit": "inches"
+    }
+  }
+}
+```
+
+### XMP
+
+```
+xmp:%xmp
+```
+
+When set to `1`, `t`, or `true`, imgproxy will return the image's XMP metadata.
+
+Default: `true`.
+
+**Response example:**
+
+```json
+{
   "xmp": {
     "aux": {
       "ApproximateFocusDistance": "4294967295/1",
@@ -100,29 +174,34 @@ imgproxy responses with a JSON body and returns the following info:
     "photoshop": {
       "DateCreated": "2016-09-11T18:44:50.003"
     }
-  },
-  "photoshop": {
-    "resolution": {
-      "XResolution": 240,
-      "XResolutionUnit": "inches",
-      "WidthUnit": "inches",
-      "YResolution": 240,
-      "YResolutionUnit": "inches",
-      "HeightUnit": "inches"
-    }
   }
 }
 ```
 
-#### Example (mp4)
+### Video meta
+
+```
+video_meta:%video_meta
+vm:%video_meta
+```
+
+When set to `1`, `t`, or `true`, imgproxy will return the video metadata and video streams info.
+
+Default: `true`.
+
+**Response example:**
 
 ```json
 {
-  "format": "mov,mp4,m4a,3gp,3g2,mj2",
-  "width": 1178,
-  "height": 730,
-  "size": 984963,
-  "exif": {},
+  "video_meta": {
+    "com.android.version": "9",
+    "compatible_brands": "isommp42",
+    "creation_time": "2022-01-12T15:04:10.000000Z",
+    "location": "+46.4845+030.6848/",
+    "location-eng": "+46.4845+030.6848/",
+    "major_brand": "mp42",
+    "minor_version": "0"
+  },
   "video_streams": [
     {
       "type": "video",
@@ -144,15 +223,282 @@ imgproxy responses with a JSON body and returns the following info:
       "codec": "subrip",
       "language": "eng"
     }
-  ],
-  "video_meta": {
-    "com.android.version": "9",
-    "compatible_brands": "isommp42",
-    "creation_time": "2022-01-12T15:04:10.000000Z",
-    "location": "+46.4845+030.6848/",
-    "location-eng": "+46.4845+030.6848/",
-    "major_brand": "mp42",
-    "minor_version": "0"
+  ]
+}
+```
+
+### Detect objects
+
+**⏳ Slow:** This option requires the image to be fully downloaded and processed.
+
+```
+detect_objects:%detect_objects
+do:%detect_objects
+```
+
+When set to `1`, `t`, or `true`, imgproxy will return the info about the objects found in the image. Read the [object detection](object_detection.md) manual to learn how to configure object detection.
+
+**📝 Note:** imgproxy returns the relative coordinates of the found objects.
+
+Default: `false`.
+
+**Response example:**
+
+```json
+{
+  "objects": [
+    {
+      "class_id": 0,
+      "class_name": "face",
+      "confidence": 0.985792,
+      "left": 0.6602726057171822,
+      "top": 0.23434072732925415,
+      "width": 0.11385439336299896,
+      "height": 0.18671900033950806
+    },
+    {
+      "class_id": 0,
+      "class_name": "face",
+      "confidence": 0.9810329,
+      "left": 0.4354642778635025,
+      "top": 0.3503067269921303,
+      "width": 0.10691609978675842,
+      "height": 0.18357203900814056
+    }
+  ]
+}
+```
+
+### Crop coordinates :id=crop
+
+**⏳ Slow:** This option requires the image to be fully downloaded and processed.
+
+```
+crop:%width:%height:%gravity
+c:%width:%height:%gravity
+```
+
+When `width` and `height` are greater than zero, imgproxy will return the _relative_ crop coordinates for the defined crop parameters.
+
+This option takes the same arguments as the [crop](generating_the_url.md#crop) processiong option.
+
+Default: `0:0:ce`.
+
+**Response example:**
+
+```json
+{
+  "crop": {
+    "left": 0.383203125,
+    "top": 0.2603861907548274,
+    "width": 0.1953125,
+    "height": 0.3510825043885313
   }
 }
 ```
+
+### Palette
+
+**⏳ Slow:** This option requires the image to be fully downloaded and processed.
+
+```
+palette:%colors
+p:%colors
+```
+
+When `colors` is greater than zero, imgproxy will build and return the image's RGBA palette containing maximum `colors` colors.
+
+**📝 Note:** When `colors` is greater than zero, its value should be between `2` and `256`.
+
+Default: `0`.
+
+**Response example:**
+
+```json
+{
+  "palette": [
+    { "R": 189, "G": 178, "B": 169, "A": 255 },
+    { "R": 83, "G": 79, "B": 67, "A": 255 }
+  ]
+}
+```
+
+### Average color :id=average
+
+**⏳ Slow:** This option requires the image to be fully downloaded and processed.
+
+```
+average:%average:%ignore_transparent
+avg:%average:%ignore_transparent
+```
+
+* `average` – when set to `1`, `t`, or `true`, imgproxy will calculate and return the image's average color. Default: `false`
+* `ignore_transparent` – _(optional)_ when set to `1`, `t`, or `true`, imgproxy will ignore fully transparent pixels. Default: `true`
+
+Default: `false:true`
+
+**Response example:**
+
+```json
+{
+  "average": { "R": 139, "G": 132, "B": 121, "A": 255 }
+}
+```
+
+### Dominant colors
+
+**⏳ Slow:** This option requires the image to be fully downloaded and processed.
+
+```
+dominant_colors:%dominant_colors:%build_missed
+dc:%dominant_colors:%build_missed
+```
+
+* `dominant_colors` – when set to `1`, `t`, or `true`, imgproxy will calculate and return the image's dominant colors (vibrant, light vibrant, dark vibrant, muted, light muted, and dark muted). Default: `false`
+* `build_missed` – _(optional)_ when set to `1`, `t`, or `true`, imgproxy will build colors that were not found in the image based on the found ones. Default: `false`
+
+Default: `false:false`
+
+**Response example:**
+
+```json
+{
+  "dominant_colors": {
+    "dark_muted": { "R": 75, "G": 70, "B": 57 },
+    "dark_vibrant": { "R": 90, "G": 78, "B": 43 },
+    "light_muted": { "R": 167, "G": 156, "B": 130 },
+    "light_vibrant": { "R": 212, "G": 198, "B": 165 },
+    "muted": { "R": 155, "G": 146, "B": 120 },
+    "vibrant": { "R": 172, "G": 146, "B": 83 }
+  }
+}
+```
+
+### BlurHash
+
+**⏳ Slow:** This option requires the image to be fully downloaded and processed.
+
+```
+blurhash:%x_components:%y_components
+bh:%x_components:%y_components
+```
+
+When `x_components` and `y_components` are greater than zero, imgproxy will calculate and return the image's [BlurHash](https://blurha.sh/). `x_components` and `y_components` is the numbers of horizontal and vertical components of BlurHash. The larger the numbers the more "detailed" will be the BlurHash.
+
+The maximum value for `x_components` and `y_components` is `9`.
+
+Default: `0:0`
+
+**Response example:**
+
+```json
+{
+  "blurhash": "LLH-}fox0fRQ%Do}9as9_3%2M{S2"
+}
+```
+
+### Page
+
+```
+page:%page
+pg:%page
+```
+
+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.
+
+Default: 0
+
+### Video thumbnail second
+
+```
+video_thumbnail_second:%second
+vts:%second
+```
+
+Allows redefining `IMGPROXY_VIDEO_THUMBNAIL_SECOND` config.
+
+### Cache buster
+
+```
+cachebuster:%string
+cb:%string
+```
+
+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
+
+### Expires
+
+```
+expires:%timestamp
+exp:%timestamp
+```
+
+When set, imgproxy will check the provided unix timestamp and return 404 when expired.
+
+Default: empty
+
+### Preset
+
+```
+preset:%preset_name1:%preset_name2:...:%preset_nameN
+pr:%preset_name1:%preset_name2:...:%preset_nameN
+```
+
+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 [Presets](presets.md) guide.
+
+Default: empty
+
+### Max src resolution
+
+```
+max_src_resolution:%resolution
+msr:%resolution
+```
+
+Allows 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`.
+
+### Max src file size
+
+```
+max_src_file_size:%size
+msfs:%size
+```
+
+Allows redefining `IMGPROXY_MAX_SRC_FILE_SIZE` 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`.
+
+## Source URL
+### Plain
+
+The source URL can be provided as is, prepended by `/plain/` part:
+
+```
+/plain/http://example.com/images/curiosity.jpg
+```
+
+**📝 Note:** If the source URL contains a query string or `@`, you'll need to escape it.
+
+### Base64 encoded
+
+The source URL can be encoded with URL-safe Base64. The encoded URL can be split with `/` as desired:
+
+```
+/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn
+```
+
+### Encrypted with AES-CBC![pro](./assets/pro.svg) :id=encrypted-with-aes-cbc
+
+The source URL can be encrypted with the AES-CBC algorithm, prepended by the `/enc/` segment. The encrypted URL can be split with `/` as desired:
+
+```
+/enc/jwV3wUD9r4VBIzgv/ang3Hbh0vPpcm5cc/VO5rHxzonpvZjppG/2VhDnX2aariBYegH/jlhw_-dqjXDMm4af/ZDU6y5sBog
+```

docs/index.html

@@ -54,6 +54,7 @@
   <script src="//unpkg.com/docsify-namespaced@0.1.1/dist/docsify-namespaced.min.js"></script>
   <script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
 
   <script src="/assets/docsify-init.js"></script>
 

docs/object_detection.md

@@ -1,6 +1,6 @@
 # Object detection![pro](./assets/pro.svg)
 
-imgproxy can detect objects on the image and use them for smart cropping, bluring the detections, or drawing the detections.
+imgproxy can detect objects on the image and use them for smart cropping, bluring the detections, or drawing the detections. You can also [fetch the detected objects info](getting_the_image_info.md#detect-objects).
 
 For object detection purposes, imgproxy uses the [Darknet YOLO](https://github.com/AlexeyAB/darknet) model. We provide Docker images with a model trained for face detection, but you can use any Darknet YOLO model found in the [zoo](https://github.com/AlexeyAB/darknet/wiki/YOLOv4-model-zoo) or you can train your own model by following this [guide](https://github.com/AlexeyAB/darknet#how-to-train-to-detect-your-custom-objects).
 
@@ -39,3 +39,11 @@ You can make imgproxy [draw bounding boxes](https://docs.imgproxy.net/generating
 ```
 .../draw_detections:1:face/...
 ```
+
+### Fetch the detected objects info
+
+You can [fetch the detected objects info](getting_the_image_info.md#detect-objects) using the `/info` endpoint:
+
+```
+.../info/detect_objects:1/...
+```

docs/presets.md

@@ -1,22 +1,22 @@
 # Presets
 
-An imgproxy preset is a named set of processing options. Presets can be used in [URLs](generating_the_url.md#preset) to make shorter and more human-readable.
+An imgproxy preset is a named set of processing or info options. Presets can be used in [processing URLs](generating_the_url.md#preset) or [info URLs](getting_the_image_info.md#preset) to make them shorter and more human-readable.
 
 ## Presets definition
 
 A preset definition looks like this:
 
 ```
-%preset_name=%processing_options
+%preset_name=%options
 ```
 
-Processing options should be defined in the same way they are defined in [URLs](generating_the_url.md#processing-options). For example, here's a preset named `awesome` that sets the resizing type to `fill` and the resulting format to `jpg`:
+Options should be defined in the same way they are defined in [processing URLs](generating_the_url.md#processing-options) and [info URLs](getting_the_image_info.md#processing-options). For example, here's a preset named `awesome` that sets the resizing type to `fill` and the resulting format to `jpg`:
 
 ```
 awesome=resizing_type:fill/format:jpg
 ```
 
-Read how to specify your presets with imgproxy in the [Configuration](configuration.md) guide.
+Read how to specify your presets with imgproxy in the [Configuration](configuration.md#presets) guide.
 
 ## Default preset
 
@@ -24,10 +24,10 @@ A preset named `default` will be applied to each image. This is useful when you
 
 ## Only presets
 
-Setting `IMGPROXY_ONLY_PRESETS` to `true` switches imgproxy into "presets-only mode". In this mode, imgproxy accepts a presets list as processing options just like you'd specify them for the `preset` option:
+Setting `IMGPROXY_ONLY_PRESETS` to `true` switches imgproxy into presets-only mode. In this mode, imgproxy accepts a presets list as processing options just like you'd specify them for the `preset` option:
 
 ```
 http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png
 ```
 
-All other URL formats are disabled in this mode.
+You can enable or disable the presets-only mode for the [info](getting_the_image_info.md) endpoint using the `IMGPROXY_INFO_ONLY_PRESETS` config. If `IMGPROXY_INFO_ONLY_PRESETS` is not set, the info endpoint respects the `IMGPROXY_ONLY_PRESETS` value.