IMGPROXY_ENFORCE_THUMBNAIL config & enforce_thumbnail option

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [Unreleased]
 ### Add
 - Add support of RLE-encoded BMP.
+- Add `IMGPROXY_ENFORCE_THUMBNAIL` config and [enforce_thumbnail](https://docs.imgproxy.net/generating_the_url?id=enforce-thumbnail) processing option.
 
 ### Change
 - Use thumbnail embedded to HEIC/AVIF if its size is larger than or equal to the requested.

config/config.go

@@ -49,6 +49,7 @@ var (
 	StripMetadata         bool
 	StripColorProfile     bool
 	AutoRotate            bool
+	EnforceThumbnail      bool
 
 	EnableWebpDetection bool
 	EnforceWebp         bool
@@ -204,6 +205,7 @@ func Reset() {
 	StripMetadata = true
 	StripColorProfile = true
 	AutoRotate = true
+	EnforceThumbnail = false
 
 	EnableWebpDetection = false
 	EnforceWebp = false
@@ -350,6 +352,7 @@ func Configure() error {
 	configurators.Bool(&StripMetadata, "IMGPROXY_STRIP_METADATA")
 	configurators.Bool(&StripColorProfile, "IMGPROXY_STRIP_COLOR_PROFILE")
 	configurators.Bool(&AutoRotate, "IMGPROXY_AUTO_ROTATE")
+	configurators.Bool(&EnforceThumbnail, "IMGPROXY_ENFORCE_THUMBNAIL")
 
 	configurators.Bool(&EnableWebpDetection, "IMGPROXY_ENABLE_WEBP_DETECTION")
 	configurators.Bool(&EnforceWebp, "IMGPROXY_ENFORCE_WEBP")

docs/configuration.md

@@ -417,5 +417,6 @@ imgproxy can send logs to syslog, but this feature is disabled by default. To en
 * `IMGPROXY_STRIP_METADATA`: when `true`, imgproxy will strip all metadata (EXIF, IPTC, etc.) from JPEG and WebP output images. Default: `true`
 * `IMGPROXY_STRIP_COLOR_PROFILE`: when `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. Default: `true`
 * `IMGPROXY_AUTO_ROTATE`: when `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. Default: `true`
+* `IMGPROXY_ENFORCE_THUMBNAIL`: when `true` and the source image has an embedded thumbnail, imgproxy will always use the embedded thumbnail instead on the main image. Currently, only thumbnails embedded in `heic` and `avif` are supported. Default: `false`
 * `IMGPROXY_HEALTH_CHECK_MESSAGE`: <i class='badge badge-pro'></i> the content of the health check response. Default: `imgproxy is running`
 * `IMGPROXY_HEALTH_CHECK_PATH`: an additional path of the health check. Default: blank

docs/generating_the_url.md

@@ -511,6 +511,15 @@ scp:%strip_color_profile
 
 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 [IMGPROXY_STRIP_COLOR_PROFILE](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
 
+### Enforce thumbnail
+
+```
+enforce_thumbnail:%enforce_thumbnail
+eth:%enforce_thumbnail
+```
+
+When set to `1`, `t` or `true` and the source image has an embedded thumbnail, imgproxy will always use the embedded thumbnail instead on the main image. Currently, only thumbnails embedded in `heic` and `avif` are supported. This is normally controlled by the [IMGPROXY_ENFORCE_THUMBNAIL](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
+
 ### Quality
 
 ```

options/processing_options.go

@@ -87,6 +87,7 @@ type ProcessingOptions struct {
 	StripMetadata     bool
 	StripColorProfile bool
 	AutoRotate        bool
+	EnforceThumbnail  bool
 
 	SkipProcessingFormats []imagetype.Type
 
@@ -136,6 +137,7 @@ func NewProcessingOptions() *ProcessingOptions {
 			StripMetadata:     config.StripMetadata,
 			StripColorProfile: config.StripColorProfile,
 			AutoRotate:        config.AutoRotate,
+			EnforceThumbnail:  config.EnforceThumbnail,
 
 			// Basically, we need this to update ETag when `IMGPROXY_QUALITY` is changed
 			defaultQuality: config.Quality,
@@ -835,6 +837,16 @@ func applyAutoRotateOption(po *ProcessingOptions, args []string) error {
 	return nil
 }
 
+func applyEnforceThumbnailOption(po *ProcessingOptions, args []string) error {
+	if len(args) > 1 {
+		return fmt.Errorf("Invalid enforce thumbnail arguments: %v", args)
+	}
+
+	po.EnforceThumbnail = parseBoolOption(args[0])
+
+	return nil
+}
+
 func applyURLOption(po *ProcessingOptions, name string, args []string) error {
 	switch name {
 	case "resize", "rs":
@@ -885,6 +897,8 @@ func applyURLOption(po *ProcessingOptions, name string, args []string) error {
 		return applyStripMetadataOption(po, args)
 	case "strip_color_profile", "scp":
 		return applyStripColorProfileOption(po, args)
+	case "enforce_thumbnail", "eth":
+		return applyEnforceThumbnailOption(po, args)
 	// Saving options
 	case "quality", "q":
 		return applyQualityOption(po, args)

processing/processing.go

@@ -239,9 +239,15 @@ func ProcessImage(ctx context.Context, imgdata *imagedata.ImageData, po *options
 	img := new(vips.Image)
 	defer img.Clear()
 
+	if po.EnforceThumbnail && imgdata.Type.SupportsThumbnail() {
+		if err := img.LoadThumbnail(imgdata); err != nil {
+			return nil, err
+		}
+	} else {
 		if err := img.Load(imgdata, 1, 1.0, pages); err != nil {
 			return nil, err
 		}
+	}
 
 	originWidth, originHeight := getImageSize(img)