coyote: CGDRAWSHAPES

Description
This program draws the entities in a shapefile, containing latitude and 
longitude polygons or polylines, on a map projection. To draw the shapefile 
entities automatically, no matter what kind of values the polygon vertices
have, and without a map projection, set the AUTODRAW keyword.
It is assumed a map projection command has been issued and is in effect at
the time this program is called. Alternatively, you can use a cgMap object,
which will set up the map coordinate space and provide the map structure required
for plotting in that XY map coordinate space.
If the ATTRVALUES keyword is undefined, all entities are drawn, but only a single value
for COLORS, FCOLORS, FILL, LINESTYLE, and THICK is allowed.
.. image:: cgdrawshapes.png
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
Examples
Example using cgMap_Set to set up the map projection space::
   shapefile = Filepath(subdir=['examples','data'], 'states.shp')
   cgDisplay, 800, 700
   cgMap_Set, 40.0, -117.5, /Albers, /IsoTropic, Limit=[30, -125, 50, -108], $
       Position=[0.05, 0.05, 0.95, 0.95]
   cgDrawShapes, shapefile, AttrName='STATE_ABBR', $
       AttrValues=['CA', 'OR', 'WA', 'AZ', 'UT', 'ID', 'NV'], Thick=1, $
       FColors=['firebrick', 'grn4', 'pur4', 'tan4', 'steel blue', 'org4', 'yellow'], $
       Fill = Replicate(1, 7), Colors='charcoal'
   cgMap_Grid, LatDel = 2.0, LonDel = 2.0, /Box_Axes, Color='charcoal'
Example using cgMap to set up the map projection space::
   shapefile = Filepath(subdir=['examples','data'], 'states.shp')
   cgDisplay, 800, 700, WID=1
   mapCoord = Obj_New('cgMap', 'Albers Equal Area', Limit=[30, -125, 50, -108], $
              Position=[0.2, 0.05, 0.8, 0.95], CENTER_LATITUDE=40.0, $
              CENTER_LONGITUDE=-117, STANDARD_PAR1=40, STANDARD_PAR2=-39)
   cgDrawShapes, shapefile, AttrName='STATE_ABBR', $
       AttrValues=['CA', 'OR', 'WA', 'AZ', 'UT', 'ID', 'NV'], Thick=1, $
       FColors=['firebrick', 'grn4', 'pur4', 'tan4', 'steel blue', 'org4', 'yellow'], $
       Fill = Replicate(1, 7), Colors='charcoal', MapCoord=mapCoord, /USELIMIT
   cgMap_Grid,  /Box_Axes, Color='charcoal', Map_Structure=mapCoord
Example drawing the states.shp file automatically, without a map projection::
   shapefile = Filepath(subdir=['examples','data'], 'states.shp')
   cgDrawShapes, shapefile, /Autodraw
Example using cgMap to set up the map projection space in a resizeable graphics window::
   shapefile = Filepath(subdir=['examples','data'], 'states.shp')
   cgWindow, WAspect=800.0/700
   mapCoord = Obj_New('cgMap', 'Albers Equal Area', LIMIT=[30, -125, 45, -108], $
              Position=[0.05, 0.05, 0.95, 0.95], CENTER_LATITUDE=37.5, $
              CENTER_LONGITUDE=-117, STANDARD_PAR1=40, STANDARD_PAR2=-39)
   mapCoord -> AddCmd
   cgDrawShapes, shapefile, AttrName='STATE_ABBR', $
       AttrValues=['CA', 'OR', 'WA', 'AZ', 'UT', 'ID', 'NV'], Thick=1, $
       FColors=['firebrick', 'grn4', 'pur4', 'tan4', 'steel blue', 'org4', 'yellow'], $
       Fill = Replicate(1, 7), Colors='charcoal', MapCoord=mapCoord, /AddCmd
   cgMap_Grid, LatDel = 2.0, LonDel = 2.0, /Box_Axes, Color=cgColor('charcoal'), $
        Map_Structure=mapCoord, /AddCmd
History
Modification History::
   Written by David W. Fanning by modifiying DrawStates to be more
      general, 13 May 2010. DWF.
   Added the AUTODRAW keyword for automatic drawing. 15 May 2010. DWF.
   Added COMPILE_OPT idl2 to make sure all loop variables are longs. 5 July 2010. DWF.
   Corrected an aspect ratio problem with AUTODRAW and upgraded to Coyote Graphics. 
      3 January 2011. DWF.
   Previous method of freeing entity pointers took 10 times times longer than freeing
      pointers as I go. Also added MinNumVerts keyword to screen out the drawing of
      small polygons. 6 October 2011. DWF.
   Wrong string case for discovering particular attributes caused them not to be drawn. 27 Oct 2011. DWF.
   Added the ability to draw point shapefiles. Changed default color to "opposite". 20 Aug 2012. DWF.
   Made sure a window is open when the default color is chosen. 29 Aug 2012. DWF.
   Added a DrawMapCoord keyword so that shapes in a different map projection can be drawn on 
      a map correctly. 29 Nov 2013. DWF.
   Changed the default value of the USELIMIT keyword to 1. Mostly, because I've been burned too many
      times to think a default value of 0 makes sense. 29 Nov 2013. DWF.
Copyright
Copyright (c) 2011-2013, Fanning Software Consulting, Inc.
raw the shape file entity on the map projection.
Params
shapefile: in, optional, type=string
    The name of a shapefile. If this variable is not provided, the user will
    be asked to select a shapefile with the normal file dialogs.
Keywords
addcmd: in, optional, type=boolean
    Set this keyword to add the command to a cgWindow.
autodraw: in, optional, type=boolean
    If set, the shapefile entities are examined to find the X and Y
    boundaries and a data coordinate space is set up to display the 
    entities automatically. If the shapefile is drawn automatically,
    the restriction that the shapefile vertices be in latitude and
    longitude values is removed. Do NOT set this keyword, if you
    are using the MAPCOORD keyword, too. If no map projection is
    currently in effect (!X.TYPE NE 3) and no map coordinate object
    has been provided, this keyword is automatically set.
attrname: in, optional, type=string
    The name of the attribute in the file that you wish to draw.
    By default, this is set to the first attribute name in the file.
    If you are unsure of the attribute names in your shapefile,
    use the Coyote Library program `cgShapeInfo` to browse the file
    ahead of time.
attrvalues: in, optional, type=varies
    The value of the attribute identified by ATTRNAME. This variable can
    be a scalar or vector string array identifying a subset of attribute
    values to be drawn. For example, if ATTRNAME='STATE_NAME', then
    ATTRVALUE can identify the particular states to draw. For example,
    ATTRVALUE=['ARIZONA', 'WYOMING', 'OREGON']. By default, the value
    is "ALL", which means that all of the shape entities identified by
    ATTRNAME will be drawn.
colors: in, optional, type=string, default="opposite"
    The name of the color or colors used to draw the entity. This
    may be a string array of the same size as ATTRVALUES.
drawmapcoord: in, optional, type=object
    A map coordinate object (e.g., cgMap) that describes the map projection
    and datum on which the shapes in the shapefile will be drawn. If not
    supplied, the map coordinate object passed with the `mapCoord` keyword will
    be used. Use this keyword only if there is a mismatch in the map projection and
    datum used in the shapefile and the the map projection and datum that the shape
    is to be drawn onto.
fcolors: in, optional, type=string
    The name of the color used to fill the entity. Used if the FILL
    keyword is set. By default, the same as the COLORS keyword.
fill: in, optional, type=boolean
    Set this keyword to fill the entity with a color.
linestyle: in, optional, type=integer, default=0
    The normal linestyle keyword index to choose plotting line styles.
    By default, set to 0 and solid lines. May be a vector of the same
    size as ATTRVALUES.
mapCoord: in, optional, type=object
    A map coordinate object (e.g., cgMap) that describes the map projection 
    and datum used in the shapefile. If `drawMapCoord` is not used, this is also
    the map coordinate system used for drawing the shape or shapes in the file.
    This keyword is required to draw the shapes on a GCTP map projection set up 
    with MAP_PROJ_INIT. Note that this could also be a map structure as returned 
    from MAP_PROJ_INIT, but in that case the user is responsible for setting up the 
    XY map coordinate space independently and outside of this program.
minnumverts: in, optional, type=long, default=3
    Set this keyword to the minimum number of vertices required to actually
    draw a polygon. In other words, to to drawn, a polygon must have at least
    this number of vertices. 
projected_xy: in, optional, type=boolean, default=0
    The program assumes the shapefile entities are expressed in latitude and
    longitude values. If the entiites are expressed in projected XY Cartesian
    coordinates, then set this value.
psym: in, optional, type=integer, default=16
    When drawing points, the symbol to use. May be any value supported by
    cgSymbol. The default is a filled circle, filled with `Colors`.
symsize: in, optional, type=float, default=1.0
    The default symbol size. Used only when displaying points.
thick: in, optional, type=integer, default=1
    The thickness of the line used to draw the entity.
uselimit: in, optional, type=boolean, default=1
    Set this keyword to use the LIMIT as determined from the map coordinate object.
    This keyword applies only if a valid `MapCoord` object is passed to the program.
window: in, optional, type=boolean, default=0
    Set this keyword to add this command to a current cgWindow program. If a
    cgWindow doesn't exist, one is created.