# coyote: CGMAP__DEFINE

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

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.