Adjust Colour Safely with pambrighten

pambrighten nudges a PPM image's HSV Saturation or Value up or down without touching Hue. This walks through doing it without wrecking the original file, using the installed package netpbm 2:11.05.02-1.1build1, which provides Netpbm 11.5.2.

Allow about ten minutes. You need a shell, a readable Netpbm image, and enough free space for a second copy. The command needs no elevated privileges as long as you can read the input and write the destination directory. Do not reach for sudo as a routine part of image conversion.

1. Check the installed command

Confirm which executable your shell will run, then ask it for its version. Both are ordinary read-only commands:

$ command -v pambrighten
/usr/bin/pambrighten
$ pambrighten --version
pambrighten: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...

The version output includes build details after the library version, so the exact lines vary. The useful checkpoint is that the command exists and reports Netpbm 11.5.2 on this installation. The manual page is dated 18 August 2020; treat the local command and manual as the contract for this machine.

2. Inspect the source before transforming it

Set a shell variable to your real path, then check the file is readable and identify its format:

INPUT='/path/to/source-image.ppm'
test -r "$INPUT" && printf '%s\n' 'input is readable'
file "$INPUT"

A PPM file commonly identifies itself as a Netpbm image with a size and either rawbits or ASCII pixels. Yours might be another format Netpbm supports. pambrighten writes the same format as its input, and passes through extra channels such as transparency.

3. Increase or decrease Value

Value is the HSV brightness component. A percentage is relative to the current Value: 100 doubles it, -50 halves it. Value cannot exceed the full range, so a requested increase that would overshoot it is capped at full Value instead.

Write to a new filename so the source stays recoverable:

$ pambrighten -value=100 "$INPUT" > brightened.ppm
$ file brightened.ppm
brightened.ppm: Netpbm image data, ...

The ellipsis stands in for host-specific wording from file. Check the destination exists and describes the expected dimensions and image family. A successful run normally prints no progress message, because the transformed image is standard output.

cp --preserve=all brightened.ppm brightened.ppm.bak
pambrighten -value=100 "$INPUT" > brightened.ppm.new
mv brightened.ppm.new brightened.ppm

If the conversion fails, leave the original destination alone and restore from brightened.ppm.bak if you need to. Do not delete the backup until you have checked the new image. That final mv only renames the destination; it never touches the source named by INPUT.

4. Change Saturation, or both at once

Saturation controls how strongly a colour separates from grey at the same Hue and Value. Turn it up and colours look more intense; turn it down and they wash out. Saturation is capped at its full range too.

Double Saturation and halve Value in one pass:

$ pambrighten -saturation=+100 -value=-50 "$INPUT" > muted-brightness.ppm
$ file muted-brightness.ppm
muted-brightness.ppm: Netpbm image data, ...

The plus sign is optional for a positive percentage, but keeping +100 makes the direction obvious in a script. The options also accept double hyphens and whitespace instead of an equals sign:

$ pambrighten --saturation +25 --value -10 "$INPUT" > adjusted.ppm

Use the full option names in scripts. The manual allows unique abbreviations, but an abbreviation can turn ambiguous the moment a later Netpbm release adds a new option.

5. Use standard input in a pipeline

Omit the input filename when another command supplies the Netpbm image on standard input. Standard output is still the transformed image:

$ pambrighten --value +25 < source.ppm > source-value-25.ppm
$ test -s source-value-25.ppm && printf '%s\n' 'output is non-empty'
output is non-empty

Handy for a pipeline, but it does not make a failed redirection safe. Choose a new destination, or write to a temporary name and rename it only after the command and your image check both succeed.

Do not open raw PPM output in a text editor. The header is text, but a P6 image carries binary pixel data. Use an image viewer or a later Netpbm converter once you have checked the file type.

6. Know the defaults, and catch failures

Both -value and -saturation default to zero. Run the command without either and you are asking for no HSV adjustment at all, though it still reads and rewrites the image. Add the option that states the change you actually want rather than relying on an unstated default.

A missing input, malformed Netpbm data, or an unwritable output directory gives a non-zero exit status. Capture it immediately when a script needs to stop safely:

pambrighten -value=25 "$INPUT" > adjusted.ppm
status=$?
if [ "$status" -ne 0 ]; then
    printf 'pambrighten failed with status %s\n' "$status" >&2
    exit "$status"
fi
test -s adjusted.ppm

If the last test fails, treat the output as unusable and keep the source. If the colours look wrong despite a clean exit, check you used the intended input, percentage sign and direction, then inspect the result in a trusted viewer. The command changes Saturation and Value, not Hue; reach for a different Netpbm tool when Hue needs to move.