% @(#)centeriqe.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:18 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      centergaus.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, CENTER/IQE
%.PURPOSE    On-line help file for the command: CENTER/IQE
%.VERSION    1.0  21-MAR-1994 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./IQE 
\es\co
CENTER/IQE 						29-JUL-1999  KB
\oc\su
CENTER/IQE  [in_specs] [out_specs] [out_opt] [curs_specs] 
             [wsize] [zw_option] [invert_flag]
	find intensity weighted center + get angle of major axis
\us\pu
Purpose:  
          Compute the central position of the specified object by fitting
          a 2-dim Gaussian to the marginal distributions in both the x- and
          y-directions (or just in x). Also determine angle of major axis with
          X-axis.
\up\sub
Subject: 
          Fitting, centering, image quality estimation.
\bus\sy
Syntax:  
          CENTER/IQE [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
\\
             (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 `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, maj.axis, min.axis, icent, return_status and 
                 angle, angle_sigma will be stored in columns
\\
                 :XCEN, :YCEN, :XERR, :YERR, :XSIG, 
                 :YSIG, :AX_MAJ, :AX_MIN, :ICENT, :STATUS, :ANGLE, :ANGLE_SIG
\\
                 if new table, then in addition to the columns explained
                 above, also the columns labeled :XSTART, :YSTART, :XEND,
                 :YEND and :IDENT 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, 
                 maj.axis, min.axis, angle, angle_sigma 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, maj.axis, min.axis, angle, angle_sigma 
             and icent (16 values)
\\ 
             Xstart, ystart, xend, yend, xcenter, ycenter are also stored
             as double precision values in keyword OUTPUTD(1 - 6).
\\
             return_status is the status returned from the centering algorithm
\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)
\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/GAUSS, 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 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 should be 0
          otherwise something is wrong (maybe just some non-convergence)
\\
          The last results are also stored in keyword OUTPUTR(1 - 16), with
          the angle + sigma-angle (in degrees) in elements 15 + 16.
\on\exs
Examples:
\ex
          1) CENTER/IQE
             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/IQE CURSOR values,d
             as 1)  but write data to beginning of real descriptor VALUES
             of displayed image
\xe\ex
          3) CENTER/IQE cursor VALUES,D A
             as 2)  but append data to the end of real descriptor VALUES
\xe\ex
          4) CENTER/IQE CURSOR values
             as 1) but store data into table `values.tbl' (will be created
             by MIDAS)
\xe\ex
          6) CENTER/IQE 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/IQE ccd001,sources VALUES,D
             as 6) but write results into real descr named Values of frame 
             `ccd001.bdf'
\xe\ex
          8) CENTER/IQE ccd001,sources sources
             as 6) but store results also in input table `sources.tbl'
\xe\ex
          9) CENTER/IQE ccd001,sources center
             as 8) but store results into new table `center.tbl'
\xe\ex
         10) CENTER/IQE ccd001,233,402 ? ? ? 20,20
             use a subwindow of 20x20 pixels centered at frame pixels 233,402
             of `ccd001.bdf'
\xe\ex
         11) CENTER/IQE cursor p6=w
             as 1) but use zoom window to determine working area via cursor,
             but we need X11 for that...
\xe \sxe