%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2008 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
