# coyote: CGDRAWSHAPES

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

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.