%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      centergaus.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, CENTER/GAUSS
%.PURPOSE    On-line help file for the command: CENTER/GAUSS
%.VERSION    1.0  07-FEB-1990 : Creation, KB
%.VERSION    1.1  02-MAR-1992 : Update, KB
%.VERSION    1.2  09-NOV-1992 : Update, KB
%----------------------------------------------------------------
\se
SECTION./GAUS
\es\co
CENTER/GAUSS					29-JUN-2011  KB
\oc\su
CENTER/GAUSS [in_specs] [out_specs] [out_opt] [curs_specs] 
             [wsize] [zw_option] [invert_flag]
	find intensity weighted center
\us\pu
Purpose:  
          Compute the central position of the specified object by fitting
          a Gaussian to the marginal distributions in both the x- and
          y-directions (or just in x).
\up\sub
Subject: 
          Position, fitting, centering.
\bus\sy
Syntax:  
          CENTER/GAUSS [in_specs] [out_specs] [out_opt] [curs_specs]
                       [wsize] [zw_option] [invert_flag]
\ys\pa
          in_specs = input specifications, either
             (a) CURSOR - if the subimages are interactively chosen via the
                 cursor rectangle, or
             (b) GCURSOR[,color] - if the subimages are interactively
                 chosen via the graphic cursor,
                 if color is given, the fitted Gaussian is plotted
                 in that color to distinguish it better from the
                 plotted image - color = 1,...,8 or blue, red, ...  ,or

                 graphic cursor, or
             (c) image,table - if the subimages are defined in a table in the
                 columns labeled :XSTART, :XEND, :YSTART and :YEND, or 
                 only columns :XSTART and :XEND (1-dim centering) or only
                 single column :X_POSITION (two rows per interval needed);
             (d) image - if subimage will be a (max) 200 * 200 window around
                 center of image
             (e) image,xfrpix,yfrpix - if subimage will be a window of 
		 param. `wsize' around xfrpix,yfrpix (frame pixels)
             defaulted to CURSOR
\ap\pa
          out_specs = output specifications:
             (x) table name, may be same as given in in_specs
             (y) if same table, only the xcenter, ycenter, xerr, yerr,
                 xsigma, ysigma, xfwhm, yfwhm, icent and  status will be 
                 stored in columns
                 :XCEN, :YCEN, :XERR, :YERR, :XSIG, 
                 :YSIG, :XFWHM :YFWHM :ICENT :STATUS
                 if new table, then in addition to the columns explained
                 above, also the columns labeled :XSTART, :YSTART, :XEND,
                 :YEND and :NO will be filled
             (z) descriptor,D if the results should be stored in a real
                 descriptor of the involved image frame;
                 data will be stored as xstart, ystart, xend, yend, xcenter,
                 ycenter, xerr, yerr, xsigma, ysigma, return_status,
                 xfwhm, yfwhm and  icent
             Per Default the values are displayed only on the terminal and
             stored in the keyword OUTPUTR which is filled as follows:
             xstart, ystart, xend, yend, xcenter, ycenter, xerr, yerr, 
	     xsigma, ysigma, return_status, xfwhm, yfwhm, icent
             Xstart, ystart, xend, yend, xcenter, ycenter are also stored
             as double precision values in keyword OUTPUTD(1 - 6).
\ap\pa
          out_opt = A, append data to a table (or descriptor), else start at 
             the beginning, only applicable to (x) or (z)
             ID, write also column labeled :IDENT to output table,
             only applicable to (x)
             EMISSION, assumes emission lines, applicable to (b)
             ABSORPTION, assumes absorption lines, applicable to (b)
\ap\pa
          curs_specs = no_curs,drawflag,max_input:
             no_curs = 1 or 2, if single cursor a fixed subimage according
             to next parameter `wsize' is used; for 2 cursors the size of
             subimage is determined by the size of the cursor rectangle.
             drawflag = option for drawing subwindow limits in the overlay
             channel;
             max_input = max. of cursor inputs.
             This parameter is only used if in_specs = CURSOR (a);
             defaulted to 2,1,9999
\ap\pa
          wsize = no. of x-and y-pixels for subwindow centered via the
             single cursor or `inp_specs' (e);
             defaulted to 50,50
\ap\pa
          zw_option = zwindow_flag,zoom;
             zwindow_flag = W for zoom window, N for none,
             zoom = initial zoom factor;
             only applicable to X11 window displays and option (a),
             defaulted to N,4 (see the help of GET/CURSOR for more info about
             the additional functionality provided in that mode);
\ap\pa
          invert_flag = YES or NO;
             if the objects are at a minimum and not maximum of the data,
             i.e. instead of a Gaussian `peak' you have a Gaussian `valley',
             set this par. to YES.
             defaulted to NO
\ap\sa
See also:
          CENTER/MOMENT, CENTER/IQE, MAGNITUDE/CENTER
\as\no
Note:  
          When using the cursor input option, a cursor window will appear 
          on the screen.
          For X-Windows use the mouse to move the complete window (or single
             cursor), use the arrow keys to change window size. Left mouse
             button (or RETURN key) is ENTER button, right button is
             EXIT button.
             If you also use the `zw_option', the cursor in the main display
             is only used to define the subwindow to work on. Then move the
             cursor to the auxiliary (zoom) window and proceed as described
             above.
          When using the graphic cursor option (b), the command needs
          two cursor positions defining the 1D interval to be used. Any key
          can be used to input the cursor. Use  SPACE-BAR to exit.
          Also be aware the fitted will be done on the LAST plotted data.
          I.e. when addtional data is plotted using an overplot command
          the CENTER command will work on this overplotted data set.
          When using the out_opt ID for table output, computations proceed
          after pressing the ENTER button and(!) entering also an identifier
          of max. 8 characters and hitting RETURN on the keyboard.
          Otherwise the string IDabcd will be written into column :IDENT
          with "abcd" the sequence number.
          The return status from the centering algorithm is specified as
          follows:
          < 0 = estimation failed
            0 = O.K.
            1 = ambiguous sources
            2 = no source
            3 = iteration failed
          > 3 = routine error 
          If you also need the angle of the 2-dim Gaussian (if it's not
          perfectly round) of the major axis with the X-axis, use the
          command CENTER/IQE (ImageQualityEstimate).
\on\exs
Examples:
\ex
          1) CENTER/GAUSS
             Use cursor to define subimages and display start- and
             end-coordinates of subimage as well as center values and
             associated errors and return status on terminal only
\xe\ex
          2) CENTER/GAUSS CURSOR values,d
             as 1)  but write data to beginning of real descriptor VALUES
             of displayed image
\xe\ex
          3) CENTER/GAUSS cursor VALUES,D A
             as 2)  but append data to the end of real descriptor VALUES
\xe\ex
          4) CENTER/GAUSS CURSOR values
             as 1) but store data into table values.tbl (will be created
             by MIDAS)
\xe\ex
          6) CENTER/GAUSS ccd001,sources
             use columns :XSTART, :YSTART, :XEND and :YEND of `sources.tbl'
             to define the subimages of image ccd001.bdf; 
	     just display results
\xe\ex
          7) CENTER/GAUSS ccd001,sources VALUES,D
             as 6) but write results into real descr values of frame 
             `ccd001.bdf'
\xe\ex
          8) CENTER/GAUSS ccd001,sources sources
             as 6) but store results also in input table sources.tbl
\xe\ex
          9) CENTER/GAUSS ccd001,sources center
             as 8) but store results into new table `center.tbl'
\xe\ex
         10) CENTER/GAUSS ccd001,233,402 ? ? ? 20,20
             use a subwindow of 20x20 pixels centered at frame 
	     pixels 233,402 of `ccd001.bdf'
\xe\ex
         11) CENTER/GAUSS cursor p6=w
             as 1) but use zoom window to determine working area via cursor,
             but we need X11 for that...
\xe\ex
         12) CENTER/GAUSS GCURSOR table EMISSION
             generate table `table.tbl' with positions of emission lines
             defined with the graphic cursor.
\xe\ex
         13) CENTER/GAUSS GCURSOR,red 
             find center of cursor defined subimage, plot fitted gaussian
	     in blue instead of given plot color
\xe \sxe
