Convert PNM gamma correctly with pnmgamma

You will use Netpbm pnmgamma to convert PGM or PPM sample values between BT.709 luminance, sRGB luminance and radiance-linear data. The examples write a new output file, inspect its header and keep the source intact. This guide describes Netpbm 11.5.2, installed from Debian package netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, a readable PNM image and the Netpbm package. The commands normally run as your ordinary user. Do not use sudo unless the input or destination directory is deliberately restricted by its permissions.

1. Decide what the samples mean

Gamma conversion is not a general brightness control. A PNM image carries sample values, and those values can be interpreted as radiance, BT.709 luminance or sRGB luminance. Choose the operation from the meaning of the input and the requirement of the next program.

• -bt709tolinear converts true BT.709 PGM or PPM samples to radiance-linear samples.
• -lineartobt709 converts radiance-linear samples to BT.709 luminance.
• -bt709tosrgb converts BT.709 luminance to sRGB luminance.
• -srgbtobt709 converts sRGB luminance to BT.709 luminance.

PGM follows the same idea as PPM, and pnmgamma treats PBM as PGM. The conversion changes sample values, not the image dimensions. If you only want a display-oriented brightness adjustment, confirm the required transfer function first. A plausible-looking image is not proof that the direction was correct.

2. Convert a PNM image with the modern syntax

Pass one transfer-function option and the input file. Standard output is the converted image, so redirect it to a new pathname:

$ pnmgamma -bt709tolinear /path/to/input.pgm > /path/to/output-linear.pgm

The installed command writes a valid PNM stream and returns zero on success. Confirm both the exit status and the output metadata:

$ printf '%s\n' "$?"
0
$ file /path/to/output-linear.pgm
/path/to/output-linear.pgm: Netpbm image data, size = ... x ..., rawbits, greymap

The reported wording varies with the file release. Check that the dimensions match the input and that the format is still the kind of PNM your next tool accepts. For colour input, use the same transfer direction with a PPM pathname.

3. Add a deliberate gamma value when needed

With the modern transfer-function options, -gamma changes the exponent used by the transfer function. The default is the standard value for the selected conversion. Component options override it for their channel:

$ pnmgamma -bt709tolinear -gamma=2.2 \
    -rgamma=1.8 /path/to/input.ppm > /path/to/output.ppm

This example applies 1.8 to red and 2.2 to the other components. Because the component-specific option makes a greyscale input become colour output on the installed version, check the result rather than assuming the suffix tells the whole story:

$ file /path/to/output.ppm
/path/to/output.ppm: Netpbm image data, size = ... x ..., rawbits, pixmap

Do not add -gamma to every invocation by habit. It is not accepted with the old default exponential form, and a custom value means you are departing from the standard transfer function. Keep the chosen value beside your processing notes or script.

4. Preserve precision with maxval

By default, the output maxval is the input maxval. A non-linear conversion can map several input levels to one output level when that range is too small. Request a larger output range when retaining distinct levels matters:

$ pnmgamma -bt709tolinear -maxval=1023 \
    /path/to/input.pgm > /path/to/output-linear-10bit.pgm
$ sed -n '1,3p' /path/to/output-linear-10bit.pgm
P5
...
1023

The value in the third header line is the output maximum, not a promise that every sample uses ten bits. Choose a value supported by the consumer. Inspect it before handing the file to a tool that assumes an 8-bit range.

5. Avoid truncating the source or a good result

Shell redirection with > truncates its destination before pnmgamma starts. Never use the input pathname as the destination:

$ pnmgamma -lineartobt709 /path/to/input.pgm > /path/to/input.pgm

That command can destroy the original even if conversion later fails. Use a temporary name in the same directory, verify it, then replace the original only when you have explicitly decided that is wanted:

$ pnmgamma -lineartobt709 /path/to/input.pgm > /path/to/input.pgm.new
$ file /path/to/input.pgm.new
$ mv /path/to/input.pgm.new /path/to/input.pgm

mv is the irreversible step in this workflow because it removes the old pathname. If verification fails, leave the original alone and remove the incomplete .new file after checking its path. If you overwrote a file without a backup, stop processing and recover it from your normal backup or snapshot system; pnmgamma has no undo operation.

6. Use the legacy form only for compatibility

The manual documents an older syntax for the default exponential transfer function and the ramp options. A single positional gamma value is accepted in that form:

$ pnmgamma 2.2 /path/to/input.pgm > /path/to/output.pgm

The old form is also used with -bt709ramp or -srgbramp. The manual calls -cieramp an obsolete synonym for -bt709ramp. Prefer the named modern conversions when they express what you need, and retain the old form only when a script or documented workflow requires it.

A common trap is mixing syntaxes. The installed command rejects -gamma=... when no modern transfer option is present, because the default form expects its gamma as a positional parameter. Conversely, do not put a positional gamma after a modern conversion option. If a command fails, capture its status and read the diagnostic before changing the image:

$ pnmgamma -gamma=2.2 /path/to/input.pgm > /tmp/test.pgm
pnmgamma: With this function, you specify the gamma values in arguments, not with the -gamma, etc.
$ printf '%s\n' "$?"
1