Fill image transform setting #12214

brianjhanson · 2022-10-27T19:31:25Z

Description

Adds an additional fill parameter to image transforms.

The value of fill must be either a hex value (3 or 6 digits) or the string transparent.

When the transform mode is set to fit and a fill color is provided, the fill color will be used to fill any empty pixels surrounding the image so the final image size is always equal to the transform sized passed in.

You can also use position in order to control where within the transform space the image should appear.

Within the UI there's a new "Fill empty pixels" checkbox that will show or hide the color field for the fill.

CleanShot.2022-10-27.at.14.01.57.mp4

Related issues

#8848

To-Do

Support for animated files (gif, webp)
Make sure non-raster images don't break

linear · 2022-10-27T19:31:27Z

DEV-239 `fill` image transform setting

fill should be checked whenever there are transforms where the resulting image is going to be smaller than the specified width and height.

When using mode=fit for any image with a different aspect ration than the target dimensions
When upscaleImages is false and the resulting image is smaller than either of the target dimensions

In these cases, if fill is specified, the resulting image should be set to the same width and height as the transform’s target dimensions, with any whitespace surrounding the image filled in based on whatever fit is set to.

Possible values could be:

a hex value (possibly supporting an alpha channel for transparent PNGs)
transparent (supported for transparent PNGs; fall back to #ffffff)

This will be useful for cases where you need something that looks like fit visually, but absolutely need the image to be a certain size (e.g. HTML email, where CSS support is limited).

brianjhanson · 2022-10-27T22:11:00Z

src/controllers/ImageTransformsController.php

+        $useFill = $this->request->getBodyParam('useFill');
+        if ($useFill && $transform->mode === 'fit') {
+            $transform->fill = $transform->fill ? ColorValidator::normalizeColor($transform->fill) : 'transparent';
+        } else {
+            $transform->fill = null;
+        }
+


I'm not wild about this, but I couldn't think of a better way to allow users to specify if they wanted the current behavior (image is sized proportionately to fit within a window) or the new behavior (image is placed within an area specified by the transform).

In code, the fact that fill exists tells Craft which behavior to us, but in the UI a fill is always returned, and currently there's not a difference between no fill and a transparent one.

src/migrations/Install.php

Adds an additional `fill` parameter to image transforms. The value of `fill` must be a value that the `ColorValidator` class accepts as valid (right now that means either 3 or 6 digit hex The fill is only applied when it is valid, the mode is set to `fit` and the upscale images setting is set to `false` OR when the ratio of the transform differs from the ratio of the image itself. In that scenario, blank pixels between the size of the source image and the specified transform will be filled with the color specified (using the image’s color space or palette). Indexes in the `imagetransformindex` table will now have the fill appended to the end of the string. Generated folders will also have the fill color appended (minus the `#` character).

When applying the fill and a position is provided it will be used to place the image within the transform size specified

Allows image to be scaled down to fit a ratio not equal to its intrinsic ration, but still apply the fill.

brandonkelly · 2023-01-10T19:50:44Z

src/base/Image.php

-    abstract public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true): self;
+    abstract public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true, string $position = 'center-center'): self;


Missing @param for $position

Also if the fill stuff is exclusive to Raster, it feels weird to have $position defined here in the base class. Maybe Raster should just be defining its own scaleToFitAndFill() method that combines scaleToFit() and setFill()?

brandonkelly · 2023-01-10T19:50:56Z

src/image/Raster.php

-    public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true): self
+    public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true, array|string $position = 'center-center'): self


$position has a different type declaration here than in the base class (array|string vs string).

….com:craftcms/cms into feature/dev-239-fill-image-transform-setting

# Conflicts: # src/helpers/ImageTransforms.php # src/imagetransforms/ImageTransformer.php

brandonkelly · 2023-01-30T23:30:49Z

@brianjhanson This doesn’t seem to be working for me.

I created a transform with the following settings:

Mode: Fit
Fill empty pixels: ✅
Fill Color: #ff0000
Width: 300
Height: 200
Quality: Auto
Interlacing: None
Image Format: Auto

However when I output a 1200x394 image using this transform, the result is 300x99 without any red pixels. I would have expected it to end up as 300x200, with ~50 red pixels above and below the original image.

(upscaleImages is true.)

And separately, looks like there’s a bug when Fill Color is left blank: when you go back to the transform edit page, the input value is set to #transparent.

brandonkelly

As discussed,

Let’s introduce a new dedicated “Letterbox” transform mode for this, with “Fill Color” and “Gravity” settings. (Gravity should default to center-center.)
All transforms should get a new “Upscale” setting, and the upscaleImages config setting should be used by default.

brianjhanson · 2023-02-02T20:31:41Z

Just pushed some code to address the first half of this and wanted to jot down some notes before I forget.

Positioning

I went with "Position" instead of "Gravity" because that felt more straightforward. In Cloudinary world, Gravity is how they refer to a focal point, but we have established language for that. We could keep it as "Focal Point" here, but given how it behaves, I think "position" is a better description (and aligns with how to determine it programmatically).

I duplicated the field rather than just messing with it via JS because JS introduced some complications (translations, accessibility, etc.). It felt like just duplicating the field was better all around.

UI Update

Focal Points

If an image has a focal point set, we will do our best to put that point into the center. Some screenshots of how this behaves are below.

Focal point

Results in

…ll-image-transform-setting

Use `_ns` to denote transforms that don't allow upscaling. The abscense of `_ns` means upscaling is allowed

[ci skip]

…//github.com/craftcms/cms into feature/dev-239-fill-image-transform-setting

[ci skip]

brianjhanson marked this pull request as ready for review October 27, 2022 21:46

brianjhanson requested a review from a team as a code owner October 27, 2022 21:46

brianjhanson changed the base branch from develop to 5.0 October 27, 2022 21:46

brianjhanson requested review from benjamindavid, nfourtythree and brandonkelly as code owners October 27, 2022 21:46

brianjhanson changed the base branch from 5.0 to 4.4 October 27, 2022 21:47

brianjhanson commented Oct 27, 2022

View reviewed changes

brianjhanson added 9 commits November 23, 2022 11:56

Add support for transparent values

467c095

Support for positioning

3a67351

When applying the fill and a position is provided it will be used to place the image within the transform size specified

Adds support for fill within the UI

07d7599

Add comment

2cf7b91

Support animated gif

52df321

Fix types

62a22ce

Remove privacy

8aa9095

Resize then fill

232b30a

Allows image to be scaled down to fit a ratio not equal to its intrinsic ration, but still apply the fill.

brianjhanson force-pushed the feature/dev-239-fill-image-transform-setting branch from b81d5f8 to 232b30a Compare November 23, 2022 19:52

Merge branch '4.4' into feature/dev-239-fill-image-transform-setting

ff77b8e

brandonkelly requested changes Jan 10, 2023

View reviewed changes

brianjhanson added 3 commits January 11, 2023 14:23

Refactor scaleToFit into scaleToFitAndFill

9d7d47c

Merge branch 'feature/dev-239-fill-image-transform-setting' of github…

b250795

….com:craftcms/cms into feature/dev-239-fill-image-transform-setting

Remove $position from SVG

79ae641

brianjhanson requested a review from brandonkelly January 11, 2023 20:36

brandonkelly added 4 commits January 30, 2023 13:31

Merge branch '4.4' into feature/dev-239-fill-image-transform-setting

87c5abc

# Conflicts: # src/helpers/ImageTransforms.php # src/imagetransforms/ImageTransformer.php

Merge branch '4.4' into feature/dev-239-fill-image-transform-setting

2318b6f

Update parseTransformString() for fills

790ff68

Bump the schema version

6cf72ab

brandonkelly requested changes Feb 1, 2023

View reviewed changes

brianjhanson added 3 commits February 2, 2023 12:00

Add new letterbox transform mode

162385e

Update UI to handle new mode

29fb7ea

Cleanup UI

fffe2c1

brianjhanson and others added 17 commits February 2, 2023 15:12

Add UI for “Allow Upscaling” option

5e86abc

Add upscale setting to image transforms

32b8895

Only use focal point for crop mode

3c1aa6d

Add translation strings

d8722f3

Merge branch '4.4' of github.com:craftcms/cms into feature/dev-239-fi…

196a613

…ll-image-transform-setting

Comment cleanup

f077af3

Fix transform string parsing

f12b320

Fix tests

169212f

Flip upscale string

d0f4181

Use `_ns` to denote transforms that don't allow upscaling. The abscense of `_ns` means upscaling is allowed

Bump the schema version

adf4936

[ci skip]

Merge branch '4.4' into feature/dev-239-fill-image-transform-setting

d402ee5

Sort translations

13703ff

Cleanup

281b91f

Fix migration for Postgres

fab0774

Null fallbacks in case fill and upscale aren't set yet

62164a6

Merge branch 'feature/dev-239-fill-image-transform-setting' of https:…

855a18c

…//github.com/craftcms/cms into feature/dev-239-fill-image-transform-setting

Update existing transforms' configs

d81e156

brandonkelly merged commit bf93085 into 4.4 Feb 4, 2023

brandonkelly deleted the feature/dev-239-fill-image-transform-setting branch February 4, 2023 01:48

brandonkelly added a commit that referenced this pull request Feb 4, 2023

Release notes for #12214

2516eb4

[ci skip]

This was referenced Feb 18, 2023

Use DI for cookie config #12699

Closed

Activation validation #12712

Merged

This was referenced Mar 3, 2023

Remove “Fit” transform “Default Focal Point” option #12774

Merged

Removes is defined checks in Image Transform settings template #12775

Merged

Fix ImageTransformController type error #12776

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fill image transform setting #12214

Fill image transform setting #12214

brianjhanson commented Oct 27, 2022 •

edited

Loading

linear bot commented Oct 27, 2022

brianjhanson Oct 27, 2022

brandonkelly Jan 10, 2023

brandonkelly Jan 10, 2023

brandonkelly Jan 10, 2023

brandonkelly commented Jan 30, 2023 •

edited

Loading

brandonkelly left a comment •

edited by brianjhanson

Loading

brianjhanson commented Feb 2, 2023

		abstract public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true): self;
		abstract public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true, string $position = 'center-center'): self;

		public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true): self
		public function scaleToFit(?int $targetWidth, ?int $targetHeight, bool $scaleIfSmaller = true, array\|string $position = 'center-center'): self

Fill image transform setting #12214

Fill image transform setting #12214

Conversation

brianjhanson commented Oct 27, 2022 • edited Loading

Description

Related issues

To-Do

linear bot commented Oct 27, 2022

brianjhanson Oct 27, 2022

Choose a reason for hiding this comment

brandonkelly Jan 10, 2023

Choose a reason for hiding this comment

brandonkelly Jan 10, 2023

Choose a reason for hiding this comment

brandonkelly Jan 10, 2023

Choose a reason for hiding this comment

brandonkelly commented Jan 30, 2023 • edited Loading

brandonkelly left a comment • edited by brianjhanson Loading

Choose a reason for hiding this comment

brianjhanson commented Feb 2, 2023

Positioning

UI Update

Focal Points

brianjhanson commented Oct 27, 2022 •

edited

Loading

brandonkelly commented Jan 30, 2023 •

edited

Loading

brandonkelly left a comment •

edited by brianjhanson

Loading