% @(#)find_pixe.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:37 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      find_pixe.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, FIND/PIXEL
%.PURPOSE    On-line help file for the command: FIND/PIXEL
%.VERSION    1.0  23-JAN-1989 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./PIXE
\es\co
FIND/PIXEL						16-JUL-1997  KB
\oc\su
FIND/PIXEL frame lo,hi [inout_flag] [first_flag] [out_spec] [maxnpix] [area]
	find first/all pixel(s) with a value in/outside interval [low,high]
\us\pu
Purpose: 
          Find first or all pixel(s) with a value inside or outside the
          closed interval [low,high].
\up\sy
Syntax: 
          FIND/PIXEL frame lo,hi [inout_flag] [first_flag] [out_spec] [maxnpix]
                     [area]
\ys\pa
          frame = name of frame to work on, max. 3 dimensions
\ap\pa
          lo,hi = low and high end of value-interval;
\\
               low may be set to "<" to indicate neg. infinity,
\\
               high may be set to ">" to indicate pos. infinity
\ap\pa
          inout_flag = IN or OUT, to indicate if we look inside or outside the
               interval [low,high];
\\
               defaulted to IN
\ap\pa
          first_flag = F(irst) or A(ll) if we want first pixel or all pixels
               in/outside the interval;
\\
               defaulted to F
\ap\pa
          out_spec = table or image name, only applicable for first_flag = ALL
\\
               to distinguish an image from a table, the image has to be
               specified as `name,image', for table just `name' is o.k.
\\
               to store all pixels in/outside the interval in a table or image.
\\
               For table, columns filled are :X_PIX, :Y_PIX, :Z_PIX, :VALUE;
\\
               for image, the output image will contain all pixels found
               and NAXIS=1, NPIX=nopix_found;
\\
               if omitted (the default) data are only displayed on the terminal
\ap\pa
          maxnpix = max. no. of pixels to be selected;
\\
               if the table option above is used, that means the max. no. of
               rows which are written,
\\
               however, the frame is searched fully to obtain the true count 
               of pixels inside/outside given interval;
\\
               if set to 0 no max-check is applied;
\\
               if set to `mx' < 0, max. `mx' pixels are selected and the search
               is stopped, i.e. final count will be at most = `mx';
\\
               defaulted to 0
\ap\pa
          area = subframe in the usual MIDAS form: [xs,ys,zs:xe,ye,ze], see
               Help of READ/IMAGE for more info about the syntax;
\\
               if not given, the complete frame will be searched (default)
\ap\sa
See also:
          STATISTICS/IMAGE, FIND/MINMAX
\as\no
Note: 
          For first_flag = F, the pixel value found is also stored into
          keyword OUTPUTR(1), corresponding pixel frame coordinates are stored
          in key OUTPUTI(1,2,3).
\\
          If a pixel with the desired value could not be found, OUTPUTI(1,2,3)
          are set to 0,0,0 and OUTPUTR(1) is meaningless.
\\
          If first_flag = A, the no. of pixels found is stored in OUTPUTI(1)
\\
          The frame is scanned starting with lowest dimension first. Unless
          the out_spec option is used, all selected data values are displayed
          on the terminal.
\on\exs
Examples:
\ex
          FIND/PIXEL manzana -22.1,12.3 OUT
            Find first pixel in frame `manzana.bdf' with a value which
            is less than -22.1 or greater than 12.3
\xe\ex
          FIND/PIXEL durazno 97.3,> in ALL platano
            Find all pixels in frame `durazno.bdf' with intensity >= 97.3 
            and store frame pixel indices as well as the data value in table
            `platano.tbl'.
\xe\ex
          FIND/PIXEL durazno 97.3,> ? ALL platano 55
            As above but write at most 55 rows into table `platano.tbl'.
            However, the true no. of pixels with intensity >= 97.3 is displayed
            and stored in keyword OUTPUTI(1).
\xe\ex
          FIND/PIXEL naranja -22.1,12.3 in all toronja,ima
            Find all pixels in frame `naranja.bdf' with a value which is in
            the interval [-22.1,12.3] and store them into 1-dim frame 
            `toronja.bdf'.
\xe\ex
          FIND/PIXEL fresa 97.3,111.2 out all ? -10 [<,@100:>,>]
            Find all pixels in frame `fresa.bdf' with data value outside the
            interval [97.3,111.2]. The search is started at row 100 of 
            `fresa.bdf' and once 10 such pixels are found we stop.
\xe\sxe