% @(#)centermome.hlq	19.1 (ESO-IPG) 02/25/03 14:02:59 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      centermome.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, CENTER/MOMENT
%.PURPOSE    On-line help file for the command: CENTER/MOMENT
%.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./MOME
\es\co
CENTER/MOMENT						 29-JUL-1999  KB
\oc\su
CENTER/MOMENT [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 using an
          intensity weighted first moment of the pixel values.
\up\sub
Subject: 
          Position, fitting, centering.
\bus\sy
Syntax:  
          CENTER/MOMENT [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) 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);
\\
             (c) image - if subimage will be a (max) 200 * 200 window around
                 center of image
\\
             (d) 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 and status will be stored in columns
\\
                 :XCEN, :YCEN, :XERR, :YERR, :XSIG, :YSIG, ;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;
\\
             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)
\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' (d);
\\
             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 `peak' you have a `valley', set this par. to YES.
\\
             defaulted to NO
\ap\sa
See also:
          CENTER/GAUSS, MAGNITUDE/...
\as\no
Note:  
          When using the cursor input option, a cursor window will appear 
          on the screen.
\\
          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, second left 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.
\\
          Last results of center calculations are also written into
          keyword OUTPUTR.
\\
          The return status from the centering algorithm should be 0
          otherwise something is wrong (maybe just some non-convergence)
\on\exs
Examples:
\ex
          1) CENTER/MOMENT
             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/MOMENT CURSOR values,d
             as 1)  but write data to beginning of real descriptor VALUES
             of displayed image
\xe\ex
          3) CENTER/MOMENT cursor VALUES,D A
             as 2)  but append data to the end of real descriptor VALUES
\xe\ex
          4) CENTER/MOMENT CURSOR values
             as 1) but store data into table `values.tbl' (will be created
             by MIDAS)
\xe\ex
          6) CENTER/MOMENT 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/MOMENT ccd001,sources VALUES,D
             as 6) but write results into real descr named Values of frame
             `ccd001.bdf'
\xe\ex
          8) CENTER/MOMENT ccd001,sources sources
             as 6) but store results also in input table `sources.tbl'
\xe\ex
          9) CENTER/MOMENT ccd001,sources center
             as 8) but store results into new table `center.tbl'
\xe\ex
         10) CENTER/MOMENT ccd001,233,402 ? ? ? 20,20
             use a subwindow of 20x20 pixels centered at frame pixels 233,402
             of `ccd001.bdf'
\xe\ex
         11) CENTER/MOMENT cursor p6=w
             as 1) but use zoom window to determine working area via cursor,
             but we need X11 for that...
\xe \sxe
