%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990,2003 European Southern Observatory
%.IDENT      integraper.hlq
%.AUTHOR     Ch. Ounnas, IPG/ESO
%.KEYWORDS   MIDAS, help files, INTEGRATE/APERTURE
%.PURPOSE    On-line help file for the command: INTEGRATE/APERTURE
%.VERSION    1.0  ??????: ChO Creation, 
%.VERSION    2.0  900801: RHW completely rewritten
%----------------------------------------------------------------
\se
SECTION./APER
\es\co
INTEGRATE/APERTURE                                      04-JUL-2007 KB
\oc\su
INTEGRATE/APERTURE [in_specs] [out_tab] [radius[,pix_flag]]
	integrate the flux within an aperature
\us\pu
Purpose:    
            Compute integrated flux inside an aperture with a certain radius
\up\sy
Syntax:     
            INTEGRATE/APERTURE [in_specs] [out_tab] [radius[,pix_flag]]
\ys\pa
            in_specs = CURSOR (a) 
		if the apertures are interactively chosen via the cursor 
                (center of circle) from the displayed image; or 
                       GCURSOR (b) 
		if the apertures are interactively chosen via
		the graphics cursor from the plotted image; or 
                       frame,table (c) 
		if the apertures are defined in a table in the columns 
		labeled  :X_COORD, :Y_COORD or :X_COORDPIX, :Y_COORDPIX
                for 1-dim frames only :X_COORD or :X_COORDPIX is needed; or
	               frame,xcent[,ycent]
		if a single aperture is defined via its center world coords;
                defaulted to CURSOR
\ap\pa
            out_tab = optional output table to store the results;
		the table will contain: xcenter, ycenter, radius, no of pixels, 
		flux, background and magnitude in the columns :X_COORD, 
		:Y_COORD, :RADIUS, :NPIX, :FLUX, :BGSB and :MAG;
		defaulted to no output table
\ap\pa
            radius = value in world coords (or frame pixels) to define the
		radius size of the aperture; 
		for `inspecs' = CURSOR (a) it can be omitted and will then be
		derived from the size of the cursor circle;
		also for GCURSOR (b) it can be omitted and will then be
		derived from the size of the interval determined by two
	        cursor clicks;
		for (c) the `radius' parameter must be given
\ap\pa
            pix_flag = F or W, indicating that the radius is expressed either
		as frame pixels or as world coordinates
\ap\no
Note:       
            The command does not compute the background level. If descriptor
            'BACKGROUND' exists for the input frame, the value of this 
	    descriptor is used (i.e. subtracted). In case the descriptor does
	    not exist, the background is assumed to be 0.

            The flux of the objects after sky background must be positive. 
            If not the command will fail and will output zeroes. 
\on\exs
Examples:
\ex
            INTEGRATE/APERTURE
              Use cursor in displayed image to define subimages and display 
	      the results on the terminal only.
\xe\ex
            INTEGRATE/APERTURE CURSOR values
              As above but write also the results into the table `values.tbl'.
\xe\ex
            INTEGRATE/APERTURE CURSOR values 11,F
              As above but set the radius of the aperture to fixed value in
              screen pixels corresponding to 11 frame pixels of the displayed 
              frame.
\xe\ex
            INTEGRATE/APERTURE GCURSOR 
              Use cursor in graphics window with plotted image twice to define 
	      the start and end of interval for integration and display 
	      the results on the terminal only.
\xe\ex
            INTEGRATE/APERTURE ccd001,sources ? 11.3
              Use columns :X_COORD,:Y_COORD (or :X_COORDPIX,:Y_COORDPIX)
              of table `sources.tbl' (created by GET/CURSOR for example) 
	      to define the centers of the apertures with radius of 11.3, 
	      compute the flux in the image `ccd001.bdf' and just display
	      the results.
\xe\ex
            INTEGRATE/APERTURE ccd001,sources values 11.3
              As above but the results are stored also into the table 
	      `values.tbl'.
\xe\ex
            INTEGRATE/APERTURE ccd001,3.6745,21.233 values 6,f
	      Compute the flux of image `ccd001.bdf' in an aperture
	      with radius of 6 pixels, centered at world coord
              3.6745,21.233, and store the results in table `values.tbl'.
\xe\sxe

