Crop Netpbm Images Precisely with pamcut

You will crop a PAM, PBM, PGM or PPM image to an exact rectangle, or remove a known number of pixels from its edges, while keeping the original file untouched. The examples use pamcut from Netpbm 11.5.2, the version installed on this machine.

Allow about fifteen minutes. You need the netpbm package, a readable input image and a directory where you can create the result. These commands are ordinary user commands. They do not need sudo unless your input or destination is deliberately protected by file permissions.

1. Check the installed command and input

Confirm which binary will run, then inspect the image before choosing coordinates:

$ command -v pamcut
/usr/bin/pamcut
$ pamcut --version
pamcut: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
$ file /path/to/input.pgm
/path/to/input.pgm: Netpbm image data, size 800 x 600, rawbits, greymap

The wording from file varies by format and version. Record the width and height. Coordinates are zero-based: column 0 is the leftmost column and row 0 is the top row. A 100 by 80 rectangle starting at column 50 and row 20 therefore ends at column 149 and row 99.

Checkpoint: keep the source path and a new destination path separate. pamcut writes the image to standard output, so the shell redirection determines where the result goes.

2. Select an exact rectangle

Use -left and -top for the starting coordinates, then -width and -height for the dimensions:

$ pamcut -left 50 -top 20 -width 100 -height 80 \
    /path/to/input.pgm > cropped.pgm

The result is 100 columns by 80 rows. The input format is preserved, so a PGM produces a PGM and a PPM produces a PPM. The command does not resize pixels: it selects an existing rectangle. The full option names are worth keeping in scripts even though the manual accepts minimum unique abbreviations.

Verify the file before replacing anything or passing it to another tool:

$ file cropped.pgm
cropped.pgm: Netpbm image data, size 100 x 80, rawbits, greymap
$ test -s cropped.pgm && printf '%s\n' 'crop created'

If the destination already exists, > truncates it before pamcut starts. That is destructive to the old destination, not to the input. Choose a new filename, or make a backup first:

$ cp --preserve=all cropped.pgm cropped.pgm.bak
$ pamcut -left 50 -top 20 -width 100 -height 80 \
    /path/to/input.pgm > cropped.pgm.new
$ mv cropped.pgm.new cropped.pgm

If the conversion fails, leave the original destination in place and remove only the incomplete cropped.pgm.new after checking that it is not needed. The input image remains the recovery copy.

3. Crop known borders instead

When the requirement is about margins rather than a subject's coordinates, use the edge-crop options. Their values are counts of columns or rows to discard:

$ pamcut -cropleft 50 -cropright 50 \
    -croptop 20 -cropbottom 20 \
    /path/to/input.pgm > border-cropped.pgm

For an 800 by 600 input, this produces a 700 by 560 image. The four options can be combined with rectangle options, but do not describe the same edge twice. For example, specifying both -right and -cropright is an error. The crop counts cannot be negative.

These edge-count options were added in Netpbm 10.85, released in December 2018. They are available in the installed 11.5.2 package. If you are maintaining a much older system, check its local manual before using them. Older releases can express some right and bottom crops with negative coordinates, but that form is easier to get wrong because the inclusive endpoint needs an extra subtraction.

4. Handle coordinates outside the image

By default, pamcut refuses a requested rectangle that extends past the input. This protects you from silently getting a different size:

$ pamcut -left 750 -top 550 -width 100 -height 100 \
    /path/to/input.pgm > edge.pgm
pamcut: You have specified a right edge (849) that is beyond the right edge of the image (799)
$ printf 'exit status: %s\n' "$?"
exit status: 1

The exact diagnostic includes the coordinates and can vary slightly. The useful result is a non-zero status and no valid promise about the redirected file. Prefer a temporary destination for commands that may fail.

Add -pad when the requested output size is intentional and the missing area should be black:

$ pamcut -left 750 -top 550 -width 100 -height 100 -pad \
    /path/to/input.pgm > edge-padded.pgm
$ file edge-padded.pgm
edge-padded.pgm: Netpbm image data, size 100 x 100, rawbits, greymap

Padding fills the area outside the input with black. It is not a way to choose a different border colour. If you need a coloured frame or more general placement, use a background image with pamcomp; if you simply need borders of known widths, inspect pnmpad.

5. Use standard input and multi-image streams carefully

Omit the input filename when the image is arriving on standard input. This makes a pipeline possible without creating an intermediate source file:

$ cat /path/to/input.pgm | \
    pamcut -left 50 -top 20 -width 100 -height 80 > cropped.pgm

The output is always standard output. Keep binary image data out of the terminal and redirect it to a file or the next image-aware program.

pamcut also processes a multi-image stream, cutting each image independently and returning a multi-image stream. That is useful when the stream already has several frames. If you are splitting one image into many same-size pieces, the manual recommends pamdice because it is faster and easier for that job.

6. Avoid the option and coordinate traps

• Use either the named options or the old four-argument form in new commands. The positional form is left top width height, but mixing it with options has unspecified results.
• Do not specify all three of -left, -right and -width. Likewise, do not specify all three of -top, -bottom and -height.
• Remember that -right and -bottom are inclusive coordinates. A rectangle from column 50 through column 149 has width 100, not 99.
• Keep the original until the result has the expected dimensions and can be opened by the next tool. A successful exit status confirms processing completed; it does not confirm that your chosen rectangle was visually the one you wanted.

For a second, human-readable diagnostic, add -verbose. It writes processing information to standard error, leaving the image data on standard output. Do not redirect both streams into the image file.