Shift Image Colours Safely with pamhue

You will create a new Netpbm image with every colour shifted around the HSV colour wheel, while leaving the source file untouched. This guide uses pamhue from Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1. Allow about ten minutes if your input image is ready.

You need the netpbm package, a readable PBM, PGM, PPM or PAM image, and write access to the directory where you will save the result. The examples are ordinary user commands. They do not need sudo, and pamhue does not change system configuration.

1. Check the installed command

Confirm that the command in your shell is the one you intend to run, then record the linked Netpbm version:

$ command -v pamhue
/usr/bin/pamhue
$ pamhue -version
pamhue: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The exact -version text can include build details, and the package version differs between distributions. The useful check is that pamhue reports a Netpbm library and that the binary is present.

2. Choose a new destination

pamhue reads one input filename and writes the processed image to standard output. Redirect that output to a different filename. Do not use the source path after > unless you deliberately want the shell to truncate the source before pamhue reads it.

$ INPUT='/path/to/source.ppm'
$ OUTPUT='/path/to/source-hue-120.ppm'
$ test -r "$INPUT" && echo "input is readable"
input is readable

These shell variables are just placeholders. Replace the paths with real files. A path containing spaces is safe when it remains inside double quotes.

3. Shift colours clockwise

Pass the mandatory -huechange option and a degree value, then redirect standard output:

$ pamhue -huechange=120 "$INPUT" > "$OUTPUT"

A positive value moves clockwise. A 120-degree shift turns red towards green, green towards blue, and blue towards red. The operation applies the same angular shift to every pixel. The value may be fractional or greater than one full revolution.

pamhue normally has no progress output because the image data is the output stream. Check the exit status and destination immediately:

$ printf 'pamhue exit status: %s\n' "$?"
pamhue exit status: 0
$ test -s "$OUTPUT" && echo "output is non-empty"
output is non-empty
$ file "$OUTPUT"
/path/to/source-hue-120.ppm: Netpbm image data, size = 640 x 480, rawbits, pixmap

Your file description will vary. Confirm that it identifies a Netpbm image and that the dimensions match the source. Keep the original until you have inspected the result.

4. Try a counterclockwise or precise shift

Negative values move counterclockwise. Whitespace can replace the equals sign, but the equals form is easier to scan in scripts:

$ pamhue -huechange=-120 "$INPUT" > /path/to/source-hue-minus-120.ppm
$ pamhue -huechange=22.5 "$INPUT" > /path/to/source-hue-22-5.ppm
$ pamhue -huechange=480 "$INPUT" > /path/to/source-hue-480.ppm

There is no special wraparound syntax to learn. pamhue accepts angles beyond 360 degrees. Choose names that record the angle and keep each run's output separate, especially when comparing variants.

5. Understand grayscale and source safety

Hue has no meaning in black-and-white or grayscale images. For those inputs, pamhue leaves the image unchanged in visual content. A colour shift is not a way to colourise a PGM or PBM file. Use a separate colourisation or compositing workflow if that is your goal.

The command writes a new image stream; it does not edit the input file in place. The risky part is shell redirection: > opens and truncates its destination before pamhue starts. To replace an existing output only after a successful run, use a temporary name in the same directory:

$ TEMP='/path/to/source-hue-120.ppm.new'
$ pamhue -huechange=120 "$INPUT" > "$TEMP" && mv -- "$TEMP" "$OUTPUT"
$ file "$OUTPUT"

If pamhue fails, the && prevents mv from replacing the old output. Inspect or remove the incomplete temporary file only after checking the error. The original input remains your recovery copy.

6. Diagnose the common failures

The angle is mandatory. If you omit it, the installed command exits with status 1 and reports that you must specify -huechange:

$ pamhue "$INPUT" > /tmp/pamhue-missing-option.ppm
pamhue: You must specify -huechange
$ printf 'exit status: %s\n' "$?"
exit status: 1

Do not treat a file created by a failed redirection as a valid result. Use the temporary-file pattern above for important outputs.

If pamhue cannot open the input, check the path and permissions without changing anything:

$ ls -l -- "$INPUT"
$ test -r "$INPUT" && echo readable || echo 'not readable'

If the output is not recognised as Netpbm, check the exit status before opening it. A shell pipeline can hide an earlier failure unless you enable pipeline failure checking with set -o pipefail. For a normal redirection, the command's immediate $? is the relevant status.