# coyote: CGWARPTOMAP

- coyote/Graphics
- coyote/Map Projections
- [Source code]

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.