%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  2011 European Southern Observatory
%.IDENT      get_posi.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, FIND/PXPOS
%.PURPOSE    On-line help file for the command: FIND/PXPOS
%.VERSION    
% 110510	creation
% 110517	last modif
%----------------------------------------------------------------
\se
SECTION./PXPOS
\es\co
FIND/PXPOS
\oc\su
FIND/PXPOS in_image [out_table] option disp_flag
	get pixel positions of input image in given data intervals
\us\pu
Purpose:      
	  Get pixel positions of input image in given data intervals
          and store them (optionally) in a table.
\up\sy
Syntax:       
          FIND/PXPOS in_image out_table option disp_flag
\ys\pa
          in_image = name of input image;
		may also be a subimage a[..:..]
\ap\pa
          output_table = name of table, which will be created and
	       filled with the results
	       table columns :X_PIX, :Y_PIX, :Z_PIX (depending on the
	       dimension of the image)  will hold the pixel no's (as real),
	       and the column :VALUE is filled with the intensity at that 
	       pixel position (as real);
	       setting this param. = ? will not create a result table 
\ap\pa
          option = different data interval definitions
	       [a,b], or ]a,b], or [a,b[, or ]a,b[ specifying
	                    closed/open intervals, with a<= b
	       min,nop to return position of the smallest value and 
		          'nop' coords of values closest to the min
	       max,nop to return position of the largest value and 
		         'nop' coords of values closest to the max
	       min+val to return position of the smallest value and 
		                    all coords of values <= min+val
	       max+val to return position of the largest value and 
		                   all coords of values >= max-val
	       med,nop to return position of the median value and 'nop' 
                    coords of closest values below and above the median 
	       med,npa,npb to return position of the median value and 
                 'npa' coords of closest values below the median, and
                        'npb' coords of closest values above the med. 
	       med+val to return position of all coords having values 
                      within the interval [median-val,median+val]
	       med+vala,valb to return position of all coords having 
		      values within the interval [median-vala,median+valb]
\ap\pa
	  disp_flag = YES or NO, to display all pixels found in the
	       interval (then also written into the logfile);
	       defaulted to NO
\ap\sa
See also:
          FIND/PIXEL, READ/IMAGE, WRITE/IMAGE
\as\no
Note:         
          This command is very similar to FIND/PIXEL, but gives
	  additional possiblities for choosing an interval, which would
	  be difficult (or cumbersome) to obtain with FIND/PIXEL.
	  The result table has the same format as the one obtained 
	  from FIND/PIXEL.
             The total no. of pixels found in the given interval is 
	  saved in keyword OUTPUTI(1). On errors, this value will be
	  set to -1.
\on\exs
Examples:
\ex
          FIND/PXPOS manzana ? [-22.1,12.3[ yes
            Find all pixels of image manzana.bdf with intensities >= -22.1 
	    and < 12.3 and display them.
\xe\ex
          FIND/PXPOS fresa.fits restable MAX+0.0234
            Find all pixels of FITS image fresa.fits with intensities 
	    >= Y-0.-234, where Y = max of fresa.fits. 
	    Do not display the pixels found, but store them into the newly
	    created table restable.tbl, the no. of rows written depends on
	    the image data.
\xe\ex
          FIND/PXPOS duraznos buenos MEDIAN,12,4
            In image duraznos.bdf find the 12 closest pixels below the median
	    value and the 4 closest pixels above the median and store their
	    pixel no.s and intensities in table buenos.tbl. A total of
	    12 + 1 + 4 pixels are selected, i.e. 17 table rows are written.
\xe\ex
          FIND/PXPOS duraznos[@10:@2:@100,@4]  MEDIAN,12,4
            Same as above, but only in the given subwindow.
	    Pixel no's. are relative to the subwindow, the corresponding 
	    pixel no's (positions) in full frame durazno.bdf are also
	    displayed.
\xe \sxe
