Version 4-preview

Author: gzigzigzeo

docs/configuration/options.mdx

@@ -5,16 +5,34 @@ 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, drawing the detections, or cropping to detected objects. 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, or drawing the detections. 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 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 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.
 
 ## 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
@@ -318,20 +336,6 @@ 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,7 +21,6 @@ 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:                       |
 
@@ -37,6 +36,10 @@ 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:
@@ -67,12 +70,6 @@ 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.
@@ -87,22 +84,3 @@ 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:**
-
-* High bit images remain high bit in the output (eg, GRAYSCALE16 remains GRAYSCALE16, RGB16 stays RGB16, scRGB becomes RGB16)
-
-**When `IMGPROXY_PRESERVE_HDR` is disabled (default):**
-
-* High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB, RGB16 and scRGB become sRGB)
-* 8-bit images remain 8-bit

docs/image_formats_support.mdx

@@ -11,7 +11,9 @@ imgproxy can process images from S3 buckets. To use this feature, do the followi
 3. _(optional)_ Specify the [AWS region](#choosing-the-aws-region) with `IMGPROXY_S3_REGION` or `AWS_REGION`. Default: `us-west-1`
 4. _(optional)_ Specify the S3 endpoint with `IMGPROXY_S3_ENDPOINT`. You can also set `IMGPROXY_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint.
 5. _(optional)_ Set the `IMGPROXY_S3_USE_DECRYPTION_CLIENT` environment variable to `true` if your objects are client-side encrypted.
-6. Use `s3://%bucket_name/%file_key` as the source image URL.
+6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_S3_ASSUME_ROLE_ARN`.
+7. _(optional)_ Specify the External ID that needs to be passed in along with the AWS IAM Role to Assume with `IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified.
+8. Use `s3://%bucket_name/%file_key` as the source image URL.
 
 If you need to specify the version of the source object, you can use the query string of the source URL:
 
@@ -76,17 +78,6 @@ 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
-
-Restrict which S3 buckets imgproxy can access for security:
-
-* `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 allow trusted buckets. Use `IMGPROXY_S3_DENIED_BUCKETS` to block specific ones. If both are set, allowed buckets override denied ones.
-:::
-
 ## 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,14 +50,3 @@ 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
-
-Restrict which Azure Blob Storage containers imgproxy can access for security:
-
-* `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 allow trusted containers. Use `IMGPROXY_ABS_DENIED_BUCKETS` to block specific ones. If both are set, allowed containers override denied ones.
-:::

docs/image_sources/azure_blob_storage.mdx

@@ -36,14 +36,3 @@ 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
-
-Restrict which GCS buckets imgproxy can access for security:
-
-* `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 allow trusted buckets. Use `IMGPROXY_GCS_DENIED_BUCKETS` to block specific ones. If both are set, allowed buckets override denied ones.
-:::

docs/image_sources/google_cloud_storage.mdx

@@ -20,14 +20,3 @@ imgproxy can process images from OpenStack Object Storage, also known as Swift.
 :::tip
 If filenames in your OpenStack Object Storage may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction.
 :::
-
-## Restricting container access
-
-Restrict which Swift containers imgproxy can access for security:
-
-* `IMGPROXY_SWIFT_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_SWIFT_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_SWIFT_ALLOWED_BUCKETS` to allow trusted containers. Use `IMGPROXY_SWIFT_DENIED_BUCKETS` to block specific ones. If both are set, allowed containers override denied ones.
-:::

docs/image_sources/openstack_swift.mdx

@@ -23,7 +23,6 @@ imgproxy can send its metrics to Datadog. To use this feature, do the following:
     * `DD_TRACE_STARTUP_LOGS`: causes various startup info to be written when the tracer starts. Default: `true`
     * `DD_TRACE_DEBUG`: enables detailed logs. Default: `false`
 4. _(optional)_ Set the `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS` environment variable to `true` to collect the [additional metrics](#additional-metrics).
-5. _(optional)_ Set the `IMGPROXY_DATADOG_PROPAGATE_EXTERNAL` environment variable to `true` to propagate Datadog tracing headers to external requests such as image downloads. Default: `false`.
 
 imgproxy will send the following info to Datadog:
 

docs/monitoring/datadog.mdx

@@ -10,7 +10,6 @@ imgproxy can send its metrics to New Relic. To use this feature, do the followin
 2. Set the `IMGPROXY_NEW_RELIC_KEY` environment variable to the license key.
 3. _(optional)_ Set the `IMGPROXY_NEW_RELIC_APP_NAME` environment variable to be the desired application name.
 4. _(optional)_ Set the `IMGPROXY_NEW_RELIC_LABELS` environment variable to be the desired list of labels. Example: `label1=value1;label2=value2`.
-5. _(optional)_ Set the `IMGPROXY_NEW_RELIC_PROPAGATE_EXTERNAL` environment variable to `true` to propagate New Relic tracing headers to external requests such as image downloads. Default: `false`.
 
 imgproxy will send the following info to New Relic:
 
@@ -21,15 +20,15 @@ imgproxy will send the following info to New Relic:
 * Image processing time
 * Errors that occurred while downloading and processing an image
 
-Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales (all metric names are prefixed with `Custom/imgproxy/`):
+Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/):
 
-* `workers`: the configured number of imgproxy workers
-* `requests_in_progress`: the number of requests currently in progress
-* `images_in_progress`: the number of images currently in progress
-* `workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `requests_in_progress / workers * 100`
-* `buffer/size`: a summary of the download buffers sizes (in bytes)
-* `buffer/default_size`: calibrated default buffer size (in bytes)
-* `buffer/max_size`: calibrated maximum buffer size (in bytes)
-* `vips/memory`: libvips memory usage (in bytes)
-* `vips/max_memory`: libvips maximum memory usage (in bytes)
-* `vips/allocs`: the number of active vips allocations
+* `imgproxy.workers`: the configured number of imgproxy workers
+* `imgproxy.requests_in_progress`: the number of requests currently in progress
+* `imgproxy.images_in_progress`: the number of images currently in progress
+* `imgproxy.workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `imgproxy.requests_in_progress / imgproxy.workers * 100`
+* `imgproxy.buffer.size`: a summary of the download buffers sizes (in bytes)
+* `imgproxy.buffer.default_size`: calibrated default buffer size (in bytes)
+* `imgproxy.buffer.max_size`: calibrated maximum buffer size (in bytes)
+* `imgproxy.vips.memory`: libvips memory usage (in bytes)
+* `imgproxy.vips.max_memory`: libvips maximum memory usage (in bytes)
+* `imgproxy.vips.allocs`: the number of active vips allocations