Create a Test PGM Image with pgmmake

Use pgmmake to produce a greyscale PGM image with an exact width, height and brightness. This is useful for testing image pipelines, creating a known input for another Netpbm command, or checking how a viewer handles PGM files. The command writes the image 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.

Checkpoint: know what the arguments mean

The required arguments are, in order:

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. Its default is 255. It changes the file's sample scale, not the width or height, and is useful when the next tool expects a particular range.

1. Check that pgmmake is installed

Run this as your ordinary user. No elevated privileges are needed to create an image in a directory you can write.

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 accepts it as a way to print its build information and then exits.

2. Create a small grey image

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

pgmmake 0.5 100 60 > grey-100x60.pgm

The command is silent on success because the image bytes go to the file. Verify both that the file exists and that its PGM header contains the 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 the pixels. Do not use a text editor to inspect them: a PGM can contain 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 can also use a space instead of an equals sign:

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

In the first command, the header should contain P5, 50 100 and 5. The short decimal form .2 is accepted. Keeping the value between 0 and 1 prevents a range error and makes the requested brightness unambiguous.

Checkpoint: 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. If pgmfile is unavailable, inspect the header directly instead:

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

The first three header fields should be recognisable as P5, the dimensions and the maximum sample value. Header whitespace varies, so do not compare the whole byte sequence with a fixed string.

Common traps and failures

Remember that 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. Use > to save standard output, or pipe it to another program.

Be careful with redirection. The shell opens the destination before pgmmake runs, and > truncates an existing file. If the filename matters, use a new name or add noclobber for this shell session:

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

If the file already exists, this refuses to overwrite it. To restore the normal shell behaviour afterwards, run set +o noclobber. If you deliberately need to replace a test file, check its path first and use >| only when that overwrite is intentional.

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. Check the diagnostic, correct one argument at a time, and rerun the command. No system configuration is changed, and there is no service to restart.

Clean up test files

Only remove files you created for this exercise, and check the names before deleting 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

rm is irreversible through the shell. If you need the images later, keep them or move them to a known directory instead. There is no need for sudo unless you chose a directory that your user cannot write, and using a user-writable working directory is safer.