Build Verified Greyscale Test Ramps with pgmramp

pgmramp generates a PGM image with a black-to-white ramp across it, in whichever direction or shape you pick. The examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, the netpbm package and a writable directory. These are ordinary user commands: pgmramp only writes image data to standard output, so nothing here touches system configuration and nothing needs sudo.

1. Check the installed command

Confirm you have the Netpbm build and note its version, a read-only checkpoint:

$ command -v pgmramp
/usr/bin/pgmramp
$ pgmramp -version 2>&1 | sed -n '1p'
pgmramp: 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 manual requires exactly one ramp type, followed by a width and a height. Output is a graymap in PGM format, sent to standard output, so a redirect is normally part of every call.

2. Generate a left-to-right ramp

Start small so the header is easy to read by eye:

$ pgmramp -lr 4 2 > ramp-lr.pgm
$ pamfile ramp-lr.pgm
ramp-lr.pgm: PGM raw, 4 by 2  maxval 255

-lr means black on the left, white on the right. The default maxval is 255, the ordinary 8-bit range. pamfile is a separate Netpbm utility and its exact wording can vary, but what matters is the PGM type, the dimensions and the maximum value it reports.

3. Choose a different ramp shape

• -tb puts black at the top and white at the bottom.
• -rectangle keeps black around the outside edges, brightening towards the centre in a rectangular pattern.
• -ellipse does the same thing but in an elliptical pattern.
• -diagonal runs black at the top-left corner to white at the bottom-right.

This example builds a diagonal ramp with a deliberately narrow sample range:

$ pgmramp -diagonal -maxval=15 3 3 > ramp-diagonal.pgm
$ pamfile ramp-diagonal.pgm
ramp-diagonal.pgm: PGM raw, 3 by 3  maxval 15

-maxval=15 drops the largest sample value from the default 255 down to 15; you can also write it as -maxval 15. The diagonal option arrived in Netpbm 10.66, so an older install may reject it even though it shows up in the manual installed here. Check the local version before copying a script to an older host.

4. Keep the ramp's meaning straight

pgmramp makes sample values rise linearly in brightness across the chosen distance. That is not the same thing as a ramp that is linear in physical light intensity. Need the latter for a calculation or a test? Pipe the result through pnmgamma with the gamma correction your workflow actually needs, rather than assuming linear light from how the file looks on screen.

The output is a handy input to other Netpbm operations. For instance, this documented pattern flips a left-to-right ramp to build a right-to-left one instead:

$ pgmramp -lr 100 100 | pamflip -lr > ramp-right-to-left.pgm
$ pamfile ramp-right-to-left.pgm
ramp-right-to-left.pgm: PGM raw, 100 by 100  maxval 255

Need a simple sequence of values from zero to a maximum, rather than a two-dimensional image, reach for pamseq instead. For a colour fade between two chosen colours, use ppmrainbow.

5. Avoid losing an existing output

Shell redirection with > truncates an existing destination before pgmramp even runs, so treat that as destructive whenever the filename already holds useful work. Write to a new temporary name first, check it, then replace the destination only once that check passes:

$ pgmramp -tb 640 480 > ramp.pgm.new
$ pamfile ramp.pgm.new
ramp.pgm.new: PGM raw, 640 by 480  maxval 255
$ mv -- ramp.pgm.new ramp.pgm

6. Diagnose the common mistakes

Omit the ramp type and pgmramp exits non-zero, reporting that one of -lr, -tb, -diagonal, -rectangle or -ellipse is required. Supply exactly one: giving two is not a way to blend shapes.

$ test -s ramp.pgm && echo 'output is non-empty'
output is non-empty
$ pamfile ramp.pgm

A downstream tool rejecting the result? Check the file header and exit status first, then confirm the dimensions and maxval actually match what you intended. A successful process exit only proves pgmramp completed; it says nothing about whether a later operation wanted that size, orientation or sample range.

Options can be abbreviated to their shortest unique prefix, and Netpbm accepts one or two hyphens with either a space or an equals sign before a value. Full option names and a conventional single hyphen read more clearly in anything shared. Keep dimensions as separate positive arguments, and quote a path if you wrap the command in a script later.