Rotate and Flip PNM Images Safely with pamflip

You will turn a PGM, PPM or PAM image around a defined axis, write the transformed image to a new file, and check its dimensions before using it. The examples use the Netpbm command installed on this machine, version 11.5.2. Allow about 10 minutes for a first conversion, plus however long the input takes to read and write.

Before you start

Install the Netpbm package and have an input image in a PAM or PNM format. PNM normally means PBM, PGM or PPM. pamflip reads the named file, or standard input when you omit the filename, and writes the transformed image to standard output. You do not need elevated privileges for an image in a directory you can read. Do not use sudo unless the input or destination is deliberately protected.

Set a real input path in the examples below. Keep the output path different from the input path. Shell redirection opens the output before pamflip runs, so using the same path can destroy the source before the program has read it.

INPUT=/path/to/input.pgm
OUTPUT=/path/to/output.pgm
test -r "$INPUT" && printf 'Input is readable: %s' "$INPUT"

Expected output is a short confirmation such as Input is readable: /path/to/input.pgm. If that check fails, fix the path or permissions first.

1. Choose one basic transformation

pamflip requires exactly one transformation option. The long names are easier to audit in a script. Use -leftright for a horizontal mirror, -topbottom for a vertical mirror, or -transpose to exchange the horizontal and vertical axes.

pamflip -leftright "$INPUT" > "$OUTPUT"

Short aliases exist: -lr, -tb and -xy. The command produces no normal terminal output because the image is sent to the file. A non-zero exit status means the conversion failed.

if pamflip -topbottom "$INPUT" > "$OUTPUT"; then
    printf 'Created %s' "$OUTPUT"
else
    printf 'pamflip failed; inspect the input and error message' >&2
fi

Checkpoint: the source should still exist, and the new file should have a recent modification time. If you selected the wrong operation, do not reuse that output as the next input. Generate a fresh output from the original instead. Once you have confirmed it is not needed, remove only the generated output, not the source.

2. Rotate by a quarter, half or three-quarter turn

Use -rotate90 for a counterclockwise 90-degree turn, -rotate180 for a half turn, and -rotate270 for a counterclockwise 270-degree turn, which is clockwise 90 degrees. Their aliases are -r90, -r180 and -r270. The 90 and 270 degree operations swap the width and height.

ROTATED=/path/to/rotated.pgm
pamflip -rotate90 "$INPUT" > "$ROTATED"
pamfile "$ROTATED"

For a valid input, pamfile reports the image type and dimensions. For example, a 3 by 2 PGM becomes a 2 by 3 PGM. pamflip may write the raw PNM variant even when the source used the plain-text variant, so identify the result by its header and dimensions rather than assuming the original encoding was preserved.

3. Apply several operations in a known order

Use -xform when one command needs more than one operation. Separate transform names with commas. pamflip applies them from left to right. Valid names are leftright, topbottom and transpose.

COMBINED=/path/to/combined.pgm
pamflip -xform=leftright,topbottom "$INPUT" > "$COMBINED"
pamfile "$COMBINED"

That example mirrors the image horizontally and then vertically. Reversing the names is a useful check when testing a workflow, because the final result should be the same for these two mirrors, while a transpose changes the dimensions. Avoid building a chain from several separate output files unless you need to inspect each stage. Each intermediate file is another opportunity to select the wrong path.

4. Verify the result without guessing

Use pamfile to check the format, width, height and maximum sample value. For a readable text dump of a raw PGM or PPM, use pnmnoraw if it is installed. This is useful for a tiny test image, but it is not a sensible way to inspect a large photograph.

pamfile "$INPUT" "$ROTATED"
if command -v pnmnoraw >/dev/null; then
    pnmnoraw "$ROTATED" | sed -n '1,6p'
fi

The first command should show the expected dimensions. The second prints the header and the first few rows for a small image. If the result is the wrong size, return to the original input and rerun the chosen transformation. Do not repair a questionable output by repeatedly transforming it, because a second rotation may hide which step was wrong.

5. Keep large rotations responsive

Horizontal mirrors and the null operation need little working memory. Rotations that exchange rows and columns can page heavily on a large image. The -memsize=MEbibytes option tells pamflip how much memory is available for its work. If the whole image cannot fit, it uses temporary files for chunks. The default is infinity, which is not a promise that the machine has enough real memory.

# Start with a conservative estimate for this job, not the machine's total RAM.
pamflip -memsize=512 -rotate90 "$INPUT" > "$ROTATED"
pamfile "$ROTATED"

Choose the value from the memory you can spare while the command runs. Too high can make allocation fail or cause severe paging. Too low usually adds temporary-file overhead and can fail if the environment cannot create temporary files. -pagesize defaults to 4 KiB and has no effect in this Netpbm release, so it is not a tuning control.

6. Handle failures and protect the original

pamflip reports a missing transformation, unreadable input, malformed image or resource problem on standard error. Run a diagnostic command without changing the source:

pamflip -verbose -rotate90 "$INPUT" > "$ROTATED"

The -verbose option reports progress to standard error. If the command stops part way through, treat the output as unusable and replace it by rerunning from the original. Check available space in the destination and the temporary-file area before retrying. A successful command does not validate visual orientation, so open the result in an image viewer when orientation matters.

There is no in-place undo. Recovery is simple if the source was kept: discard the failed or unwanted output and run pamflip again with a new destination. If the source was overwritten by a shell redirection, restore it from your backup rather than attempting to reverse an unknown sequence of transformations.

Done means

• The original image is still present and was not used as the redirection target.
• Exactly the intended transformation was selected, or the -xform order was recorded.
• pamfile confirms the output format and expected dimensions.
• A large rotation has a realistic -memsize value and enough temporary-file space.
• The output opens correctly in the next tool or image viewer.