;------------------------------------------------------------
;------------------------------------------------------------
;------------------------------------------------------------
;+
;
; @file_comments
; Allow to pass from a 2d sill level array to the 3d mask array with 1s in 
; levels above the sill level and 0s below (and on it)
;
; @categories 
; Without loop
;
; @param TAB {in}{required}
; 2d level array of sill level (or a structure respecting litchamp criterions)
;
; @returns
; It is a 3d array containing the mask associated to the 2d sill level array
;
; @uses
; common.pro
;
; @history
; Sebastien Masson (smasson\@lodyc.jussieu.fr)
;                       17/6/1999
; Setp 2004: boundary level have 0 values and not 1 (as it was
; explained before in the header). see:
; print, array_equal(niveau, total(level2mask(niveau),3))
;
;
; @version
; $Id$
;
;-
;------------------------------------------------------------
;------------------------------------------------------------
;------------------------------------------------------------
FUNCTION level2mask, tab
;------------------------------------------------------------
;
  compile_opt idl2, strictarrsubs
;
   tempsun = systime(1)         ; To key_performance
@common
;------------------------------------------------------------
; Reading of the input field and recovery of the size of the used subdomain
;------------------------------------------------------------
   niveaux = litchamp(tab)
   grille,maskterre, -1, -1, -1,nx,ny,nz,firstx,firsty,firstz,lastx,lasty,lastz
;---------------------------------------------------------------
; verification of the coherence between the array's size and the defined by domdef domain
;---------------------------------------------------------------
   IF ny EQ 1 THEN niveaux = reform(niveaux, nx, ny, /over)
   taille = size(niveaux)
   if taille[0] NE 2 then return, report('le champ en entree doit contenir un tableau 2d')
   case 1 of
      taille[1] eq jpi and taille[2] eq jpj:niveaux=niveaux[firstx:lastx, firsty:lasty]
      taille[1] eq  nx and taille[2] eq  ny:
      else:return, report('Probleme d''adequation entre les tailles du domaine et celle du champ.')
   endcase
;------------------------------------------------------------
;------------------------------------------------------------
; We transform the 2d leval array in 3d mask array
;------------------------------------------------------------
   mask = reform( niveaux[*]#(1./(indgen(nz)+1)), nx, ny, nz )
   mask = floor(temporary(mask)) < 1
   mask = temporary(mask)*temporary(maskterre)
;------------------------------------------------------------
;------------------------------------------------------------
;------------------------------------------------------------
   if keyword_set(key_performance) THEN print, 'temps level2mask', systime(1)-tempsun 
   return, mask
end