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