;+
;
; @file_comments
; interpolate data from an irregular 2D grid to any 2D grid.
;   Only 1 method available = bilinear
;
; @categories
; Interpolation
;
; @param method {in}{required}{type=string}
; the interpolation method. must be 'bilinear'
;
; @param datain {in}{required}{type=2d array}
; the input data to interpolate
;
; @param lonin {in}{required}{type=2d array}
; the longitude of the input data
;
; @param latin {in}{required}{type=2d array}
; the latitude of the input data.
;
; @param mskin {in}{required}{type=2d array or -1}
; a 2D array, the land-sea mask of the input data (1 on ocean, 0 on land)
; put -1 if input data are not masked
;
; @param lonout {in}{required}{type=1d or 2d array}
; the longitude of the output data.
;
; @param latout {in}{required}{type=1d or 2d array}
; the latitude of the output data.
;
; @param mskout {in}{required}{type=2d array or -1}
; a 2D array, the land-sea mask of the output data (1 on ocean, 0 on land)
; put -1 if output data are not masked
;
; @keyword WEIG {type=2d array}
; (see ADDR)
;
; @keyword ADDR {type=2d array}
; 1) at the first call of fromirr:
; This keyword can be set to a named variable (undefined or equal to 0) into which the
; addresses used to perform the interpolation will be copied when the current routine exits.
; 2) Next, once this keyword is set to a defined 2d array, it is used to bypass the computation
; of the weights and addresses used to perform the interpolation. In this case, fromirr simply
; compute the interpolated field as:
;          dataout = total(weig*datain[addr], 1)
;          dataout = reform(dataout, jpio, jpjo, /over)
; In that case, method, lonin, latin, are not used (but are necessary).
; lonout, latout are used only to know the output domain size
;
; @keyword 
; _EXTRA to be able to call fromirr with _extra keyword
;
; @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
;
;  To interpolate 1 field:
;
; IDL> tncep = fromirr('bilinear', topa, glamt, gphit, tmask[*,*,0], lonout, latout, mskout)
;
;  or if you have several fields to interpolate from the same source and target grids
;
; 1) get back the weights and addresses in variables a and b
;   (that must be undefined or equal to 0 before calling fromirr)
;
; IDL> t1ncep = fromirr('bilinear', topa, glamt, gphit, tmask[*,*,0], lonout, latout, mskout $
;                            , WEIG = a, ADDR = b)
; IDL> help, a, b
;
; 2) use a and b that are now defined to bypass the computation of the weights 
; and addresses and speed-up the computation!
;
; IDL> t2ncep = fromirr('bilinear', topa, WEIG = a, ADDR = b)
;
; @history
;  June 2006: Sebastien Masson (smasson\@lodyc.jussieu.fr)
;
; @version
; $Id$
;
;-
;
FUNCTION fromirr, method, datain, lonin, latin, mskin, lonout, latout, mskout $
                  , WEIG = weig, ADDR = addr, _EXTRA = ex
;
  compile_opt strictarr, strictarrsubs
;
;---------------
; 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
;---------------
  IF NOT (keyword_set(weig) AND keyword_set(addr)) THEN BEGIN
    CASE method OF
      'bilinear':compute_fromirr_bilinear_weigaddr, alon, alat, mskin, olon, olat, mskout, weig, addr
      ELSE:BEGIN
        ras = report(' 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