Create Repeatable PPM Patterns with ppmpat

You will finish with a small, verified PPM image generated by Netpbm's ppmpat, plus a command you can rerun to get the same pixels. This is useful for test fixtures, wallpapers, demonstrations and image-processing pipelines.

Allow about ten minutes. You need a shell, the Netpbm package, and a directory where you can write the output. The examples use Netpbm 11.5.2, reported by the installed command on this machine. They do not need elevated privileges. Do not use sudo unless filesystem permissions, rather than ppmpat, are the actual problem.

1. Check the installed command

Confirm which executable will run and record its Netpbm version. These are read-only checks:

$ command -v ppmpat
/usr/bin/ppmpat
$ ppmpat --version
ppmpat: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
ppmpat: Built from source dated 2024-03-31 09:09:47

The version text includes build details, so the exact lines can vary between distributions. The important check is that the command is present and identifies the library version you are about to rely on.

Checkpoint: if command -v prints nothing, install Netpbm through your normal package-management process before continuing. Do not copy an image command from a different host and assume its pattern options match.

2. Generate a simple coloured pattern

Choose one pattern option, then provide width and height as the final two arguments. This command creates an 800 by 600 PPM using a two-colour gingham pattern:

$ ppmpat -gingham2 -color 'navy,white' 800 600 > gingham.ppm
$ file gingham.ppm
gingham.ppm: Netpbm image data, size = 800 x 600, rawbits, pixmap

The colour-list option takes a comma-separated list. For -gingham2, the list must contain two colours, background first and foreground second. Names such as navy and white are parsed by Netpbm's colour parser. Quoting the whole list prevents the shell from treating punctuation as part of your command syntax.

The output is written to standard output, so > sends it to a file. Shell redirection truncates an existing destination before ppmpat runs. If the file matters, use a new name or a temporary file and rename it only after verification:

$ ppmpat -gingham2 -color 'navy,white' 800 600 > gingham.ppm.new
$ file gingham.ppm.new
$ mv gingham.ppm.new gingham.ppm

The final mv replaces the old file. That replacement is the state-changing step, so keep the old file until the new image has passed your checks. To recover before the move, simply leave the old file in place and remove the unneeded .new file with your normal file-management command.

3. Make generated output reproducible

Without a seed, ppmpat derives randomness from the time of day and process ID. That is suitable for varied decorative images, but inconvenient for tests. Add -randomseed when you need repeatable output:

$ ppmpat -poles -color 'black,red,orange' -randomseed 42 320 200 > poles-a.ppm
$ ppmpat -poles -color 'black,red,orange' -randomseed 42 320 200 > poles-b.ppm
$ sha256sum poles-a.ppm poles-b.ppm
same-digest poles-a.ppm
same-digest poles-b.ppm

Your digest will be different from this illustrative output, but the two lines should contain the same digest. A seed makes separate invocations reproducible for the same program and input parameters. It is not a security token and does not make the image cryptographically random.

Checkpoint: if the digests differ, compare the complete commands, including pattern, colours, dimensions and seed. Also check that both files were produced by the same installed Netpbm version.

4. Pick the colour count that matches the pattern

Pattern options have different colour requirements. -gingham3, -madras and -tartan take three colours. -poles takes two or more, while -squig, -camo and -anticamo take three or more. The two argyle patterns have fixed requirements: -argyle1 takes two, and -argyle2 takes three.

For a woven-looking gingham, add -mesh. It changes the intersections in the gingham, madras and tartan patterns from averaged colour blocks to checkerboard areas made from the two intersecting colours:

$ ppmpat -gingham3 -mesh -color 'ivory,red,blue' -randomseed 42 320 200 > woven.ppm
$ file woven.ppm
woven.ppm: Netpbm image data, size = 320 x 200, rawbits, pixmap

-mesh has no effect on other pattern types. Treat a diagnostic saying it was ignored as a command-line mistake to review, not as proof that the requested pattern changed.

5. Reduce a busy image when needed

Some patterns use many colours. If a simpler palette is more useful, pipe the PPM to pnmquant after generation:

$ ppmpat -squig -randomseed 42 640 360 > squig.ppm
$ pnmquant 16 squig.ppm > squig-16.ppm
$ file squig-16.ppm
squig-16.ppm: Netpbm image data, size = 640 x 360, rawbits, pixmap

This creates a second file and leaves the source image unchanged. Check the output visually or with the next tool in your pipeline. Quantisation changes colours, so keep the original if exact source pixels matter.

6. Diagnose failed commands

A wrong colour count is rejected. For example, -gingham2 needs two colours:

$ ppmpat -gingham2 -color red 4 4 > failed.ppm
ppmpat: Wrong number of colors: 1. 2 colors are required for the specified pattern.

The installed diagnostic uses its US spelling; that is program output, not prose. Supply the count required by the selected pattern. If a failed command redirected output, inspect the file before using it and replace it with a successful run rather than assuming a non-zero exit left a valid image.

For a quick structural check, file should report the expected dimensions and a PPM image. The PPM header starts with P6 for the raw format commonly emitted here, followed by the width, height and maximum value. Pixel data is binary, so do not edit the file in a text editor. If you need a display format, convert the verified PPM with another installed Netpbm tool, such as pnmtopng, rather than changing the generator command.