; MAXFIT
;---------------------------------------------------------------
;! returns pixel position and image intensity at a maximum
;# Verb Analysis
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2003, 2009, 2012-2013
;;  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
;-----------------------------------------------------------------------
MAXFIT    LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
MAXFIT: Verb to find coordinates and value of an image extremum
INNAME                             Image name (name)
INCLASS                            Image name (class)
INSEQ           0.0      9999.0    Image name (seq. #)
INDISK          0.0         9.0    Disk drive #
PIXXY           0.0      4096.0    Approximate (X,Y,...) pixel
                                   of maximum
IMSIZE          3.0        16.0    Search area for peak value.
PRTLEV         -2.0        10.0    <= -1 => no display results
         @      Output adverbs
PIXXY    @                         Fitted (X,Y,...) pixel of
         @                         maximum.
PIXVAL   @                         Peak intensity at maximum
COORDINA @                         Coordinates at pixel
FSHIFT   @                         RA/Dec shift to put on
                                   nearest pixel
ERROR    @                         > 0 => fit failed, else okay
----------------------------------------------------------------
MAXFIT
Type: Verb
Use:  MAXFIT fits a quadratic function to a 3x3 map array to
      determine the position and strength of an extremum.  It
      uses PIXXY as an estimate of the center of the 3x3 array,
      but searches over an area of up to 16x16 pixels for the
      actual peak value before fitting.
Adverbs: (inputs)
  INNAME......Image name(name).       Standard defaults.
  INCLASS.....Image name(class).      Standard defaults.
  INSEQ.......Image name(seq. #).     0 => highest.
  INDISK......Disk drive # of image.  0 => any.
  PIXXY.......The approximate (X,Y,...) pixel of the maximum.
  IMSIZE......(X,Y) search area in pixels.  Verb uses 11 if the values
              are outside the range 3 to 16.
  PRTLEV......Print level: if <= -1, then do not put result info in
              message file, otherwise do the coordinate and flux
              displays.
Adverbs: (outputs)
  PIXXY.......Fitted (X,Y,...) position of peak.
  PIXVAL......Fitted intensity at the peak.
  COORDINA....The X and Y coordinates are found as:
              Xpos = abs(CO(1)) + abs(CO(2))/60 + abs(CO(3))/3600
                 if any of CO(1), CO(2), CO(3) < 0: Xpos = -Xpos
              Ypos = abs(CO(4)) + abs(CO(5))/60 + abs(CO(6))/3600
                 if any of CO(4), CO(5), CO(6) < 0: Ypos = -Ypos
              Note that, although these are most suited to RA, Dec in
              sexagesimal notation, they can be used for any type of
              coordinate.  The units are standard FITS units (e.g
              degrees, m/sec, Hz, sec, etc.) except that right
              ascensions are in hours of time.
  FSHIFT......The values that one could put in RASHIFT and DECSHIFT
              to move this peak to the nearest integer pixel.  These
              values include any previous shifts and are corrected
              for rotation.
  ERROR.......If the verb is not aborted for error, but the fit fails,
              ERROR will be TRUE (1), else it will be FALSE (-1).
              Used to detect failures without stopping a procedure or
              RUN file.
----------------------------------------------------------------
MAXFIT: Verb to find coordinates and value of an image extremum
DOCUMENTOR: E.B.Fomalont (NRAO/VLA)
RELATED PROGRAMS:  IMFIT, MOMFT, IMVAL

                          PURPOSE

     MAXFIT is a verb which fits a quadratic function to a specified
3x3 map area in order to determine the location and intensity of an
extremum.  An area as large as 16x16 can be specified in IMSIZE to
search for the extremum, although the fit will only be made on the 3x3
area surrounding the extremum.
     The verb is useful for communicating the location and intensity
of the extremum to other verbs and tasks.  After execution PIXVAL will
contain the intensity and PIXXY = a,b will contain the pixel location
of the extrumum.  COORDINA will contain the RA and Dec of the
component in sexagesimal form.  SHIFT will contain an ra, dec shift in
arc sec which could be fed back to IMAGR (in RASHIFT and DECSHIFT) to
put the source more exactly on a pixel for improved imaging.
     MAXFIT is less sophisticated than IMFIT and JMFIT, which do
linearized least-square solutions on a specified map region for a set
of Gaussians.  If you want to determine the component size, determine
the errors of the parameters, or if the component is complex in shape,
the use of IMFIT or JMFIT is required.
     MAXFIT performs a simple least-square analysis on a 3x3 array
with the function

              a + b*x + c*y + d*x*y + e*x*x + f*y*y

The location and position of the extremum is obtained from the
parameters a,b,c,d,e and f.  No error checking or goodness of fit
analysis is made in MAXFIT.
     If there is an input specification error (bad PIXVAL, bad image
name), MAXFIT aborts the input line, procedure, RUN file, or whatever
which invoked it.  However, if the fit itself is the sole source of
error, then MAXFIT does not abort the command stream.  Instead, it
sets the adverb ERROR to TRUE if the fit fails or FALSE if it
succeeds.  Procedures which depend on the output of MAXFIT should test
ERROR and do appropriate things if it is TRUE.  For example:
        PROC FITS (I, J)
        SCALAR K
        ARRAY  VALS(20)
        PIXXY = I, J
        FOR K = 1:20;
           EGETNAME(K)
           IF ERROR THEN VALS(K) = 0;
              ELSE MAXFIT ;
              IF ERROR THEN VALS(K) = -1;
                 ELSE VALS(K) = PIXVAL;
                 END
              END
           END
        FOR K = 1:20; PRINT K,VALS(K); END
        FINISH
PRTLEV = -1 could be used to eliminate the message file displays of
all the coordinates and fluxes.  This speeds the process.
----------------------------------------------------------------
