Add "letterbox" image transform mode

[piotrpog]

Letterbox is a transform mode used in imager/imager-x plugin. It adds an empty area to top and bottom or left and right area of an image in order to fit it into specific dimensions.

Personally, I find it extremely useful, especially for things like product listings where each image needs to have same dimensions and images should not be cropped.

[brandonkelly]

Hm, this seems like it would be better handled with CSS that adds a background color to the image container or something, rather than adding additional pointless image data. I’ll leave it open though.

[CMeldgaard]

I dont think that the background color is the important thing with letterbox mode. I think the important part is that you can generete a grid of images, for instance for a webshop, where all images are the same dimensions.

[brandonkelly]

I think the important part is that you can generete a grid of images, for instance for a webshop, where all images are the same dimensions.

You could do that with either flexbox or grid these days.

[CMeldgaard]

Perhaps im missing something, but how would you maintain the same aspectratio of the image container ? for instance on a product grid, how would you make sure that the "image div" inside the "product div" has the same aspectratio across the entire grid with images thats not the aspectratio (because we can't crop the images).

[brandonkelly]

Let’s say you want each thumbnail to fit within a 300 x 200 container…

<div class="thumb-container">
  {{ asset.getImg({width: 300, height: 200, mode: 'fit'}, ['1x', '2x']) }}
</div>

And then in your CSS, using object-fit:

.thumb-container {
  width: 300px;
  height: 200px;
}
.thumb-container img {
  object-fit: contain;
}

Or using flexbox:

.thumb-container {
  display: flex;
  width: 300px;
  height: 200px;
  justify-content: center;
  align-items: center;
}

[piotrpog]

@brandonkelly
Please note that craft might generate html that might not be used in the browser, but in enviroment that does not support flexbox, like some email clients.

[brandonkelly]

@piotrpog That is a valid point!

[brandonkelly]

We’ve just added a new “Letterbox” transform mode for Craft 4.4 🎉 (via #12214)

Unlike Fill transforms, Letterbox transforms will always generate images with the exact width and height specified by the transform. The surrounding pixels can either be transparent or a certain color fill.

You can define Letterbox transforms in your templates by setting mode to 'letterbox':

{% do asset.setTransform({
  mode: 'letterbox',
  width: 200,
  height: 200,
  position: 'top-center',
  fill: '#000000',
}) %}

We’ve also added a new “Allow Upscaling” setting to all transforms, which takes precedence over the upscaleImages config setting when specified. (Template-defined transforms can set this via an upscale property.)

We did that because there’s a good chance that upscaling would be desired when using Letterbox transforms (so you don’t end up with images that have padding on all sides), even if in general upscaling should be avoided.

[brandonkelly]

4.4 is out now!

[volodymyr-bihus]

Hello, we use Imager 4.0 and image mode "fit" works well with *.jpg but does not with *.png - can you please give a hint what can cause the issue?

[brandonkelly]

@volodymyr-bihus Pretty sure Imager X has its own transform system. You’ll want to bring it up over at https://github.com/spacecatninja/craft-imager-x.

[volodymyr-bihus]

Thank you for response, the issue was with the vertical images, we made separate transformation params for it.