;;----------------------------------------------------------------------------------------
; This example code illustrates how to access and visualize a LaRC CATS HDF5 file in NCL.
;
;   ncl CATS-ISS_L2O_D-M7.2-V1-05_05kmLay.2017-05-01T00-47-40T01-28-41UTC.hdf5.ncl
;   Data variable size is: [DIM_000 | 3786] x [DIM_001 | 10]
;
; CATS: https://cats.gsfc.nasa.gov/
;   The Cloud-Aerosol Transport System (CATS), launched in January of 2015, 
;   is a lidar remote sensing instrument that will provide range-resolved profile 
;   measurements of atmospheric aerosols and clouds from the International Space Station (ISS). 
;   CATS is intended to operate on-orbit for at least six months, and up to three years.
;
; References
; [1] https://cats.gsfc.nasa.gov/data/segment_detail/265125/
; [2] https://cats.gsfc.nasa.gov/media/docs/CATS_QS_L2O_Layer_2.00.pdf
; [3] https://cats.gsfc.nasa.gov/media/docs/ISS-CATS_Final_508.pdf
;;----------------------------------------------------------------------------------------

   ;dir_name  = "/project/cas/shea/HDF5/"
   ;dir_name  = "/glade/p/ncldev/data/hdf5/" 
    dir_name  = "./"
    file_name = "CATS-ISS_L2O_D-M7.2-V1-05_05kmLay.2017-05-01T00-47-40T01-28-41UTC.hdf5"
    path_name = dir_name + file_name

    var_name  = "/layer_descriptor/Aerosol_Type_Fore_FOV" ; HDF path
                                                          ; user specified
    nlay      = 0                                         ; 'layer'
    nloc      = 2                                         ; 'location'

    f    = addfile(path_name, "r")                        ; open file
    data = f->$var_name$(:,nlay)                          ; read only specified 'layer'
    printVarSummary(data)                                 ; data(3786)
    printMinMax(data,0)                                   ; min=0   max=8
    print("---")
    
;-- Get the geolocation data using 'nloc'

    latitude        = f->$"/geolocation/CATS_Fore_FOV_Latitude"$(:,nloc)  
    longitude       = f->$"/geolocation/CATS_Fore_FOV_Longitude"$(:,nloc)

    printVarSummary(latitude)                             ; [DIM_000 | 3786]
    printMinMax(latitude,0)                               ;  min=-13.7501   max=51.795
    print("---")
    printVarSummary(longitude)                            ; [DIM_000 | 3786]
    printMinMax(longitude,0)                              ;  min=-179.983   max=179.978 
    print("---")

;******************************************************************
; Define aerosol category types and corresponding colors
; Explore the data: Count and print the number in each category
;******************************************************************

   catTypes   = (/ "invalid" \                                              ; 0
                 , "marine"  , "p. marine"     , "dust" , "dust mixture" \  ; 1,2,3,4
                 , "clean/bg", "p. continental", "smoke", "volcanic"     /) ; 5,6,7,8  
   nCatTypes  = dimsizes(catTypes)                                          ; nCatTypes=9

   catColors  = (/ "gray90"  \                                              ; 0
                 ,  "blue", "aquamarine", "yellow", "orange" \              ; 1,2,3,4
                 , "green",        "red", "black" , "brown"  /)             ; 5,6,7,8
   nCatColors = dimsizes(catColors)                                         ; nCatColors=9

   do k=0,nCatTypes-1            
      knt = num(data.eq.k)
      print("k="+k+sprinti("%5i",knt)+"  "+catTypes(k)+"  "+catColors(k))
   end do
   print("---")

;******************************************************************
; create plot
;******************************************************************
   wks = gsn_open_wks("png" ,"CATS_poly_labelbar_"+nlay+"_"+nloc); send graphics to PNG file

;---Create base map

   res                      = True                 ; plot mods desired
  ;res@gsnDraw              = False
   res@gsnFrame             = False
   res@gsnMaximize          = True                 ; maximize plot

   res@mpFillOn             = False                ; do not fill land with light gray [default]
   res@mpGridAndLimbOn      = True
   res@mpGridLatSpacingF    = 45
   res@mpGridLonSpacingF    = 45
   res@mpGridLineDashPattern=  2

   res@tiMainString         = file_name
   res@tiMainFontHeightF    = 0.016 
   res@gsnLeftString        = "Unobstructed FOV Quality Flag"
   res@gsnRightString       = "nlay="+nlay+" nloc="+nloc

   map  = gsn_csm_map(wks, res)                     ; map

;---Place 'small' colored markers onto map
;---http://www.ncl.ucar.edu/Document/Graphics/Images/markers.png

   polyres                   = True
   polyres@gsMarkerIndex     =  1                   ; period
   polyres@gsMarkerSizeF     = 0.01 

;---For each of the aerosol catagories add the appopriate colored marker  
;---Must check for a category where no values were encountered (=> _FillValue)

   object = new(nCatTypes,"graphic")                ; graphic object place holder
   do k=0,nCatTypes-1
      ji        := ind(data.eq.k)                   ; indices will change each iteration
      nji        = dimsizes(ji)
      if (nji.gt.1 .or. .not.ismissing(ji)) then 
          polyres@gsMarkerColor  = catColors(k)
          object(k)  = gsn_add_polymarker(wks,map,longitude(ji),latitude(ji),polyres)
      end if
   end do
   draw(map)

;---Explicitly create and locate label bar based on 'map' ViewPort information

   getvalues map                                 ; get 'map' ViewPort information
     "vpXF"      : vpx
     "vpYF"      : vpy
     "vpWidthF"  : vpw
     "vpHeightF" : vph
   end getvalues

   lbres                    = True               ; Set up a resource list for the labelbar.
   lbres@vpWidthF           = vpw                ; size for map
   lbres@vpHeightF          = 0.075              ; make thinner
   
  ;lbres@lbBoxLinesOn       = False
   lbres@lbFillColors       = catColors
   lbres@lbLabelStrings     = catTypes    
   lbres@lbOrientation      = "Horizontal"
   lbres@lbLabelAlignment   = "BoxCenters"
   lbres@lbLabelAutoStride  = False              ; False =>  every label
   lbres@lbMonoFillPattern  = True
   lbres@lbLabelFontHeightF = 0.012
   lbres@lbPerimOn          = False

   xpos = (1.-vpw)/2 + 0.025
   ypos = (vpy-vph)  - 0.040

   gsn_labelbar_ndc (wks,nCatColors,catTypes,xpos,ypos,lbres)
   frame(wks)