Version 4.0-rc docs

Author: gzigzigzeo

docs/configuration/options.mdx

@@ -0,0 +1,117 @@
+---
+title: Cache
+description: Learn about how to configure and use imgproxy's internal cache
+---
+
+# Cache ((pro))
+
+imgproxy Pro provides an internal cache that stores processed images on disk or in cloud storage. This cache can act as both a primary cache and a secondary cache that serves as a fallback when your CDN cache misses.
+
+:::tip
+While putting a CDN in front of imgproxy is and will always be a best practice, the internal cache provides long-term storage for cases that require an additional caching layer.
+:::
+
+## Why use internal cache?
+
+The internal cache provides long-term persistent storage for processed images, unlike CDNs that typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand.
+
+The cache is protected by the same security measures as imgproxy itself, including URL signatures and processing restrictions. Importantly, URL signatures are not part of the cache key, so you can rotate keys or use multiple key/salt pairs without invalidating cached images. You maintain full control over where the cache is stored and how it integrates with your infrastructure.
+
+## Configuration
+
+You need to define the following config variables to enable the internal cache:
+
+* [`IMGPROXY_CACHE_USE`]: the cache storage adapter to use. Can be `filesystem`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift`. When blank, the cache is disabled. Default: blank
+* [`IMGPROXY_CACHE_PATH_PREFIX`]: _(optional)_ a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank
+* [`IMGPROXY_CACHE_BUCKET`]: _(optional)_ the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank
+* [`IMGPROXY_CACHE_KEY_HEADERS`]: _(optional)_ a list of HTTP request headers (comma-separated) to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank
+* [`IMGPROXY_CACHE_KEY_COOKIES`]: _(optional)_ a list of HTTP request cookies (comma-separated) to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank
+* [`IMGPROXY_CACHE_REPORT_ERRORS`]: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false`
+
+### Storage configuration
+
+The internal cache supports all the storage backends that imgproxy can read source images from: local filesystem, Amazon S3 and compatible services (Cloudflare R2, DigitalOcean Spaces, MinIO, etc.), Google Cloud Storage, Microsoft Azure Blob Storage, and OpenStack Swift.
+
+Configure the storage backend using the same configuration options as for image sources, but with the `IMGPROXY_CACHE_` prefix instead:
+
+* For filesystem cache, use [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`](../configuration/options.mdx#cache-storage-local-filesystem)
+* For S3 cache, use `IMGPROXY_CACHE_S3_*` [variables](../configuration/options.mdx#cache-storage-amazon-s3) (e.g., `IMGPROXY_CACHE_S3_REGION`, `IMGPROXY_CACHE_S3_ENDPOINT`)
+* For GCS cache, use `IMGPROXY_CACHE_GCS_*` [variables](../configuration/options.mdx#cache-storage-google-cloud-storage)
+* For Azure Blob Storage cache, use `IMGPROXY_CACHE_ABS_*` [variables](../configuration/options.mdx#cache-storage-azure-blob-storage)
+* For Swift cache, use `IMGPROXY_CACHE_SWIFT_*` [variables](../configuration/options.mdx#cache-storage-openstack-swift)
+
+See the [configuration options](../configuration/options.mdx#cache) documentation for the full list of available variables.
+
+## Examples
+
+### Filesystem cache
+
+```bash
+IMGPROXY_CACHE_USE=filesystem
+IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy
+IMGPROXY_CACHE_PATH_PREFIX=images
+```
+
+### S3 cache
+
+```bash
+IMGPROXY_CACHE_USE=s3
+IMGPROXY_CACHE_BUCKET=my-imgproxy-cache
+IMGPROXY_CACHE_S3_REGION=us-east-1
+# AWS credentials are provided via IAM role or environment variables
+```
+
+### Google Cloud Storage cache
+
+```bash
+IMGPROXY_CACHE_USE=gcs
+IMGPROXY_CACHE_BUCKET=my-imgproxy-cache
+IMGPROXY_CACHE_GCS_KEY=/path/to/credentials.json
+```
+
+### Azure Blob Storage cache
+
+```bash
+IMGPROXY_CACHE_USE=abs
+IMGPROXY_CACHE_BUCKET=imgproxy-cache
+IMGPROXY_CACHE_ABS_NAME=mystorageaccount
+IMGPROXY_CACHE_ABS_KEY=your_account_key
+```
+
+## Cache key
+
+The cache key is generated based on:
+
+* Source image URL
+* Processing options
+* Output format
+* Optional: Request headers specified in `IMGPROXY_CACHE_KEY_HEADERS`
+* Optional: Request cookies specified in `IMGPROXY_CACHE_KEY_COOKIES`
+
+URL signature is **not** a part of the cache key, which allows key rotation without invalidating the cache.
+
+## Limitations
+
+* **No manual cache invalidation**: Currently, imgproxy doesn't provide built-in means to invalidate the cache. However, imgproxy includes the [cachebuster](../usage/processing.mdx#cache-buster) in the cache key, so you can use it to force cache invalidation when needed. Most storage offerings also support object expiration, so you can set a reasonable expiration time for cached images.
+* **No cache for info requests**: The internal cache is currently only used for image processing requests. Requests to the `/info` endpoint are not cached.
+
+## How it works
+
+When a request comes in:
+
+1. imgproxy checks the URL signature (if enabled)
+2. imgproxy generates the cache key from the request parameters
+3. imgproxy checks if a cached image exists in the configured storage
+4. If the cached image exists and is valid, imgproxy serves it directly
+5. If not, imgproxy processes the image and stores the result in the cache before serving it
+
+## Monitoring
+
+Monitor cache performance with metrics:
+
+* Cache hit rate
+* Cache size
+* Cache evictions
+* Cache latency
+
+These metrics are available through [monitoring endpoints](../monitoring/prometheus.mdx).

docs/features/cache.mdx

@@ -0,0 +1,69 @@
+---
+title: Object classification
+description: Learn about how to classify objects in your images with imgproxy
+---
+
+# Object classification ((pro))
+
+imgproxy Pro can classify objects detected in images, providing detailed information about what the objects are. This feature extends [object detection](object_detection.mdx) by not only detecting objects but also identifying their specific classes or categories.
+
+:::info
+Object classification requires [object detection](object_detection.mdx) to be configured and enabled. Classification is performed on the objects detected by the object detection model.
+:::
+
+You can use object classification for content moderation, image organization, and automatic tagging. You can [fetch the classified objects info](../usage/getting_info.mdx#classify-objects) via the info handler.
+
+## Configuration
+
+:::tip
+If you're using an imgproxy Pro Docker image with a tag suffixed with `-ml`, a basic classification model is included. For advanced classification, you may want to configure your own model.
+:::
+
+You need to define the following config variables to enable object classification:
+
+* [`IMGPROXY_OBJECT_CLASSIFY_NET`]: a path to the classification neural network model in ONNX format
+* [`IMGPROXY_OBJECT_CLASSIFY_CLASSES`]: a path to the [class names file](#class-names-file)
+* [`IMGPROXY_OBJECT_CLASSIFY_NET_SIZE`]: the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224
+* [`IMGPROXY_OBJECT_CLASSIFY_THRESHOLD`]: classifications with confidence below this value will be discarded. Default: 0.5
+* [`IMGPROXY_OBJECT_CLASSIFY_NORMALIZATION`]: the normalization type to apply to the input image. Possible values:
+  * `none`: no normalization
+  * `half`: normalize to [-0.5, 0.5] range
+  * `full`: normalize to [-1, 1] range
+  * `imagenet`: normalize using ImageNet mean and standard deviation
+
+  Default: `none`
+* [`IMGPROXY_OBJECT_CLASSIFY_LAYOUT`]: the data layout of the neural network input. Possible values:
+  * `nchw`: channels first (default)
+  * `nhwc`: channels last
+
+  Default: `nchw`
+
+### Class names file
+
+The class names file is used to map the class indexes from the neural network output to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_OBJECT_CLASSIFY_CLASSES` config variable.
+
+The class names file should contain one class name per line. The class names should be in the same order as the classes in the neural network output. Example:
+
+```text
+person
+bicycle
+car
+```
+
+## Getting classification info
+
+Object classification is available via the info handler using the `co` (classify objects) endpoint. Fetch classification results by specifying the number of top classes to return:
+
+```imgproxy_url
+.../info/co:5/...
+```
+
+Where `5` is the number of top classes to return.
+
+The response is an array of objects, each containing:
+
+* `class_id`: The numeric ID of the class
+* `name`: The class name from the class names file
+* `confidence`: The confidence score for this classification
+
+See [getting info documentation](../usage/getting_info.mdx#classify-objects) for more details.

docs/features/object_classification.mdx

@@ -5,34 +5,16 @@ description: Learn about how to detect objects in your images and use them with
 
 # Object detection ((pro))
 
-imgproxy can detect objects in the image and use them for smart cropping, blurring the detections, or drawing the detections. You can also [fetch the detected objects info](../usage/getting_info.mdx#detect-objects).
+imgproxy can detect objects in the image and use them for smart cropping, blurring the detections, drawing the detections, or cropping to detected objects. You can also [fetch the detected objects info](../usage/getting_info.mdx#detect-objects).
 
-For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. imgproxy supports models in DarkNet or ONNX format. We provide Docker images with a model trained for face detection, but you can use any YOLO model found on the internet or train your own model.
+For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. imgproxy supports models in ONNX format. We provide Docker images with a model trained for face detection, but you can use any YOLO model found on the internet or train your own model.
 
 ## Configuration
 
 :::tip
 You don't need to configure object detection if you're using an imgproxy Pro Docker image with a tag suffixed with `-ml` and you want to use the face detection model. The model is already included in the image and the configuration is already set up.
 :::
 
-:::info
-DarkNet model format has priority over ONNX model format. If you define both, imgproxy will use the DarkNet model.
-:::
-
-### DarkNet model format
-
-:::warning
-DarkNet models support is deprecated and will be removed in imgproxy v4. Please use ONNX models instead.
-:::
-
-You need to define the following config variables to enable object detection with a [DarkNet](https://github.com/AlexeyAB/darknet) model:
-
-* [`IMGPROXY_OBJECT_DETECTION_CONFIG`]: a path to the neural network config in DarkNet format
-* [`IMGPROXY_OBJECT_DETECTION_WEIGHTS`]: a path to the neural network weights in DarkNet format
-* [`IMGPROXY_OBJECT_DETECTION_CLASSES`]: a path to the [class names file](#class-names-file)
-
-### ONNX model format
-
 You need to define the following config variables to enable object detection with an ONNX model:
 
 * [`IMGPROXY_OBJECT_DETECTION_NET`]: a path to the neural network model in ONNX format
@@ -336,6 +318,20 @@ You can make imgproxy [draw bounding boxes](../usage/processing.mdx#draw-detecti
 .../draw_detections:1:face/...
 ```
 
+### Crop to detected objects
+
+You can make imgproxy [crop the image](../usage/processing.mdx#crop-objects) to fit all detected objects of the desired classes:
+
+```imgproxy_url
+.../crop_objects:1.2:face:person/...
+```
+
+This will automatically crop the image to include all detected faces and persons with 20% padding around them. You can omit class names to crop to all detected objects:
+
+```imgproxy_url
+.../co:1.0/...
+```
+
 ### Fetch the detected objects' info
 
 You can [fetch the detected objects info](../usage/getting_info.mdx#detect-objects) using the `/info` endpoint:

docs/features/object_detection.mdx

@@ -21,6 +21,7 @@ At the moment, imgproxy supports only the most popular image formats:
 | TIFF                        | `tiff`    | :white_check_mark:             | :white_check_mark:        |
 | PDF ((pro))                 | `pdf`     | :white_check_mark:             | [See notes](#pdf-support) |
 | PSD ((pro))                 | `psd`     | [See notes](#psd-support)      | :x:                       |
+| RAW ((pro))                 |           | [See notes](#raw-support)      | :x:                       |
 | MP4 (h264) ((pro))          | `mp4`     | [See notes](#video-thumbnails) | :white_check_mark:        |
 | Other video formats ((pro)) |           | [See notes](#video-thumbnails) | :x:                       |
 
@@ -36,10 +37,6 @@ imgproxy supports SVG sources without limitations, but SVG results are not suppo
 
 When the source image is SVG and an SVG result is requested, imgproxy returns the source image without modifications.
 
-imgproxy reads some amount of bytes to check if the source image is SVG. By default it reads a maximum of 32KB, but you can change this:
-
-* `IMGPROXY_MAX_SVG_CHECK_BYTES`: the maximum number of bytes imgproxy will read to recognize SVG. If imgproxy can't recognize your SVG, try to increase this number. Default: `32768` (32KB)
-
 ## Animated images support
 
 Since the processing of animated images is a pretty heavy process, only one frame is processed by default. You can increase the maximum of animation frames to process with the following variable:
@@ -70,6 +67,12 @@ We tested imgproxy with all variants of PSD/PSB files that we could find or prod
 We couldn't find any PSD/PSB files with their image data compressed with ZIP, so imgproxy renders them as solid white images. If you had such files, we would very much appreciate it if you could share them with us.
 :::
 
+## RAW support ((pro)) {#raw-support}
+
+RAW image formats from digital cameras are supported as source images only (read-only). RAW files are decoded and converted to standard image formats during processing.
+
+imgproxy uses [libraw](https://www.libraw.org/) to process RAW files. For a complete list of supported camera models and RAW formats, see the [libraw supported cameras list](https://www.libraw.org/supported-cameras).
+
 ## Converting animated images to MP4 ((pro)) {#converting-animated-images-to-mp4}
 
 Animated image results can be converted to MP4 by specifying the `mp4` extension.
@@ -84,3 +87,22 @@ Since this still requires more data to be downloaded, video thumbnail generation
 
 * `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`: when true, enables video thumbnail generation. Default: `false`
 * `IMGPROXY_VIDEO_THUMBNAIL_SECOND`: the timestamp of the frame (in seconds) that will be used for the thumbnail. Default: `1`.
+
+## Colorspace and HDR preservation
+
+imgproxy always preserves the source image's colorspace:
+
+* Color images remain color images
+* Grayscale images remain grayscale images
+* Colorspace types are maintained
+
+The bit depth handling depends on the [IMGPROXY_PRESERVE_HDR](configuration/options.mdx#IMGPROXY_PRESERVE_HDR) configuration setting:
+
+**When `IMGPROXY_PRESERVE_HDR` is enabled:**
+
+* 16-bit images remain 16-bit in the output (eg. GRAYSCALE16 remains GRAYSCALE16, scRGB remains scRGB)
+
+**When `IMGPROXY_PRESERVE_HDR` is disabled (default):**
+
+* 16-bit images are converted to 8-bit (eg. GRAYSCALE16 becomes GRAYSCALE8, RGB and scRGB become sRGB)
+* 8-bit images remain 8-bit

docs/image_formats_support.mdx

@@ -78,6 +78,17 @@ This allows imgproxy to access buckets in any region. However, the initial reque
 * If your most frequently used buckets are in the same region, set the region to that one.
 * If your buckets are spread across multiple regions, set the region to the closest one to your imgproxy instance.
 
+## Restricting bucket access
+
+For security purposes, you can restrict which S3 buckets imgproxy is allowed to access:
+
+* `IMGPROXY_S3_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed)
+* `IMGPROXY_S3_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank
+
+:::tip
+Use `IMGPROXY_S3_ALLOWED_BUCKETS` to create an allowlist of trusted buckets, or use `IMGPROXY_S3_DENIED_BUCKETS` to block specific buckets. If both are set, allowed buckets take precedence.
+:::
+
 ## MinIO
 
 [MinIO](https://github.com/minio/minio) is an object storage server released under Apache License v2.0. It is compatible with Amazon S3, so it can be used with imgproxy.

docs/image_sources/amazon_s3.mdx

@@ -50,3 +50,14 @@ For certificate authentication:
 ### Using Storage Account Key
 
 Alternatively, you can set `IMGPROXY_ABS_KEY` to your Azure Blob Storage account key. See the [Manage storage account access keys](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage) guide for more info.
+
+## Restricting container access
+
+For security purposes, you can restrict which Azure Blob Storage containers imgproxy is allowed to access:
+
+* `IMGPROXY_ABS_ALLOWED_BUCKETS`: a comma-separated list of container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed)
+* `IMGPROXY_ABS_DENIED_BUCKETS`: a comma-separated list of container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank
+
+:::tip
+Use `IMGPROXY_ABS_ALLOWED_BUCKETS` to create an allowlist of trusted containers, or use `IMGPROXY_ABS_DENIED_BUCKETS` to block specific containers. If both are set, allowed containers take precedence.
+:::

docs/image_sources/azure_blob_storage.mdx

@@ -36,3 +36,14 @@ Otherwise, set `IMGPROXY_GCS_KEY` environment variable to the content of Google
 :::warning
 For security reasons, imgproxy accepts only service account keys for Google Cloud Storage integration.
 :::
+
+## Restricting bucket access
+
+For security purposes, you can restrict which GCS buckets imgproxy is allowed to access:
+
+* `IMGPROXY_GCS_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed)
+* `IMGPROXY_GCS_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank
+
+:::tip
+Use `IMGPROXY_GCS_ALLOWED_BUCKETS` to create an allowlist of trusted buckets, or use `IMGPROXY_GCS_DENIED_BUCKETS` to block specific buckets. If both are set, allowed buckets take precedence.
+:::