# coyote: CGMAP_GRID

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

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.
      degree_label: 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`.