coyote: CGMAP_GRID

Description
This program provides a significantly modified MAP_GRID command that 
can be used with other Coyote Graphics routines.
  Description of known MAP_GRID problems::
     http://www.idlcoyote.com/map_tips/noclip.html
     http://www.idlcoyote.com/map_tips/missinggrid.html
     http://www.idlcoyote.com/map_tips/extralines.php
Categories
Graphics, Map Projections
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 by David W. Fanning, 7 November 2011.
   Significant modification of the MAP_GRID command in IDL to fix known
      problems, especially when used in conjunction with map projection spaces
      set up with MAP_PROJ_INIT. David W. Fanning, 7 November 2011.
   Added an ERASE=0 to the /NOGRAPHICS keyword on the Draw method call to cgMap. 27 Dec 2011.
   Changed the default line thickness to !P.Thick to better support PostScript files. 28 Dec 2011. DWF.
   Fixed a problem with grid labeling when values were passed with LATS or LONS keyword. 6 April 2012. DWF.
   Modified slightly to allow a three-element byte array to be used as the COLOR. 18 April 2012. DWF.
   If a Map object is available, I make sure to call DRAW method before drawing graphics. 12 Sept 2012. DWF.
   Added cgGRID keyword to allow the cgMap object to create latitude and longitude grid in its
       LatLonLabels method. Previously used by default, but it doesn't work well with global
       map projections. It works best with small map areas in UTM projection space. 3 Jan 2013. DWF.
   Removed some old code that was used to correct latitude and longitude values. No longer needed,
       I hope, with the new cgGRID keyword. 3 Jan 2013. 
   Corrected bug in variable spelling that affect LONDELTA and LATDELTA keywords. 6 Jan 2013. DWF.
   Lost a piece of code that allows longitude box axes. Added back in. 23 Jan 2013. DWF.
   T3D keyword was not being applied. Fixed. 11 February 2013. DWF.
   Added NOCLIP keyword. 15 February 2013. DWF.
   Sometimes a longitude line is draw incorrectly due to the fact that the longitude vector does not
      have a point in the XRANGE of the projection. A fix to that problem has failed to work in all
      circumstances, so I have done more work on that algorithm to see if I can solve the problem is
      a better way. Now usine Value_Locate to test for point. 19 February 2013. DWF.
   Now implementing label formatting when using CGGRID keyword. 27 November 2013. DWF.
Copyright
Copyright (c) 2011-2013, Fanning Software Consulting, Inc.
nd the grid increment find defining the latitude and longitude delta
lues, if they are not currently defined.
Params
xy: in, required, type=float
   The input label point. Normally, a two element array.
Keywords
addcmd: in, optional, type=boolean, default=0
   If this keyword is set, the object is added to the resizeable graphics
   window, cgWindow. Note that a map projection command must be added to the
   window before this command is added to be effective.
bcolor: in, optional, type=string, default='opposite'
   The name of the color to draw box axes with.
bthick: in, optional, type=float
    The thickness of the box axes in device units.
blabel: in, optional, type=float, default=0
     Set this keyword to 0 to label all four of the box axes.
     Set this keyword to 1 to label the left and bottom box axes only.
     Set this keyword to 2 to label the top and right box axes only.
box_axes: in, optional, type=boolean, default=0
   Set this keyword to draw box axes on the map projection.
cggrid: in, optional, type=boolean, default=0
   Set this keyword to allow the latitude and longitude values to be set by
   the LatLon_Labels method in the cgMap object. Previously this was used by
   default, but it caused a lot of problems with global or near global map projections.
   This really should be used ONLY if you are mapping a very small region of the Earth,
   and maybe if you are using a UTM map projection. Othersize, it is probably not 
   needed, so I have made it an optional choice.
charsize: in, optional, type=float
   The character size for the labels. Default is cgDefCharSize()*0.75.
clip_text: in, optional, type=boolean, default=1
   Set this keyword to a zero value to turn off clipping of text labels. 
   By default, text labels are clipped. This keyword is ignored if the `Box_Axes` 
   keyword is set.
color: in, optional, type=string, default='opposite'
   The name of the drawing color for the program.
fill_horizon: in, optional, type=boolean, default=0
format: in, optional, type=string
   Set this keyword to a format for the grid labels.
fuzzy: in, optional, type=float, default=0.0
   This keyword applies only if the MAP_STRUCTURE keyword is used. Set the
   keyword to a value that is a percentage of the current data range.
   This percentage of the range is added to or subtracted from the
   values used to determine if the label is "inside" the boundary.
   It allows you to be a little less exact when selecting inside 
   points. There are occasional aesthetic reasons for allowing fuzzy
   boundaries. A reasonable value for fuzziness might be 0.0125.
glinestyle: in, optional
   Not used. Use `Linestyle` instead.
glinethick: in, optional
   Not used. Use `Thick` instead.
horizon: in, optional, type=boolean, default=0
   Set this keyword to draw the current map horizon.
increment: in, optional, type=integer, default=4
   Determines the smoothness of graticle lines by setting the spacing between
   them. A low number is a smooth number. 
label: in, optional, type=integer, default=0
   An number that tells how to label the grid line. A 0 means no grid lines are 
   labelled. A 1 means all grid lines are labelled. A 2 means label every 2nd 
   grid line is labelled. A 3 means every  3rd grid line is labelled, and so on.
label_with_degree: in, optional, type=boolean, default=0
   Set this keyword to expand the labels with "degrees N/S/W/E" (i.e., $\deg$?).
latalign: in, optional, type=float, default=0.0
   This keyword controls the alignment of the text baseline for latitude labels. 
   A value of 0.0 left justifies the label, 1.0 right justifies it, and 0.5 
   centers it. This keyword is ignored if the `Box_Axes` keyword is set.
latdelta: in, optional, type=float
   Set this keyword to the spacing in degrees between parallels of latitude in
   the grid. If this keyword is not set, a suitable value is determined from the
   current map projection.
latlabel: in, optional, type=float
   The longitude at which to place latitude labels. The default is the center 
   longitude on the map if using Map_Set, and a longitude line on the left of the
   plot if using Map_Proj_Init. This keyword is ignored if the `Box_Axes` keyword is set. 
latnames: in, optional, type=string
   Set this keyword equal to an array specifying the names to be used for the 
   latitude labels. By default, this array is automatically generated in units 
   of degrees. The LATNAMES array can be either type string or any single numeric 
   type, but should not be of mixed type. When LATNAMES is specified, the LATS 
   keyword must also be specified. The number of elements in the two arrays need 
   not be equal. If there are more elements in the LATNAMES array than in the LATS 
   array, the extra LATNAMES are ignored. If there are more elements in the LATS 
   array than in the LATNAMES array, labels in degrees will be automatically 
   provided for the missing latitude labels. The LATNAMES keyword can be also used 
   when the LATS keyword is set to a single value. It this case, the first label 
   supplied will be used at the specified latitude; subsequent names will be 
   placed at the next latitude line to the north, wrapping around the globe if 
   appropriate. Caution should be used when using LATNAMES in conjunction with a 
   single LATS value, since the number of visible latitude gridlines is dependent 
   on many factors. 
lats: in, optional, type=float
   Set this keyword equal to a one or more element vector of latitudes for which 
   lines will be drawn (and optionally labeled). If LATS is omitted, appropriate 
   latitudes will be generated based on the value of the (optional) LATDEL keyword. 
   If LATS is set to a single value, that latitude and a series of automatically 
   generated latitudes will be drawn (and optionally labeled). Automatically generated 
   latitudes have values that extend over the map. If LATS is a single value, that 
   value is taken to be the starting point for labelling (See the LABEL keyword). 
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.
linestyle: in, optional, type=integer, default=1
   This keyword is the same as the GLineStyle keyword, but is a more
   natural way of setting the value.
lonalign: in, optional, type=float, default=0.0
   This keyword controls the alignment of the text baseline for longitude labels. 
   A value of 0.0 left justifies the label, 1.0 right justifies it, and 0.5 
   centers it. This keyword is ignored if the `Box_Axes` keyword is set.
londelta: in, optional, type=float
   Set this keyword to the spacing in degrees between parallels of longitude in
   the grid. If this keyword is not set, a suitable value is determined from the
   current map projection.
lonlabel: in, optional, type=float
   The latitude at which to place longitude labels. The default is the center 
   longitude on the map if using Map_Set, and a longitude line on the left of the
   plot if using Map_Proj_Init. This keyword is ignored if the `Box_Axes` keyword is set. 
lonnames: in, optional, type=string
   Set this keyword equal to an array specifying the names to be used for the 
   longitude labels. By default, this array is automatically generated in units 
   of degrees. The LATNAMES array can be either type string or any single numeric 
   type, but should not be of mixed type. When LATNAMES is specified, the LATS 
   keyword must also be specified. The number of elements in the two arrays need 
   not be equal. If there are more elements in the LATNAMES array than in the LATS 
   array, the extra LATNAMES are ignored. If there are more elements in the LATS 
   array than in the LATNAMES array, labels in degrees will be automatically 
   provided for the missing longitude labels. The LATNAMES keyword can be also used 
   when the LATS keyword is set to a single value. It this case, the first label 
   supplied will be used at the specified longitude; subsequent names will be 
   placed at the next longitude line to the north, wrapping around the globe if 
   appropriate. Caution should be used when using LATNAMES in conjunction with a 
   single LATS value, since the number of visible longitude gridlines is dependent 
   on many factors. 
lons: in, optional, type=float
   Set this keyword equal to a one or more element vector of longitudes for which 
   lines will be drawn (and optionally labeled). If LATS is omitted, appropriate 
   longitudes will be generated based on the value of the (optional) LATDEL keyword. 
   If LATS is set to a single value, that longitude and a series of automatically 
   generated longitudes will be drawn (and optionally labeled). Automatically generated 
   longitudes have values that extend over the map. If LATS is a single value, that 
   value is taken to be the starting point for labelling (See the LABEL keyword). 
map_structure: in, optional
   This keyword is normally used to pass in a map structure of the type
   created by Map_Proj_Init. In this version of the program, it can also
   be used to pass in a cgMap object, from which the map structure and other
   pertinent information for creating map grid lines can be obtained.
noclip: in, optional, type=boolean, default=0
   Normally, output is clipped to the map projection boundaries. Set this keyword
   to be able to draw outside the map boundaries.
no_grid: in, optional, type=boolean, default=0
   Set this keyword if you only want labels but not grid lines.
orientation: in, optional, type=float, default=0.0
   Set this keyword equal to an angle in degrees from horizontal (in the clockwise 
   direction) to rotate the labels. This keyword is ignored if the `Box_Axes` keyword is set. 
t3d: in, optional, type=boolean, default=0
   Set this keyword if you are labeling in 3D space.
thick: in, optional, type=integer, default=!P.Thick
   Sets the thickness of the grid lines.
zvalue: in, optional, type=float
   Draw the grid lines at this Z-value. Implies the use of `T3D`.