%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1986-2008 European Southern Observatory
%.IDENT      extracrefe.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, EXTRACT/REFERENCE_IMAGE
%.PURPOSE    On-line help file for the command: EXTRACT/REFERENCE_IMAGE
%.VERSION    1.0  04-JUNE-1986 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./REFE
\es\co
EXTRACT/REFERENCE_IMAGE					22-JAN-2008   KB
\oc\su
EXTRACT/REFERENCE_IMAGE in ref out low[,hi] [inout_flag]
	extract subimage according to reference image
\us\pu
Purpose:      
           Extract pixels from input image according to reference image.
\up\sy
Syntax:       
           EXTRACT/REFERENCE_IMAGE in ref out low[,hi] [inout_flag]
\ys\pa
           in = input frame
\ap\pa
           ref = reference frame, must have same dimension as input frame;
	      defaulted to the input image
\ap\pa
           out = resulting 1-dimensional frame
\ap\pa
           low,hi = (closed) interval for pixel values in ref. frame
              low may be set to "<" to indicate minval of ref. frame
              hi may be set to ">" to indicate maxval of ref. frame
\ap\pa
           inout_flag = IN or OUT, to indicate if we look inside or outside
              the interval [low,high]
\ap\no
Note:         
           For all pixels in the ref. frame with a value inside or
           outside the interval [low,hi], depending upon the 'inout_flag'
           parameter, the corresponding pixels of the input frame are 
           copied into the result frame, which will be a 1-dim image 
           (i.e. the pixels will be stored as one vector. 
              By changing the descriptors NAXIS, NPIX, etc. one could then 
           adapt the result frame to your needs.
              A previous version of this command used a different, very
           simple rule for extracting pixels:
           For all pixels in the ref. frame with a value >= 'low',
           the corresponding pixels of the input frame are copied into the
           result frame.
           For backwards compatibility this rule is used when only one
           value is entered for the 'low,hi' parameter and 'inout_flag'
           is not set.
              The no. of pixels found is stored in OUTPUTI(15).

\on\see
See also:     
           EXTRACT/IMAGE, EXTRACT/LINE, FIND/PIXEL
\ees\exs
Examples:
\ex
           EXTRACT/REFERENCE durazno ref result 97.3,> 
             Frame result.bdf will contain all pixels of durazno.bdf where
             the corresponding pixel in ref.bdf has a value >= 97.3
\xe\ex
           EXTRACT/REFERENCE naranja ref result 97.3,> out
             Frame result.bdf will contain all pixels of naranja.bdf where
             the corresponding pixel in ref.bdf has a value < 97.3
\xe\ex
           EXTRACT/REFERENCE naranja ? result 97.3,> out
             Frame result.bdf will contain all pixels of naranja.bdf which
             have a value < 97.3
\xe\ex
           EXTRACT/REFERENCE itest ref result 2.2
             This is the previous usage of the command: frame result.bdf will 
             contain all pixels of itest.bdf where the corresponding pixel 
             in ref.bdf has a value >= 2.2
\xe\ex
\xe \sxe
