Program:       REGRID

Purpose:       Create an output map with different grid along one axis.

Category:      COORDINATES, MANIPULATION, UTILITY

File:          regrid.c

Author:        M.G.R. Vogelaar

Keywords:

   INSET=      Give NAME of set:
    
               There is no need to specify subsets. The 'regrid axis'
               is entered with AXNAME=


   AXNAME=     Enter name of axis to regrid:                    [Abort]
   
               After INSET= a list is displayed with the names of
               all axes in INSET=. One of these axes can be selected
               to become the 'regrid axis'. For this axis you will
               be prompted to enter a new grid spacing. Abbreviation
               of axis names is allowed.


   CDELT=      Enter new grid spac. for ... axis in ...:       [header]
   
               The new grid spacing sets the regridding. It can be a 
               number greater than or less than the original value.
               Its sign will be converted to the sign of the 
               original grid spacing. In the prompt the axis name
               and the corresponding units are listed. The default
               spacing is read from the header. The units are also
               read from the header, but if these units are DEGREE,
               then they are converted to seconds of arc.
  
  
   BOX=        Give BOX in ....                         [entire subset]
   
               Resize the INPUT by entering a box. The default is 
               the entire set as selected by INSET= and the box 
               values cannot exceed the limits of INSET=
               Note that the output set will show axis limits as in
               BOX= except for the 'regrid axis' which will get
               new values because of the regridding.
   
  
   OUTSET=     Give output set:

               This will be the name of the regridded INSET=
               It has sizes as defined by BOX= The size of the
               regridded axis is also defined by CDELT=


   IPOL=       Enter interpolation method:                   [1=linear]
    
               See also 'description'.
               A list with interpolation methods will be presented.
               After selecting a method, the program starts to regrid.


   WIDTH=      Enter width of regridding function:                [1.0]
   
               Only asked if IPOL=2.
               Give the position of the first zero of the sinc 
               in old gridunits.
               
              
             

Description:   Regrid data in INSET= in one direction. The direction
               is one of the axis names in a set. Before the prompt
               AXNAME= you get a list with all set axes. The regrid 
               direction is selected by entering one of the axis names.
               If you want to regrid more than one axis, please repeat 
               the process onto intermediate results (sets).
               The sign of the grid spacing cannot be altered. If you
               want to change this sign then use a program like AXSWAP
               to do this. The new limits of the 'regrid axis' LO and
               HI are:
               
               LOnew = LOold * ABS(CDELTold/CDELTnew)
               HInew = HIold * ABS(CDELTold/CDELTnew)               



               INTERPOLATIONS:
               ==============
               
              
               1) Linear interpolation
               
               Standard linear interpolation between two pixels in the 
               input image.


               2) Sinc interpolation
               
               Interpolation method is SINC.                    
               This gives a weight to an old pixel dependent on 
               its distance to the new pixel position and on    
               the ratio of old and new gridspacings.           
               The default regridding function is the following:
                                                                
                           sin pi*x              pi      2      
                  R(x)  =  --------  exp (  4*ln(--)  * x  )    
                             pi*x                 4             
                                                                
               with  a = signed distance from the central pixel 
               in x or y. This regridding function has the      
               following properties:                            
               R(0) = 1;  R(+/-0.5) = 0.5;  R(+/-1) = 0         
               
              
               3) Spline interpolation
                
               Standard 1-dim. cubic spline interpolation.
               
               4) Average
               
               Replace output by average of a number of input pixels.
               This number of input pixels is set by the ratio of
               input pixels to output pixels. The averaging will only
               work if this ratio is integer and greater than 1.
               
               
              
               BLANKS:
               ======
               
               All interpolation methods take care of blank image data.
               1) If the LINEAR interpolation is used, all input values
                  that are blank, set the corresponding output values
                  to blank.
               2) If the SINC method is used, then the weight of an 
                  'input' blank is set to 0. If the sum of the weights 
                  is 0 then a blank is returned for the output.
               3) The SPLINE method interpolates over blanks.
               
               

Notes:         .......

Example:       .......

Updates:       Dec 07, 1995: VOG, Document created.
               Nov 30, 1998: VOG, Average option inserted.
               Apr 14, 2009: VOG, Replaced macro NINT by a version that uses
                                  floor() which is consistent with other 
                                  routines which process coordinates.