Build a Gaussian Convolution Kernel with pamgauss

pamgauss builds a two-dimensional Gaussian image as a PAM file, ready to inspect and use as a convolution kernel for blurring another image. The examples use Netpbm 11.5.2, as installed on this machine. Allow about ten minutes if Netpbm is already installed and you have a scratch directory to work in.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command
2. Choose the image size and spread
3. Create a normalised Gaussian PAM
4. Use maximize only for a deliberate peak-value image
5. Control sampling when the curve is tight
6. Diagnose failures and recover safely

1. Check the installed command

You need the netpbm package and a writable working directory. Nothing in this guide needs root. Check which executable will actually run, and record its library version:

$ command -v pamgauss
/usr/bin/pamgauss
$ pamgauss --version
pamgauss: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version output also carries build details. The manual page installed with this package describes the options used here. Releases before Netpbm 10.79 lack -maximize and the documented oversampling behaviour, so do not assume this guide's option set works unchanged on an old installation.

2. Choose the image size and spread

width and height are positional arguments.
-sigma is required and has no default. It is the standard deviation in sample units: a smaller value gives a tighter centre, a larger value spreads the function over more pixels.

For a kernel, pick dimensions large enough that the Gaussian has actually reached zero at the edges. A 7 by 7 image with sigma 0.5 is a compact demonstration. An 11 by 11 image with sigma 2 is broader, but can still clip the tails. Clipping does not make the command fail, it just changes the mathematical kernel you end up with.

There is a real trade-off here. Too small a kernel wastes the outer part of the curve. Too large a kernel costs more when it is applied. Start with a size that matches the blur you need, then inspect the result rather than guessing from the filename.

3. Create a normalised Gaussian PAM

Without -maximize, pamgauss picks an amplitude so the sum of the samples equals the image maxval, within rounding error. That is normally the useful interpretation for a convolution kernel. Set the tuple type to GRAYSCALE so other Netpbm tools treat the one-plane PAM as a greyscale image.

$ pamgauss 11 11 -sigma=2 -tupletype=GRAYSCALE > gauss-11x11.pam

Warning

The redirection creates or truncates gauss-11x11.pam before pamgauss even runs. Do not aim this at a valuable existing file unless overwriting it is deliberate, pick a new filename or make a backup first.

Verify the output without opening its binary sample data in a text editor:

$ pamfile gauss-11x11.pam
gauss-11x11.pam: PAM, 11 by 11 by 1 maxval 255
    Tuple type: GRAYSCALE

The exact wording can vary slightly, but check the dimensions, one plane, maxval and tuple type. The PAM header is also readable directly:

$ sed -n '1,7p' gauss-11x11.pam
P7
WIDTH 11
HEIGHT 11
DEPTH 1
MAXVAL 255
TUPLTYPE GRAYSCALE
ENDHDR

Checkpoint

You should now have a non-empty PAM file whose centre is brighter than its edges. The default maxval is 255. The manual recommends 65535 in most cases, but some non-Netpbm programs cannot handle values above 255. If precision matters and the next tool supports it, create the file explicitly with -maxval=65535:

$ pamgauss 11 11 -sigma=2 -maxval=65535 -tupletype=GRAYSCALE > gauss-11x11-16bit.pam
$ pamfile gauss-11x11-16bit.pam

Do not confuse maxval with the peak of the default kernel. Without -maximize, the total volume is scaled to maxval, so individual samples can sit well below it.

4. Use maximize only for a deliberate peak-value image

-maximize changes the amplitude so the largest sample reaches the selected maxval. That is useful when you need the available sample range for inspection or another operation, but it is a different thing entirely from the volume-normalised kernel above.

$ pamgauss 7 7 -sigma=.5 -maximize -tupletype=GRAYSCALE > gauss-7x7-max.pam
$ pamfile gauss-7x7-max.pam
gauss-7x7-max.pam: PAM, 7 by 7 by 1 maxval 255
    Tuple type: GRAYSCALE

If you plan to feed a maximised image into pnmconvol, follow the manual's pattern: convert it to a PNM format if needed, use -nooffset, and add -normalize. That normalisation step rescales the samples with more precision than the PAM file itself can hold. Always apply the kernel to a real input image large enough for it, a 7-row input cannot be convolved with a 7-row kernel.

5. Control sampling when the curve is tight

pamgauss averages samples from the continuous Gaussian to represent each output pixel. -oversample controls how many points it samples horizontally and vertically. The default is five divided by sigma, rounded up. -oversample=1 switches off that averaging and just uses the value at each pixel centre.

Leave the default in place for ordinary kernels. Set an explicit value when reproducibility matters, or when comparing output generated on different systems:

$ pamgauss 7 7 -sigma=.5 -oversample=10 -tupletype=GRAYSCALE > gauss-7x7-sampled.pam

A larger value costs more computation but can describe a tight Gaussian more faithfully. It does not enlarge the output or change what sigma means.

6. Diagnose failures and recover safely

A missing or non-positive sigma is an input error, for example:

$ pamgauss 7 7 -sigma=0 > /tmp/unused.pam
pamgauss: -sigma must be positive.  You specified 0.000000

Warning

Shell redirection opens the destination first, so even an invalid command can truncate an existing destination. Use a new path while testing, or write to a temporary file and rename it only after verification:

$ pamgauss 11 11 -sigma=2 -tupletype=GRAYSCALE > gauss-11x11.pam.new
$ pamfile gauss-11x11.pam.new
$ mv -- gauss-11x11.pam.new gauss-11x11.pam

Recovery

That mv replaces the destination if it already exists, so run it only after checking the temporary file. If generation fails, remove the incomplete .new file once you have confirmed it is not needed, the original destination stays untouched as long as the command only ever wrote to the temporary name.

If another program rejects the file, check its accepted formats and maxval before changing the kernel. Convert PAM with an installed Netpbm tool such as pamtopnm only when the consumer actually requires PGM or another PNM format, and keep the PAM source until the converted output has been checked.

Done means

pamgauss resolves to the intended Netpbm installation.
-sigma, dimensions, tuple type, maxval and oversampling match the job.
pamfile reports the expected dimensions, depth, maxval and greyscale tuple type.
The output was written to a new or deliberately replaceable path.
A convolution consumer uses -nooffset, with -normalize where a maximised kernel needs rescaling.