; docformat = 'rst'
;+
; This is an example program to demonstrate how to create a GOES image plot
; in with each pixel has an associated latitude and longitude with Coyote Graphics routines.
;
; :Categories:
;    Graphics
;    
; :Examples:
;    Save the program as "goes_image_plot.pro" and run it like this::
;       IDL> .RUN goes_image_plot
;       
; :Author:
;    FANNING SOFTWARE CONSULTING::
;       David W. Fanning 
;       1645 Sheely Drive
;       Fort Collins, CO 80526 USA
;       Phone: 970-221-0438
;       E-mail: david@idlcoyote.com
;       Coyote's Guide to IDL Programming: http://www.idlcoyote.com
;
; :History:
;     Change History::
;        Written, 27 January 2013 by David W. Fanning.
;
; :Copyright:
;     Copyright (c) 2013, Fanning Software Consulting, Inc.
;-
PRO GOES_Image_Plot
 
   ; Set up variables for the plot. Normally, these values would be 
   ; passed into the program as positional and keyword parameters.
   ; GOES images are not map projected, but have associated latitude
   ; and longitude values with each pixel in the image. The IDL save
   ; file used here contains a GOES image of Peru. Additional information
   ; can be obtained here: http://www.idlcoyote.com/map_tips/goesmap.html.
   goesDataFile = 'goes_example_data.sav'
   
   ; Restore the variables: peruImage, peru_lat, and peru_lon.
   Restore, goesDataFile
   
   ; These must be divided by 1000 to convert them to the 
   ; proper floating point values.
   lats = Temporary(peru_lat) / 10000.0
   lons = Temporary(peru_lon) / 10000.0
   Help, peruImage, lats, lons
   
   ; Find the center of the image.
    s = Size(peruImage, /DIMENSIONS)
    centerLat = lats[s[0]/2, s[1]/2]
    centerLon = lons[s[0]/2, s[1]/2]
       
   ; Open a display window.
   cgDisplay, 800, 575
   
   ; Set up a map projection for this image. We will use an Alber's Equal Area
   ; projection. Almost any projection can be used.
   mapPosition = [0.05, 0.05, 0.95, 0.95]
   mapCoord = Obj_New('cgMap', 'Albers Equal Area', Ellipsoid='sphere', $
         Position=mapPosition, Standard_Par1=-19, Standard_Par2=21, $
         Center_Lat=centerLat, Center_Lon=centerLon)  
         
   ; We need to warp the image data into a 2D that we can display. In this
   ; case we use a pixel resolution of 600x500. You have great flexibility in
   ; choosing the resolution. Choose it for your display. The SetRange keyword
   ; sets the XRange and YRange properites of the map coordinate object internally,
   ; so we don't have to set it when we return from cgWarpToMap.
   warped = cgWarpToMap(peruImage, lons, lats, Map=mapCoord, Missing=0, $
       Resolution=[600, 500], /SetRange)
       
   ; If we just want to see the image, we could display it now. But, I want to see
   ; the image in a larger context, so I can get a better sense of where this image
   ; is located in the world. To do this, I need to expand the map coordinate object's
   ; range. Get the current map range.
   mapCoord -> GetProperty, XRange=xrange, YRange=yrange
   mapCoord -> SetProperty, XRange=[xrange[0]-1.5e6, xrange[1]+1.5e6], $
           YRange=[yrange[0]-1.5e6, yrange[1]+1.5e6], /Draw
   
   ; Draw map annotations.
   cgMap_Continents, MAP=mapCoord, Color='tan', /Fill
   cgMap_Continents, MAP=mapCoord, Color='navy'
   cgMap_Continents, MAP=mapCoord, Color='navy', /Countries
   cgMap_Grid, Map=mapCoord, /Label, Color='navy', LATDEL=8, LONDEL=8, /cgGrid
   
   ; Now display the image itself on the map.
   cgImage, warped, Stretch=2, Position=mapPosition, OPosition=imagePos, $
         XRange=xrange, YRange=yrange, /Overplot
   mapCoord -> SetProperty, XRange=xrange, YRange=yrange, Position=imagePos, /Draw
   
   annotateColor = 'Yellow'
   cgMap_Grid, Map=mapCoord, /Label, Color=annotateColor, LATDEL=8, LONDEL=8, /cgGrid
   cgMap_Continents, MAP=mapCoord, Color=annotateColor, /HiRes
   cgMap_Continents, MAP=mapCoord, Color=annotateColor, /Countries
   
END ;*****************************************************************

; This main program shows how to call the program and produce
; various types of output.

  ; Display the plot in a graphics window.
  GOES_Image_Plot
  
  ; Display the plot in a resizeable graphics window.
  cgWindow, 'GOES_Image_Plot',  WBackground='white', $
    WTitle='GOES Image in a Resizeable Graphics Window'
  
  ; Create a PostScript file.
  cgPS_Open, 'goes_image_plot.ps'
  GOES_Image_Plot
  cgPS_Close
  
  ; Create a PNG file with a width of 600 pixels.
  cgPS2Raster, 'goes_image_plot.ps', /PNG, Width=600

END