;+
;
; @file_comments interpolate data from an irregular 2D grid to any 2D grid.
;   Only 1 metod available: bilinear
;   
; @categories interpolation
;
; @examples  
; dataout = fromirr(method, datain [, lonin, latin, mskin, lonout, latout, mskout])
;
;    @param method: {in}{required} a string defining the interpolation method. must be 'bilinear'
;    @param datain: {in}{required} a 2D array the input data to interpolate
;    @param lonin: {in}{optional} a 2D array defining the longitude of the input data
;           optionals if WEIG and ADDR keywords used.
;    @param latin: {in}{optional} a 2D array defining the latitude of the input data.
;                     optionals if WEIG and ADDR keywords used.
;    @param mskin: {in}{optional} a 2D array, the land-sea mask of the input data (1 on ocean, 0 on land)
;    @param lonout: {in}{optional} 1D or 2D array defining the longitude of the output data.
;                       optionals if WEIG and ADDR keywords used.
;    @param latout: {in}{optional} 1D or 2D array defining the latitude of the output data.
;                       optionals if WEIG and ADDR keywords used.
;    @param mskout: {in}{optional} a 2D array, the land-sea mask of the ouput data (1 on ocean, 0 on land)
;
; @keyword WEIG (see ADDR)
; @keyword 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. This greatly
;     speed-up the interpolation! In that case, lonin, latin, lonout and latout are not necessary.
;
; @returns 2D array: the interpolated data
;
; @restrictions We supposed the data are located on a sphere, with a periodicity along
;              the longitude.
;              Note that the input data can contain the same cells several times
;             (like ORCA grid near the north pole boundary)
;
; @examples
;  
;  tncep = fromirr('bilinear', topa, glamt, gphit, tmask[*,*,0], lonout, latout, mskout)
;
;  or 
;
;  t1ncep = fromirr('bilinear', topa, glamt, gphit, tmask[*,*,0], lonout, latout, mskout $
;                            , WEIG = a, ADDR = b)
;  help, a, b
;  t2ncep = fromirr('bilinear', topa, WEIG = a, ADDR = b)
;
; @history
;  June 2006: Sebastien Masson (smasson\@lodyc.jussieu.fr) 
; 
;-
;----------------------------------------------------------
;----------------------------------------------------------
;
FUNCTION fromirr, method, datain, lonin, latin, mskin, lonout, latout, mskout $
                  , WEIG = weig, ADDR = addr
;
  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, 2, /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_fromirr_bilinear_weigaddr, alon, alat, mskin, olon, olat, mskout, weig, addr
      ELSE:BEGIN 
        print, ' unknown interpolation method... we stop'
        stop
      ENDELSE
    ENDCASE
  ENDIF
;---------------
; to the interpolation
;---------------
  dataout = total(weig*datain[addr], 1)
  dataout = reform(dataout, jpio, jpjo, /over)
;
  RETURN, dataout
END