To letterbox an image, resize it proportionally until it fits inside the target rectangle, then center it on a canvas of the required size. Directly resizing a square image to a wide rectangle stretches it; cropping to fill removes content. Letterboxing preserves the full composition and adds padding.
This Python example returns both the finished image and the exact placement rectangle, so the layout can be tested. It uses a real generated image fixture and does not require a generation API.
Start with a full source
The fixture is the public floating-sneaker example from the GPT Image 2 prompt workspace. Its source prompt describes a floating packshot above a peach gradient. It is a 1024 × 1024 PNG. The displayed lettering is generated image content, not proof of a real product or brand relationship.
Define the output contract
Return a 640 × 360 RGB canvas. Preserve the source aspect ratio, keep all source content, center the result, composite transparency onto an explicit background, and do not enlarge a small image. With odd padding, the right or bottom side may have one extra pixel.
Pillow documents thumbnail as an in-place operation that preserves aspect ratio. We run it on a normalized copy. ImageOps.exif_transpose applies orientation first.
Save letterbox.py:
from PIL import Image, ImageOps
def letterbox(image, size=(640, 360), background=(24, 24, 24)):
"""Return an RGB canvas without cropping or enlarging the source."""
if len(size) != 2 or any(type(v) is not int or v <= 0 for v in size):
raise ValueError('size must contain two positive integers')
if image.width <= 0 or image.height <= 0:
raise ValueError('empty source')
if image.width * image.height > 20_000_000 or size[0] * size[1] > 20_000_000:
raise ValueError('pixel budget exceeded')
if getattr(image, 'n_frames', 1) != 1:
raise ValueError('single-frame images only')
normalized = ImageOps.exif_transpose(image).convert('RGBA')
normalized.thumbnail(size, Image.Resampling.LANCZOS)
x = (size[0] - normalized.width) // 2
y = (size[1] - normalized.height) // 2
canvas = Image.new('RGB', size, background)
canvas.paste(normalized, (x, y), normalized)
return canvas, (x, y, normalized.width, normalized.height)
The returned box is (left, top, width, height), measured in output pixels. The pixel budget is an example application limit. It does not replace request-size limits, safe decoding, worker isolation, or a color-management policy. The function rejects multi-frame inputs rather than silently choosing one frame.
Test geometry and edge cases
Save test_letterbox.py:
import unittest
from PIL import Image
from letterbox import letterbox
class LetterboxTests(unittest.TestCase):
def test_square_into_wide_canvas(self):
image, box = letterbox(Image.new('RGB', (1000,1000), 'red'))
self.assertEqual(image.size, (640,360));self.assertEqual(box,(140,0,360,360))
self.assertEqual(image.getpixel((139,180)),(24,24,24))
self.assertEqual(image.getpixel((140,180)),(255,0,0))
def test_wide_into_square(self):
_,box=letterbox(Image.new('RGB',(1200,600)),(400,400))
self.assertEqual(box,(0,100,400,200))
def test_small_source_is_not_enlarged(self):
_,box=letterbox(Image.new('RGB',(31,21)),(100,100))
self.assertEqual(box,(34,39,31,21))
def test_transparent_pixels_use_background(self):
image,_=letterbox(Image.new('RGBA',(10,10),(255,0,0,0)),(10,10))
self.assertEqual(image.getpixel((5,5)),(24,24,24))
def test_invalid_sizes(self):
for size in [(0,10),(-1,10),(10.0,10),(True,10),(10,)]:
with self.subTest(size=size),self.assertRaises(ValueError):letterbox(Image.new('RGB',(2,2)),size)
def test_source_not_mutated(self):
src=Image.new('RGB',(800,600));letterbox(src,(200,200));self.assertEqual(src.size,(800,600))
def test_pixel_budget(self):
with self.assertRaises(ValueError):letterbox(Image.new('RGB',(2,2)),(10000,10000))
if __name__=='__main__':unittest.main()
Run in an isolated environment:
python -m pip install Pillow
python -m unittest -v test_letterbox.py
All seven test methods passed in the executed environment, including invalid-size subcases. The tests check actual output pixels at the content boundary, not just the dimensions of a helper calculation. They also verify no upscaling, transparent-pixel compositing, and preservation of the input object's dimensions.
Reproduce the actual-file result
from PIL import Image
from letterbox import letterbox
with Image.open('source.png') as source:
canvas, box = letterbox(source)
canvas.save('letterboxed.jpg', quality=94)
print(canvas.size, box)
For the actual 1024 × 1024 source, the measured result is (640, 360) with placement (140, 0, 360, 360). Each side receives 140 pixels of padding. The shoe stays proportionally square within the canvas rather than becoming wider.
This second image is a deterministic local resize and padding operation on the first source, not another AI generation. Inspect the edges: no source area was cropped. JPEG encoding can change pixel values slightly; use PNG if exact lossless output matters.
Keep presentation choices explicit
Padding may be the wrong product choice when a layout demands edge-to-edge imagery. Decide that before implementation. Do not quietly switch to cropping or stretching to eliminate bars. Test portrait, landscape, small, and transparent fixtures in the same layout.
The live Voor workspace on September 24 selected GPT Image 2, 3:4, one output, Low quality, and 5 credits, with Public · watermarked visibility. Prompt, Reference images, Mask, and Generate were visible; uploads required sign-in and Generate led the signed-out session to sign-in. These controls do not establish the historical settings behind the square fixture.
If you need another source for layout testing, inspect the image workspace and current quote. The code and tests above work independently of Voor.
AI disclosure: an automated assistant prepared this article and code. The seven tests and the actual-file conversion were executed.
Top comments (0)