Build Verified Greyscale Test Ramps with pgmramp

You will generate a PGM image containing a black-to-white ramp, select its direction or shape, and verify the dimensions and maximum sample value before using it elsewhere. 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 working directory. The commands are ordinary user commands. No example needs sudo, because pgmramp only writes image data to standard output and does not change system configuration.

1. Check the installed command

Confirm that the command is the one provided by Netpbm and record its version. This is 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 installed manual requires exactly one ramp type followed by width and height. The output is a graymap in PGM format. It goes to standard output, so a redirect is normally part of the command.

2. Generate a left-to-right ramp

Start with a small image whose header is easy to inspect:

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

-lr means black at the left and white at the right. The default maxval is 255, so each pixel sample is in the usual 8-bit range. pamfile is a separate Netpbm utility; its wording can vary slightly, but the useful checks are the PGM type, the dimensions and the maximum value.

Checkpoint: if the command returned success and pamfile reports the expected geometry, you have a usable test image. The file is binary PGM, so do not expect all of its pixel data to be readable in a text editor.

3. Choose a different ramp shape

Use one of the other documented shapes when the test needs a different spatial relationship:

• -tb: black at the top and white at the bottom.
• -rectangle: black around the outside edges, becoming white towards the centre in a rectangular pattern.
• -ellipse: black around the outside edge, becoming white towards the centre in an elliptical pattern.
• -diagonal: black at the top-left corner and white at the bottom-right corner.

For example, this creates a diagonal ramp with a deliberately small 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

In this command, -maxval=15 changes the largest sample value from the default 255 to 15. The option can also be written as -maxval 15. The diagonal option was added in Netpbm 10.66, so an older installation may reject it even though it is present in the installed manual 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 selected distance. That is not the same as a ramp that is linear in physical light intensity. If the latter is required for a test or calculation, pass the result through pnmgamma using the gamma correction appropriate to the workflow. Do not infer a physically linear light source from the visual appearance of this file alone.

The output is useful as an input to other Netpbm operations. For example, the documented pattern below creates a right-to-left ramp by flipping a left-to-right one:

$ 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

For a simple sequence of values from zero to a maximum, rather than a graphic image with two-dimensional geometry, use 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 runs. Treat that as a destructive step when the filename already contains useful work. Write to a new temporary name in the same directory, verify it, then replace the destination only if the 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

The final mv replaces ramp.pgm if it already exists. If generation or verification fails, leave the original in place and remove the unneeded ramp.pgm.new manually after checking that it is the file you meant to discard. Do not use a broad wildcard for cleanup.

6. Diagnose the common mistakes

If you omit the ramp type, the installed command exits non-zero and reports that one of -lr, -tb, -diagonal, -rectangle or -ellipse is required. Supply exactly one. Supplying two is not a way to combine shapes.

If a later tool cannot read the result, first check the file header and exit status:

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

Also check that the dimensions and maxval match the values you intended. A successful process exit only says that pgmramp completed; it does not prove that a downstream operation wanted that size, orientation or sample range.

Options may be abbreviated to their shortest unique prefix, and Netpbm accepts one or two hyphens plus either whitespace or an equals sign before an option value. Full option names and the conventional single hyphen are clearer in shared scripts. Keep the dimensions as separate positive arguments and quote a path if you later wrap the command in a script.