pgmkernel

Generate a convolution kernel

$ pgmkernel [width] [height] > [path/to/output.pgm]

$ pgmkernel [size] > [path/to/output.pgm]

$ pgmkernel [[-w|-weight]] [value] [width] [height] > [path/to/output.pgm]

pgmkernel [-rows N] [-cols M] kernel_file [pgm_file]

-rows N
    Specifies the number of rows (height) of the convolution kernel to use. If this option is omitted, the dimensions are read from the kernel_file. This option is primarily for backward compatibility or when the kernel file format doesn't explicitly begin with dimensions.

-cols M
    Specifies the number of columns (width) of the convolution kernel to use. If this option is omitted, the dimensions are read from the kernel_file. Similar to -rows, used for compatibility or specific kernel file formats.

pgmkernel is a Netpbm utility that performs convolution on a Portable Graymap (PGM) image using a specified kernel. Convolution is a fundamental image processing operation used for various effects such as blurring, sharpening, edge detection, and embossing. The command reads a convolution kernel definition from a specified file and applies it to an input PGM image. The input image can be provided as a file argument or read from standard input. The resulting processed PGM image is written to standard output. It's an essential tool for advanced image manipulation within the Netpbm suite, allowing users to define custom image filters.

• Pixels outside the image boundaries are treated as having a value of 0 during convolution. This can lead to dark edges depending on the applied kernel.
• Output pixel values are clipped to the maximum allowed value for PGM images (typically 255 for 8-bit images, or the maxval specified in the PGM header).
• The -rows and -cols options, if used, override the dimensions specified within the kernel file. However, the standard and most common practice is for the kernel file itself to explicitly define its dimensions.

The kernel_file is a plain text file with the following structure:

1. The first line contains two integers: width height (unless -rows and -cols are used, in which case this line should simply be "rows cols").
2. The second line contains a single floating-point number: divisor. All calculated pixel values are divided by this number.
3. The subsequent height lines each contain width floating-point numbers, separated by whitespace, representing the kernel matrix values.

Example (3x3 blurring kernel with a divisor of 9.0):

3 3
9.0
1.0 1.0 1.0
1.0 1.0 1.0
1.0 1.0 1.0

pgmkernel is commonly used in conjunction with pipes to process images from other Netpbm tools or to chain multiple operations:

cat input.pgm | pgmkernel blur.kern > output.pgm
pnmtopgm image.pnm | pgmkernel sharpen.kern | pgmtopng > sharp_image.png

pgmkernel is an integral part of the Netpbm project, a comprehensive toolkit of graphics programs and a programming library designed for handling a wide array of image formats. It has been a core utility within the Netpbm suite for many years, offering a flexible method to apply custom image filters defined by convolution kernels. Its design adheres to the Unix philosophy of creating small, specialized tools that can be efficiently chained together in pipelines.

pgm(5), pnm(5), netpbm(1), pgmconv(1), pgmnoise(1), pgmmedian(1)