Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value.
pnmconvol reads two PNM images as input, convolves the second using the first, and writes a PNM image as output.
Convolution means replacing each pixel with a weighted average of the nearby pixels. The weights and the area to average are determined by the convolution matrix. There are two ways pnmconvol interprets the PNM convolution kernel pixels as weights: with offsets, and without offsets.
The simpler of the two is without offsets. That is what happens when you specify the -nooffset option. In that case, pnmconvol simply normalizes the sample values in the PNM image by dividing by the maxval.
For example, here is a sample convolution file that causes an output pixel to be a simple average of its corresponding input pixel and its 8 neighbors, resulting in a smoothed image:
P2
3 3
18
2 2 2
2 2 2
2 2 2
pnmconvol divides each of the sample values (1) by the maxval (18)
so the weight of each of the 9 input pixels gets is 1/9, which is
exactly what you want to keep the overall brightness of the image the
same. pnmconvol creates an output pixel by multiply the values
of each of 9 pixels by 1/9 and adding.
For a normal convolution, where you're neither adding nor subtracting total value from the image, but merely moving it around, you'll want to make sure that all the values in (each plane of) your convolution PNM add up to the maxval.
When you don't specify -nooffset, pnmconvol applies an offset, the purpose of which is to allow you to indicate negative weights even though PNM sample values are never negative. In this case, pnmconvol subtracts half the maxval from each sample before normalizing. So to get the same result as we did above with -nooffset, the convolution PNM image would have to look like this:
P2
3 3
18
10 10 10
10 10 10
10 10 10
To see how this works, do the above-mentioned offset: 10 - 18/2 gives 1. The possible range of values is from 0 to 18, and after the offset that's -9 to 9. The normalization step makes the range -1 to 1, and the values get scaled correspondingly so they become 1/9 - exactly what you want. The equivalent matrix for 5x5 smoothing would have maxval 50 and be filled with 26.
For a normal convolution, where you're neither adding nor subtracting total value from the image, but merely moving it around, you'll want to make sure that all the values in (each plane of) your convolution PNM, less half the maxval, add up to half the maxval.
The convolution file will usually be a PGM, so that the same convolution gets applied to each color component. However, if you want to use a PPM and do a different convolution to different colors, you can certainly do that.
At the edges of the convolved image, where the convolution matrix would extend over the edge of the image, pnmconvol just copies the input pixels directly to the output.
The convolution computation can result in a value which is outside the range representable in the output. When that happens, pnmconvol just clips the output, which means brightness is not conserved.
The -nooffset option was new in Netpbm 10.23 (July 2004).