pnmconvol

Convolve a PNM image with the specified convolution matrix

$ pnmconvol -matrix=-1,3,-1 [path/to/image.pnm] > [path/to/output.pnm]

$ pnmconvol -matrixfile [path/to/matrix1,path/to/matrix2,...] [path/to/image.pnm] > [path/to/output.pnm]

$ pnmconvol [path/to/matrix.pnm] [path/to/image.pnm] > [path/to/output.pnm]

$ pnmconvol -matrix=-1,3,-1 -normalize [path/to/image.pnm] > [path/to/output.pnm]

pnmconvol [-normalize] [-offset float] [-scale float] kernel_width kernel_height [pnmfile]

kernel_width
    The width (number of columns) of the convolution kernel matrix. This is a required integer argument.

kernel_height
    The height (number of rows) of the convolution kernel matrix. This is a required integer argument.

pnmfile
    Optional. The path to the input PNM image file. If omitted, pnmconvol reads the image from standard input.

-normalize
    An optional flag. If specified, the command normalizes the kernel elements so that their sum equals 1. This is particularly useful for blur filters to prevent image brightness changes.

-offset float
    An optional argument. Adds the specified floating-point value to each pixel's result after convolution. Useful for adjusting brightness or black levels.

-scale float
    An optional argument. Multiplies each pixel's result by the specified floating-point value after convolution. Useful for adjusting contrast or intensity.

pnmconvol is a command-line utility from the Netpbm toolkit designed to apply a convolution filter to a Portable Anymap (PNM) image. It reads an image either from a specified file or standard input and writes the processed image to standard output.

A convolution operation involves sliding a kernel (a small matrix of numbers) over each pixel of the image. For each pixel, the kernel's values are multiplied by the corresponding pixel values in the image region covered by the kernel, and the results are summed to determine the new pixel value. This process is fundamental for various image processing effects such as blurring (e.g., Gaussian blur), sharpening, edge detection (e.g., Sobel, Laplace filters), and embossing.

The user defines the kernel's dimensions and its floating-point values, which are read from standard input. pnmconvol provides options to normalize the kernel, apply an offset, or scale the resulting pixel values, offering flexibility in achieving desired visual outcomes.

pnmconvol expects the convolution kernel matrix to be supplied via standard input immediately after the command line arguments. Each row of the kernel must contain kernel_width space-separated floating-point numbers.
The command only processes PNM (Portable Anymap) image formats (PBM, PGM, PPM). Other image formats must first be converted using appropriate Netpbm utilities (e.g., jpegtopnm, pngtopnm).
Output pixel values are clamped to the maximum value of the PNM format if they exceed it, potentially leading to saturation for extreme convolution results.

Convolution kernels define the transformation applied to the image. Here are common examples:

A simple 3x3 blurring kernel, often used with the -normalize option:
0.111 0.111 0.111
0.111 0.111 0.111
0.111 0.111 0.111

A basic 3x3 sharpening kernel:
0 -1 0
-1 5 -1
0 -1 0

To apply these, the kernel values are typically piped to pnmconvol's standard input. For example, to sharpen an image, you might use: echo "0 -1 0\n-1 5 -1\n0 -1 0" | pnmconvol 3 3 image.pnm > sharpened.pnm

pnmconvol is a core utility within the Netpbm image processing toolkit. The Netpbm project itself originated from the PBMPLUS package created by Jef Poskanzer in the late 1980s. Over the years, Netpbm has evolved as a robust and comprehensive suite of command-line tools for converting and manipulating various image formats, primarily using the Portable Anymap (PNM) family as an intermediate format. pnmconvol exemplifies the Unix philosophy of small, focused tools that can be chained together (via pipes) to perform complex tasks. Its stable functionality for convolution has been a fundamental component for image filtering operations within the Netpbm ecosystem for decades, serving as a building block for many advanced image processing workflows.

pnm(5), pamarith(1), netpbm(1)