Rotate and Flip PNM Images Safely with pamflip

pamflip turns a sideways scan or an upside-down photo the right way round, as a PGM, PPM or PAM file, without touching your original. These examples use the Netpbm build on this machine, version 11.5.2. Budget 10 minutes for your first conversion, plus however long the image itself takes to read and write.

Before you start

• Have the Netpbm package installed and an input image in PAM or PNM format (PNM covers PBM, PGM and PPM).
• Know how pamflip reads and writes. It reads the named file, or standard input if you leave the filename off, and writes the transformed image to standard output.
• Skip sudo. You do not need elevated privileges for an image in a directory you can already read. Only reach for it if the input or destination is deliberately locked down.
• Use two different paths. Shell redirection opens the output file before pamflip runs, so pointing output at the same path as input destroys the source before the program ever reads it.

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

1. Pick exactly one basic transformation

pamflip needs exactly one transformation option per run. Stick to the long names in scripts, they are far easier to audit later than the short aliases.

• -leftright (alias -lr) mirrors the image horizontally.
• -topbottom (alias -tb) mirrors it vertically.
• -transpose (alias -xy) swaps the horizontal and vertical axes.

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

A working run produces no terminal output at all, the image goes straight to the file. The only signal you get is the exit status, so check it rather than trusting silence:

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

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

Same rule applies: one rotation option per run.

• -rotate90 (alias -r90) turns the image 90 degrees counterclockwise.
• -rotate180 (alias -r180) turns it a full half turn.
• -rotate270 (alias -r270) turns it 270 degrees counterclockwise, which is the same as 90 degrees clockwise.

The 90 and 270 degree turns swap width and height, so a wide image comes out tall and vice versa.

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

3. Chain several operations in a known order

Need more than one transformation in a single command? Use -xform with a comma-separated list. pamflip applies the names left to right, and the valid names are leftright, topbottom and transpose.

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

That mirrors the image horizontally, then vertically. Reversing the order of the two mirror names is a handy sanity check while you are testing a workflow: the result should come out identical either way, whereas adding a transpose into the mix changes the dimensions and breaks that symmetry.

4. Verify the result, do not guess

Never assume a transform worked just because the command exited cleanly.

• Run pamfile. It reports format, width, height and the maximum sample value.
• Dump a small image with pnmnoraw, if it is installed, for a readable text view of a raw PGM or PPM. Fine for a tiny test image, useless as a way to inspect a real photograph.

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

The first command should report the dimensions you expected. The second prints the header and first few rows for a small image. Wrong size? Go back to the original input and rerun the correct transformation. Do not try to fix a shaky output by transforming it again, a second pass just hides which step went wrong.

5. Keep a large rotation responsive

Mirrors and the null operation barely touch memory. Rotations that swap rows and columns can page heavily on a big image. The -memsize=MEbibytes option tells pamflip how much memory it can use for the job; run out and it spills to temporary files for the overflow. The default is infinity, which is not a guarantee the machine actually has that much RAM.

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

Base the value on the memory you can genuinely spare while the command runs. Too high risks a failed allocation or heavy paging. Too low usually just adds temporary-file overhead, and fails outright if the environment cannot create temp files. -pagesize defaults to 4 KiB but has no effect in this Netpbm release, so do not treat it as a tuning knob.

6. Handle failures without losing the original

pamflip reports a missing transformation, unreadable input, malformed image or resource problem on standard error. Run a diagnostic pass that leaves the source untouched:

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

The -verbose option reports progress to standard error as it goes. If the command stops partway through, treat that output as unusable and rerun from the original rather than trying to patch it. Check free space in both the destination and the temp-file area before you retry. A clean exit does not confirm visual orientation either, so open the result in an image viewer whenever orientation actually matters.

Done means

• The original is untouched and was never used as the redirection target.
• You applied exactly the intended transformation, or wrote down the -xform order you used.
• pamfile confirms the output format and dimensions match what you expected.
• A large rotation has a realistic -memsize and enough temporary-file space behind it.
• The output opens cleanly in the next tool or an image viewer.