Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015

single page | use frames     summary     class     fields     routine details     file attributes


top cgMap_GSHHS

Graphics, Map Projections

cgMap_GSHHS [, filename] [, /ADDCMD] [, COLOR=string] [, /FILL] [, LAND_COLOR=string] [, LEVEL=integer] [, MAP_STRUCTURE=varies] [, MINAREA=float] [, /NOCLIP] [, /OUTLINE] [, THICK=integer] [, WATER_COLOR=string]

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.


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.


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.


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

Author information



David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 < E-mail: Coyote's Guide to IDL Programming:


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


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.

File attributes

Modification date: Fri Mar 27 11:07:35 2015
Lines: 411
Docformat: rst rst