;+
; NAME: fromreg
;
; PURPOSE: interpolate data from a "regular/rectangular grid" to any grid.
;   2 metods availables: bilinear and imoms3 
;   A "regular/rectangular grid" is defined as a grid for which each lontitudes lines have 
;   the same latitude and each latitudes columns have the same longitude.
;   
; CATEGORY:interpolation
;
; CALLING SEQUENCE: dataout = fromreg(method, datain [, lonin, latin, lonout, latout])
;
; INPUTS:
;    method: a string defining the interpolation method. 
;            must be 'bilinear' or 'imoms3'
;    datain: a 2D array the input data to interpolate
;    lonin and latin: longitude/latitude of the input data. optionals if
;            WEIG and ADDR keywords used.
;    lonout and latout: longitude/latitude of the output data. optionals if
;            WEIG and ADDR keywords used.
;
; KEYWORD PARAMETERS: 
;
;     WEIG, ADDR: 2D arrays, weig and addr are the weight and addresses used to
;     perform the interpolation:
;          dataout = total(weig*datain[addr], 1)
;          dataout = reform(dataout, jpio, jpjo, /over)
;     Those keywords can be set to named variables into which the values will be
;     copied when the current routine exits. Next, they can be used to perform
;     the interpolation whithout computing again those 2 parameters. In that
;     case, lonin, latin, lonout and latout are not necessary.
;
;     /NONORTHERNLINE and /NOSOUTHERNLINE: activate if you don't whant to take into
;          account the northen/southern line of the input data when perfoming the
;          interpolation.
;
; OUTPUTS: 2D array: the interpolated data
;
; COMMON BLOCKS: none
;
; SIDE EFFECTS: ?
;
; RESTRICTIONS:We supposed the data are located on a sphere, with a periodicity along
;              the longitude.
;
; EXAMPLE: 
;  
;  topa = fromreg('bilinear', tncep, xncep, yncep, glamt, gphit)
;
;  or 
;
;  t1opa = fromreg('bilinear', t1ncep, xncep, yncep, glamt, gphit, WEIG = a, ADDR = b)
;  help, a, b
;  t2opa = fromreg('bilinear', t2ncep, xncep, WEIG = a, ADDR = b)
;
; MODIFICATION HISTORY:
;  November 2005: Sebastien Masson (smasson@lodyc.jussieu.fr) 
; 
;-
;
;----------------------------------------------------------
;----------------------------------------------------------
;
FUNCTION fromreg, method, datain, lonin, latin, lonout, latout $
                  , WEIG = weig, ADDR = addr $
                  , NONORTHERNLINE = nonorthernline $
                  , NOSOUTHERNLINE = nosouthernline
;
  compile_opt strictarr, strictarrsubs 
;
  IF NOT (keyword_set(weig) AND keyword_set(addr)) THEN BEGIN
;---------------
; atmospheric grid parameters
;---------------
    alon = lonin
    alat = latin
    get_gridparams, alon, alat, jpia, jpja, 1, /double
;---------------
; Oceanic grid parameters
;---------------
    olon = lonout
    olat = latout
    get_gridparams, olon, olat, jpio, jpjo, 2, /double
;---------------
; Compute weight and address
;---------------
    CASE method OF
      'bilinear':compute_fromreg_bilinear_weigaddr, alon, alat, olon, olat, weig, addr, NONORTHERNLINE = nonorthernline, NOSOUTHERNLINE = nosouthernline
      'imoms3':  compute_fromreg_imoms3_weigaddr,   alon, alat, olon, olat, weig, addr, NONORTHERNLINE = nonorthernline, NOSOUTHERNLINE = nosouthernline
      ELSE:BEGIN 
        print, ' unknown interpolation method... we stop'
        stop
      ENDELSE
    ENDCASE
  ENDIF
;
  dataout = total(weig*datain[addr], 1)
  dataout = reform(dataout, jpio, jpjo, /over)
;
  RETURN, dataout
END