source: trunk/SRC/ToBeReviewed/PLOTS/DESSINE/plt1d.pro @ 293

;+
;
; @file_comments
; Trace 1d graphs: x,y,z (or t but in this case, we recall directly pltt)
;
; @categories
; Graphics
;
; @param TAB {in}{required}
; The field whose we want to make the hovmoller map can be 2 kind of thing:
;       1) An array which can be:
;          * 2d, 3d or 4d:  array xy, xyz. xyt or xyzt. In this case, the array will pass
;          in moyenne or grossemoyenne to be averaged and become  an array 1d.
;          * 1d:Nevertheless, the type must be specified in order to we know which trace
;          it is about. To have a correct caption, respecify the  extraction zone via BOXZOOM.
;       2) a structure respecting all criterions specified by <pro>litchamp</pro>
;          See IDL> xhelp,'litchamp'. The array contained in the structure
;          respecting criterions of case 1)
;
; @param PARAM2 {in}{required}
; Min value we want to consider in the contour's drawing.
; Note: could also be the type of plot:'x','y','z'
;
; @param PARAM3 {in}{optional}{default=min/max of tab (on ocean points)}
; Max value we want to consider in the contour's drawing.
; Note: if param2 is defined as 'x','y','z' then param3 is used to define the min (see param2)
;
; @param PARAM4 {in}{optional}{default=max of tab (on ocean points)}
; Type of plot (can be only 'x','y','z' for plt1d).
; Note: if param2 is defined as 'xy' then param4 is used to define the max (see param3)
;
; @keyword BOXZOOM
; Vector indicating the geographic zone (3d) on which the extraction of the field must
; be done to do the hovmoeller.
;  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, vert1, vert2]
; 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,vert1,vert2 are global variables defined at the last 
; <pro>domdef</pro> !
;
; @keyword COL1D
;  --OBSOLETE--Color number when we make a trace 1d by default, 0.
; It is better to use the keyword COLOR used by plot.
;
; @keyword ENDPOINTS
; keyword specifying that we want to make a vertical cut in diagonal.
; Then coordinated of extremities of these one are defined by the 4 elements
; of the vector ENDPOINTS: [x1,y1,x2,y2] which are coordinates.
;
; @keyword MAXIN
; Allows to specify the max value we want to consider in the drawing of contour
; helping by the keyword instead of the argument max.
; If the argument and the keyword are specified in the same time, it is the
; value specified by the keyword which is retained.
;
; @keyword MININ
; Allows to specify the min value we want to consider in the drawing of contour
; helping by the keyword instead of the argument min.
; If the argument and the keyword are specified in the same time, it is the
; value specified by the keyword which is retained.
;
; @keyword OV1D
; Allow the double exposure of an 1d curve to a precedent 1d trace.
;
; @keyword REVERSE_X
; To invert the x axis (so as the drawing)
;
; @keyword REVERSE_Y
; To invert the y axis (so as the drawing)
;
; @keyword SIN
; Activate this keyword if we want the x axis to be traced in sinus of the
; latitude when we make a drawing f(y)
;
; @keyword STY1D
; --OBSOLETE--
; Number of the style used when we make a 1d drawing. We should better use the
; keyword LINESTYLE which is tho one of the plot. Beware, this keyword is still
; useful if we want to d bars instead of curves, put sty1d='bar'
;
; @keyword TYPEIN
; allows to specify the type of hovmoller we want to do
;             'xt','yt','zt','t'
; with help of a keyword rather than the argument type. If the argument and the
; keyword are specified in the same time, it is the value specified by the
; keyword which is retained.
;
; @keyword _EXTRA
; Used to pass keywords
;
; @history
; creation 24/6/99 Eric Guilyardi
; (a partir routine pltt de Sebastien Masson)
; 8/7/1999 Sebastien Masson (smasson\@lodyc.jussieu.fr)
; inspection des travaux finis
; 8/2/2000 Sebastien Masson: checkfield
;
; @version
; $Id$
;
;-
;
PRO plt1d, tab, param2, param3, param4, BOXZOOM = boxzoom, SIN = sin $
           , MININ = minin, MAXIN = maxin, TYPEIN = typein, ENDPOINTS = endpoints $
           , COL1D = col1d, STY1D = sty1d, OV1D = ov1d, X = x, Y = y, Z = z, TT = tt $
           , REVERSE_X = reverse_x, REVERSE_Y = reverse_y, SWITCHXY = switchxy $
           , _EXTRA = ex
;
  compile_opt idl2, strictarrsubs
;
@cm_4mesh
@cm_4data
  IF NOT keyword_set(key_forgetold) THEN BEGIN
@updatenew
@updatekwd
  ENDIF
;------------------------------------------------------------
  tempsun = systime(1)          ; pour key_performance
;--------------------------------------------------------------
; 1st part: initialization small calculations...
;--------------------------------------------------------------
;--------------------------------------------------------------
;--------------------------------------------------------------
; verification of the type's value
;--------------------------------------------------------------
;
  if n_elements(param2) NE 0 then type = param2
  if n_elements(param3) NE 0 then min = param3
  if n_elements(param4) NE 0 then max = param4
  if n_elements(minin) NE 0 then min = minin
  if n_elements(maxin) NE 0 then max = maxin
  if keyword_set(tt) then typein = 't'
  if keyword_set(typein) then BEGIN
    if size(type, /type) NE 7 AND size(type, /type) NE 0 then begin
      if n_elements(min) NE 0 then max = min
      min = type
    endif
    type = typein
  endif
;
  checktypeminmax, 'plt1d', TYPE = type, MIN = min, MAX = max, ENDPOINTS = endpoints $
    , XX = keyword_set(x), YY = keyword_set(y), ZZ = keyword_set(z)
  if type EQ 't' then BEGIN
    pltt, tab, type, min, max, BOXZOOM = boxzoom, SIN = sin, TYPEIN = typein $
      , COL1D = col1d, STY1D = sty1d, OV1D = ov1d, ENDPOINTS = endpoints, _extra = ex
    return
  endif
;--------------------------------------------------------------
; I2) reinitialization. !p.,!x.,!y.
; Comment: We do not reinitializate when we call back plt1d
;--------------------------------------------------------------
  if NOT keyword_set(ov1d) then reinitplt
;--------------------------------------------------------------
; I1) Reading of the field
;--------------------------------------------------------------
   if (keyword_set(boxzoom) OR keyword_set(endpoints)) THEN BEGIN
     savedbox = 1b
     saveboxparam, 'boxparam4plt1d.dat'
   ENDIF
;
  if keyword_set(endpoints) then begin
    section, tab, z1d, glam, gphi, ENDPOINTS = endpoints, TYPE = type $
      , BOXZOOM = boxzoom, DIREC = direc
    nx = n_elements(glam)
    ny = nx
    if strupcase(vargrid) EQ 'W' then begin
      z = gdepw[firstzw:lastzw]
      nz = nzw
    ENDIF ELSE BEGIN
      z = gdept[firstzt:lastzt]
      nz = nzt
    ENDELSE
  ENDIF ELSE BEGIN
    z1d = checkfield(tab, 'plt1d', TYPE = type, BOXZOOM = boxzoom $
                     , direc = direc, _extra = ex)
    grille, mask, glam, gphi, gdep, nx, ny, nz, type = type
  ENDELSE
  if n_elements(z2d) EQ 1 AND z1d[0] EQ -1 then BEGIN
    IF keyword_set(savedbox) THEN restoreboxparam, 'boxparam4plt1d.dat'
    return
endif
; We build the mask. For this, the array must be hidden (Automatically done at valmask
; value if we pass in moyenne or grossemoyenne)
  mask = fltarr(n_elements(z1d))
  if n_elements(valmask) EQ 0 then valmask = 1e20
  nan = total(finite(z1d, /nan))  < 1
  if keyword_set(nan) then begin
    notanum = where(finite(z1d) EQ 0)
    z1d[notanum] = 0
    mask[where(z1d LT valmask/10)] = 1
    z1d[notanum] = !values.f_nan
  ENDIF ELSE mask[where(z1d LT valmask/10)] = 1
;-----------------------------------------------------------------------------
; determination of the min and of the max after the average
;-----------------------------------------------------------------------------
  nan = total(finite(z1d, /nan)) < 1
  determineminmax, z1d, mask, mi, ma, MININ = min, MAXIN = max, nan = nan, INTERVALLE = intervalle, _extra = ex
  if n_elements(z2d) EQ 1 AND z1d[0] EQ -1 THEN return
;-----------------------------------------------------------------------------
;-----------------------------------------------------------------------------
  if NOT keyword_set(ov1d) THEN placedessin, 'autre', posfenetre, posbar, contour = contour, DIREC = direc, endpoints = endpoints, _extra = ex
;--------------------------------------------------------------
;--------------------------------------------------------------
; 2nd part: Drawing
;--------------------------------------------------------------
;-----------------------------------------------------------------------------
; definition of the abscisse and ordinate vectors.
; The triangulation is defined in order to the drawing be done from the
; left bottom to the right up. So the matrix have to be shown like this,
; from which some transpose and reverse
;-----------------------------------------------------------------------------
;-----------------------------------------------------------------------------
  case type of
    'y': begin
      yy = z1d
      IF (size(gphi))[0] EQ 1 then xx = gphi ELSE BEGIN
        IF keyword_set(key_irregular) THEN BEGIN
          cln = (where(gphi EQ max(gphi)))[0]
          xx = reform(gphi[cln MOD nx, *])
        ENDIF ELSE xx = reform(gphi[0, *])
      ENDELSE
      if keyword_set(sin) then xx = sin(!pi/180.*xx)
      min0 = lat1 & max0 = lat2
    END
    'x':begin
      yy = z1d
      xx = glam[*, 0]
      min0 = lon1 & max0 = lon2
    END
    'z':begin
      yy = reverse(gdep, 1)
      xx = reverse(z1d, 1)
      min0 = 0 & max0 = 0
      case n_elements(boxzoom) of
        0:!y.range = [vert1, vert2]
        1:!y.range = [0, boxzoom]
        2:!y.range = boxzoom
        4:!y.range = [vert1, vert2]
        5:!y.range = [0, boxzoom[4]]
        6:!y.range = boxzoom[4:5]
      endcase
      if NOT keyword_set(ov1d) then !y.range = reverse(!y.range)
    END
  ENDCASE
;-----------------------------------------------------------
;-----------------------------------------------------------
;   definition of axes
;----------------------------------------------------------
;    if keyword_set(integrationtps) then axe, type, time[0], time[jpt-1], SIN = sin, _extra = ex $
;    ELSE axe, type, SIN = sin
  if NOT keyword_set(ov1d) then axe, type, SIN = sin
;------------------------------------------------------------
;------------------------------------------------------------
; drawing
;------------------------------------------------------------
;------------------------------------------------------------
  if type EQ 'z' then begin
    idx = where(xx NE valmask)
    if NOT keyword_set(ov1d) then BEGIN
      if min EQ mi then !x.range = [min-abs(max-min)/5., max+abs(max-min)/5.] $
      ELSE !x.range = [min, max]
    ENDIF
  ENDIF ELSE BEGIN
    idx = where(yy NE valmask)
    if NOT keyword_set(ov1d) then BEGIN
      if min EQ mi then !y.range = [min-abs(max-min)/5., max+abs(max-min)/5.] $
      ELSE !y.range = [min, max]
    ENDIF
  ENDELSE
;
  if NOT keyword_set(ov1d) then BEGIN
    legende, mi, ma, type, CONTOUR = contour, DIREC = direc, ENDPOINTS = endpoints, _EXTRA = ex
;
  ENDIF
  IF keyword_set(switchxy)  THEN BEGIN
    tmp = xx
    xx = yy
    yy = temporary(tmp)
    if NOT keyword_set(ov1d) then BEGIN
      tmp = !x
      !x = !y
      !y = temporary(tmp)
    ENDIF
  ENDIF
  if NOT keyword_set(ov1d) then BEGIN
    if keyword_set(reverse_x) then !x.range = reverse(!x.range)
    if keyword_set(reverse_y) then !y.range = reverse(!y.range)
  ENDIF
;
  xx = xx[idx]
  yy = yy[idx]
  if (not keyword_set(col1d)) then col1d = 0
  if keyword_set(sty1d) then BEGIN ;If we want to make bars
    IF strlowcase(strtrim(sty1d)) EQ 'bar' then begin
      !y.range = [!y.range[0]-(!y.range[1]-!y.range[0])*.05, !y.range[1]]
      bar_plot, yy, background = (!d.n_colors-1) < 255,  $
        baselines = replicate(!y.range[0], n_elements(yy)), barnames = ['', ''], $
        colors    = replicate(col1d, n_elements(yy)), /outline
      if n_elements(ex) NE 0 then BEGIN
; To have a black frame
        if (where(tag_names(ex) EQ 'COLOR'))[0] NE -1 then ex.COLOR = 0
      ENDIF
      plot, [0], [0], /noerase, /nodata, _extra = ex
      GOTO, fini
    ENDIF
  ENDIF
;
  if NOT keyword_set(ov1d) then BEGIN
;
    plot, xx, yy, color = col1d, linestyle = sty1d, thick = 2, title = '', subtitle = '', _extra = ex
    if n_elements(ex) NE 0 then BEGIN
; To have a 0 colored frame and trace a line at y=0
      if (where(tag_names(ex) EQ 'COLOR'))[0] NE -1 then ex.COLOR = 0
      if (where(tag_names(ex) EQ 'LINESTYLE'))[0] NE -1 then ex.LINESTYLE = 0
      if (where(tag_names(ex) EQ 'THICK'))[0] NE -1 then ex.THICK = 0
    ENDIF
    plot, !x.range, [0, 0], /noerase, /nodata $
      , xstyle = 1+4*(keyword_set(endpoints) AND $
                      ((type EQ 'x' AND lat1 NE lat2) OR (type EQ 'y' AND lon1 NE lon2))) $
      , ystyle = 1, _extra = ex
; Add of an axis in the case where we use endpoints
    if keyword_set(endpoints) then addaxe, endpoints, type, posfenetre, _EXTRA = ex
; Trace a line at x=0
    plot, [0, 0], !y.range, /noerase, /nodata, title = '', subtitle = '', _extra = ex
  ENDIF ELSE oplot, xx, yy, color = col1d, linestyle = sty1d, thick = 2, _extra = ex
;------------------------------------------------------------
;------------------------------------------------------------
; 3rd part: Possible print.
;------------------------------------------------------------
;------------------------------------------------------------
fini:
  terminedessin, _extra = ex
  if keyword_set(savedbox) THEN restoreboxparam, 'boxparam4plt1d.dat'
;------------------------------------------------------------
  if n_elements(key_performance) NE 0 then $
    IF key_performance EQ 1 THEN print, 'temps plt1d', systime(1)-tempsun
;------------------------------------------------------------
;------------------------------------------------------------
;------------------------------------------------------------
  return
end