Generate Reproducible PBM Noise with pbmnoise

Need a stress-test image with no structure to it at all, or a repeatable fixture for a test suite? pbmnoise builds a PBM bitmap at whatever dimensions and black-pixel ratio you choose, with an optional seed that makes the result identical every time.

The examples use the Netpbm package installed here, version 2:11.05.02-1.1build1. Allow about ten minutes. You need a shell, the pbmnoise command, and a directory where you can create a new output file.

No service, system setting or input image is required: this command creates a new image, it does not edit an existing one, and nothing here needs elevated privileges.

1. Check the installed command

Confirm the executable and package are the ones you expect. Both checks below are read-only:

$ command -v pbmnoise
/usr/bin/pbmnoise
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The command takes two positional arguments, width and height, and writes a PBM image to standard output, so a shell redirection is normally part of the command. PBM is a black-and-white bitmap format, not a greyscale or colour one.

2. Generate a small test image

Start with a new filename and a modest size. This creates a 320 by 200 image at the default ratio:

$ pbmnoise 320 200 > noise-320x200.pbm
$ file noise-320x200.pbm
noise-320x200.pbm: Netpbm image data, size = 320 x 200, rawbits, bitmap

The default black-pixel probability is one half, so a reasonably large image should come out roughly equal parts black and white; the exact count varies since the pixels are random. The file wording can differ slightly between systems, so just check the file is identified as a PBM bitmap with the requested dimensions.

Redirection with > truncates an existing destination before pbmnoise even starts. Treat an existing image as valuable: use a new name, or turn on the shell's no-clobber mode first:

$ set -o noclobber
$ pbmnoise 320 200 > noise-320x200.pbm
bash: noise-320x200.pbm: cannot overwrite existing file

Need to replace an image? Generate a separate file such as noise-320x200.new.pbm, check it, then move it over the old one deliberately. That move is the state-changing step, and there is no automatic undo for it.

3. Control the proportion of black pixels

Use -ratio=M/N to set the probability that each pixel is black. The denominator must be 1 or a power of two up to 65536, and the numerator cannot exceed the denominator. For roughly one third black pixels, use a nearby permitted fraction such as 11/32:

$ pbmnoise -ratio=11/32 1200 1200 > noise-one-third.pbm
$ file noise-one-third.pbm
noise-one-third.pbm: Netpbm image data, size = 1200 x 1200, rawbits, bitmap

Use -ratio=0/1 for an entirely white result and -ratio=1/1 for an entirely black one; the installed command accepts those explicit fractions. Worth knowing: on this installation, bare -ratio=0 and -ratio=1 get rejected as invalid ratios, even though the manual describes the endpoint values as 0 and 1. Writing the denominator sidesteps that version-specific trap.

A ratio controls probability, not an exact quota. On a small image, the measured proportion can drift noticeably from the requested fraction, so increase the dimensions when you need the aggregate result to sit closer to target.

4. Make a result repeatable

By default the seed comes from the time of day and process ID, so separate invocations normally produce different images. Supply -randomseed when a test, fixture or comparison needs identical bytes every time:

$ pbmnoise -randomseed=12345 320 200 > noise-seed-a.pbm
$ pbmnoise -randomseed=12345 320 200 > noise-seed-b.pbm
$ cmp --silent noise-seed-a.pbm noise-seed-b.pbm && echo 'same seed: identical output'
same seed: identical output

A seed makes the invocation repeatable on the same implementation and relevant machine behaviour, so keep dimensions, ratio, seed and endian setting unchanged when you are reproducing a file. Do not use a generated test image as evidence that a production random source is unpredictable; this option deliberately makes the stream repeatable, which is the opposite point.

5. Use pack for narrow images

Without -pack, the program generates pixels in 32-bit units and discards fractional pixels left at the end of each row. -pack carries those unused pixels into the next row instead, which can improve performance when the width is small, at the cost of some overhead:

$ pbmnoise -pack -randomseed=7 5 300 > narrow-packed.pbm
$ file narrow-packed.pbm
narrow-packed.pbm: Netpbm image data, size = 5 x 300, rawbits, bitmap

This is an output-generation choice, not a request to resize an image; the dimensions stay exactly what you gave on the command line. If you are comparing byte-for-byte fixtures, pick one setting and keep it fixed.

6. Keep cross-machine tests explicit

pbmnoise internally uses random 32-bit integers, and since byte order affects how those integers become pixel strings, the -endian option lets tests select big, little, native or swap. native is the default and leaves your machine's normal encoding unchanged.

Leave this option out for ordinary image generation. For a fixture shared between machines, record the exact Netpbm version, dimensions, ratio, seed, pack setting and endian mode alongside the expected file, otherwise a change in any one of those inputs can look exactly like a random failure.

7. Diagnose failures without guessing

A non-zero exit status means the command did not produce a valid result for your invocation. Check the dimensions first, then the ratio spelling. This deliberately invalid example shows the kind of diagnostic to expect:

$ pbmnoise -ratio=3/10 320 200 > rejected.pbm
pbmnoise: Denominator must be a power of two.  You specified 10.
$ echo $?
1

Do not treat a file created by shell redirection as proof of success: the shell may create or truncate the destination before the program rejects an option. If a command fails, check the exit status and inspect the file before using it, and generate into a disposable new name whenever you are testing unfamiliar arguments.

For a successful result, use file to check the format and dimensions, and pass the PBM to a separate Netpbm viewer or converter for a visual check. The generated PBM is binary, so avoid running cat on it in a terminal.