Build a Gaussian Convolution Kernel with pamgauss

You will create a two-dimensional Gaussian image as a PAM file, inspect its header, and prepare it for use as a convolution kernel. The examples use Netpbm 11.5.2, as installed on this machine. Allow about ten minutes if Netpbm is already installed and you are working in a scratch directory.

1. Check the installed command

You need the netpbm package and a writable working directory. No step in this guide needs root privileges. Check which executable will 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 contains build details. The manual page installed with this package describes the options used here. Releases before Netpbm 10.79 do not have -maximize or the documented oversampling behaviour, so do not silently apply this guide's option set to 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 makes a tighter centre, while a larger value spreads the function over more pixels.

For a kernel, choose dimensions large enough that the Gaussian has 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 may still clip the tails. Clipping does not make the command fail; it changes the mathematical kernel you get.

There is a practical trade-off here. A kernel that is too small wastes the outer part of the curve. A very large 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 chooses an amplitude so the sum of the samples is the image maxval, within rounding error. That is normally the useful interpretation for a convolution kernel. Set the tuple type to GRAYSCALE so Netpbm tools can treat the one-plane PAM as a greyscale image.

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

The redirection creates or truncates gauss-11x11.pam before pamgauss runs. Do not use this command with a valuable existing output unless overwriting it is deliberate. Choose 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 with a short command:

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

Checkpoint: the kernel file

At this point you should 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 be much lower than maxval.

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 not the same as 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 use a maximised image with pnmconvol, follow the manual's pattern: convert it to a PNM format if needed, use -nooffset, and add -normalize. The normalisation step rescales the samples with more precision than can be retained in the PAM file. Always apply the kernel to a real input image large enough for the chosen kernel; 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 disables this averaging and uses the value at each pixel centre.

For ordinary kernels, leave the default in place. Set an explicit value when reproducibility matters or when you are 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 the meaning of sigma.

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

Because shell redirection opens the destination first, an invalid command can still 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

The mv replaces the destination if it already exists, so use it only after checking the temporary file. If generation fails, remove the incomplete .new file once you have confirmed that it is not needed. The original destination remains untouched when the command wrote only to the temporary name.

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