Create a Test PGM Image with pgmmake

pgmmake builds a greyscale PGM at an exact width, height and brightness, which is exactly what you want for a known-good test input. Reach for it when testing an image pipeline, feeding another Netpbm command a predictable file, or checking how a viewer handles PGM. It writes to standard output, so the practical result is normally a new file made with shell redirection.

Allow about five minutes if Netpbm is already installed. The examples below use the Debian package netpbm version 11.5.2, which reports itself as Netpbm 11.5.2. Behaviour described here comes from the installed pgmmake(1) manual and a local run of the command.

The required arguments, in order, are:

1. graylevel: a decimal value from 0 to 1. Zero is black, one is white, and 0.5 is half-luminosity grey.
2. width: the image width in pixels.
3. height: the image height in pixels.

The optional -maxval sets the largest sample value in the PGM file, defaulting to 255. It changes the file's sample scale, not the width or height, which matters when the next tool in your pipeline expects a particular range.

1. Check that pgmmake is installed

Run this as your ordinary user; creating an image in a directory you can write needs no elevated privileges.

command -v pgmmake
pgmmake --version 2>&1 | head -4

On the package version used for this guide, the second command starts with output like this:

pgmmake: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pgmmake: Built from source dated 2024-03-31 09:09:47

The manual page is the useful reference for options. --version is not a documented image-generation option; the installed program just accepts it as a way to print build information before exiting.

2. Create a small grey image

Redirect standard output to a new file. This makes a 100 by 60 pixel image at half brightness:

pgmmake 0.5 100 60 > grey-100x60.pgm

The command is silent on success, since the image bytes go straight to the file. Verify both that the file exists and that its PGM header carries the right dimensions and default maximum value:

file grey-100x60.pgm
head -c 32 grey-100x60.pgm | od -An -c

Expect file to identify a Netpbm greyscale image, and the header to contain P5, 100 60 and 255. The remaining bytes are pixels; do not open them in a text editor, since a PGM can carry binary sample data.

3. Choose a different brightness and sample range

This makes a 50 by 100 image at 20 per cent brightness, with sample values from 0 through 5:

pgmmake .2 50 100 -maxval=5 > dim-50x100-max5.pgm

The option also accepts a space instead of an equals sign:

pgmmake 0.8 50 50 -maxval 100 > bright-50x50-max100.pgm

For the first command, the header should show P5, 50 100 and 5. The short decimal form .2 is accepted fine. Keeping the grey level between 0 and 1 sidesteps a range error and makes the brightness you asked for unambiguous.

4. Verify the file without opening it

For a quick check, ask Netpbm's pgmfile to parse the result if it is installed:

pgmfile grey-100x60.pgm

It should report a 100 by 60 PGM with maxval 255. No pgmfile available? Inspect the header directly instead:

od -An -c -N 32 grey-100x60.pgm

Common traps and failures

pgmmake does not take an output filename. A command such as pgmmake 0.5 100 60 result.pgm supplies a fourth positional argument and fails outright. Use > to save standard output, or pipe it to another program.

Redirection needs care too. The shell opens the destination before pgmmake runs, and > truncates an existing file the moment it does. If the filename matters, use a new name, or enable noclobber for the session:

set -o noclobber
pgmmake 0.5 100 60 > result.pgm

With noclobber on, an existing file is not overwritten. Run set +o noclobber afterwards to put normal shell behaviour back. If you genuinely need to replace a test file, check its path first and use >| only when that overwrite is deliberate.

A value outside the documented grey-level range, a non-positive dimension, or an invalid maximum value produces an error rather than a useful image. Read the diagnostic, fix one argument at a time, and rerun. Nothing about this changes system configuration, and there is no service to restart.

5. Clean up test files

Only remove files you created for this exercise, and check the names before you delete them:

ls -l -- grey-100x60.pgm dim-50x100-max5.pgm bright-50x50-max100.pgm
rm -- grey-100x60.pgm dim-50x100-max5.pgm bright-50x50-max100.pgm