# coyote: CGMAP_GSHHS

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

Description

      The program uses files from the Globally Self-consistent Hierarchical High-resolution Shoreline
      (GSHHS) data base to draw shorelines in the manner of MAP_CONTINENTS. In other words,
      it is assumed that a map coordinate data space has been established prior to calling
      this routine. See the example below. The GSHHS data files are
      `available for downloading <http://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html>`.
      An `article describing how to use this program <http://www.idlcoyote.com/map_tips/gshhs.html>`
      is also available.
      Note, the authors of the GSHHS software *continually* change the header
      structure, which you MUST know to read the data file. There are are now
      at least four different structures in common use. Please find the one
      you need from the commented list in the code itself. The current code uses the structure
      for the 2.2 version of the GSHHS software.
      I have noticed that the polygon areas in the 2.2 version of the GSHHS software seem
      to contain completely bogus information. For example, the Great Lakes polygon is 1.7e7
      square kilometers, while a tiny lake near-by is listed as 3.5e7 square kilometers. I have
      no explanation for why these values seem to be so wrong. I haven't tested this on other
      GSHHS versions of the data.

Categories

      Graphics, Map Projections

Params

      filename: in, optional, type=string
         The name of the GSHHS file to open. If not provided, the user will
         be asked to select the file with a file selection tool.

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.
      color: in, optional, type=string, default="opposite"
          The name of the drawing color.
      fill: in, optional, type=boolean, default=0
          Set this keyword to draw filled outlines.
      land_color: in, optional, type=string, default="tan8"
          The name of the land color (for FILL).
      level: in, optional, type=integer, default=2
          The polygon LEVEL. All polygons less than or equal to this value
          are drawn. 1-land, 2-lakes, 3-island in lake, 4-pond in island.
          By default, 2 (land and lake outlines).
      map_structure: in, optional, type=varies
          A map projection structure (as created from MAP_PROJ_INIT) or a map coordinate
          object (i.e., cgMap). If using a map projection structure, a map coordinate system
          must be set up for the entire display window.
      minarea: in, optional, type=float, default=500
          The minimum feature area in square kilometers. Features with area below
          the minimum area will not be drawn on the map.
      noclip: in, optional, type=boolean, default=0
          Normally the polygons and outlines are clipped to the plot boundaries.
          Set this keyword to turn this feature off.
      outline: in, optional, type=boolean
          Set this keyword to draw outlines on filled polygons. Set to 1, by default,
          if FILL=0. Set to zero to not draw outlines on filled polygons.
      thick: in, optional, type=integer, default=!P.Thick
          Set this keyword to the thickness of the lines that are drawn.
      water_color: in, optional, type=string, default="sky blue"
          The name of color to draw water features in.

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

Examples

      Example using cgMAP_SET to set up the map coordinate space::
          datafile = 'gshhs_h.b'
          cgDisplay, 500, 350
          pos = [0.1,0.1, 0.9, 0.8]
          cgMap_Set, -25.0, 135.0, Position=pos, /Mercator, Scale=64e6, Color='black'
          cgColorfill, [pos[0], pos[0], pos[2], pos[2], pos[0]], $
                       [pos[1], pos[3], pos[3], pos[1], pos[1]], $
                       /Normal, Color='sky blue'
          cgMap_GSHHS, datafile, Fill=1, Level=3, Color='black', /Outline
          cgText, 0.5, 0.85, 'Australia', Font=0, Color='black', /Normal, Alignment=0.5
          cgPlotS, [pos[0], pos[0], pos[2], pos[2], pos[0]], $
                   [pos[1], pos[3], pos[3], pos[1], pos[1]], $
                   /Normal, Color='black', Thick=2
      Example using MAP_PROJ_INIT to set up the map coordinate space::
          datafile = 'gshhs_h.b'
          cgDisplay
          map = Obj_New('cgMap', "Lambert Azimuthal", Limit=[40, -95, 50, -75], $
              Center_Lat=45, Center_Lon=-85)
          map -> SetProperty, Position=[0.1, 0.1, 0.90, 0.75], /Draw
          cgMap_GSHHS, datafile, /Fill, Level=3, Map_Structure=map, $
              Water='DODGER BLUE'
          cgMap_Grid, /Label, /Box, Color='charcoal', Map_Structure=map
          cgMap_Continents, /USA, Map_Structure=map
          cgText, 0.5, 0.85, 'Great Lakes Region', Font=0, Color='charcoal', $
              /Normal, Alignment=0.5

History

      Modification History::
          Written by David W. Fanning, from Map_GSHHS_Shoreline program, 12 November 2011.
          Added THICK keyword. 28 Dec 2011. DWF.
          Modified so you can pass a map object with the MAP_STRUCTURE keyword and not
             have it change the object to a structure. 5 April 2012. DWF.
          Updated to use the polygon magnitude factor when calculating polygon area that
             was introduced in GSSHG 2.2. 22 Nov 2013. DWF.

Copyright

      Copyright (c) 2011, Fanning Software Consulting, Inc.