;+
;
; @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
; litchamp cf. IDL> xhelp,'litchamp'
;
; @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
; domdef !
;
; @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 placedessin, TV,
; axe, legende, barrecouleur,
; terminedessin
;
; @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