| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Pamgauss User Manual" 1 "18 May 2017" "netpbm documentation" |
| 7 |
|
| 8 |
.SH NAME |
| 9 |
\fBpamgauss\fP - create a two-dimensional Gaussian function as a PAM image |
| 10 |
|
| 11 |
.UN synopsis |
| 12 |
.SH SYNOPSIS |
| 13 |
|
| 14 |
\fBpamgauss\fP |
| 15 |
\fIwidth\fP |
| 16 |
\fIheight\fP |
| 17 |
\fB-sigma=\fP\fInumber\fP |
| 18 |
[\fB-maxval=\fP\fInumber\fP] |
| 19 |
[\fB-tupletype=\fP\fIstring\fP] |
| 20 |
[\fB-maximize\fP] |
| 21 |
[\fB-oversample=\fP\fInumber\fP] |
| 22 |
.PP |
| 23 |
Minimum unique abbreviation of option is acceptable. You may use double |
| 24 |
hyphens instead of single hyphen to denote options. You may use white |
| 25 |
space in place of the equals sign to separate an option name from its value. |
| 26 |
|
| 27 |
|
| 28 |
.UN examples |
| 29 |
.SH EXAMPLES |
| 30 |
|
| 31 |
.nf |
| 32 |
pamgauss 7 7 -sigma=.5 -maximize -tupletype=GRAYSCALE | pamtopnm >gauss.pgm |
| 33 |
pnmconvol -nooffset -normalize gauss.pgm myimage.ppm >blurred.ppm |
| 34 |
|
| 35 |
.fi |
| 36 |
|
| 37 |
.UN description |
| 38 |
.SH DESCRIPTION |
| 39 |
.PP |
| 40 |
This program is part of |
| 41 |
.BR "Netpbm" (1)\c |
| 42 |
\&. |
| 43 |
.PP |
| 44 |
\fBpamgauss\fP generates a one-plane PAM image whose samples are a |
| 45 |
Gaussian function of their distance from the center of the image. I.e. |
| 46 |
the sample value is highest in the center and goes down, in a bell curve |
| 47 |
shape, as you move away from the center. |
| 48 |
.PP |
| 49 |
You can use this image as a convolution kernel with |
| 50 |
\fBpnmconvol\fP to blur an image. (This technique is known as |
| 51 |
Gaussian blurring). |
| 52 |
|
| 53 |
\fIwidth\fP and \fIheight\fP are the dimensions of the image that |
| 54 |
\fBpamgauss\fP generates. Mathematically speaking, they are the domain of |
| 55 |
the two-dimensional Gaussian function. If you want to be sure you get a whole |
| 56 |
Gaussian function, make sure that you choose a standard deviation and image |
| 57 |
dimensions so that if you made it any larger, the sample values at the edges |
| 58 |
would be zero. |
| 59 |
.PP |
| 60 |
The output image is PAM. To make it usable with \fBpnmconvol\fP, |
| 61 |
specify \fB-tupletype=GRAYSCALE\fP so \fBpnmconvol\fP can use it as |
| 62 |
if it were PGM. You must use the \fB-nooffset\fP option on |
| 63 |
\fBpnmconvol\fP because zero means zero in the PAM that |
| 64 |
\fBpamgauss\fP generates. |
| 65 |
.PP |
| 66 |
Without \fB-maximize\fP, the sum of all the samples is equal to the |
| 67 |
image's maxval (within rounding error). This is true even if you clip the |
| 68 |
Gaussian function by making the image too small. This is what is normally |
| 69 |
required of a convolution kernel. |
| 70 |
.PP |
| 71 |
\fBpamgauss\fP oversamples and averages to represent the continuous |
| 72 |
Gaussian function in discrete samples in the PAM output. Consider an image 11 |
| 73 |
samples wide and an oversampling factor of 10. The samples can be thought of |
| 74 |
as contiguous squares one unit wide. The center of the image is thus the |
| 75 |
center of the 6th sample from the left. The 3rd sample from the left covers a |
| 76 |
range of distances from 3 to 4 units from the center of the image. Because |
| 77 |
the oversampling factor is 10, \fBpamgauss\fP computes the value of the |
| 78 |
Gaussian function at 10 points evenly spaced between 3 and 4 units from the |
| 79 |
center of the image and assigns the 3rd sample from the left the mean of those |
| 80 |
10 values. |
| 81 |
|
| 82 |
|
| 83 |
.UN options |
| 84 |
.SH OPTIONS |
| 85 |
.PP |
| 86 |
In addition to the options common to all programs based on libnetpbm |
| 87 |
(most notably \fB-quiet\fP, see |
| 88 |
.UR index.html#commonoptions |
| 89 |
Common Options |
| 90 |
.UE |
| 91 |
\&), \fBpamgauss\fP recognizes the following |
| 92 |
command line options: |
| 93 |
|
| 94 |
|
| 95 |
.TP |
| 96 |
\fB-sigma=\fP\fInumber\fP |
| 97 |
This is the standard deviation of the Gaussian function. The higher the |
| 98 |
number, the more spread out the function is. Normally, you want to make this |
| 99 |
number low enough that the function reaches zero value before the edge of your |
| 100 |
image. |
| 101 |
.sp |
| 102 |
\fInumber\fP is in units of samples. |
| 103 |
.sp |
| 104 |
This option is required. There is no default. |
| 105 |
|
| 106 |
.TP |
| 107 |
\fB-maximize\fP |
| 108 |
Causes \fBpamgauss\fP to use the whole dynamic range available in |
| 109 |
the output PAM image by choosing an amplitude for the Gaussian function that |
| 110 |
causes the maximum value in the image to be the maxval of the image. |
| 111 |
.sp |
| 112 |
If you select this, you probably want to normalize the output (scale the |
| 113 |
samples down so the volume under the surface of the two-dimensional Gaussian |
| 114 |
function is the maxval) before you use it, for example with |
| 115 |
\fBpnmconvol\fP's \fB-normalize\fP option. The reason this is different |
| 116 |
from just not using \fB-maximize\fP is that this subsequent normalization can |
| 117 |
be done with much more precision than can be represented in a PAM image. |
| 118 |
.sp |
| 119 |
Without this option, \fBpamgauss\fP uses an amplitude that makes the volume |
| 120 |
under the surface of the two-dimensional Gaussian function the maxval of the |
| 121 |
image. This means all the samples in the image are normally considerably less |
| 122 |
than the maxval. |
| 123 |
.sp |
| 124 |
This option was new in Netpbm 10.79 (June 2017). |
| 125 |
|
| 126 |
.TP |
| 127 |
\fB-maxval=\fP\fInumber\fP |
| 128 |
This is the maxval for the output image. 65535 is almost always the best |
| 129 |
value to use. But there may be some programs (not part of Netpbm) that can't |
| 130 |
handle a maxval greater than 255. |
| 131 |
.sp |
| 132 |
The default is 255. |
| 133 |
|
| 134 |
.TP |
| 135 |
\fB-tupletype=\fP\fIstring\fP |
| 136 |
This is the value of the "tuple_type" attribute of the created PAM image. |
| 137 |
It can be any string up to 255 characters. |
| 138 |
.sp |
| 139 |
If you don't specify this, \fBpamgauss\fP generates a PAM with unspecified |
| 140 |
tuple type. |
| 141 |
|
| 142 |
.TP |
| 143 |
\fB-oversample=\fP\fInumber\fP |
| 144 |
This sets the oversampling factor. \fBpamgauss\fP samples the Gaussian |
| 145 |
function this many times, both horizontally and vertically, to get the value |
| 146 |
of each sample in the output. |
| 147 |
.sp |
| 148 |
An oversampling factor of 1 means no oversampling, which means each |
| 149 |
sample is based only on the value of the Gaussian function at the center of |
| 150 |
the sample. |
| 151 |
.sp |
| 152 |
The default is 5 divided by the standard deviation, rounded up to a whole |
| 153 |
number. |
| 154 |
.sp |
| 155 |
This option was new in Netpbm 10.79 (June 2017). Before that, it is |
| 156 |
essentially 1 - there is no oversampling. |
| 157 |
|
| 158 |
|
| 159 |
|
| 160 |
.UN seealso |
| 161 |
.SH SEE ALSO |
| 162 |
.BR "pnmconvol" (1)\c |
| 163 |
\&, |
| 164 |
.BR "pamtopnm" (1)\c |
| 165 |
\&, |
| 166 |
.BR "pgmkernel" (1)\c |
| 167 |
\&, |
| 168 |
.BR "pamseq" (1)\c |
| 169 |
\&, |
| 170 |
.BR "pam" (1)\c |
| 171 |
\& |
| 172 |
|
| 173 |
.UN history |
| 174 |
.SH HISTORY |
| 175 |
.PP |
| 176 |
\fBpamgauss\fP was new in Netpbm 10.23 (July 2004). |
| 177 |
.SH DOCUMENT SOURCE |
| 178 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 179 |
source. The master documentation is at |
| 180 |
.IP |
| 181 |
.B http://netpbm.sourceforge.net/doc/pamgauss.html |
| 182 |
.PP |