% @(#)filterdigi.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:36 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      filterdigi.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, FILTER/DIGITAL
%.PURPOSE    On-line help file for the command: FILTER/DIGITAL
%.VERSION    1.0  07-MAR-1984 : Creation, KB
%.VERSION    1.1  31-MAY-1991 : Remove edge comments, KB
%----------------------------------------------------------------
\se
SECTION./DIGI
\es\co
FILTER/DIGITAL						03-JUN-1997  KB
\oc\su
FILTER/DIGITAL frame outframe [filter_specs] [subimage] [options]
	use digital filter on an image
\us\pu
Purpose:
          Use digital filter on an image.
\up\sub
Subject:    
          Smoothing.
\bus\sy
Syntax:     
          FILTER/DIGITAL frame outframe [filter_specs] [subimage] [options]
\ys\pa
          frame = input image
\ap\pa
          outframe = result image
\ap\pa
          filter_specs = values (weights) of filter kernel\
\\
              (a) a list of weights 
\\
              (b) or name of a predefined 3x3 or 5x5 filter;
\\
                  LAPLACE, LOW_PASS, POINT, CONE, CONE5, PYRAMID, SHARP
                  and TENT
\\
              (c) or name of an image serving as filter, in that case the
                  size of the weight matrix is determined by the size of the
                  filter image; the dimensions in x and y must be odd numbers!
\\
              defaulted to predefined filter POINT.
\ap\pa
          subimage = optional specification of a subimage on which the
              filter will be applied, may be either
\\
              [xstart,ystart:xend,yend] (see page 3.4 in the MIDAS user
              manual, chapter 3) to indicate the limits of the subimage
              (with coordinates given according the MIDAS standard), or
\\
              CURSOR if the subimage will be chosen interactively.
\\
              table_name if the table "table_name" holds the endpoints of the
              subimage(s) in columns labeled :XSTART, :YSTART, :XEND and :YEND,
\\
              Defaulted to the complete input frame.
\ap\pa
          options = flag of 3 characters for options;
\\
              (1) L or N for loop or no loop,
\\
              (2) D or N for display of smoothed area or no display;
\\
              (3) E or N for expanding input frame first, so that result frame
                  has same dimensions as input frame or no expansion with
                  result frame smaller than input;
\\
              defaulted to NNE
\ap\sa:
See also:
          FILTER/MAX, FILTER/MIN, FILTER/GAUSS, FILTER/MEDIAN,
\\
          FILTER/SMOOTH, TUTORIAL/FILTER,
\\
          FFT/IMAGE, CONVOLVE/IMAGE, DECONVOLVE/IMAGE
\as\no
Note: 
          If `filter_specs' are given as weights (option a) they specify a 
          3x3 or 5x5 2-dim kernel or a 1-dim kernel. The elements for 
          a 2-dim matrix are given row by row, e.g. w(1),w(2),...,w(9) for
          a 3x3 kernel are stored in the matrix like:
\\{\tt
              w1 w2 w3
\\
              w4 w5 w6
\\
              w7 w8 w9 
\\}
          for 1-dim filters in x or y enter:
\\
          w(1),...,w(n):x  or  w(1),...,w(n):y (n odd, n < 40);
\\
          The fixed filters (option b) are set as follows:
\\        
          LAPLACE (this filter boosts high spatial frequencies)
\\{\tt
          0  -1  0
\\
          -1  5 -1
\\
          0  -1  0
\\}
          LOW_PASS (this filter boosts low spatial frequencies)
\\{\tt
          1   2  1
\\
          2   5  2
\\
          1   2  1
\\}
          POINT (this filter boosts point source)
\\{\tt
          -1 -2 -1
\\
          -2 13 -2
\\
          -1 -2 -1
\\}
          CONE (this filter enhances Gaussian PSF structures), CONE5
\\{\tt
          1  -6  1              0  0  1  0  0
\\
          -6 36 -6              0  2  2  2  0
\\
          1  -6  1              1  2  5  2  1
\\
                                0  2  2  2  0
\\
                                0  0  1  0  0
\\}
          SHARP,                TENT
\\{\tt
          -1 -2 -1              1  1  1
\\
          -2 13 -2              1  8  1
\\
          -1 -2 -1              1  1  1
\\}
          PYRAMID
\\{\tt
          1  2  3  2  1
\\
          2  4  6  4  2
\\
          3  6  9  6  3
\\
          2  4  6  4  2
\\
          1  2  3  2  1
\\}
          these filters are internally normalized, i.e. total sum of weights
          is 1.0.
\\
          New points are calculated as outpix = SUM(inpix*w(m)), where the
          SUM is taken over the pixels in the neighbourhood determined by
          the size of the filter kernel, i.e. NPIX(1) and NPIX(2) of the
          digital filter.
\\
          If the subimage option is chosen, it must be at least as big as the
          filter kernel...
\\
          If `option(3:3) = 'E' the input image is expanded by 2*radx columns
          and 2*rady lines, so that also the "edge" pixels can be calculated.
\\
          Note, that the flux is not conserved.
\on\exs
Examples:
\ex
          FILTER/DIGITAL gordo flaco LAPLACE
            Use the Laplacian filter with the weights shown above on
            image `gordo.bdf' and store resulting image into frame `flaco.bdf'.
\\
            The input frame is first expanded, so that the dimensions of the
            frame `flaco.bdf' are the same as the ones of `gordo.bdf'.
\xe\ex
          FILTER/DIGITAL grande chico 0.,-2.,0.,-2.,8.,-2.,0.,-2.,0.
            Use the filter with weights
\\{\tt
            0  -2  0
\\
            -2  8 -2
\\
            0  -2  0
\\}
            on image `grande.bdf' and store result into frame `chico.bdf'.
            Remember, that the number of weights determines the size of the
            filter kernel.
\xe\ex
          FILTER/DIGITAL mucho poco 0.1,0.15,0.5,0.15,0.1:y
            Use a column filter of 5 elements on `mucho.bdf' and store result
            into frame `poco.bdf'.
\xe \sxe