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