; IMFLT
;---------------------------------------------------------------
;! fits and removes a background intensity plane from an image
;# Task Optical
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1998
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
IMFLT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
IMFLT     Flattens an image by fitting a plane to the image.
INNAME                             Input image name (name)
INCLASS                            Input image name (class)
INSEQ             0.0     9999.0   Input image name (seq. #)
INDISK            0.0        9.0   Input image disk unit #
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
BLC                                Bottom left corner of output
TRC                                Top   right corner of output
NBOXES             0.0        10.0 Number of boxes to include
BOX                0.0      4096.0 Four coordinates for each box
APARM                              (1) type of fit
                                   (2) direction of fit.
PIXRANGE                           Limit fit to pixels in range
----------------------------------------------------------------
IMFLT
Task:  Task to read flatten an image by fitting a plane through
       the data specified in the boxes.
       If no boxes are specified, the entire map is included in
       the fit.
Adverbs:
  INNAME.....Input image name (name).       Standard defaults.
  INCLASS....Input image name (class).      Standard defaults.
  INSEQ......Input image name (seq. #).     0 => highest.
  INDISK.....Disk drive # of input image.   0 => any.
  OUTNAME....Output image name (name).      Standard defaults.
  OUTCLASS...Output image name (class).     Standard defaults.
  OUTSEQ.....Output image name (seq. #).    0 => highest unique.
  OUTDISK....Disk drive # of output image.  0 => highest disk
             number with sufficient space.
  BLC........Bottom left corner of subimage. 0=> all of axis
  TRC........Top   right corner of subimage. 0=> all of axis
  NBOXES.....Number of boxes to include in fit to plane
  BOX........Four coordinates for each box
  APARM......Specifies the type of fit to perform and fixed
             parameters.
             (1) type of fit 0 => subrt. off mean
                             1 => subrt. off best fit plane
                            -1 => subrt. off constrained plane
             The constrained plane has maximum slope in the
             direction APARM(2) measured in degrees CCW from
             the x-axis.
  PIXRANGE...Only pixels within PIXR(1) - PIXR(2) are used in the fit.
             PIXR(1) >= PIXR(2) -> full range.
----------------------------------------------------------------
IMFLT:  Task which reads an image file and subtracts a best fit
        plane to the data. The data included in the fit is
        determined by the parameters BOX(I,J), J=1, NBOXES where
        I =1,4 provide BLC and TRC for each box.  These
        parameters are most easilly fit using the verb TVBOX.
        The type of fit is determined by APARM

        APARM(1) =  0 => only subtrct off the mean value.
                 =  1 => subtract off the best fit plane.
                 = -1 => subtract off a plane, but constrain
                         the direction of the slope using
                         APARM(2)
        APARM(2)  This is an angle measured in degrees.  It
                  specifies which direction in the output
                  map should have zero slope.  APARM(2) is
                  only used if APRAM(1) = -1.

        A future version of IMFLT should allow higher order
        fits and use APARM(5) and APARM(6) as max and min
        values for a pixel to be included in the fit.

        There are two KNOWN problems with this routine, although
        neither one is a major threat to its usefullness.
        (1)   Not all points included in BOX are used to
                 determine the fit.  The image is truncated
                 using BLC and TRC before the fit is determined.
        (2)   If the output image is not flat, because APARM(1)
                 was set to either -1 or 0, there is some
                 ambiguity in determining a mean level for the
                 image.  This probably should be the center
                 of the image.  Instead, it is the mean position
                 of the pixels included in the fit.

