%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2010 European Southern Observatory
%.IDENT      magnitcirc.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, MAGNITUDE/CIRCLE
%.PURPOSE    On-line help file for the command: MAGNITUDE/CIRCLE
%.VERSION    1.0  30-JUL-1990 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./CIRC
\es\co
MAGNITUDE/CIRCLE					16-DEC-2010  KB
\oc\su
MAGNITUDE/CIRCLE [in_specs] [out_specs] [Fsiz,Nsiz,Bsiz] [out_opt]
                 [center_params] [curs_specs] [zw_option]
	compute magnitude within circular aperture
\us\pu
Purpose:    
          Compute the magnitude of the specified object by integrating
          over the central area defined by a circular aperture.
          The local background as integrated over the given background area
          is subtracted.
\up\sy
Syntax:     
          MAGNITUDE/CIRCLE [in_specs] [out_specs] [Fsiz,Nsiz,Bsiz] [out_opt]
                           [center_params] [curs_specs] [zw_option]
\ys\pa
          in_specs = input specifications, either
             (a) CURSOR - if the subimages are chosen via the cursor(s)
             (b) image,table - if the subimages are defined in a table in the
                 columns labeled :XSTART, :XEND, :YSTART and :YEND
             (c1) image - if subimage is defined by `Fsiz,Nsiz,Bsiz' around
                         center of the image
             (c2) image,xpix,ypix - if subimage is defined by `Fsiz,Nsiz,Bsiz'
                         around pixel (xpix,ypix) of the image
             defaulted to CURSOR
\ap\pa
          out_specs = output specifications:
             (d) table name, may be same as given in in_specs (b),
                 if same table only the magnitude, sigma-mag., sky value and
                 sigma-sky will be stored in columns :MAGNITUDE, :MAG_SIGMA,
                 :SKY and SKY_SIGMA. If new table, then in addition to the
                 columns explained above, also the columns labeled :XSTART,
                 :YSTART, :XEND and :YEND will be filled, a column labeled
                 :IDENT will automatically be added if not already existing.
             (e) 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, magnitude, mag-sigma,
                 sky and sky-sigma
             (f) ? , the default, to just display values on the terminal
\ap\pa
          Fsiz,Nsiz,Bsiz = size of flux area, no_man's_land and background
             (sky) area given as world coordinates or pixel numbers;
             the innermost (flux) circle will have a radius of r = (Fsiz-1)/2
             pixels, the total area will be a circle with diameter: 
             1 + 2*(r + Nsiz + Bsiz), i.e. for odd Fsiz we have diameter:
             Fsiz+2*(Nsiz+Bsiz);
             defaulted to @13,@2,@2 (i.e. 13, 2 and 2 pixels)
\ap\pa
          out_opt = options for descriptor or table output:
             A, append data to table/descriptor, else start at the beginning,
             applicable to (d) or (e)
             I, fill column labeled :IDENT in output table with character
             string typed in at the terminal, only applicable to (d) with
             cursor input
             if you want to append rows to the output table and also fill the
             :IDENT column, set `out_opt' = AI;
             defaulted to `+', i.e. none of the above
\ap\pa
          center_params = center_flag,kappa
             center_flag = 1 or 0,
               if 1 we first find the center of the subimage and shift to it
               the center of the window we use for the magnitude calculation;
               else we use the given subimage to calculate the magnitude,
             kappa = factor for kappa-sigma clipping algorithm which is used
               to calculate the mean background (sky);
             defaulted to 0,2. for cursor input, in_specs (a),
             to 1,2. for (b) + (c1), and to 0,2. for (c2)
\ap\pa
          curs_specs = no_curs,drawflg1,drawflg2,max_input
             no_curs = 1 or 2, both for a single cursor with 3 circles which
             have a radius according to Fsiz, Nsiz and Bsiz given above;
             but no_curs = 1 inhibits, no_curs = 2 enables the modification of
             the radius of the circles interactively, as explained below;
             drawflg1 = 1/0 for drawing circles in overlay plane or not,
             drawflg2 = 1/0 for drawing labels in overlay plane or not,
             max_input = max. of cursor inputs.
             this parameter is only used if in_specs = CURSOR (a),
             defaulted to 1,1,0,9999
\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\sa
See also:
          MAGNITUDE/CENTER, MAGNITUDE/RECT, INTEGRATE/APERTURE, 
          CENTER/MOMENT
\as\no
Note:       
          The magnitude calculation is done in a two-step procedure:
          First, the center of the subimages is computed (using the same
          algorithm as in CENTER/MOMENT) , which is then used for the
          magnitude calculations.
            Besides the usual errors due to invalid input parameters, the
          algorithm may fail depending upon the chosen region and 
	  return Nan, Inf, and other such nasty values as magnitude...
	  Keyword OUTPUTR(13) serves as a control flag:
	  OUTPUTR(13) < 0.0 if something failed in the execution of the 
	  command, otherwise it's > 0.0.
            When using the `image,table' input option (b) and the table
          contains also the columns :XCEN, :YCEN, then these center values
          determine the subimages we work on (instead of using :XSTART, ...).
          Depending upon `center_flag' the resulting subimage may again be
          shifted to the newly determined centers. 
            When using the cursor input option (a), 3 circles will be drawn 
          showing the respective areas for the flux calculation,
          the no_man's_land and the background/sky area.
          Press ENTER button on the mouse to start magnitude calculations 
          and draw all the circles. Use the mouse to move the cursor.
          To exit press the EXIT button on the mouse.
          If `no_curs' = 2, use the arrow keys to change the size of the
          cursor circles individually. Pressing the function key F1 lets you
          change the inner circle only, F2 lets you change the middle circle
          only, F3 lets you change the outer circle only and F4 updates all
          circles synchronously (default is F4).
          If you also use the `zw_option', the cursor in the main display
          is 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' I 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 magnitude calculations are also written into
          keyword OUTPUTR.
          Xstart, ystart, xend, yend, xcenter, ycenter are also stored
          as double precision values in keyword OUTPUTD(1 - 6).
            It is recommended NOT to change the size of the flux area once you
          have started in order to integrate always over the same fraction of
          the stellar profile (working in Cursor mode).
            The mean background level is estimated by iterating in a kappa-sigma
          clipping procedure (max_iter=10) with controllable `kappa' (via
          parameter `center_params').
\on\exs
Examples:
\ex
          MAGNITUDE/CIRCLE
            Use cursor to define center of subimages and display start- and
            end-coordinates of subimage as well as magnitude and sky values
            and associated errors on terminal only.
            The sizes of the different cursor circles cannot be modified.
\xe\ex
          MAGNITUDE/CIRCLE cursor p7=w
            As above but use zoom window to determine working area via cursor,
            but we need X11 for that...
\xe\
          MAGNITUDE/CIRCLE CURSOR values,D
            As 1. example but write data to beginning of real descriptor VALUES
            of displayed frame.
\xe\ex
          magnitude/CIRCLE ? values ? ? 1,3.0
            As above but store data into table `values.tbl' (will be created 
            by MIDAS), also we recenter the subimage before computing the 
            magnitudes and use a kappa of 3.0.
\xe\ex
          magnitude/CIRCLE ? values ? A 1,3.0
            As above but append rows with data to table `values.tbl' (if the
            table already exists, othwerwise it will be created).
\xe\ex
          MAGNITUDE/CIRCLE CURSOR values @19,@10,@6 AI
            As above but enter character identifier via keyboard and use
            different Fsize,Nsize,Bsize and do not recenter.
\xe\ex
          MAGNITUDE/CIRCLE ccd001,sources
            Use columns :XSTART, :YSTART, :XEND, :YEND of table 
            `sources.tbl' to define the subimages of `ccd001.bdf', just show
            results on terminal.
\xe\ex
          MAGNITUDE/CIRCLE ccd001,sources sources
            As above but store results also in same table `sources.tbl'
\xe\ex
          MAGNITUDE/CIRCLE ccd001,@120,@320
            Use the subimage centered at xpix=120,ypix=320 of `ccd001.bdf',
            just show results on terminal.
\xe \sxe
