Add Predictable Borders to PNM Images with pnmpad

You will add black, white, background-coloured, or edge-extended borders to a PNM image, while keeping the original file untouched. The examples use Netpbm 11.5.2 from the Debian netpbm package, version 2:11.05.02-1.1build1. Allow about ten minutes if the input path is ready.

This guide uses ordinary, unprivileged commands. You need a shell, pnmpad, and a readable PNM file. Do not use sudo for an image in your own working directory. Elevated privileges only belong in the separate case where filesystem permissions genuinely require them.

1. Check the installed command

Confirm which executable will run and record its Netpbm version:

$ command -v pnmpad
/usr/bin/pnmpad
$ pnmpad -version 2>&1 | head -2
pnmpad: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmpad: Built from source dated 2024-03-31 09:09:47

The option syntax in this guide uses full names. The manual allows a shortest unique abbreviation, one or two leading hyphens, and either whitespace or an equals sign before a value. Full names are easier to review in scripts.

2. Add fixed borders without replacing the input

Pass the input file last and redirect standard output to a new destination. This example adds two pixels on every side and makes a white border:

$ pnmpad -left=2 -right=2 -top=2 -bottom=2 -white \
    /path/to/input.pnm > /path/to/input-bordered.pnm

pnmpad reads a PNM image and writes a PNM image. The default padding is black, so specify -white when the border colour matters. The older -white and -black switches remain useful for those two colours. Do not use the same path for input and output: shell redirection can truncate the destination before the program reads anything.

Verify the new dimensions with an installed image inspection command:

$ file /path/to/input-bordered.pnm
/path/to/input-bordered.pnm: Netpbm image data, size = 104 x 84, rawbits, pixmap

The reported dimensions will differ for your input. They should be the original width plus left and right padding, and the original height plus top and bottom padding. Keep the source until the output has been inspected.

3. Request a target size and choose its alignment

Use -width or -height when you know the desired outer dimension but not the individual margins. With no explicit side margin, the extra space is split evenly by default:

$ pnmpad -width=800 -height=600 \
    /path/to/input.pnm > /path/to/input-800x600.pnm

If the input is smaller than the target, -halign=0.0 puts horizontal padding on the right, -halign=0.5 centres it, and -halign=1.0 puts it on the left. The equivalent vertical control is -valign. Values between zero and one divide the padding proportionally.

$ pnmpad -width=800 -halign=0.0 \
    /path/to/input.pnm > /path/to/input-left-aligned.pnm

If the input is already at least as wide or tall as the requested target, that target adds no padding in that direction. If you combine -width with both -left and -right, the explicit margins must already make the image at least the requested width. Otherwise the command fails. The same rule applies vertically.

$ pnmpad -reportonly -width=800 -height=600 \
    /path/to/input.pnm
37 38 24 24 800 600

Use the real six-number result, rather than the illustrative values above, when a later command needs exact placement.

4. Pad to a multiple for tiled or batched output

-mwidth and -mheight round the output dimensions up to multiples. They add to any padding requested by the other options:

$ pnmpad -mwidth=16 -mheight=16 \
    /path/to/input.pnm > /path/to/input-tiles.pnm

For example, a 4 by 3 input produced 1 0 1 0 5 4 with -mwidth=5 -mheight=4 on the installed command. The extra space is normally shared according to the alignment ratios. Check the actual output with -reportonly, especially when an odd number of pixels must be divided between two sides.

5. Choose colour behaviour deliberately

Use the named-colour option for a Netpbm colour name, such as red. The background-detection option takes the colour of the input's top-left pixel. That can be surprising when the image has a meaningful corner, so it is not a general-purpose background detector. The edge-extension option repeats the adjacent edge pixels, which is useful when a solid border would create a visible seam.

Colour can require a more expressive output format. A red request on a greyscale PGM promotes the output to PPM by default. The no-promotion mode keeps the input format and approximates the requested colour; the format-only mode can change the format to PPM while keeping the input maxval; the all-promotion mode, which is the default, also makes the maxval capable of representing the colour. The promotion decision is made even when the requested dimensions result in no actual padding.

$ pnmpad -color=red /path/to/input.pgm > /path/to/input-red.pnm
$ file /path/to/input-red.pnm
/path/to/input-red.pnm: Netpbm image data, size = 104 x 84, rawbits, pixmap

Inspect the header if the output format matters. Do not assume that a colour option preserves PGM or PBM.

6. Recover safely from mistakes

There is no in-place undo. If a command fails, the redirected destination may be empty or incomplete. Write to a temporary name in the same directory, verify it, then replace the old output only if you explicitly want to:

$ pnmpad -white -left=10 -right=10 -top=10 -bottom=10 \
    /path/to/input.pnm > /path/to/output.pnm.new
$ file /path/to/output.pnm.new
$ mv /path/to/output.pnm.new /path/to/output.pnm

The final mv changes state and replaces an existing destination. Before running it, make a backup if that file is valuable. If the conversion fails, leave the old file alone and remove the incomplete .new file after checking its path. Never remove the original input as part of this workflow.