Build a Netpbm Convolution Kernel with pgmkernel

pgmkernel generates a PGM image holding a convolution kernel, ready to feed straight into Netpbm tools such as pnmconvol. This walks through checking its format and dimensions and saving it safely.

Allow about ten minutes. You need the netpbm package and a shell; none of the examples need 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, which is worth knowing if you are comparing against another distribution or a newer Netpbm build: check the command on the actual 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 and never picks an output filename for you. A failed run can leave a partial file behind if shell redirection points straight at a destination you actually care about.

2. Generate a square kernel

Give one dimension for a square kernel. This 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 rest is binary sample data, so do not expect the whole file to be readable in a text editor.

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

Exact spacing in od output can vary. What matters is 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 square will not do:

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

Those arguments describe the generated kernel's dimensions, not a later resize. Keep the filename and the two numbers aligned in scripts, and validate a variable before you invoke the command with it, so a missing value cannot silently change what the arguments mean:

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

4. Tune the distance falloff

Each location in the kernel gets a value based on its distance from the centre. -weight controls how fast that value falls as distance increases, defaulting to 6.0. Push the weight higher and the falloff speeds up, concentrating more of the kernel's value near the middle.

$ 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 also accepts whitespace instead of an equals sign, as -weight 10. The manual permits unique abbreviations and double hyphens too, but full option names are easier to audit in a script. The weight itself must stay positive: do not copy an old example using a negative value, because the current program rejects it outright.

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

That diagnostic is an expected failure, not a kernel. Check the shell status whenever you are 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. It defaults to 255; the option itself was added in Netpbm 10.65, so it is present in the installed release here.

$ 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 together works fine too:

$ 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 human review step, specifically needs the text PGM form instead:

$ 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 treat those displayed sample values as some universal fixture; they simply come from the installed command's default weight and maximum value. The checks that matter are the P2 magic number, the requested dimensions, and the declared maximum value.

7. Preserve an existing kernel

Shell > truncates its destination before pgmkernel even runs, which is destructive if that destination already holds a working kernel. Generate into a temporary name, verify it, and only then replace the old file:

$ 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

That final mv is what replaces the old destination. If generation or verification fails, leave the original alone and remove only the failed .new file after checking its path. Want a rollback option? Copy the old kernel to a clearly named backup before the replacement; removing that backup later cannot be undone.

Common traps

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

Kernel generation time grows with width multiplied by height. Very large dimensions can turn unexpectedly slow and eat substantial output space, so start small, verify it, and scale up deliberately. For genuinely large convolution work, the manual points towards FFT-based approaches as an alternative.

No sudo is needed for reading ordinary input files and writing into a directory you own. Reach for elevated privileges only when filesystem permissions genuinely require them, and hold off on placing generated output in a system directory until its contents are checked.