% @(#)rebin_line.hlq	19.1 (ESO-IPG) 02/25/03 14:03:39 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      rebin_line.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, REBIN/LINEAR
%.PURPOSE    On-line help file for the command: REBIN/LINEAR
%.VERSION    1.0  25-JAN-1990 : Creation, KB
%.VERSION    1.1  09-JAN-1992 : Update, KB
%.VERSION    1.1  01-OCT-1992 : Update, KB
%----------------------------------------------------------------
\se
SECTION./LINE
\es\co
REBIN/LINEAR						26-JUN-1997  KB
\oc\su
REBIN/LINEAR in out [stepx,stepy] [offx,offy] [stx,sty] [fluxcons] [proc_mode]
REBIN/LINEAR in out [refframe] [fluxcons] [proc_mode]
	rebin an image linearly
\us\pu
Purpose:  
          Do linear rebinning of an image using new stepsizes and start 
          points.
\up\sy
Syntax: 
          REBIN/LINEAR in out [stepx,stepy] [offx,offy] [stx,sty] [fluxcons]
                              [proc_mode]
          REBIN/LINEAR in out [refframe] [fluxcons] [proc_mode]
\ys\pa
          in = input frame
\ap\pa
          out = output frame 
\ap\pa
          refframe = optional reference frame; if given, the start (and with
               that the offsets `offx,offy' will be determined) and step values
               for the output frame will be copied from the refframe
\ap\pa
          stepx,stepy = new stepsizes in x,y (in world coordinates) or
	                @xpix,@ypix (pixel coordinates referring to the size
			of the pixels of the input frame);
\\
               defaulted to 1.,1. (world coordinates)
\ap\pa
          offx,offy = absolute offset (in world coordinates) from start in x,y 
               of input frame where we begin sampling for the result frame; 
\\
               defaulted to 0.,0.
\ap\pa
          stx,sty = new start values (in world coords), if given, these
               values will be stored in descriptor START of result frame
               (but they do not affect the beginning of the sampling, that is
               controlled by `offx,offy');
\\
               otherwise, descriptor START of the input frame + the offsets
               described above will determine the new values of START
\ap\pa
          fluxcons = YES or NO, only applicable for new larger stepsizes;
\\
               if YES the total flux should be conserved, i.e. if n pixels of
               value z are rebinned into one, this resulting pixel will have
               value n*z;
\\
               if NO, the resulting pixel will have value z;
\\
               so with NO you can do overlapping PLOT and OVERPLOT commands;
\\
               defaulted to NO
\ap\pa
          proc_mode = optional processing mode for 2-dim and 3-dim frames,
\\ 
               = ROWS, only the rows of a 2-dim frame are rebinned,
\\ 
               = PLANES, all planes of a 3-dim frame are rebinned
\ap\sa
See also:
          REBIN/SPLINE, REBIN/ROTATE, REBIN/II, REBIN/IT, REBIN/TI, REBIN/TT
\\
          REBIN/STATISTICS, RESAMPLE/IMAGE, READ/DESCR, @a scaler
\as\no
Note:  
          In MIDAS the following convention is used:
\\
            World coordinate values (e.g. start values) are related to the
          center of the pixels!
\\
            So, if you have e.g. start values 12.4,4.8 and stepsize 1.4,1.2 in
          a frame, the left and right edges of the first pixel (seen as a small
          plane) would be at 11.7 and 13.1 (x) and the lower and upper edge 
          at 4.2 and 5.4 (y), respectively. 
          The center of the first sampled pixel (new start value) would be at
          12.4+`offx'+0.5*(`stepx'-1.4),and 4.8+`offy'+0.5*(`stepy'-1.2).
\\
          Thus, for an offset of 0 the sampling of the first pixel will start
          again exactly at the lower left edge of the first pixel plane.
\\ 
            Pixels in the result frame sampled outside the input frame are set
          to the null value stored in real keyword NULL(2); the no. of pixels
          set to null will be stored in NULL(1). You can start sampling 
          outside the input frame by specifying the offsets accordingly.
\\
            If you just want to expand a frame by replacing each pixel with
          intensity=I, by N pixels with intensity=I/N without changing the
          start values use the application procedure `scaler.prg' and
          COMPUTE/IMAGE to obtain the desired result. E.g. if we want to
          expand (subsample) a frame `mariposa.bdf' (with start=1.2,1.8 and
          step=1.6,1.6) by a factor of 4 (with result in `rana.bdf'), we do:
\\
          @a scaler mariposa rana 2,2
\\
          compute/image rana = rana/4
\\
          write/descr rana step/d/1/2 0.8,0.8
\\
          write/descr rana start/d/1/2 0.8,1.4
\\ 
            For 3-dim frames only the first plane is rebinned (thus result
          frame is 2-dim image), unless the PLANES processing mode is used,
          in which case all planes of the input cube are rebinned individually
          (result frame is 3-dim image).
\\
  
\\
          If you just want to resample your image, consider RESAMPLE/IMAGE.
\on\exs
Examples:
\ex
          REBIN/LINEAR conejo tortuga 0.3,.9
            Let us assume that the frame `conejo.bdf' has start = 0.0,0.0 and
            step = 1.0,1.0.
\\
            Then we rebin it linearly with stepsizes 0.3 in x- and 0.9 in
            y-direction, we start sampling using the first pixel in x and y of
            `conejo.bdf', and store results in frame `tortuga.bdf'. The result
            frame has start values = -0.35,-0.05 and more pixels than
            `conejo.bdf'.
\xe\ex
          REBIN/LINEAR conejo tortuga 0.3,0.9 1.0,3.3
            As above, but start sampling at pixel with center = 0.65,3.25, 
            therefore `tortuga.bdf' will have less pixels than in the ex. above.
            Descriptor START of tortuga = 0.65,3.25 (0.0+1.0+0.15-0.5,
            0.0+3.3+0.45-0.5).
\xe\ex
          REBIN/LINEAR conejo tortuga 0.3,0.9 1.,3.3 401.3,-20.8
            As above but descriptor START of `tortuga.bdf' will contain
            401.3,-20.8; the data will be exactly the same.
\xe\ex
          REBIN/LINEAR conejo pajaro mariposa 
            Let us assume that the frame `mariposa.bdf' has start = 1.2,1.8 and
            step = 1.6,1.6.
\\
            Then we rebin `conejo.bdf' linearly with stepsizes 1.6 in x- and 
            y-direction.
\\
            We start sampling with the pixel the center of which is located
            at 1.2 and 1.8. Keep intensity of new pixels at same scale and
            store results in frame `pajaro.bdf'.
\xe\ex
          REBIN/LINEAR conejo pajaro mariposa NO
            As above but new pixels will have approx. 1.6 times the intensity
            of the input pixels.
\xe\ex
          REBIN/LINEAR mariposa rana 1.45 -0.2 ? ? rows
            Rebin `mariposa.bdf' only along all rows with new x-step = 1.45
            and offset = -0.2. So `rana.bdf' will have unchanged y-start and
            y-step, i.e. descr. START = 0.925,1.8 and STEP = 1.45,1.6 .
\xe\ex	  REBIN/LINEAR conejo tortuga @2,@2  
            If input image conejo would have step size 1.5,1.5, 
	    this would be binned with a step size of 2 pixels in x and 
	    y direction. Therefore, the output image tortuga.bdf would have 
	    step size 3,3.
\xe\ex	  REBIN/LINEAR conejo tortuga 2,2
            (see last example) this time, the binned image would have step 
	    size 2,2 because the binning was done with a step size of 2 (in
	    world coordinates!)   	    
\xe \sxe
