Build a Netpbm convolution kernel with pgmkernel

You will generate a PGM image containing a convolution kernel, check its format and dimensions, and save it safely for use with Netpbm tools such as pnmconvol. Allow about ten minutes. You need the netpbm package and a shell; the examples do not require root access.

1. Check the installed command

This guide follows the installed Netpbm 11.05.02 package, reported by the local package manager as 2:11.05.02-1.1build1. The local manual page is dated 19 December 2013. That combination matters when comparing another distribution or a newer Netpbm build, so check the command on the machine where the kernel will be used.

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

pgmkernel writes the PGM image to standard output. It does not choose an output filename for you. A failed run can therefore leave a partial file if shell redirection is aimed directly at a useful destination.

2. Generate a square kernel

Give one dimension for a square kernel. This example creates a 5 by 5 kernel in a new file:

$ pgmkernel 5 > kernel-5x5.pgm
$ file kernel-5x5.pgm
kernel-5x5.pgm: Netpbm image data, size 5 x 5, rawbits, greymap

The default output is raw PGM, also called binary PGM. Its header starts with P5; the remaining sample values are binary data, so do not expect the whole file to be readable in a text editor.

Checkpoint: confirm the header and dimensions without changing the file:

$ head -c 11 kernel-5x5.pgm | od -An -tc
   P   5  \n   5       5  \n   2   5   5  \n

The exact spacing in od output can vary. The meaningful fields are the P5 magic number, dimensions 5 5, and the default maximum sample value 255.

3. Make a rectangular kernel

Supply width and height as two arguments when a square shape is not suitable:

$ pgmkernel 7 3 > kernel-7x3.pgm
$ file kernel-7x3.pgm
kernel-7x3.pgm: Netpbm image data, size 7 x 3, rawbits, greymap

The arguments describe the dimensions of the generated kernel, not a later resize operation. Keep the filename and the two numbers aligned in scripts. If you use a variable, validate it before invoking the command so a missing value cannot change the meaning of the arguments.

$ width=7
$ height=3
$ pgmkernel "$width" "$height" > kernel-${width}x${height}.pgm

4. Tune the distance falloff

Each location is assigned a value based on its distance from the centre. The -weight option controls how quickly that value falls as distance increases. Its default is 6.0. A higher positive weight makes the falloff faster, concentrating more of the kernel's value near the centre.

$ pgmkernel -weight=10 7 7 > kernel-weight10.pgm
$ file kernel-weight10.pgm
kernel-weight10.pgm: Netpbm image data, size 7 x 7, rawbits, greymap

The option can also be written with whitespace, as -weight 10. The manual permits unique abbreviations and double hyphens, but full option names are easier to audit in a script. The weight must be positive. Do not copy old examples that use a negative value: the current program rejects one.

$ pgmkernel -weight -1 3 > /tmp/not-a-kernel.pgm
pgmkernel: -weight cannot be negative.  You specified -1.000000

That diagnostic is an expected failure test, not a kernel. Check the shell status when handling errors in automation:

$ pgmkernel -weight -1 3 > /tmp/not-a-kernel.pgm
$ printf 'exit status: %s\n' "$?"
exit status: 1

5. Choose the PGM maximum value

Use -maxval to change the maximum sample value in the PGM output. The default is 255; this option was added in Netpbm 10.65, so it is available in the installed release.

$ pgmkernel -maxval=100 5 > kernel-max100.pgm
$ head -n 3 kernel-max100.pgm
P5
5 5
100

That command changes the PGM scale, not the kernel dimensions. Combining both controls is also valid:

$ pgmkernel -weight=8 -maxval=100 9 5 > kernel-9x5.pgm
$ file kernel-9x5.pgm
kernel-9x5.pgm: Netpbm image data, size 9 x 5, rawbits, greymap

6. Request plain PGM when text output helps

Raw PGM is the default in current Netpbm. Add -plain when another program or a review workflow specifically needs the text PGM form:

$ pgmkernel -plain 3 > kernel-plain.pgm
$ head -n 6 kernel-plain.pgm
P2
3 3
255
141 146 141
146 255 146
141 146 141

Do not mistake the displayed sample values for a universal fixture. They are the output from the installed command with its default weight and maximum value. The useful checks are the P2 magic number, the requested dimensions, and the declared maximum value.

7. Preserve an existing kernel

Shell > truncates its destination before pgmkernel runs. That is destructive if the destination already contains a working kernel. Generate into a temporary name, verify it, then replace the old file only when you are satisfied:

$ pgmkernel 5 > kernel-5x5.pgm.new
$ file kernel-5x5.pgm.new
kernel-5x5.pgm.new: Netpbm image data, size 5 x 5, rawbits, greymap
$ mv kernel-5x5.pgm.new kernel-5x5.pgm

The final mv replaces the old destination. If generation or verification fails, leave the original in place and remove only the failed .new file after checking its path. If you need a rollback, copy the old kernel to a clearly named backup before the replacement. Removing that backup later is irreversible.

Common traps and failures

A dimension must be positive. pgmkernel 0 exits with an error instead of producing a zero-sized image. An omitted second argument means a square kernel, not an inferred height. A wrong width or height is therefore easy to introduce when values come from a script.

Kernel generation time grows with width multiplied by height. Very large dimensions can become unexpectedly slow and consume substantial output space. Start with a small kernel, verify it, and increase the size deliberately. For unusually large convolution work, the manual points towards FFT-based approaches as a possible alternative.

There is no need for sudo when reading ordinary input files and writing in a directory you own. Use elevated privileges only when filesystem permissions genuinely require them, and avoid placing generated output in a system directory until its contents have been checked.