1IM_FMASKPROF(3) Library Functions Manual IM_FMASKPROF(3)
2
6 im_create_fmask - create a frequency domain filter mask according to
7 args
8
10 #include <vips/vips.h>
11 int
13 im_create_fmask( IMAGE *out, int xs, int ys, int type, double p1, ... )
14
17 im_create_fmask() creates a float one band image mask. Sizes xs and
18 ys must be powers of 2, and must be square. Non-square masks may be
19 added in a future version.
20 There are 18 types of filter mask supported in this VIPS - they are
22 listed below. For each type, you are expected to give the correct num‐
23 ber of additional parameters. See the table.
24 -----------------------------------------------------------
26 | Filter mask; type; num_args; parameters |
27 -----------------------------------------------------------
28 | Ideal high pass; 0; 1; fc |
29 | Ideal low pass; 1; 1; fc |
30 | Butterworth high pass; 2; 3; order, fc, ac |
31 | Butterworth low pass; 3; 3; order, fc, ac |
32 | Gaussian low pass; 4; 2; fc, ac |
33 | Gaussian high pass; 5; 2; fc, ac |
34 | |
35 | Ideal ring pass; 6; 2; fc, width |
36 | Ideal ring reject; 7; 2; fc, width |
37 | Butterworth ring pass; 8; 4; order, fc, width, ac |
38 | Butterworth ring reject; 9; 4; order, fc, width, ac |
39 | Gaussian ring pass; 10; 3; fc, width, ac |
40 | Gaussian ring reject; 11; 3; fc, width, ac |
41 | |
42 | Ideal band pass; 12; 3; fcx, fcy, r |
43 | Ideal band reject; 13; 3; fcx, fcy, r |
44 | Butterworth band pass; 14; 5; order, fcx, fcy, r, ac |
45 | Butterworth band reject; 15; 5; order, fcx, fcy, r, ac |
46 | Gaussian band pass; 16; 4; fcx, fcy, r, ac |
47 | Gaussian band reject; 17; 4; fcx, fcy, r, ac |
48 | |
49 | fractal filter mask; 18; 1; fractal_dimension |
50 -----------------------------------------------------------
51 All masks are created with the four quadrants rotated so the (0,0) dc
53 component is at the top left corner of the image. In order to view a
54 mask, the four quadrants must be rotated (im_rotquad(3)) and scaled
55 (im_scale(3)). If the masks are used for filtering in the frequency
56 domain, there is no need for rotation. Function im_flt_imag_freq(3)
57 creates a mask and filter a square image in the frequency domain.
58 As a matter of convention the positive x axis is from left to right
60 while the positive y axis is from top to bottom (on the image with the
61 frequency (0,0) close to the centre i.e the four quadrants rotated).
62 All produced filters are float images with the maximum value normalised
63 to 1.0. Ideal and Butterworth filters are given in the book by Gonza‐
64 lez and Wintz.
65 HIGH PASS - LOW PASS FILTER MASKS (flag: 0 to 5)
67 A high pass filter mask filters the low frequencies while allowing the
69 high frequencies to get through. The reverse happens with a low pass
70 filter mask. The transition is controlled by the frequency cutoff
71 (fc). All masks are circularly symmetric and they are creating by
72 duplicating one forth of them.
73 Ideal high pass/low pass (argno=1):
75 The variable fc determines the frequency cutoff which can be given
77 either as percentage of the max spatial frequency (normalised by con‐
78 vention to 1.0) or in pixels. In the latter case it is assumed that the
79 input image is square and that the maximum spatial frequency corre‐
80 sponds to xs/2 points horizontally and and ys/2 points vertically. The
81 following line of code creates an ideal circularly symmetric high pass
82 filter mask:
83 im_create_fmask(im, 128, 128, 0, .5);
85 with all values above half the max spatial frequency (corresponding to
87 32 pixels) set to 1.0 and the remaining set to 0.0. The dc value (cor‐
88 responding to the frequency (0,0)) is set to 1.0. When the mask is
89 properly scaled and has its four quadrants rotated it is a black circle
90 within a white square. The radius of the circle is determined by fc
91 which is .5*max_spatial_frequency that is, for the example above
92 .5*64=32. The centre of the circle is set to 1.0 (white), in order to
93 allow the dc component to pass unaltered. A circularly symmetric ideal
94 low pass filter mask is constructed in a similar way.
95 Butterworth high pass/low pass (argno=3):
97 Each mask needs three arguments: the order, fc and ac. Order corre‐
99 sponds to the order of the Butterworth filter mask, fc is the frequency
100 cutoff and ac is the amplitude cutoff. The same conventions are valid
101 for both fc and ac as for the ideal high pass and low pass filter mask.
102 The amplitude cutoff is determined by ac and corresponds to the per‐
103 centage of the maximum amplitude at fc. The maximum amplitude is
104 always normalised to 1.0. If the transfer function of the filter is
105 H(r) then H(fc) = ac*H(0). The transfer function at frequency (0,0) is
106 also set to 1.0.
107 The transfer function of the Butterworth high pass is:
109 H(r)=1.0/(1.0+(1.0/ac-1.0)*pow((fc*fc)/(r*r),order)).
110 For a Butterworth low pass:
111 H(r)=1.0/(1.0+(1.0/ac-1.0)*pow((r*r)/(fc*fc),order)).
112 Both masks are given in Gonzalez and Wintz (Digital Image Processing,
113 2nd edn, 1987). By increasing the order, the filter becomes steeper
114 introducing ringing.
115 Gaussian high pass/low pass (argno=2):
117 Each of these masks needs 2 arguments: fc and ac. For both arguments
119 the same conventions as for the Butterworth mask are valid. The trans‐
120 fer function of a Gaussian high pass filter mask is given by the equa‐
121 tion:
122 H(r) = 1.0 - exp(log(ac)*r*r/(fc*fc)).
123 The corresponding mask for a Gaussian high pass is:
124 H(f) = exp(log(ac)*r*r/(fc*fc)).
125 ac being the amplitude cutoff.
126 RING PASS - RING REJECT FILTER MASKS (flag: 6 to 11)
129 A circularly symmetric ring pass filter mask allows all frequencies
131 within a ring, to pass while blocking all other frequencies. The ring
132 is specified by its width and it radius which corresponds to fc the
133 frequency cutoff. The fc is centred within the width and, therefore,
134 the ring starts at point fc-width/2 up to fc+width/2 along the positive
135 horizontal x axis. The reverse happens with a low pass filter mask.
136 The transition is controlled by the frequency cutoff (fc). All masks
137 are circularly symmetric and they are creating by duplicating one forth
138 of them.
139 Ideal ring pass/ring reject filter masks (argno=2):
141 An ideal ring pass filter mask has two arguments, the width and the
143 frequency cutoff. The created mask when properly rotated, is a white
144 ring of internal radius fc-df and external radius fc+df, on a black
145 square. All band pass values within the ring are set to 1.0 while the
146 remaining band reject frequencies are set to 0.0. The (0,0) frequency
147 component is set to 1.0. Both fc and width must be either between 0.0
148 and 1.0, or between 1.0 and xs/2. If both are between 0.0 and 1.0 then
149 the program normalises then to the maximum spatial frequency which is
150 xs/2=ys/2.
151 An ideal ring reject filter mask is the reverse of the ideal ring pass
153 filter mask, that is it allows all frequencies to get through apart
154 from the frequencies within a ring specified by the args of the func‐
155 tion, in a similar way as the ideal ring pass filter.
156 Butterworth ring pass/ring reject filter masks (argno=4):
158 Each of these masks has 4 arguments: the order of the filter (order),
160 the frequency cutoff (fc), the width (width) and the amplitude cutoff
161 (ac).
162 A Butterworth ring pass filter mask is a circularly symmetric ring
163 shape mask. The profile of the mask along the horizontal positive axis
164 is a shifted low pass Butterworth filter mask, with the maximum value
165 set to 1.0. This mask is similar to the ideal ring pass but the tran‐
166 sition between band pass and band reject zones instead of a sharp brick
167 wall, is a shifted Butterworth low pass filter mask. The transfer func‐
168 tion of the mask is given by the equation:
169 H(r)=1./(1.+cnst*pow(((r-fc)*(r-fc)/(w2)),order))
170 where cnst=1/ac, w2 = width*width/4.
171 Both fc and width should be either between 0.0 and 1.0 or between 1.0
172 and xs/2 as in the case of the ideal ring pass or ring reject mask.
173 The amplitude cutoff should be always between 0.0 and 1.0. It should
174 be noted that:
175 H(fc+df)=H(fc-df)=ac*H(fc)
176 The value of H(0) at frequency (0,0) has been set to 1.0 in order to
177 allow the dc component of the image to pass unaltered.
178 For the case of the Butterworth ring reject filter mask, its transfer
180 function is given by the equation:
181 H(r)=1./(1.+cnst*pow((w2/((r-fc)*(r-fc))),order))
182 where cnst=1/ac, w2 = width*width/4.
183 Gaussian ring pass/ring reject filter masks (argno=3):
185 Each of these masks takes three arguments: the frequency cutoff (fc),
187 the width (width) and the amplitude cutoff (ac). The conventions for
188 the arguments are the same as for the Butterworth ring pass and ring
189 reject masks above; however the order is not needed.
190 The transfer function of a Gaussian ring pass filter mask is:
192 H(r)=exp(log(ac)*(r-fc) * (r-fc)/w2)
193 where w2 = width*width/4.
194 BAND PASS - BAND REJECT MASKS (flag:13 to 17)
196 These filter masks are used in order to eliminate spatial frequencies
198 around a given frequency. Since the masks must be symmetrical with
199 respect to the origin, they cannot be realised by creating one forth
200 and replicating it four times.
201 Ideal band pass/band reject filter masks (argno=3):
203 An ideal band reject filter mask takes three arguments: the coordinates
205 of the centre of the one circle (fcx,fcy) and its radius r. The pro‐
206 duced filter mask has all values 0.0 except two disks centred at
207 (fcx,fcy), (-fcx,-fcy) each one having radius r. The two disks have
208 values of 1.0. The value of the mask corresponding to (0,0) spatial
209 frequency, as also set to 1.0.
210 All three arguments fcx, fcy and r should be either between 0 and 1 or
212 between 1 and the max spatial frequency which is xs/2=ys/2. In the
213 case that the arguments are between 0.0 and 1.0 they are interpreted as
214 percentage of the maximum spatial frequency. For the case of band pass
215 filter masks the value of the (0,0) frequency is set to 1.0 so that the
216 dc component can pass unaltered.
217 Butterworth band pass/band reject filter masks (argno=4):
219 A Butterworth band pass/band reject filter mask allows/rejects spatial
221 frequencies around a given frequency. The mask consists of the sum of
222 two Butterworth shape filters centered at (fcx,fcy) and (-fcx,-fcy).
223 The shape of each mask is determined by the parameters of the function.
224 The arguments fcx, fcy and r obey the same conventions as for those of
225 the ideal band pass / band reject masks. The transfer function of the
226 filter at point (0,0) is set to 1.0.
227 The function works by adding the two Butterworth masks. As a result,
229 if the whole mask is normalised with respect to frequency (fcx,fcy),
230 the cutoff frequency at (fcx+||r||,fcy+||r||) will be different to that
231 of (fcx-||r||,fcy-||r||), since the tail of the mask centered at
232 (-fcx,-fcy) will give a different contribution to (fcx+||r||,fcy+||r||)
233 than that to (fcx-||r||,fcy-||r||). In order to simplify the calcula‐
234 tions, the function estimates the amplitude at a cutoff frequency
235 ((fcx-||r||,fcy-||r||) as if the contribution comes only from the mask
236 centred at (fcx,fcy). The side effect of this approach is that for big
237 values of r the cutoff frequency of the filter mask is different at
238 frequencies (fcx+||r||,fcy+||r||) and (fcx+||r||,fcy+||r||).
239 More specifically, given that each disk has a Butterworth shape of
241 radius r with centres at (x0, y0) and (-x0,-y0), the transfer function
242 of a Butterworth band pass filter mask is given by the equation:
243 H(d)= { H1(d) + H2(d) }
244 H1(d) = cnst1/(1 + cnst2 * pow((d-d0)/r, 2*order))
245 H2(d) = cnst1/(1 + cnst2 * pow((d+d0)/r, 2*order))
246 where
247 cnst1=1./(1.+1./(1.+cnst1*pow(d02/((r/2)*(r/2)),order)))
248 cnst2=1./ac - 1.,
249 d02 = x0*x0+y0*y0.
250 With this configuration for d=+d0, H(+d0) = 1.0; for d=-d0 H(-d0) =
251 1.0. If da=(xa,ya), then for d=+da, H1(+da)=ac and for d=-da,
252 H1(-da)=ac. In the latter case it is assumed that
253 xa=x0*(1-radius/sqrt(x0*x0+y0*y0)) and that
254 ya=y0*(1-radius/sqrt(x0*x0+y0*y0)).
255 The transfer function of a Butterworth band reject filter H_bbr(d) is
257 given by the equation:
258 H_bbr(d) = 1.0 - H_bbp(d),
259 where H_bbp(d) is the transfer function of the Butterworth bandpass
260 filter defined above.
261 Gaussian band pass/band reject filter masks (argno=3):
263 For a Gaussian band pass or band reject filter mask, similar conven‐
265 tions to those of the Butterworth filter masks, are valid however the
266 order as an argument is not needed.
267 The transfer function of a Gaussian band pass filter mask is given by
269 the equation
270 H(d)= { H1(d) + H2(d) }
271 H1(d) = cnst1 * exp(-cnst2 * (d-d0)*(d-d0)/(r*r))
272 H1(d) = cnst1 * exp(-cnst2 * (d+d0)*(d+d0)/(r*r))
273 where
274 cnst1=1/( 1+exp(-cnst*d02/((r/2)*(r/2))) ),
275 d02 = x0*x0+y0*y0 and cnst2=-log(ac).
276 The transfer function of a Gaussian band reject filter H_gbr(d) is
278 given by the equation:
279 H_gbr(d) = 1.0 - H_gbp(d),
280 where H_gbp(d) is the transfer function of the Gaussian bandpass filter
281 defined above.
282 FRACTAL FILTER MASK (flag:18)
284 The fractal filter mask should be used only to filter square images of
286 white Gaussian noise in order to create fractal surfaces of a given
287 fractal dimension. The fractal dimension should be between 2.0 and
288 3.0. The produced mask has a power spectrum which decays according to
289 the rule entered by the parameter fractal dimension.
290
292 The function returns 0 on success and -1 on error.
293
295 im_flt_image_freq(3).
296
298 N. Dessipris
299
301 N. Dessipris - 10/08/1991
302 8 Oct 1991 IM_FMASKPROF(3)