# coyote: CGCHANGEMAPPROJECTION

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

Description

      This function warps a map projected image from one map projection to another, using
      Map_Proj_Image to do the warping. Useful in general, it is used specifically to
      warp map projected images into the Equirectangular map projection with a WGS 84 ellipsoid
      that is used by Google Earth. See the program `cgImage2KML` to see how it is used.

Categories

      Map Projections, Utilities

Returns

      An image warped into the output map projection is returned.

Params

      image: in, required
         Any 2D or true-color image with or without an alpha channel. This image will
         be warped to the output map projection (`mapOut`).
      mapin: in, required, type=object
         A map coordinate object (cgMap) describing the map projection and coordinates of the
         input image that is to be warped.

Keywords

      boundary: in, optional, type=dblarr
         A four-element array specifying the Cartesian (XY) coordinates of the input
         image range, in the form [xmin, ymin, xmax, ymax]. If this parameter is not
         present, the boundary will be obtained from the `MapIn` map coordinate object.
         On output, this variable will contain the Cartesian boundary of the warped image.
      bilinear: in, optional, type=boolean, default=0
         Set this keyword to warp the image with bilinear interpolation. The default is
         to do nearest neighbor interpolation.
      latlonbox: out, optional, type=fltarr
         A four-element float array containing the boundaries of the warped image in
         the [north, south, east, west] form preferred by Google Earth. Listed as degrees.
      mapout: in, optional, type=object
         A map coordinate object (cgMap) describing the map projection and coordinates of the
         warped image. This image will be warped into this map projection. The [XY]Range of
         this object will be set to the `XYRange` of the output image.
      mask: out, optional
         Set this keyword equal to a named variable that will contain a byte array of the same
         dimensions as the output image, containing a mask of the “good” values. Values in the output
         image that were set to `Missing` (that is, the values were off the map) will have a mask value
         of 0, while all other mask values will be 1.
      missing: in, optional, type=integer, default=0
         Set this keyword equal to an integer value to be used for pixels that fall outside of
         the valid map coordinates. The default value is 0.
      xyrange: out, optional, type=dblarr
         The Cartesian (XY) coordinates associated with the output image. These are the map image
         boundaries of the output image.

Examples

      To prepare a GeoTiff file for creating a KML overlay on Google Earth::
         netObject = Obj_New('IDLnetURL')
         url = 'http://www.idlcoyote.com/data/AF03sep15b.n16-VIg.tif'
         returnName = netObject -> Get(URL=url, FILENAME=AF03sep15b.n16-VIg.tif')
         Obj_Destroy, netObject
         map = cgGeoMap('AF03sep15b.n16-VIg.tif')
         googleMap = Obj_New('cgMap', 'Equirectangular', Ellipsoid='WGS 84')
         warpedImage = cgChangeMapProjection(image, map, MAPOUT=googleMap)

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, 30 October 2012 by David W. Fanning.
         Fixed a problem with a TRANSPOSE command for true-color images. Bad logic. 4 Jan 2012. DWF.
         Fixed a problem in which Map_Proj_Image was not handling true-color image warping correctly
            and also a problem with handling missing values passed from cgImage2KML correctly. 20 Feb 2013. DWF.
         Forgot to specify the default value for MISSING. 25 Feb 2014. DWF.

Copyright

      Copyright (c) 2012, Fanning Software Consulting, Inc.