coyote: CGMAP_GSHHS

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 `.
An `article describing how to use this program `
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.