NAME
im_create_fmask - create a frequency domain filter mask according to
args
SYNOPSIS
#include <vips/vips.h>
int
im_create_fmask( IMAGE *out, int xs, int ys, int type, double p1, ... )
DESCRIPTION
im_create_fmask() creates a float one band image mask. Sizes xs and
ys must be powers of 2, and must be square. Non-square masks may be
added in a future version.
There are 18 types of filter mask supported in this VIPS - they are
listed below. For each type, you are expected to give the correct
number of additional parameters. See the table.
-----------------------------------------------------------
| Filter mask; type; num_args; parameters |
-----------------------------------------------------------
| Ideal high pass; 0; 1; fc |
| Ideal low pass; 1; 1; fc |
| Butterworth high pass; 2; 3; order, fc, ac |
| Butterworth low pass; 3; 3; order, fc, ac |
| Gaussian low pass; 4; 2; fc, ac |
| Gaussian high pass; 5; 2; fc, ac |
| |
| Ideal ring pass; 6; 2; fc, width |
| Ideal ring reject; 7; 2; fc, width |
| Butterworth ring pass; 8; 4; order, fc, width, ac |
| Butterworth ring reject; 9; 4; order, fc, width, ac |
| Gaussian ring pass; 10; 3; fc, width, ac |
| Gaussian ring reject; 11; 3; fc, width, ac |
| |
| Ideal band pass; 12; 3; fcx, fcy, r |
| Ideal band reject; 13; 3; fcx, fcy, r |
| Butterworth band pass; 14; 5; order, fcx, fcy, r, ac |
| Butterworth band reject; 15; 5; order, fcx, fcy, r, ac |
| Gaussian band pass; 16; 4; fcx, fcy, r, ac |
| Gaussian band reject; 17; 4; fcx, fcy, r, ac |
| |
| fractal filter mask; 18; 1; fractal_dimension |
-----------------------------------------------------------
All masks are created with the four quadrants rotated so the (0,0) dc
component is at the top left corner of the image. In order to view a
mask, the four quadrants must be rotated (im_rotquad(3)) and scaled
(im_scale(3)). If the masks are used for filtering in the frequency
domain, there is no need for rotation. Function im_flt_imag_freq(3)
creates a mask and filter a square image in the frequency domain.
As a matter of convention the positive x axis is from left to right
while the positive y axis is from top to bottom (on the image with the
frequency (0,0) close to the centre i.e the four quadrants rotated).
All produced filters are float images with the maximum value normalised
to 1.0. Ideal and Butterworth filters are given in the book by
Gonzalez and Wintz.
HIGH PASS - LOW PASS FILTER MASKS (flag: 0 to 5)
A high pass filter mask filters the low frequencies while allowing the
high frequencies to get through. The reverse happens with a low pass
filter mask. The transition is controlled by the frequency cutoff
(fc). All masks are circularly symmetric and they are creating by
duplicating one forth of them.
Ideal high pass/low pass (argno=1):
The variable fc determines the frequency cutoff which can be given
either as percentage of the max spatial frequency (normalised by
convention to 1.0) or in pixels. In the latter case it is assumed that
the input image is square and that the maximum spatial frequency
corresponds to xs/2 points horizontally and and ys/2 points vertically.
The following line of code creates an ideal circularly symmetric high
pass filter mask:
im_create_fmask(im, 128, 128, 0, .5);
with all values above half the max spatial frequency (corresponding to
32 pixels) set to 1.0 and the remaining set to 0.0. The dc value
(corresponding to the frequency (0,0)) is set to 1.0. When the mask is
properly scaled and has its four quadrants rotated it is a black circle
within a white square. The radius of the circle is determined by fc
which is .5*max_spatial_frequency that is, for the example above
.5*64=32. The centre of the circle is set to 1.0 (white), in order to
allow the dc component to pass unaltered. A circularly symmetric ideal
low pass filter mask is constructed in a similar way.
Butterworth high pass/low pass (argno=3):
Each mask needs three arguments: the order, fc and ac. Order
corresponds to the order of the Butterworth filter mask, fc is the
frequency cutoff and ac is the amplitude cutoff. The same conventions
are valid for both fc and ac as for the ideal high pass and low pass
filter mask. The amplitude cutoff is determined by ac and corresponds
to the percentage of the maximum amplitude at fc. The maximum
amplitude is always normalised to 1.0. If the transfer function of the
filter is H(r) then H(fc) = ac*H(0). The transfer function at
frequency (0,0) is also set to 1.0.
The transfer function of the Butterworth high pass is:
H(r)=1.0/(1.0+(1.0/ac-1.0)*pow((fc*fc)/(r*r),order)).
For a Butterworth low pass:
H(r)=1.0/(1.0+(1.0/ac-1.0)*pow((r*r)/(fc*fc),order)).
Both masks are given in Gonzalez and Wintz (Digital Image Processing,
2nd edn, 1987). By increasing the order, the filter becomes steeper
introducing ringing.
Gaussian high pass/low pass (argno=2):
Each of these masks needs 2 arguments: fc and ac. For both arguments
the same conventions as for the Butterworth mask are valid. The
transfer function of a Gaussian high pass filter mask is given by the
equation:
H(r) = 1.0 - exp(log(ac)*r*r/(fc*fc)).
The corresponding mask for a Gaussian high pass is:
H(f) = exp(log(ac)*r*r/(fc*fc)).
ac being the amplitude cutoff.
RING PASS - RING REJECT FILTER MASKS (flag: 6 to 11)
A circularly symmetric ring pass filter mask allows all frequencies
within a ring, to pass while blocking all other frequencies. The ring
is specified by its width and it radius which corresponds to fc the
frequency cutoff. The fc is centred within the width and, therefore,
the ring starts at point fc-width/2 up to fc+width/2 along the positive
horizontal x axis. The reverse happens with a low pass filter mask.
The transition is controlled by the frequency cutoff (fc). All masks
are circularly symmetric and they are creating by duplicating one forth
of them.
Ideal ring pass/ring reject filter masks (argno=2):
An ideal ring pass filter mask has two arguments, the width and the
frequency cutoff. The created mask when properly rotated, is a white
ring of internal radius fc-df and external radius fc+df, on a black
square. All band pass values within the ring are set to 1.0 while the
remaining band reject frequencies are set to 0.0. The (0,0) frequency
component is set to 1.0. Both fc and width must be either between 0.0
and 1.0, or between 1.0 and xs/2. If both are between 0.0 and 1.0 then
the program normalises then to the maximum spatial frequency which is
xs/2=ys/2.
An ideal ring reject filter mask is the reverse of the ideal ring pass
filter mask, that is it allows all frequencies to get through apart
from the frequencies within a ring specified by the args of the
function, in a similar way as the ideal ring pass filter.
Butterworth ring pass/ring reject filter masks (argno=4):
Each of these masks has 4 arguments: the order of the filter (order),
the frequency cutoff (fc), the width (width) and the amplitude cutoff
(ac).
A Butterworth ring pass filter mask is a circularly symmetric ring
shape mask. The profile of the mask along the horizontal positive axis
is a shifted low pass Butterworth filter mask, with the maximum value
set to 1.0. This mask is similar to the ideal ring pass but the
transition between band pass and band reject zones instead of a sharp
brick wall, is a shifted Butterworth low pass filter mask. The transfer
function of the mask is given by the equation:
H(r)=1./(1.+cnst*pow(((r-fc)*(r-fc)/(w2)),order))
where cnst=1/ac, w2 = width*width/4.
Both fc and width should be either between 0.0 and 1.0 or between 1.0
and xs/2 as in the case of the ideal ring pass or ring reject mask.
The amplitude cutoff should be always between 0.0 and 1.0. It should
be noted that:
H(fc+df)=H(fc-df)=ac*H(fc)
The value of H(0) at frequency (0,0) has been set to 1.0 in order to
allow the dc component of the image to pass unaltered.
For the case of the Butterworth ring reject filter mask, its transfer
function is given by the equation:
H(r)=1./(1.+cnst*pow((w2/((r-fc)*(r-fc))),order))
where cnst=1/ac, w2 = width*width/4.
Gaussian ring pass/ring reject filter masks (argno=3):
Each of these masks takes three arguments: the frequency cutoff (fc),
the width (width) and the amplitude cutoff (ac). The conventions for
the arguments are the same as for the Butterworth ring pass and ring
reject masks above; however the order is not needed.
The transfer function of a Gaussian ring pass filter mask is:
H(r)=exp(log(ac)*(r-fc) * (r-fc)/w2)
where w2 = width*width/4.
BAND PASS - BAND REJECT MASKS (flag:13 to 17)
These filter masks are used in order to eliminate spatial frequencies
around a given frequency. Since the masks must be symmetrical with
respect to the origin, they cannot be realised by creating one forth
and replicating it four times.
Ideal band pass/band reject filter masks (argno=3):
An ideal band reject filter mask takes three arguments: the coordinates
of the centre of the one circle (fcx,fcy) and its radius r. The
produced filter mask has all values 0.0 except two disks centred at
(fcx,fcy), (-fcx,-fcy) each one having radius r. The two disks have
values of 1.0. The value of the mask corresponding to (0,0) spatial
frequency, as also set to 1.0.
All three arguments fcx, fcy and r should be either between 0 and 1 or
between 1 and the max spatial frequency which is xs/2=ys/2. In the
case that the arguments are between 0.0 and 1.0 they are interpreted as
percentage of the maximum spatial frequency. For the case of band pass
filter masks the value of the (0,0) frequency is set to 1.0 so that the
dc component can pass unaltered.
Butterworth band pass/band reject filter masks (argno=4):
A Butterworth band pass/band reject filter mask allows/rejects spatial
frequencies around a given frequency. The mask consists of the sum of
two Butterworth shape filters centered at (fcx,fcy) and (-fcx,-fcy).
The shape of each mask is determined by the parameters of the function.
The arguments fcx, fcy and r obey the same conventions as for those of
the ideal band pass / band reject masks. The transfer function of the
filter at point (0,0) is set to 1.0.
The function works by adding the two Butterworth masks. As a result,
if the whole mask is normalised with respect to frequency (fcx,fcy),
the cutoff frequency at (fcx+||r||,fcy+||r||) will be different to that
of (fcx-||r||,fcy-||r||), since the tail of the mask centered at
(-fcx,-fcy) will give a different contribution to (fcx+||r||,fcy+||r||)
than that to (fcx-||r||,fcy-||r||). In order to simplify the
calculations, the function estimates the amplitude at a cutoff
frequency ((fcx-||r||,fcy-||r||) as if the contribution comes only from
the mask centred at (fcx,fcy). The side effect of this approach is
that for big values of r the cutoff frequency of the filter mask is
different at frequencies (fcx+||r||,fcy+||r||) and
(fcx+||r||,fcy+||r||).
More specifically, given that each disk has a Butterworth shape of
radius r with centres at (x0, y0) and (-x0,-y0), the transfer function
of a Butterworth band pass filter mask is given by the equation:
H(d)= { H1(d) + H2(d) }
H1(d) = cnst1/(1 + cnst2 * pow((d-d0)/r, 2*order))
H2(d) = cnst1/(1 + cnst2 * pow((d+d0)/r, 2*order))
where
cnst1=1./(1.+1./(1.+cnst1*pow(d02/((r/2)*(r/2)),order)))
cnst2=1./ac - 1.,
d02 = x0*x0+y0*y0.
With this configuration for d=+d0, H(+d0) = 1.0; for d=-d0 H(-d0) =
1.0. If da=(xa,ya), then for d=+da, H1(+da)=ac and for d=-da,
H1(-da)=ac. In the latter case it is assumed that
xa=x0*(1-radius/sqrt(x0*x0+y0*y0)) and that
ya=y0*(1-radius/sqrt(x0*x0+y0*y0)).
The transfer function of a Butterworth band reject filter H_bbr(d) is
given by the equation:
H_bbr(d) = 1.0 - H_bbp(d),
where H_bbp(d) is the transfer function of the Butterworth bandpass
filter defined above.
Gaussian band pass/band reject filter masks (argno=3):
For a Gaussian band pass or band reject filter mask, similar
conventions to those of the Butterworth filter masks, are valid however
the order as an argument is not needed.
The transfer function of a Gaussian band pass filter mask is given by
the equation
H(d)= { H1(d) + H2(d) }
H1(d) = cnst1 * exp(-cnst2 * (d-d0)*(d-d0)/(r*r))
H1(d) = cnst1 * exp(-cnst2 * (d+d0)*(d+d0)/(r*r))
where
cnst1=1/( 1+exp(-cnst*d02/((r/2)*(r/2))) ),
d02 = x0*x0+y0*y0 and cnst2=-log(ac).
The transfer function of a Gaussian band reject filter H_gbr(d) is
given by the equation:
H_gbr(d) = 1.0 - H_gbp(d),
where H_gbp(d) is the transfer function of the Gaussian bandpass filter
defined above.
FRACTAL FILTER MASK (flag:18)
The fractal filter mask should be used only to filter square images of
white Gaussian noise in order to create fractal surfaces of a given
fractal dimension. The fractal dimension should be between 2.0 and
3.0. The produced mask has a power spectrum which decays according to
the rule entered by the parameter fractal dimension.
RETURN VALUE
The function returns 0 on success and -1 on error.
SEE ALSO
im_flt_image_freq(3).
COPYRIGHT
N. Dessipris
AUTHOR
N. Dessipris - 10/08/1991
8 Oct 1991 IM_FMASKPROF(3)