coyote: CGWARPTOMAP

Description
The purpose of this function is to warp an image into a map projection, given
latitude and longitude values for each data point. It is the Coyote Graphics
equivalent of MAP_PATCH in IDL.
Please note: I have only used and tested this function with the well-behaved
data I am using in my own research and for which I needed this functionality.
I have no doubt there might be problems with less well-behaved data sets.
If you discover a problem with your own data, please let me know and I'll take
another look at this function. DWF.
Categories
Graphics, Map Projections
Returns
An output 2D grid in which the data points have been warped into the
particular map projection at the requested pixel resolution.
Params
data:  in, required, type=numerical
    A vector or 2D data set. Longitude and latitude values must be present
    (or easily calculated) for each element in the data array.
lons: in, required, type=float
    If data is a vector, a vector of longitude values corresponding to each
    data value. Values must be in the range -180 to 360. If data is 2D, either
    a 1D vector or a 2D array of corresponding longitude values. If data is 2D,
    and the LONS parameter is missing, a vector of appropriate length scaled into
    the range -180.0 to 180.0 will be created.
lats: in, required, type=float
    If data is a vector, a vector of latitude values corresponding to each
    data value. Values must be in the range -90 to 90. If data is 2D, either
    a 1D vector or a 2D array of corresponding latitude values. If data is 2D,
    and the LONS parameter is missing, a vector of appropriate length scaled into
    the range -90.0 to 90.0 will be created.
Keywords
cubic: in, optional, type=boolean, default=0
   If this keyword is set, and the data is a two-dimensional grid, then cubic
   interpolation will be used to create the output image. It is ignored in the
   case of non-gridded input data.
griddata: in, optional, type=boolean, default=1
   If the input data is non-gridded, setting this keyword will choose the GRIDDATA
   function to grid the data into a 2D output array. If not set, the data will be
   gridded using the TRIGRID function.
map: in, optional, type=object
   An input map projection object (cgMap). If provided, the data will be gridded into
   this map projection. If not provided, a map object using a equirectangular map projection
   with a spherical datum will be used. The XRANGE and YRANGE properties of the map object
   will be set by the program in the course of doing the gridding if the `SetRange` keyword is
   set.
missing: in, optional, type=varies
   Missing data in the gridding process will be set to this value.
nearest_neighbor: in, optional, type=boolean, default=0
   If this keyword is set, the nearest neighbor algorithm will be used to create the output
   grid. Otherwise, bilinear (gridded input data) or natural neighbor (non-gridded input data)
   interpolation is used as the default algorithm. The keyword is ignored if non-grided input 
   data is being used and the GRIDDATA keyword is not set, or if gridded input data is being 
   used and the CUBIC keyword is set. 
resolution: in, optional, type=integer
   A two-element array giving the pixel resolution of the output array in X and Y.
   The default is a 400x400 array.
setrange: in, optional, type=boolean, default=1
   If this keyword is set, the XRANGE and YRANGE parameters of the cgMap object will
   be set to the output X and Y ranges. 
xrange: out, optional, type=float
   The output X range in projected meter space (usually associated with the longitude).
yrange: out, optional, type=float
   The output Y range in projected meter space (usually associated with the latitude).
Examples
To display a GOES image with map annotations::
    fileURL = 'http://www.idlcoyote.com/misc/goes_example_data.sav'
    filename = "goes_example_data.sav"
    netObject = Obj_New('IDLnetURL')
    void = netObject -> Get(URL=fileURL, FILENAME=filename)
    Obj_Destroy, netObject
    Restore, filename 
    peru_lat = Temporary(peru_lat) / 10000.
    peru_lon = Temporary(peru_lon) / 10000.
    s = Size(peruimage, /DIMENSIONS)
    centerLat = peru_lat[s[0]/2, s[1]/2]
    centerLon = peru_lon[s[0]/2, s[1]/2]
    map = Obj_New('cgMap', 'Albers Equal Area', Ellipsoid='sphere', /OnImage, $
       STANDARD_PAR1=-19, STANDARD_PAR2=20, CENTER_LAT=centerLat, CENTER_LON=centerLon)
    warped = cgWarpToMap(peruImage, peru_lon, peru_lat, MAP=map, MISSING=0, $
        Resolution=[400, 300], /SetRange)
    cgDisplay, /Free, Title='Warped Image with cgWarpToMap'
    cgImage, warped, Stretch=2, Position=[0,0,1,1]
    map -> Draw
    cgMap_Grid, Map=map, /Label, Color='goldenrod'
    cgMap_Continents, MAP=map, Color='goldenrod'
    cgMap_Continents, MAP=map, Color='goldenrod', /Countries
Additional examples can be found here: http://www.idlcoyote.com/map_tips/warptomap.php.
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
Modification History::
   Written by David W. Fanning, 12 Sept 2012.
   Modifications to accommodate lat/lon arrays that are one-dimensional to go along
      with 2D data. 13 Sept 2012. DWF.
   Fixed a problems in which projected meter X values were sometimes reversed in order. 31 Oct 2014. DWF.
Copyright
Copyright (c) 2012, Fanning Software Consulting, Inc.