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