Debian Codegraph @

upstream/debian-unstable/man1/pamgauss.1

raw
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