pnmmargin

Add a border of the specified size to a PNM image

$ pnmmargin [size] [path/to/image.pnm] > [path/to/output.pnm]

$ pnmmargin [[-c|-color]] [color] [size] [path/to/image.pnm] > [path/to/output.pnm]

pnmmargin [-left=pixels] [-right=pixels] [-top=pixels] [-bottom=pixels] [-margincolor=color] [-verbose] [-pgm | -ppm]

-left=pixels
    Sets the width of the margin on the left side of the image, specified in pixels.

-right=pixels
    Sets the width of the margin on the right side of the image, specified in pixels.

-top=pixels
    Sets the width of the margin on the top side of the image, specified in pixels.

-bottom=pixels
    Sets the width of the margin on the bottom side of the image, specified in pixels.

-margincolor=color
    Specifies the color to use for the margins. The color can be an X color name (e.g., "red"), an RGB hexadecimal value (e.g., "#FF0000"), or simple names like "black" or "white".

-verbose
    Causes pnmmargin to print informational messages about its processing to standard error.

-pgm
    Forces the output image format to be PGM (Portable Graymap). If the input is PPM, it will be converted to grayscale.

-ppm
    Forces the output image format to be PPM (Portable Pixmap). If the input is PGM or PBM, it will be promoted to color.

The pnmmargin command is a utility from the Netpbm image manipulation suite. It reads a Portable Anymap (PNM) format image (which includes PBM for bitmaps, PGM for graymaps, and PPM for pixmaps) from standard input, adds specified margins around the image, and then writes the modified image to standard output.

Users can specify the width of margins independently for the left, right, top, and bottom sides of the image in pixels. Additionally, the color of these margins can be customized. If no margin color is explicitly provided, the margins will default to black. This tool is particularly useful for preparing images for layout, printing, or when consistent padding is required around visual content. Its standard input/output behavior allows for easy integration into shell scripts and pipelines with other Netpbm tools.

If no margin options are specified, pnmmargin effectively acts as a no-operation, simply copying the input image to the output without modification.

When adding margins to PBM (Portable Bitmap) images, specifying a margin color that is neither black nor white will cause the image to be promoted to PGM (Portable Graymap) to accommodate the color. Similarly, adding a non-grayscale margin to a PGM image will promote it to PPM (Portable Pixmap). This automatic promotion might alter the intended output format if not explicitly handled with -pgm or -ppm options.

pnmmargin reads the input PNM image from standard input and writes the resulting image to standard output. This design makes it highly suitable for use in Unix pipelines, allowing it to easily chain with other Netpbm utilities or commands. For example, an image can be piped from a file using cat or directly from another image processing command.

pnmmargin is part of the Netpbm project, a comprehensive suite of graphics file format converters and image processing tools. Netpbm originated from the pbmplus package, which was first released in 1988 by Jef Poskanzer. The project has undergone continuous development and maintenance, with pnmmargin being developed by Bryan Henderson as part of the Netpbm suite. Its long history reflects the enduring utility of its minimalist, pipeline-friendly design philosophy for image manipulation on Unix-like systems.

pnmcat(1), pnmcrop(1), pnmcut(1), pnmremap(1), pnmscale(1), pnm(5)