Build a Four-Corner PAM Gradient with pamgradient

You will finish with a PAM image whose four corners blend smoothly between colours you choose, plus checks for its dimensions, tuple type and sample depth. The examples use Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a shell, the pamgradient command from Netpbm, and a writable working directory. The workflow writes new image files but does not need elevated privileges. Do not use sudo unless your chosen output directory is deliberately restricted.

1. Check the installed command

Confirm the executable and package before relying on its output. These are ordinary, read-only checks:

$ command -v pamgradient
/usr/bin/pamgradient
$ pamgradient --version
pamgradient: 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 version text contains build details that vary by distribution, so the useful checkpoint is the Netpbm version and the package version. The command's documented shape is four corner colours followed by width and height.

2. Generate a small colour gradient

Give the corners in this order: top left, top right, bottom left, bottom right. Redirect standard output to a new file. This example produces a 4 by 3 image:

$ pamgradient red green blue white 4 3 > gradient.pam
$ pamfile gradient.pam
gradient.pam: PAM, 4 by 3 by 3 maxval 255
    Tuple type: RGB

A successful command normally prints no progress message because the image is written to standard output. The pamfile result confirms four columns, three rows, three channels and the RGB tuple type. Open the file with an image viewer that supports PAM, or convert it with a separate Netpbm tool if you need PNG or another delivery format.

Checkpoint: the file should be non-empty and identified as PAM. If the shell reports that pamgradient is missing, stop here and install Netpbm through your normal package-management process. Do not work around a missing executable by guessing a different generator's option syntax.

3. Use colour names that the parser accepts

The four colour arguments use Netpbm's colour-name parser. Common names such as red, green, blue, white and black are straightforward. Keep each argument as one shell word. If a colour specification contains shell-significant characters or spaces, quote it and test it on a small image before using it in a batch.

Do not confuse the argument order with a clockwise list. The third argument is the bottom-left corner, not the next colour along the top edge. A swapped pair can still produce a valid image, which makes this a visual error rather than a command failure.

$ pamgradient black yellow white red 8 6 > corners.pam
$ file corners.pam
corners.pam: Netpbm PAM image file, size = 8 x 6

The interpolation is two-dimensional, so pixels between the corners are blended in both directions. Integer arithmetic can leave the non-top-left corner samples slightly shifted from the exact requested values. That small implementation detail matters when comparing individual pixels, but it does not stop the image being a useful gradient.

4. Produce a grayscale PAM

If all four arguments are grayscale values, Netpbm emits a one-channel grayscale image. Named values such as black, white, gray50 and gray100 make the intent clear:

$ pamgradient black white gray50 gray100 3 2 > grey-gradient.pam
$ pamfile grey-gradient.pam
grey-gradient.pam: PAM, 3 by 2 by 1 maxval 255
    Tuple type: GRAYSCALE

This is a useful checkpoint when a downstream program expects one channel. If one corner is a named colour such as red, the result becomes RGB instead. Do not infer the tuple type from the filename; inspect the PAM header or use pamfile.

5. Set a lower maximum sample value

Use -maxval when the receiving tool or format needs a particular PAM sample range. The option accepts either an equals sign or whitespace, and the long option can use two hyphens:

$ pamgradient --maxval=31 red green blue white 4 3 > gradient-31.pam
$ pamfile gradient-31.pam
gradient-31.pam: PAM, 4 by 3 by 3 maxval 31
    Tuple type: RGB

The default shown by the installed command is maxval 255. A lower value changes the representation of every channel; it is not a display-only label. Verify the header after generation and make sure the consumer understands PAM with that maxval.

6. Protect an existing output

Shell redirection with > truncates its destination before the program runs. That is destructive if the filename already contains a useful image. Generate into a temporary name, check it, then replace the old file only when you have chosen to do so:

$ pamgradient red green blue white 640 480 > gradient.pam.new
$ pamfile gradient.pam.new
gradient.pam.new: PAM, 640 by 480 by 3 maxval 255
    Tuple type: RGB
$ mv gradient.pam.new gradient.pam

The mv command changes state and replaces the destination. Keep a backup first if the old file cannot be recreated:

$ cp --preserve=all gradient.pam gradient.pam.bak

To recover, move the backup back over the generated file after checking its path: mv gradient.pam.bak gradient.pam. Removing the backup is optional and irreversible, so do not include that deletion in an unattended example.

7. Diagnose a failed invocation

Dimensions must be positive. A zero width is rejected before an image is written:

$ pamgradient red green blue white 0 3 > bad.pam
pamgradient: Width argument must be a positive number.  You specified 0.

Check both dimensions and the four colour arguments before retrying. If the output file is empty after a failed redirection, remove that known incomplete file with rm -- bad.pam only after confirming its path. Never apply a broad wildcard cleanup to a directory that contains other work.

If pamfile cannot read the result, first check the exit status of the generating command and the file size. A valid-looking filename does not prove that the producer succeeded. For a pipeline or script, use set -o pipefail so a failure before the final consumer is not hidden.