coyote: CGMAP__DEFINE

Description
Provides an easy way to set up a map projection coordinate space using GCTP map 
projections normally accessed via Map_Proj_Init. Allows an unlimited number of map
overlays, and can provide a fresh map structure on demand, eliminating the problem
of ephemerial map structures that plaqued Map_Proj_Init until IDL 8.x. This program
is basically a wrapper for Map_Proj_Init, with additional features that make it 
superiour for working with map projections in IDL.
Categories
Graphics, Map Projections
File_comments
Only GCTP projections are allowed. If you wish to use projections normally 
set up with Map_Set, use the comparable cgMap_Set command. 
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::
   Brought over to the Coyote Library from a similar routine in the Catalyst Library.
      Updated to account for the bug that creates incorrect result in UTM projections
      when using the WGS84 ellipsoid. The Wallbeck ellipsoid is substituted for the
      WGS84 ellipsoid in this instance. David W. Fanning, 7 November 2011.
   Added IS_CYLINDRICAL method to solve a problem with grid labeling and drawing
      of grid lines. 16 Dec 2011. DWF.
   Added ERASE method to erase the display. 28 Dec 2011. DWF.
   Added check for identical range values in FORWARD method. 30 Dec 2011. DWF.
   I am convinced that the map structure returned by Map_Proj_Init, when there
      is a LIMIT used in the call contains a uv_box with incorrect latitude values.
      This is important because other routines (e.g., cgMapGrid) depend on these values.
      I've created a fix wherein I fixed the uv_box latitude values to correspond
      to the LIMIT of the map projection. 6 April 2012. DWF.
   Set the default CENTER_LATITUDE and CENTER_LONGITUDE to 0.0. 9 April 2012. DWF.
   Added NOFORWARDFIX keyword to allow skipping of the "fix" in the FORWARD method,
      as sometimes this is not needed or required. 29 June 2012. DWF.
   Fixed a problem that required having to set the UTM zone in addition to the latitude
      and longitude in a UTM projection. Now using cgUTMZone to determine the proper
      zone. 8 Aug 2012. DWF.
   Added a BOUNDARY keyword to the GetProperty method. 16 Aug 2012. DWF.
   Modified to allow Hotine Oblique Mercator map projections to work correctly. 7 Sept 2012. DWF.
   Additional changes to better handle IDL 8.2 map projections. 12 Sept 2012. DWF.
   Added LATLONBOX keyword to the GetProperty method to allow me to obtain
       the map boundary in the Google Map preferred notation of [north, south, east, west]
       in degrees. 30 Oct 2012.
   I was calculating the default X and Y range incorrectly for non-UTM map projections.
       I have now gone back to my original method of using the UV_BOX of the map structure
       to do this. However, there is still a problem with the UV_BOX when the center latitude
       is not zero. I still attempt to fix this problem in the code (SetMapProjection method). 3 Jan 2012. DWF.
   I added ASPECT and ISOTROPIC keywords to allow the setting of the aspect ratio of the map. 3 Jan 2012. DWF.
   Added zone to the information returned with MapInfo method if projection is UTM. 25 April 2013. DWF.
   The map aspect was disappearing because Total(!P.Multi) can occasionally be LT 0! Fixed. 3 July 2013. DWF.
   Added Hughes ellipsoid, used at NSIDC, as index 26 or as "Hughes". 11 Sept 2013. DWF.
   Fixed a bug in the way ellipsoids were selected when using numbers to choose elliposids. All ellipsoids
      with values over 20 were affected. 18 Sept 2013. DWF.
   Added FORMAT keyword to LanLonLabels method. 27 November 2013. DWF.
   Change EASTING and NORTHING keywords to FALSE_EASTING and FALSE_NOTHING to conform to Map_Proj_Init. 29 Nov 2013. DWF.
   Forgetting to add the false_easting and false_northing values to the structure in INIT method. 29 Nov 2013. DWF.
   Added Cylindrical Equal Area to list of projections that don't allow CENTER_LATITUDE keyword. 24 Dec 2014. DWF.
   Typo in code to handle ASPECT ratio was causing aspect ratio of output to be lost. Fixed. 19 Feb 2015. DWF.
Copyright
Copyright (c) 2011-2013, Fanning Software Consulting, Inc.
e initialization method for the cgMap object.
Params
class: out, optional, type=structure
   Occasionally, it is useful to have an object class definition as
   a structure variable. Using this output keyword will allow that.
Keywords
background: in, optional, type=string, default='white'
   The name of the background color. Used only if the map object erases
   the display when it draws its contents.
bcolor: optional, type=string, default='opposite'
   The name of the color to draw box axes with. Requires BOX_AXES be set.
box_axes: in, optional, type=boolean, default=0
   Set this keyword to draw a box-style grid axes around the map. Applies
   only if creating a mapGrid object.
center_latitude: in, optional, type=float, default=varies
   The center latitude of the map projection.
center_longitude: in, optional, type=float, default=varies
   The center longitude of the map projection.
ccolor: in, optional, type=string, default='charcoal'
   The name of the drawing color for the MapContinents object if this is requested.
color: in, optional, type=string, default='opposite'
   The name of the drawing color for the object. Passed along to the mapGrid
   and MapContinents object if these are requested.
continents: in, optional, type=boolean, default=0
   Set this keyword if you wish to create an overlay object of continental outlines
   that will be rendered when the draw method is called.
datum: in, optional, type=string/integer, default='Sphere'
   This keyword is being depreciated in favor of the keyword ELLIPSOID,
   corresponding to changes to Map_Proj_Init initiated in IDL 7.
draw: in, optional, type=boolean, default=0
   Set this keyword if you wish to immediately call the DRAW method after the
   object has been completely initialized.
ellipsoid: in, optional, type=string/integer, default='Sphere'
   Set this to the name or index number of the ellopsoid or datum you wish to use
   for the map projection. The value is passed directly to Map_Proj_Init.
erase: in, optional, type=boolean, default=0
   Set this keyword if you wish to have the object erase the current graphics display
   before drawing its content in the DRAW method. The graphics display will be erased
   in the background color.
false_easting: in, optional, type=double, default=0.0
   Set this keyword to the false easting value (in meters) to be added to each x
   coordinate for the forward transform, or subtracted from each x coordinate for
   the inverse transform.
false_northing: in, optional, type=double, default=0.0
   Set this keyword to the false northing value (in meters) to be added to each y
   coordinate for the forward transform, or subtracted from each y coordinate for
   the inverse transform.
gcolor: in, optional, type=string, default='gray'
   The name of the drawing color for the MapGrid object if this is requested.
grid: in, optional, type=boolean, default=0
   Set this keyword if you wish to create an overlay object of map grid lines
   that will be rendered when the draw method is called.
hires: in, optional, type=boolean, default=0
   Set this keyword if you wish to use high resolution continental outlines.
   Passed to the MapContinents object if one is requested.
latlon_ranges: in, optional, type=boolean, default=0
   Normally the XRANGE and YRANGE keywords are set in terms of projected meters. If 
   this keyword is set, then the values of XRANGE and YRANGE are assumed to be in longitude
   and latitude values, respectively, and will be converted to projected meters prior to 
   being stored in the object.
limit: in, optional, type=FltArr(4), default=none
   The normal LIMIT keyword to Map_Proj_Init, specifying the limit of the map
   projection in terms of latitude and longitude. Normally, little used when using
   Map_Proj_Init. Most work is done by specifying the projected XY rectangular
   coordinate system with the keywords XRANGE and YRANGE.
lcolor: in, optional, type=string
   Set this to the name of the label color to use in labeling grid lines.
   By default, the same as COLOR, or if BOX_AXIS is set, then same as BCOLOR.
map_projection, in, optional, type=varies
   The name or index number of a GCTP map projection to use.
name: in, optional, type=string, default=selected by cgContainer.
   Use this keyword to name the object. Names are often used to select objects in 
   program code. 
noborder: in, optional, type=boolean, default=0
   If this keyword is set, the customary border than surrounds the map projection is
   not drawn.
noforwardfix: in, optional, type=boolean, default=0
   There is, I believe, a bug in MAP_PROJ_FORWARD that renders longitude values 
   incorrectly in projected meter space. This is evidenced by MAP_GRID not producing
   the correct longitude lines in map coordinate systems set up in projected XY meters.
   In the FORWARD method I correct for this. But, this correction is not always needed
   or wanted. This property of the object allows me to turn that correction on or off,
   as needed. Normally, the fix is provided, unless this keyword is set to 1.
onimage: in, optional, type=boolean, default=0
   If this keyword is set, the position of the map projection in the graphics window
   is obtained from the last image displayed with cgImage. This makes it extremely
   easy to display an image and immediately set up a map projection space that will
   allow you to annotate the image using map locations.
position: in, optional, type=FltArr(4)
   The normalized position of the map projection space in the graphics window.
   The default value is [0.075, 0.075, 0.925, 0.900].
radians: in, optional, type=boolean, default=0
   Set this keyword to indicate latitude and longitude values are in radians rather 
   than degrees.
semimajor_axis: in, optional, type=double, default=varies
   The length of the semimajor axis of the ellipsoid in meters. Normally calculated
   from the ELLIPSOID keyword values.
semiminor_axis: in, optional, type=double, default=varies
   The length of the semiminor axis of the ellipsoid in meters. Normally calculated
   from the ELLIPSOID keyword values.
sphere_radius: in, optional, type=double, default=varies
   The length of the ellipsoidal sphere in meters. Normally calculated from the 
   ELLIPSOID keyword values.
title: in, optional, type=string, default=""
   The title of the map projection display.
uvalue: in, optional, type=any, default=none
   A storage space for storing any kind of IDL variable of importance to the user.
xrange: in, optional, type=various
   Set this keyword to the X axis range desired in the data coordinate system.
   Normally expressed in XY projected meter space, unless the LATLON_RANGES 
   keyword is set. The default is mapStruct.uv_box[[0,2]].
yrange: in, optional, type=various
    Set this keyword to the X axis range desired in the data coordinate system.
    Normally expressed in XY projected meter space, unless the LATLON_RANGES 
    keyword is set. The default is mapStruct.uv_box[[1,3]]
zone: in, optional, type=integer, default=varies
    The zone (normally in UTM projections) of the map projection. If not given and needed,
    calculated from the CENTER_LATITUDE and CENTER_LONGITUDE keyword values.
Returns
The projected lon/lat coordinates are returned in a 2xN array. The first
column contains the longitude values and the second column contains
the latitude values.
Private
This method calls MAP_PROJ_INIT to create a map structure variable.
This method should not be called directly. Use GetMapStruct() instead.
This is the clean-up routine for the object.
This is the class definition module. Structures used to manipulate
map projectatum information are also created here.