.TH IM_FMASKPROF 3 "8 Oct 1991"
.SH NAME
im_create_fmask \- create a frequency domain filter mask according to args
.SH SYNOPSIS
.B #include <vips/vips.h>

int 
.br
im_create_fmask( IMAGE *out, int xs, int ys, int type, double p1, ... )

.SH 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.

.br
-----------------------------------------------------------
.br
| Filter mask;         type; num_args; parameters         |
.br
-----------------------------------------------------------
.br
| Ideal high pass;          0;  1; fc                     |
.br
| Ideal low pass;           1;  1; fc                     |
.br
| Butterworth high pass;    2;  3; order, fc, ac          |
.br
| Butterworth low pass;     3;  3; order, fc, ac          |
.br
| Gaussian low pass;        4;  2; fc, ac                 |
.br
| Gaussian high pass;       5;  2; fc, ac                 |
.br
|                                                         |
.br
| Ideal ring pass;          6;  2; fc, width              |
.br
| Ideal ring reject;        7;  2; fc, width              |
.br
| Butterworth ring pass;    8;  4; order, fc, width, ac   |
.br
| Butterworth ring reject;  9;  4; order, fc, width, ac   |
.br
| Gaussian ring pass;      10;  3; fc, width, ac          |
.br
| Gaussian ring reject;    11;  3; fc, width, ac          |
.br
|                                                         |
.br
| Ideal band pass;         12;  3; fcx, fcy, r            |
.br
| Ideal band reject;       13;  3; fcx, fcy, r            |
.br
| Butterworth band pass;   14;  5; order, fcx, fcy, r, ac |
.br
| Butterworth band reject; 15;  5; order, fcx, fcy, r, ac |
.br
| Gaussian band pass;      16;  4; fcx, fcy, r, ac        |
.br
| Gaussian band reject;    17;  4; fcx, fcy, r, ac        |
.br
|                                                         |
.br
| fractal filter mask;     18;  1; fractal_dimension      |
.br
-----------------------------------------------------------

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:
.br
H(r)=1.0/(1.0+(1.0/ac-1.0)*pow((fc*fc)/(r*r),order)).
.br
For a Butterworth low pass:
.br
H(r)=1.0/(1.0+(1.0/ac-1.0)*pow((r*r)/(fc*fc),order)).
.br
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:
.br
H(r) = 1.0 - exp(log(ac)*r*r/(fc*fc)).
.br
The corresponding mask for a Gaussian high pass is:
.br
H(f) = exp(log(ac)*r*r/(fc*fc)).
.br
ac being the amplitude cutoff.
.br


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):

.br
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).
.br
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:
.br
H(r)=1./(1.+cnst*pow(((r-fc)*(r-fc)/(w2)),order))
.br
where cnst=1/ac, w2 = width*width/4.
.br
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:
.br
H(fc+df)=H(fc-df)=ac*H(fc)
.br
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:
.br
H(r)=1./(1.+cnst*pow((w2/((r-fc)*(r-fc))),order))
.br
where cnst=1/ac, w2 = width*width/4.
.br

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:
.br
H(r)=exp(log(ac)*(r-fc) * (r-fc)/w2)
.br
where w2 = width*width/4.
.br

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:
.br
H(d)=  { H1(d) + H2(d) }
.br
H1(d) = cnst1/(1 + cnst2 * pow((d-d0)/r, 2*order))
.br
H2(d) = cnst1/(1 + cnst2 * pow((d+d0)/r, 2*order))
.br
where
.br
cnst1=1./(1.+1./(1.+cnst1*pow(d02/((r/2)*(r/2)),order)))
.br
cnst2=1./ac - 1.,
.br
d02 = x0*x0+y0*y0.
.br
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:
.br
H_bbr(d) = 1.0 - H_bbp(d),
.br
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
.br
H(d)=  { H1(d) + H2(d) }
.br
H1(d) = cnst1 * exp(-cnst2 * (d-d0)*(d-d0)/(r*r))
.br
H1(d) = cnst1 * exp(-cnst2 * (d+d0)*(d+d0)/(r*r))
.br
where
.br
cnst1=1/( 1+exp(-cnst*d02/((r/2)*(r/2))) ),
.br
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:
.br
H_gbr(d) = 1.0 - H_gbp(d),
.br
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.
.SH RETURN VALUE
The function returns 0 on success and -1 on error.
.SH SEE\ ALSO
im_flt_image_freq(3).
.SH COPYRIGHT
.br
N. Dessipris
.SH AUTHOR
N. Dessipris \- 10/08/1991