;+
;
; @file_comments
; Draw 2d plots with TV procedure
;
; @categories 
; find a file
; graphic
;
; @param DATA {in}{required}
; The field we want to display can be:
;    1) an array. If the array is not a 2D array, its mean along
;       the z and t direction will be automatically performed
;       (as it is done in plt).
;    2) a structure respecting all criterions specified by
;       <pro>litchamp</pro>
;
; @param MIN {in}{optional}{default=min of DATA (on non-masked points)}
;
; @param MAX {in}{optional}{default=max of DATA (on non-masked points)}
;
; @keyword BOTTOM {default=1}
; The lowest color index of the colors to be used.
;
; @keyword BOXZOOM
; Vector indicating the geographic zone on which we want to cut the map.
;  If BOXZOOM has :
; 1 element : The extraction is made on [lon1, lon2, lat1, lat2, 0.,boxzoom[0]]
; 2 elements: The extraction is made on [lon1, lon2, lat1, lat2, boxzoom[0],boxzoom[1]]
; 4 elements: The extraction is made on [Boxzoom, 0, max([gdept, gdepw])]
; 5 elements: The extraction is made on [Boxzoom[0:3], 0, Boxzoom[4]]
; 6 elements: The extraction is made on Boxzoom
;
; Where lon1, lon2, lat1, lat2 are global variables defined at the last 
; <pro>domdef</pro> !
;
; @keyword C_NAN {default=!d.n_colors < 255}
; The color number that should be used for the NaN values.
;
; @keyword C_MASK {default=0}
; The color number that should be used for the mask values.
;
; @keyword INV
; Reverse the color order
;
; @keyword MASKVAL {default=1.e+20}
; The mask value. Note that if abs(mask) < 1.e6, then the
; exact value of the mask is used to find the maskwd point.
; if abs(mask) > 1.e6, the test to find the masked value is ge
; abs(mask)/10. This is necessary to avoid the rounding errors
;
; @keyword NCOLORS {default=(d.n_colors < 256) - 1 - BOTTOM}
; number of colors to be used.
;
; @keyword NOINTERP
; Used this keyword if you don't want that the values
; are interpolated from BOTTOM using NCOLORS colors.
; This can be for example useful when working on byte type arrays.
;
; @keyword _EXTRA
; Used to pass keywords to <pro>placedessin</pro>, <proidl>TV</proidl>,
; <pro>axe</pro>, <pro>legende</pro>, <pro>barrecouleur</pro>, 
; <pro>terminedessin</pro>
;
; @examples
;   IDL> tvplus, dist(100)
;
; @history
; Aug 2006: Sebastien Masson (smasson\@lodyc.jussieu.fr)
;
; @version
; $Id$
;
;-
PRO pltv, data, min, max, BOTTOM=bottom, BOXZOOM=boxzoom $
        , C_MASK=c_mask, C_NAN=c_nan, INV=inv, MININ=minin, MAXIN=maxin $
        , MASKVAL=maskval, NCOLORS=ncolors, NOINTERP=nointerp $
        , _EXTRA=ex
;
  compile_opt idl2, strictarrsubs
;
  @cm_general ; for key_performance
;--------------------------------------------------------------
  tempsun = systime(1)          ; for key_performance
;--------------------------------------------------------------
;--------------------------------------------------------------
; I2) Reading of the field and checkup.
;--------------------------------------------------------------
  IF n_elements(minin) NE 0 THEN min = minin
  IF n_elements(maxin) NE 0 THEN max = maxin
  IF size(data, /type) NE 8 THEN z2d = reform(float(data)) ELSE z2d = data
  IF size(z2d, /n_dimensions) NE 2 then BEGIN
    if keyword_set(boxzoom) then BEGIN
      savedbox = 1b
      saveboxparam, 'boxparam4pltv.dat'
    ENDIF
    z2d = checkfield(temporary(z2d), 'plt', TYPE = 'xy', direc = direc, BOXZOOM = boxzoom)
    if n_elements(z2d) EQ 1 AND z2d[0] EQ -1 then BEGIN
      IF keyword_set(savedbox) THEN restoreboxparam, 'boxparam4pltv.dat'
      return
    ENDIF
  ENDIF
  dtasize = size(z2d, /dimensions)
;------------------------------------------------------------
; def of ncolmax, bottom, topcol et ncolors
;------------------------------------------------------------
  ncolmax = !d.n_colors < 256
  IF n_elements(bottom) EQ 0 THEN bottom = 1 ELSE bottom = 0 > bottom
  IF NOT keyword_set(ncolors) then topcol = ncolmax - 2 ELSE topcol = (bottom + ncolors - 1) < (ncolmax - 1)
  ncolors = topcol - bottom + 1
;------------------------------------------------------------
; Do we have NaN values in z2d???
;------------------------------------------------------------
  msknan = finite(z2d, /nan)
  nan = total(msknan)
  IF keyword_set(nan) THEN nanind = where(temporary(msknan) EQ 1)
;------------------------------------------------------------
; get the mask
;------------------------------------------------------------
  IF n_elements(maskval) EQ 0 THEN maskval = 1.e20
  IF abs(maskval) LT 1e6 THEN BEGIN
    IF keyword_set(nan) THEN z2d[nanind] = 1.e20
    msk = z2d NE maskval
  ENDIF ELSE BEGIN
    IF keyword_set(nan) THEN z2d[nanind] = 0
    msk = abs(z2d) LT abs(maskval)/10.
  ENDELSE
  maskind = where(msk EQ 0, masked)
  IF keyword_set(nan) THEN z2d[nanind] = !values.f_nan
;------------------------------------------------------------
; get the real min/max and the user defined min/max of the array
;------------------------------------------------------------
  determineminmax, z2d, msk, truemin, truemax, MININ = min, MAXIN = max, NAN = nan
  if n_elements(z2d) EQ 1 AND z2d[0] EQ -1 then BEGIN
    IF keyword_set(savedbox) THEN restoreboxparam, 'boxparam4pltv.dat'
    return
  ENDIF
  z2d = min > temporary(z2d) < max
;------------------------------------------------------------
; apply other keywords (nointerp, c_nan, c_mask)
;------------------------------------------------------------
  IF NOT keyword_set(nointerp) THEN BEGIN
; interpolation between bottom and bottom+ncolors-1
    m = 1.*(ncolors-1)/(max-min)
    p = bottom - 1.*min*m
    z2d = m * temporary(z2d) + p
  ENDIF
; set c_nan for NaN values
  IF keyword_set(nan) THEN BEGIN
    IF n_elements(c_nan) NE 0 THEN cnan = 0 > c_nan < (ncolmax -1) ELSE cnan = (ncolmax -1)
    z2d[nanind] = cnan
  ENDIF
; c_mask for masked values
  IF keyword_set(masked) THEN BEGIN
    IF n_elements(c_mask) NE 0 THEN cmask = 0 > c_mask < (ncolmax - 1) ELSE cmask = (ncolmax -1)
    z2d[maskind] = cmask
  ENDIF
; reverse colors (from topcol to bottom instead of bottom to topcol)
  IF keyword_set(inv) THEN BEGIN
    m = float(topcol   - bottom  )/float(bottom - topcol)
    p = float(bottom^2 - topcol^2)/float(bottom - topcol)
    z2d = m * temporary(z2d) + p
  ENDIF
; avoid rounding errors
  z2d = round(temporary(z2d))
; use byte type to save memory
  z2d = byte(temporary(z2d))
;--------------------------------------------------------------
; .
;--------------------------------------------------------------
  if NOT keyword_set(overplot) then reinitplt, /z, /invert
  placedessin, 'pltv', posplot, posbar, dtasize, _extra = ex
;--------------------------------------------------------------
; 3) Drawing
;--------------------------------------------------------------

   xsize = !p.position[2] - !p.position[0]
   ysize = !p.position[3] - !p.position[1]
   IF !d.name EQ 'X' THEN BEGIN
     xsize = ceil(xsize * !d.x_size)
     ysize = ceil(ysize * !d.y_size)
     z2d = congrid(z2d, xsize, ysize)
   ENDIF

   tv, z2d, !p.position[0], !p.position[1] $
       , xsize = xsize, ysize = ysize $
       , /normal, _EXTRA = ex

;------------------------------------------------------------
;  caption + display of these.
;------------------------------------------------------------
   axe, 'pltv', dtasize, _EXTRA = ex
   legende, truemin, truemax, 'plt', DIREC = direc $
            , INTERVALLE = float(max-min)/(topcol-bottom) $
            , _extra = ex
   plot, [0], [0], /noerase, /nodata, xstyle = 1, ystyle = 1, _extra = ex

   IF keyword_set(masked) THEN tracemask, msk, indgen(dtasize[0]), indgen(dtasize[1])
;------------------------------------------------------------
; color bar
;------------------------------------------------------------
   IF keyword_set(inv) THEN colors = topcol - bindgen(ncolors) ELSE colors = bottom + bindgen(ncolors)
   barrecouleur, colors, min,  max, 10, position = posbar,  _extra = ex
; 4) End of drawing
   terminedessin, _extra=ex
;
  if keyword_set(savedbox) THEN restoreboxparam, 'boxparam4pltv.dat'
  if keyword_set(key_performance) NE 0 THEN print, 'time pltv', systime(1)-tempsun
;
   return
end