Build a Four-Corner PAM Gradient with pamgradient

pamgradient generates a PAM image whose four corners blend smoothly into colours you pick, ready to check for dimensions and tuple type. The examples use Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command
2. Generate a small colour gradient
3. Use colour names the parser accepts
4. Produce a greyscale PAM
5. Set a lower maximum sample value
6. Protect an existing output
7. Diagnose a failed invocation

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 needs no elevated privileges, do not use sudo unless your output directory is deliberately restricted.

1. Check the installed command

Confirm the executable and package before trusting 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 carries build details that vary by distribution, so the useful bit 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 run normally prints no progress message, the image just goes 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 pamgradient missing, stop here and install Netpbm through your normal package-management process, do not work around a missing executable by guessing at a different generator's option syntax.

3. Use colour names 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, and quote and test on a small image first if a colour specification contains shell-significant characters or spaces.

Tip

Do not read the argument order as a clockwise list. The third argument is the bottom-left corner, not the next colour along the top edge. A swapped pair still produces 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 blend 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 greyscale PAM

If all four arguments are greyscale values, Netpbm emits a one-channel greyscale 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

Useful checkpoint when a downstream program expects one channel. Slip in a named colour such as red for even one corner, though, and the result becomes RGB instead. Do not infer the tuple type from the filename, check 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 form 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 just a display-only label. Verify the header after generation and make sure whatever consumes it understands PAM at that maxval.

6. Protect an existing output

Warning

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

$ 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

That mv 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

Recovery

Move the backup back over the generated file after checking its path, mv gradient.pam.bak gradient.pam. Removing the backup afterwards is optional and irreversible, so do not fold that deletion into an unattended example.

7. Diagnose a failed invocation

Dimensions must be positive. A zero width gets 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 all four colour arguments before retrying. If the output file is empty after a failed redirection, remove that known incomplete file with rm -- bad.pam, but only after confirming its path. Never run a broad wildcard cleanup in a directory that holds other work.

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

Done means

You know the installed Netpbm and pamgradient versions.
The four arguments are in top-left, top-right, bottom-left, bottom-right order.
pamfile confirms the expected dimensions, tuple type and maxval.
All-greyscale corners produced GRAYSCALE; mixed corners produced RGB.
Existing images were protected by generating to a new name before replacement.
No elevated privileges or persistent system changes were needed.