Add a Verified Border to a PNM Image with pnmmargin

You will finish with a new PNM image surrounded by a border of the width and colour you chose, while keeping the source image available for recovery. This guide uses pnmmargin from Netpbm 11.5.2, packaged on this machine as netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a readable PNM file, such as PGM, PBM or PPM, and enough free space for a second image. The examples write to the current directory and do not need elevated privileges. Use sudo only to read an input directory that your account cannot access, not as a routine part of image conversion.

1. Check the installed command

Confirm that the command on your path is the Netpbm utility you intend to use:

$ command -v pnmmargin
/usr/bin/pnmmargin
$ pnmmargin -version
pnmpad: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version output includes build details and may vary slightly between installations. The useful fact is the Netpbm version, not the generated date. The command's usage is:

$ pnmmargin [-white|-black|-color <colorspec>] <size> [pnmfile]

size is the border width in pixels. If you omit the input filename, pnmmargin reads PNM data from standard input. Its image result goes to standard output, so redirection is part of the normal workflow.

2. Inspect the source before changing anything

Use pnmfile if it is installed, or another trusted image inspection tool, to record the current format and dimensions:

$ pnmfile /path/to/input.pgm
/path/to/input.pgm:    PGM raw, 640 by 480  maxval 255

Your format, dimensions and maxval may differ. Keep this file untouched. A border operation creates a new image; it does not provide an undo command for a destination that you have already overwritten.

Checkpoint: choose a destination with a different name, for example /path/to/input-bordered.pgm. Do not use the source path after > unless you deliberately accept shell redirection truncating the original before pnmmargin has finished.

3. Add a white or black border

For a plain border, state the colour explicitly. This avoids relying on pnmmargin's colour guess, which is allowed when you omit all colour options:

$ pnmmargin -white 24 /path/to/input.pgm > /path/to/input-white-border.pgm
$ pnmfile /path/to/input-white-border.pgm
/path/to/input-white-border.pgm:    PGM raw, 688 by 528  maxval 255

A 24-pixel border is added to every side, so the width increases by 48 and the height by 48. Replace the example paths and size with values suitable for your image. For a black border, change only the colour option:

$ pnmmargin -black 8 /path/to/input.pgm > /path/to/input-black-border.pgm

These commands normally print no progress message. A successful exit status means the command completed; the pnmfile check confirms that the destination exists and has the expected dimensions.

4. Choose a specific colour

Use the colour-selection option when white or black is not enough. Its value follows Netpbm's colour-name syntax. A hexadecimal RGB value is an easy choice for a PPM-compatible result:

$ pnmmargin -color '#ff0000' 12 /path/to/input.ppm > /path/to/input-red-border.ppm
$ pnmfile /path/to/input-red-border.ppm
/path/to/input-red-border.ppm:    PPM raw, 664 by 504  maxval 255

Quote a colour value that contains shell punctuation. When a colour is supplied to a greyscale source such as PGM, Netpbm may promote the output to PPM because a single grey channel cannot represent a full RGB colour. That is a format change, not a failed border. Check the destination before passing it to another tool.

If the colour is not recognised, pnmmargin reports an error and the redirected destination may be empty or incomplete. Treat that file as disposable, choose a documented Netpbm colour specification, and rerun with a fresh destination name.

5. Use a pipeline when the image is already on standard input

Omit the filename to read from standard input. This is useful when another Netpbm command produces the image:

$ pnmcrop /path/to/scanned.pgm | pnmmargin -white 16 > /path/to/scanned-framed.pgm
$ pnmfile /path/to/scanned-framed.pgm
/path/to/scanned-framed.pgm:    PGM raw, ...

The ellipsis above represents host-specific dimensions, not literal output to copy. Check the actual dimensions and keep the intermediate source available while testing. In a pipeline, the final redirection still creates or truncates its destination before the producer and pnmmargin run.

For a safer replacement of an existing destination, write a temporary sibling, check it, then move it into place:

$ pnmmargin -white 16 /path/to/input.pgm > /path/to/input.pgm.new
$ pnmfile /path/to/input.pgm.new
$ mv -- /path/to/input.pgm.new /path/to/input.pgm

The final mv replaces the old file, so treat it as a deliberate destructive step. Before it, the original remains available. If conversion fails, remove only the incomplete .new file after checking that it is the intended temporary output.

6. Remove or vary the border with the right tool

pnmmargin applies one size to all four sides. To remove a known border, use pamcut with the matching crop rectangle. To let a tool detect a border from the image content, look at pnmcrop. For different widths on different sides, use pamcat. The choice matters: cropping by guess can remove real image content.

pnmpad performs a similar job with more individual-margin control, but its documented margins are black or white. Use it when geometry matters more than a custom colour.

7. Diagnose the common failures

If pnmmargin cannot open the input, check the path and permissions without changing the image:

$ ls -l /path/to/input.pgm
$ test -r /path/to/input.pgm && echo readable
readable

If the output dimensions are wrong, remember that the total increase is twice the supplied size in both directions. If pnmfile cannot read the result, inspect the command's exit status and the destination size before trying to open it in an image viewer. Do not assume a non-empty file is valid.

The common -plain option is available from Netpbm 10.40 onwards, but it changes the PNM encoding rather than the border geometry. The installed manual says -quiet is not implemented for pnmmargin, so do not add it to suppress output.