coyote: CGCLIPTOMAP

Description
Allows an image or geoTiff file to be clipped or subset to a map projected boundary.
Categories
Map Utilities
Returns
The clipped or subsetted image is returned.
Params
imageIn: in, required, type=varies
    Either a 2D or true-color image (in which, in both cases, a map coordinate object must be provided with the
    MAP keyword) or the name of the GeoTiff file from which an image and a map coordinate object
    can be obtained.
boundary: in, required, type=fltarr
    A four-element array containing the map boundary to which the image should be clipped.
Keywords
latlonbox: out, optional, type=fltarr
    A four-element array representing the boundary of the output image in
    the Google Map preferred form of [north, south, east, west] in decimal
    degrees.
map: in, required, type=object
    A map coordinate object (cgMap) that maps or georeferences the input image.
outboundary: out, optional, type=fltarr
    A four-element array containing the final map boundary of the clipped image.
    The boundary will be in XY coordinates (projected meters).
outmap: out, optional, type=object
    An output map coordinate object (cgMap) that describes the output image.
outposition: out, optional, type=intarr
    A four-element array containing the pixel locations of the output image
    in the input image pixel coordinate system: [x0,y0,x1,y1]. In other words,
    these are the values used to subset the input image.
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, 16 August 2012. DWF.
   If the absolute value of the maximum of the boundary is LE 360, assume you need to convert
      from lat/lon space to projected meter space. 23 Aug 2012. DWF.
   Added MAPOUT and LATLONBOX keywords. 1 Nov 2012. DWF.
   Added OUTPOSITION keywords. 29 Nov 2012. DWF.
   I have reason to believe the way I was creating the location vectors and
      and image subset in this program was causing me to be 1 pixel off in
      creating the image subset. The algorithm has been tweaked to correct this. 12 Dec 2012. DWF.
   Duh! Changed the name of MapOut keyword to OutMap to make it work, but forgot to change
       the variable name. Output map coordinate object now returning properly. 20 May 2014. DWF.
Copyright
Copyright (c) 2012, Fanning Software Consulting, Inc.