Add Reproducible Noise to Netpbm Images with pamaddnoise

You will finish with a repeatable command for adding noise to a PGM, PPM or other Netpbm image, plus a quick check that the output is readable. The examples use Netpbm 11.5.2, installed here as package version netpbm 2:11.05.02-1.1build1. Allow about ten minutes if your input image is ready.

You need the netpbm package, a readable Netpbm input file and a writable destination directory. The work is normally unprivileged. Do not use sudo unless filesystem permissions genuinely require it. This guide writes new output files and leaves the input untouched.

1. Check the installed command

Confirm which executable is being used and record the installed package version:

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

The command accepts one optional input filename. If you omit it, it reads a Netpbm image from standard input. Its default noise type is gaussian. A successful command writes the resulting image to standard output, so redirect that output to a deliberately new pathname.

Checkpoint: make sure the input is actually a Netpbm image before adding noise:

$ pamfile /path/to/input.pgm
/path/to/input.pgm: PGM raw, 640 by 480  maxval 255

Your dimensions and whether the file is PGM, PPM or PAM will differ. If pamfile cannot identify it, stop and fix the input path or format first.

2. Add the default Gaussian noise

For a first run, use a new output filename and a fixed seed:

$ pamaddnoise -seed 42 /path/to/input.pgm > /path/to/input-noisy.pgm

The seed makes the random sequence repeatable for the same input and options. It is useful for tests, documentation and comparing parameter changes. It is not encryption and does not make an image confidential.

Verify the output instead of assuming that a created file is valid:

$ pamfile /path/to/input-noisy.pgm
/path/to/input-noisy.pgm: PGM raw, 640 by 480  maxval 255
$ test -s /path/to/input-noisy.pgm && echo 'output is non-empty'
output is non-empty

The installed defaults for Gaussian noise are -sigma1 4.0 and -sigma2 20.0. The first controls the standard deviation of the component scaled by the square root of each sample; the second controls the component added directly. These values can push samples towards the image's permitted range, so inspect the result rather than treating them as harmless brightness adjustments.

3. Make impulse noise predictable

Impulse noise is the familiar salt-and-pepper effect. Set the fraction of samples changed with -tolerance. Set -salt to control the fraction of changed samples that become maximum brightness; the rest become zero.

$ pamaddnoise -type impulse -tolerance 0.10 -salt=0.5 -seed 7 \
    /path/to/input.pgm > /path/to/input-salt-pepper.pgm

The command above changes about ten per cent of samples, with an even split between the two extremes. The manual's default tolerance is 0.10, and the default salt fraction is 0.5, but stating them explicitly makes a script easier to review.

Run the same command twice when you need evidence that a test is reproducible:

$ pamaddnoise -type impulse -tolerance 0.10 -salt=0.5 -seed 7 /path/to/input.pgm > /tmp/noisy-a.pgm
$ pamaddnoise -type impulse -tolerance 0.10 -salt=0.5 -seed 7 /path/to/input.pgm > /tmp/noisy-b.pgm
$ cmp --silent /tmp/noisy-a.pgm /tmp/noisy-b.pgm && echo identical
identical

Files under /tmp are convenient for a short test, but do not use them as the only copy of a result you need to retain.

4. Choose another noise model

The installed command also supports multiplicative_gaussian, laplacian and poisson. Their parameters apply only to their matching type. Supplying an option for a different model is a distraction and may be rejected, so keep the type and its parameter together in a reviewed command.

$ pamaddnoise -type poisson -lambda 12 -seed 3 \
    /path/to/input.pgm > /path/to/input-poisson.pgm
$ pamfile /path/to/input-poisson.pgm
/path/to/input-poisson.pgm: PGM raw, 640 by 480  maxval 255

For Poisson noise, -lambda is the expected value at maximum intensity and defaults to 12. Laplacian noise uses -lsigma, which defaults to 10.0. Multiplicative Gaussian noise uses -mgsigma, which defaults to 0.5. The default Gaussian model instead uses -sigma1 and -sigma2.

5. Use standard input safely

Because the input filename is optional, you can put another Netpbm command before pamaddnoise. Keep the output redirection at the end so the pipeline's final image is saved:

$ cat /path/to/input.pgm | pamaddnoise -type poisson -lambda 12 -seed 3 > /path/to/piped-noisy.pgm
$ pamfile /path/to/piped-noisy.pgm
/path/to/piped-noisy.pgm: PGM raw, 640 by 480  maxval 255

A pipeline can hide which command failed unless you check its status. In Bash, use pipefail when the input producer matters:

set -o pipefail
cat /path/to/input.pgm | pamaddnoise -seed 42 > /path/to/piped-noisy.pgm
status=$?
printf 'pipeline status: %s\n' "$status"
exit "$status"

This example does not require elevated privileges. Treat a non-zero status as a failed conversion and inspect the error before using the destination.

6. Avoid overwriting and recover from a failed run

Shell redirection with > truncates an existing destination before pamaddnoise starts. That is the main destructive trap in this workflow. Prefer a new name:

$ pamaddnoise -seed 42 /path/to/input.pgm > /path/to/input-noisy.pgm.new
$ pamfile /path/to/input-noisy.pgm.new
$ mv /path/to/input-noisy.pgm.new /path/to/input-noisy.pgm

The final mv is only appropriate after the verification succeeds and the destination is the result you intend to publish or keep. If the command fails, do not move the partial file. Remove only that known temporary pathname, for example rm /path/to/input-noisy.pgm.new; the original input and any existing final output remain untouched. If you already redirected over a useful output, recovery requires a backup or snapshot. pamaddnoise has no undo operation.