Crop Plain Borders from Netpbm Images with pnmcrop

pnmcrop strips a uniform border from a PBM, PGM or PPM image, which turns a scanned page with wide white margins into a tight crop in one command. You will also learn how to preview the proposed crop before creating output, and how to avoid the background-colour guesses that cause most surprises. Allow about fifteen minutes for a first image. The examples use Netpbm package version 2:11.05.02-1.1build1 on this machine.

• You need: a shell, a readable Netpbm image and the netpbm package.
• No elevated privileges normally needed. Use sudo only if your input or output directory is deliberately restricted, and check the resulting file ownership before using it in a service or automated job.

1. Check the installed command

Confirm the executable is available before investigating image content:

$ command -v pnmcrop
/usr/bin/pnmcrop
$ pnmcrop --help
pnmcrop: Use 'man pnmcrop' for help.

The installed manual accepts a single input filename, or standard input when no filename is supplied, and writes the resulting image to standard output. The help response above is normal for this build, so use man pnmcrop for the complete option list.

2. Preview the crop without writing an image

Use --reportsize when you want only the crop amounts and final dimensions. This command changes nothing:

$ pnmcrop --reportsize /path/to/input.pgm
-3 -3 -1 -2 2 2

The six fields are the signed changes for the left, right, top and bottom edges, followed by the output width and height. A negative value means pixels will be removed; a positive value means padding will be added. In this example, three columns disappear from each side, one row from the top and two rows from the bottom, leaving a 2 by 2 image.

For a more detailed audit, use --reportfull:

$ pnmcrop --reportfull /path/to/input.pgm
-3 -3 -1 -2 2 2 rgb-255:255/255/255 0.000000

The additional fields show the background colour selected by pnmcrop and the closeness value used. Report mode is useful in scripts and batch jobs because it lets you reject an unexpected crop before producing an output file. It cannot be combined with --borderfile.

3. Crop all four borders

Once the report looks reasonable, redirect standard output to a new filename:

$ pnmcrop /path/to/input.pgm > /path/to/input-cropped.pgm
$ pamfile /path/to/input-cropped.pgm
/path/to/input-cropped.pgm: PGM raw, 2 by 2 pixels

pnmcrop preserves the Netpbm image type. A PGM input therefore remains PGM, while PBM and PPM inputs produce their corresponding formats. If pamfile is not installed or uses different wording, inspect the dimensions with another Netpbm reader or an image tool you already trust.

$ pnmcrop /path/to/input.pgm > /path/to/input-cropped.pgm.new
$ pamfile /path/to/input-cropped.pgm.new
$ mv /path/to/input-cropped.pgm.new /path/to/input-cropped.pgm

4. Select edges and make the background explicit

By default, pnmcrop tries to crop every side. Add one or more of --left, --right, --top and --bottom when only particular edges should be removed:

$ pnmcrop --bottom /path/to/input.pgm > /path/to/no-bottom-border.pgm

The background-colour decision is independent of the edges you select. Without another option, pnmcrop uses the top-left and top-right corners, or an intermediate colour when they differ, which means a blue top border can prevent a black bottom border being recognised even when you request only --bottom.

Choose the rule that matches the image instead of relying on that default:

• --white crops white borders.
• --black crops black borders.
• --bg-color=white or another Netpbm colour name sets an explicit background colour.
• --bg-corner=bottomleft, topright and the other corner names use the selected corner as the background sample.
• --sides compares all four corners, choosing a repeated corner colour where possible.

Use at most one of those background selectors. A white scan with a border on just the bottom edge, for example, can be checked and cropped as follows:

$ pnmcrop --bottom --white --reportfull /path/to/scan.pgm
-0 -0 -0 -18 640 842
$ pnmcrop --bottom --white /path/to/scan.pgm > /path/to/scan-cropped.pgm

5. Handle uneven borders and margins

Exact matching is the default: --closeness=0 requires a border pixel to match the chosen background exactly. A photographed white backdrop often contains small shading changes, so try a modest percentage when the border is visibly uneven:

$ pnmcrop --white --closeness=5 --reportfull /path/to/photo.pgm

Review the report carefully. A value that is too high can classify pale subject detail as background and remove it. If the border contains noise or speckles, prepare a separate cleaned image and pass it with --borderfile=/path/to/clean-border.pgm. The border file controls the detected border sizes and background, while the original input supplies the output pixels, and it must contain the same number of images as the input stream.

Keep a frame around the result with --margin=12. pnmcrop leaves twelve pixels of border and pads up to that size when needed:

$ pnmcrop --white --margin=12 /path/to/scan.pgm > /path/to/scan-with-margin.pgm

6. Deal with blank images and image streams

An image consisting entirely of background has no meaningful foreground boundary. The default --blank-image=abort fails with an explanatory message. Use --blank-image=pass when a blank input should be copied unchanged, or --blank-image=minimize when a one-row, one-column or one-pixel result is useful. The margin is ignored for a blank image unless the selected behaviour supports an all-margin result.

For a multi-image Netpbm stream, pnmcrop processes each image independently, which can produce different output dimensions within one stream. If every output must share dimensions, use --reportsize to inspect the images first, or calculate a common crop and apply it later with pamcut. Do not assume that one report line describes the entire stream.