Fit an image with letterbox bars

Fit an image inside a fixed canvas without guessing, stretching, or cutting away content. Enter the source width and height plus the target canvas dimensions to receive the uniform scale, final integer pixel size, and the exact top, right, bottom, and left bars. The result distinguishes letterboxing, pillarboxing, and an exact aspect-ratio match, making it useful for video frames, presentation layouts, image pipelines, responsive previews, and any workflow that must preserve the complete source image.

Fit the whole image while preserving its shape

A contain-style fit has one strict promise: every source pixel remains visible inside the target canvas. The calculator compares the source and canvas aspect ratios, chooses the smaller of the horizontal and vertical scale factors, and applies that single factor to both image dimensions. Because the width and height always change together, circles stay circular, faces are not squeezed, and the composition is never cropped.

The returned fitted width and height are integer pixel dimensions that do not exceed the canvas. When an exact proportional dimension falls between pixels, the constrained dimension fills its canvas edge and the other dimension rounds down. Rounding down is intentional because rounding up could place a row or column outside the requested canvas.

The response also includes the mathematical scale before pixel rounding, which is useful when configuring graphics software or comparing several candidate canvas sizes. All four input dimensions must be positive integers; a zero dimension has no usable aspect ratio and is rejected as invalid input rather than producing an infinite or undefined result.

Read letterbox and pillarbox bar measurements

The bars object gives padding in pixels for the top, right, bottom, and left sides of the fitted image. A wide image placed in a relatively tall canvas leaves unused vertical space, so the result is letterboxed with bars above and below. A tall or narrow image placed in a relatively wide canvas leaves horizontal space, producing pillarbox bars on the left and right.

If source and canvas share the same aspect ratio, the fit is exact and every bar is zero. The image is centered in every case. When the unused number of pixels is even, opposite bars have equal sizes.

When it is odd, the top or left receives the smaller share and the bottom or right receives the remaining pixel. This deterministic convention makes the four bars add back to the canvas dimensions exactly and avoids ambiguous half-pixel placement. You can use the bar values directly as padding, offsets, or drawing coordinates: the image origin is at left and top, while the fitted rectangle ends before the right and bottom bars.

Apply the result in rendering and media pipelines

Use these numbers before resizing rather than after exporting an image. First create or select the target canvas, resize the source to the returned fitted width and height with your preferred resampling method, then place it at the returned left and top offsets. Fill the remaining canvas area with a solid color, transparency, a blurred extension, or another background treatment.

The calculation itself does not inspect image bytes, choose a color, or perform resampling; it is a geometry step that stays independent of file format and rendering library. That separation makes the output equally useful with CSS, Canvas, SVG, FFmpeg, ImageMagick, mobile drawing APIs, presentation software, or server-side thumbnail jobs. For batch systems, validate dimensions early and store the fit result beside the render request so later stages use one agreed geometry.