Recolour an image while preserving its luminance with pamrecolor

You will use pamrecolor to change the colours of an image while keeping each pixel's luminance as close as the tool can make it. The result stays visually similar when converted to greyscale. Allow about fifteen minutes for a first run, including a small verification step.

You need a Linux shell, the Netpbm package, a readable input image and enough space for a new output file. The examples use Netpbm 11.5.2 from package netpbm version 2:11.05.02-1.1build1. The installed manual page is dated 31 July 2010, so this guide describes the command available on this machine and calls out the details that matter for repeatable work.

1. Check the installed command

Confirm which executable your shell will run and ask it for its build information:

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

The version output includes additional build details on this installation. If the command is missing, stop and install Netpbm through your normal package-management process. Do not use sudo merely to recolour an image. Reading an input and writing a file in your own working directory should normally be unprivileged.

2. Tint the whole image with one target colour

Choose a new destination before running the command. pamrecolor writes a PAM image to standard output, so redirect that output to a new file:

$ pamrecolor --targetcolor=yellow /path/to/input.pam > recoloured-yellow.pam
$ file recoloured-yellow.pam
recoloured-yellow.pam: Netpbm PAM image file

For every input pixel, the program seeks the closest possible version of yellow whose luminance matches the original. The input is not modified. Colour names such as yellow and hexadecimal values such as #ff69b4 are accepted by the Netpbm colour parser.

Do not interpret a normal shell prompt as proof that the image is correct. Check the command status and the output format:

$ printf '%s\n' "$?"
0
$ pamfile recoloured-yellow.pam
recoloured-yellow.pam:	PAM image, RGB, 2 by 1

Your pamfile wording and dimensions will differ. The useful checks are a zero exit status and a readable PAM image with the expected dimensions.

3. Apply colours from another image

Use --colorfile when each output pixel should take its target colour from a second image. The colour file must be a PPM or a colour PAM image:

$ pamrecolor --colorfile=/path/to/palette.ppm /path/to/greyscale.pgm > colourised.pam
$ pamfile colourised.pam
colourised.pam:	PAM image, RGB, 640 by 480

The luminance comes from the input image, while the target colour comes from the corresponding position in the colour file. A colour file larger than the input is cropped at the input's top-left corner. A smaller one is repeated as a tile. That tiling is easy to miss, so check the dimensions and inspect a representative area before using the result in a batch.

--targetcolor and --colorfile are alternatives. Supplying both is an error. Keep the command simple enough that the choice is obvious when you review a script.

4. Make random recolouring repeatable

If neither target option is supplied, pamrecolor chooses a target colour independently for each pixel. The default seed is derived from the time of day and process ID, so separate runs normally differ. Use --randomseed when you need a reproducible result:

$ pamrecolor --randomseed=42 /path/to/input.pam > random-a.pam
$ pamrecolor --randomseed=42 /path/to/input.pam > random-b.pam
$ cmp --silent random-a.pam random-b.pam && echo 'identical output'
identical output

The installed command produced byte-for-byte identical PAM files for those two runs. This option was added in Netpbm 10.61, and is present in the installed 11.5.2 release. A seed makes the generated image repeatable; it does not make random recolouring suitable for hiding sensitive information.

5. Match the luminance colour space

The default colour space is ntsc. That is the space the manual describes as matching Netpbm formats and many graphics utilities. If your surrounding workflow uses sRGB, specify it explicitly:

$ pamrecolor --colorspace=srgb --targetcolor=tan /path/to/input.ppm > sepia-like.pam

This setting controls how red, green and blue contribute to luminance. It does not convert an image between colour spaces. With --colorspace, the sample values are interpreted using the selected space, and another program may interpret the resulting PAM differently if its assumptions do not match.

The named spaces documented by this version are adobe, apple, cie, ntsc, pal, smpte-c, srgb and wide. You can instead provide all three channel contributions with --rmult, --gmult and --bmult. They must be supplied together and must add up to 1.0:

$ pamrecolor --rmult=0.2880402 --gmult=0.7118741 --bmult=0.0000857 \
    --targetcolor=tan /path/to/input.ppm > prophoto-like.pam

6. Convert PAM only when the next tool needs it

PAM is the normal output format. Current Netpbm programs can read it directly, but some other image programs expect PPM, PGM or PBM. Convert a verified result with pamtopnm:

$ pamtopnm recoloured-yellow.pam > recoloured-yellow.ppm
$ file recoloured-yellow.ppm
recoloured-yellow.ppm: Netpbm image data, size 640 x 480, rawbits, pixmap

This conversion does not undo the recolouring. It changes the container format for compatibility. If you need a different format, use the appropriate later converter and verify that tool separately.

7. Protect existing output and diagnose failures

$ pamrecolor --targetcolor=yellow input.pam > recoloured.pam.new
$ pamfile recoloured.pam.new
$ mv recoloured.pam.new recoloured.pam

If the command fails, leave the original destination alone and inspect the input, target file and options. Check that a colour file is PPM or colour PAM, that the input is readable, and that you have not supplied both target options. If the output is unexpectedly dark or bright when converted to greyscale, compare the --colorspace setting used by the next converter with the one used by pamrecolor.

There is no undo for a completed mv unless you kept a backup. Recovery is therefore simple: preserve the original input, use a new output name, and only remove an old result after the replacement has been checked.