Man Linux: Main Page and Category List

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)