                                        - 1 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

     NAME
          drawmap - draw customized maps, using raw USGS data files

     SYNOPSIS
          drawmap [-l latitude1,longitude1,latitude2,longitude2] [-L] [-o
          output_file.sun] [-c contour_interval_in_meters] [-a attribute_file]
          [-x x_size] [-y y_size] [-d dem_file1 [-d dem_file2 [...]]] [-g
          gnis_file] [dlg_file1 [dlg_file2 [...]]]

     VERSION
          This is the manual page for version 1.7 of drawmap.

     DESCRIPTION
          The U.S. Geological Survey supports sites on the Internet with many
          gigabytes of raw geographic data, mostly for the USA.  Drawmap draws
          maps, using a subset of the available data for the USA.  The relevant
          subset includes:

          250K Digital Elevation Model (DEM) files
               Each file covers a block, one-degree square, with a 1201 by 1201
               grid of elevations (in meters).  The extra sample in each
               direction is due to overlap of the DEM files at their edges.
               (Files for Alaska use smaller grids, with only 401 or 601 samples
               in the east-west direction.) For Hawaii and the "lower 48," the
               one-degree square is covered by elevation samples spaced 3
               seconds apart.  In terms of distance along the ground, the sample
               spacing varies with latitude.  It is generally less than 100
               meters.

          100K Digital Line Graph (DLG) files (in the 'optional' format)
               These files come in collections, each of which covers a quarter
               of the one-degree square covered by a DEM file.  The files
               contain information that allows segmented linear and polygonal
               features to be drawn on maps, including boundary lines,
               hydrographic features (streams, lakes, and so on), transportation
               features (roads, rail lines, pipelines, and so on), public land
               survey data, and hypsographic lines (the familiar contour lines
               of a topographic map).  The different general classes of data
               come in separate files.

          Geographic Names Information System (GNIS) files
               These files contain lists of place names, complete with their
               latitude/longitude and other information.

          Using the data in these files, drawmap can produce various kinds of
          customized maps, including shaded relief maps (with or without roads,
          streams, place names, and so on) and topographic maps (again, with or
          without additional features).

          The only type of map projection currently supported is a cylindrical
          (Transverse Mercator) projection, with a rectangular grid of latitudes

                                        - 1 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

          and longitudes.  (By default, the grid is square, in the sense that
          1000 pixels in the latitude direction represent the same number of
          degrees as 1000 pixels in the longitude direction.  You can make the
          grid non-square by playing with the "-x" and "-y" options.) There are
          two reasons for using this projection.  First, it is an intuitive
          projection for small-area maps, and is often used for topological
          maps.  Second, the USGS DLG data are specified in the Universal
          Transverse Mercator (UTM) system.

          In order to find your way around the DLG data, it is useful to know
          something about the UTM system, which is an international military
          standard that divides the world into 60 zones (like panels on a beach
          ball), each of which is 6 degrees of longitude in width, and runs from
          80 S to 84 N.  A UTM projection (of a given zone) has a central
          meridian bisecting the map from top to bottom, which serves as a
          reference from which the locations of other features are derived.
          (Zone 1 runs from 180W to 174W, with its central meridian at 177W.
          Successive zones run to the east, with zone 2 beginning at 174W.) In
          the UTM system, the location of a feature is specified by its distance
          to the north of the equator in meters, and its distance eastward from
          the central meridian in meters plus 500,000.  In the southern
          hemisphere, 10,000,000 is added to the distance north from the
          equator.  (The purpose of the 500,000 and 10,000,000 offsets is to
          avoid having any negative distances.) Drawmap internally converts UTM
          distances into latitude/longitude coordinates before plotting features
          on a map.

          The result of the cylindrical projection is to map each one-degree by
          one-degree latitude/longitude patch (on the curved surface of the
          Earth) into a rectangular area (on the map projection).  In the
          process, of course, the projection distorts shapes and areas as it
          stretches the beach-ball panels into rectangular areas; and these
          deviations get larger as the distance from the central meridian
          increases.  Distortion may also occur due to the way the latitude
          lines are projected.  In the classical Mercator projection, for
          example, the latitude lines are spaced farther and farther apart as
          they near the pole.  This gives the map some useful directional
          properties, but grossly distorts shapes and areas near the poles.
          (You can approximate this kind of stretching by using the "-x" and "-
          y" options to vary the number of pixels per longitudinal or
          latitudinal degree.)

          It is a fact of life that mapping a sphere onto a flat piece of paper
          is going to produce distorted results.  Various types of map
          projections are chosen for the ways they preserve one or more valuable
          features of a globe-shaped map (features like shape, area, distance,
          and direction).  In the Transverse Mercator projection used by
          drawmap, the distortions are reasonable for points that are within
          several degrees of the central meridian, and for maps that aren't too
          near the poles.  In fact, a cylindrical projection has the property
          that it is "conformal," meaning that it preserves angles and shapes

                                        - 2 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

          within small areas of the resulting map.

          Since the user can define arbitrary image boundaries, the output map
          may span any portion of one or more UTM zones, and one or more central
          meridians may appear at arbitrary positions within the map boundaries.
          At present, no corrections are made so that the data are plotted
          relative to a new central meridian at the center of the map.  You
          probably won't notice or care.

          The output is an image, in SUN rasterfile format, which can be viewed
          with your favorite image viewer, or converted to other forms for
          display or hard copy output.  (My preferred viewing/converting
          packages are the "ImageMagick" package and the "xv" package.)

          At the time this manual page was written (January, 1999), the DEM and
          DLG files were available for free download from
          http://edcwww.cr.usgs.gov/doc/edchome/ndcdb/ndcdb.html, and the GNIS
          files were available from http://mapping.usgs.gov/.  The first site
          provides a convenient graphical interface that lets you locate desired
          files by clicking on a map.  This can be far superior to trying to
          guess which of hundreds of files contains the data you want.  The
          files are in (gzip-compressed) ASCII text format, and are human
          readable (when uncompressed) except that they generally don't contain
          line-feeds to structure them into individual data records.  The Web
          sites provide information on how to add newlines and view the file
          contents, but drawmap is able to read and use the files in their
          native state (in gzip format, with a ".gz" suffix on the file name).
          Drawmap can also process them in uncompressed form, but will not be
          happy if you add newlines to them.  (Be careful.  Some download
          software will uncompress gzip files during a download but still store
          them in files with a ".gz" suffix.  Other downloading software will
          leave the data compressed, but remove the ".gz" suffix.  Drawmap will
          become confused when this happens.  It relies on the suffix to
          determine the file type.)

          If you provide all three types of files (DEM, DLG, and GNIS) as input,
          then drawmap will first produce a shaded relief map (or, when -c is
          specified, a contour map), and then overlay it with data from the DLG
          files (with the data from each DLG file, in succession, being overlaid
          on all previous data), and then overlay everything with place names
          from the GNIS file.  If you omit the DEM data, then the shaded relief
          (or contouring) is replaced by a simple white background.

          In general, you can add or remove records to or from a DLG or GNIS
          file, as long as you don't violate the record structure.  For example,
          I have added newlines to a DLG file, deleted some records, added some
          records, and then removed all of the newlines to allow drawmap to
          process the file.  If you want to do this sort of thing, then you may
          also want to get copies of the various guides and standards for the
          different kinds of files.  These documents are available through the
          Web sites.  (The drawmap distribution contains two undocumented

                                        - 3 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

          programs to add appropriate newlines to DLG files but, beyond that,
          you are on your own if you want to muck around inside the files.)

        OPTIONS
          Drawmap will take whatever information you provide and assemble a map
          containing just that information.  If you provide information that
          falls outside of your specified map boundaries, it is simply ignored.
          If you supply any DEM data, and if you don't specify a contour map
          (via the -c option), and if there is room, a color key will be placed
          at the bottom of the map to help you interpret the shaded relief.  If
          you specify the -c option, then a message about the contour interval
          will appear at the bottom of the map, if there is room.  Also, if
          there is room, a title will be placed at the top, containing the
          lowest and highest values of longitude and latitude for this map, and
          containing the latitude and longitude of the points on the map of
          lowest and highest elevation.  (Actually, of course, there may be
          multiple points on the map that attain the lowest or highest
          elevation, but drawmap shows only the first ones that it finds.
          Furthermore, for low-resolution output images that have small x and y
          pixel dimensions relative to the granularity of the available DEM
          data, drawmap may be a little sloppy about the exact latitude and
          longitude.) If only one DEM file is supplied, the name of the
          associated DEM block will be included in the title.  Latitude and
          longitude tick marks will be placed around the map boundaries, with
          one tick every tenth of a degree.  Tick marks at full degrees and half
          degrees will be larger and will have text next to them that specifies
          the latitude/longitude.  North is always at the top of the map, and
          east is always at the right.

          -L   Print out the program license information and exit.

          -o output_file.sun
               You may provide an output file name.  It can be any name that you
               choose.  By convention, SUN rasterfile images have a ".sun" file
               name extension, but you can omit it if you wish.  If you provide
               no name, then "drawmap.sun" is used.

          -l latitude_low,longitude_low,latitude_high,longitude_high
               You usually must provide latitude and longitude coordinates that
               define two diagonal corners of the image.  They must be separated
               by a comma or other non-space character (as in:  -l 34.3,-
               109,35.9,-109.713), and they must be in decimal degrees.  Note
               that east longitude is positive and west longitude is negative.
               Similarly, north latitude is positive and south latitude is
               negative.  If you only provide one "-d dem_file" option, then you
               can omit the "-l", and the corners of the single DEM file will be
               used to define the map boundaries.  This is useful when you are
               simply trying to figure out what area a given DEM file covers.

          -d dem_file
               You can provide as many DEM files as you want.  Since each one

                                        - 4 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

               covers a one degree block, it can take quite a few to cover the
               image if you specify a large latitude/longitude range for the
               image boundaries.  (You don't, of course, have to provide enough
               files to cover the whole map area.  Areas not covered by a DEM
               file will simply have a white background.  If you have selected
               the -c option, there will be anomalous contour lines along the
               edges of these white areas.  Sorry.) The DEM files will be
               processed into multicolored shaded relief (or contour lines, if
               you specify the -c option), serving as a background for any other
               features you add to the map.  If you are trying to draw a contour
               map using hypsographic data from DLG files (as opposed to drawing
               a contour map using the -c option and the data in the DEM files),
               then you probably don't want to provide any DEM files, since the
               DEM data will make the contour lines from the DLG files hard to
               follow.

          -c contour_interval_in_meters
               This option has no effect unless you provide one or more DEM
               files.  The DEM files are normally processed into multicolored
               shaded relief.  If you include the -c option, then the shaded
               relief is replaced by a set of contour lines that represent
               elevations separated by the given contour interval (in meters).
               Note that it is also possible to generate contour lines by using
               data in hypsographic DLG files, making the -c option seem
               somewhat redundant.  However, at the present time, the area
               covered by the available DEM files is a large superset of the
               area covered by hypsographic DLG files.  Furthermore, the -c
               option allows finer control over the spacing of contour lines
               than is available with hypsographic DLG data.

          -g gnis_file
               Only one GNIS file is allowed, which is not really a restriction
               since you can edit these files with an ordinary text editor, so
               that they contain whatever place names you want to include.  In
               fact, it is normally necessary to winnow out much of the
               available GNIS data; otherwise the map would be plastered nearly
               solid with place names.  The GNIS data generally come in separate
               files, one for each US state.  Files can be in one of two
               different formats:  a fixed-field-width format in which fields
               are padded out with white space, and a tokenized format in which
               the fields are separated by the delimiter "','".  You can mix
               together records from both formats in your customized GNIS file.
               The llsearch program (included in the drawmap package) allows you
               to extract all place names within a certain range of latitudes
               and longitudes.  You can manually edit the resulting extracted
               data and make further reductions.  Each GNIS entry has a field
               that denotes its type, such as "ppl" for a populated place and
               "summit" for a mountain top.

               The place names are added to the image on top of any other
               features that you choose to include.

                                        - 5 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

          -a attribute_file
               There are three high-level types of objects in a DLG file:  Nodes
               (points where lines join), Areas, and Lines.  These objects often
               have attribute codes associated with them.  Each attribute code
               consists of a major code and a minor code.  The major code
               denotes a particular general type of feature, such as 050 for
               hydrographic features.  The minor code denotes a subtype, such as
               412 for a stream, or 421 for a lake or pond.

               You can provide an attribute file to control what DLG information
               is included in the image.  Each line in the file consists of a
               letter 'N', 'A', or 'L' (for Node, Area, or Line), followed by a
               pair of numbers to denote the major and minor codes, followed by
               any comments you choose to add.  The fields should be separated
               by white space.  Lines that begin with '#', or white space, are
               ignored.

               A negative number for either the major or minor code matches
               anything.  Thus, an attribute specification of "L -1 -1" will
               draw all lines in the DLG files, whether they have associated
               attribute codes or not.  (Omitting the attribute file, or
               providing the "L -1 -1" attribute specification, guarantees that
               every possible line is drawn, except for the "neatlines" that
               form a rectangle around the boundaries of the data from each DLG
               file.) If only the minor code is negative, then all lines of a
               given major type are drawn.  (For example, an attribute
               specification of "L 050 -1" will match all hydrographic
               features.)

               Roads and trails show up in red, hydrographic features in blue,
               hypsographic data in orange, boundaries in gray, and other data
               in black.

               At present, drawmap parses Node data from the DLG file, but does
               nothing at all with it.

               If no attribute file is given, drawmap will ignore the Area data
               from the DLG file.  If Area attributes are specified in the
               attribute file, then drawmap will attempt to fill the specified
               types of areas with the same color as the boundary lines that
               surround them.  The chief use for this is to fill in lakes,
               reservoirs, and the like.  However, because the area-filling
               algorithm is currently not very robust, and because the area data
               in the DLG file can be somewhat ambiguous, it is theoretically
               possible for the outside of an area to be filled in instead of
               the inside.  (I have not had this happen in practice, except when
               stretching a map in one direction by specifying odd map
               dimensions with the "-x" and "-y" options.  However, I haven't
               tried drawing maps with all of the billions of bytes of available
               data.) This potential problem is the reason why areas are not
               filled in unless you make an explicit request in an attribute

                                        - 6 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

               file.

               A more common problem is that sometimes lakes or rivers will be
               only partially filled in.  The reasons for this are beyond the
               scope of this manual page, but are discussed in detail in
               comments in the drawmap source code.

               The distribution for drawmap includes a file, called
               "attrib_codes," which is pulled from a USGS guide, and describes
               the various major and minor codes.  The distribution also
               contains a sample attribute file, called "attributes." The sample
               attribute file contains Area attribute specifications that will
               cause lakes, ponds, streams, and reservoirs to be filled in.

               Precious little error checking is done on the data in the
               attribute file, so be careful.

               There is a debugging feature associated with the attribute file.
               If you specify a major code of 10000, and a minor code of your
               choosing, then the minor code is taken to be a specific node,
               area, or line identifier.  (Within each node, area, or line
               record in a DLG file, the first integer in the record is an
               identifier for the node, area, or line.  In general the nodes,
               areas, and lines are numbered sequentially, starting at 1.) Thus,
               by specifying area or line attributes with major codes set to
               10000, you can draw individual areas or lines from a DLG file.
               This can be useful when you are trying to fine-tune a map or find
               the source of some problem.  When using this feature, it is
               probably not a good idea to include more than one DLG file in the
               input arguments.  This is because the node, area, and line
               identifiers are unique within individual files but are re-used
               from file to file.  Thus, if you specify multiple DLG files, you
               may have a hard time figuring out which file is the source of
               each area or line on the output map.

          -x x_size and -y y_size
               The horizontal and vertical dimensions of the map, in picture
               elements (pixels), can be specified via the x and y options.  You
               can supply either or both of them.  If you don't provide them,
               they will be selected so that the DEM data can be displayed at
               one half of full resolution.  (Full resolution is 1200 pixels per
               degree of longitude or latitude).  It is generally desirable to
               specify small x and y values, when you are first trying to fine
               tune your map, because (at full resolution) even a single one-
               degree block covers a 1200 by 1200 image, which is larger than
               many display screens.

               Note that the x and y values define the boundaries of the actual
               map area, but do not define the size of the output image.
               Drawmap also adds a white border around the image, which makes
               the output image a bit larger than the x and y values would

                                        - 7 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

               otherwise imply.

               Note also, that it is best to choose x and y values that are some
               integer multiple or sub-multiple of "1200 times the width and
               height of the image in degrees of longitude and latitude."  For
               example, if the image is to cover an area that is 0.1 degree
               square, then the automatically-chosen value for x and y is 60,
               and full resolution would require x and y to be set to 120.  If
               you want to specify your own dimensions with "-x" and "-y", then
               it is best to choose an integer multiple or sub-multiple of the
               full resolution of 120.  Choices, in this case, might include 30,
               120, 240, and so on.  If you choose strange values for x and y,
               then the program may produce shaded relief that contains odd-
               looking linear artifacts.  If you aren't providing DEM data, then
               you don't need to worry about this constraint.

               Odd-numbered image dimensions are inconvenient when working with
               SUN rasterfiles.  If you give odd-numbered dimensions (such as
               137 by 141), drawmap will silently make the dimensions even (as
               in 138 by 142).

          dlg_file
               Any argument that doesn't match any of the above options is
               assumed to be a DLG file.  You can add as many as you like.
               (There is a hard-coded limit in the program of 400 files, but
               feel free to increase it.) Note that files are processed in the
               order given, and each file is overlaid by the ones that come
               after it.  Thus, you generally want to put "transportation" files
               after "hydrography" files, so that roads will be shown as
               crossing over streams instead of the other way around.

        EXAMPLES
          Generate a simple shaded relief map for a portion of the southern
          California coast, with the size of the map set to a reduced resolution
          of 300x300 pixels (the default would be 600x600, and full resolution
          would be 1200x1200):

          drawmap -d santa_ana-w.gz -l 33,-117,34,-118 -x 300 -y 300

          Extract the upper right quadrant of the above map, and display it at
          full resolution:

          drawmap -d santa_ana-w.gz -l 33.5,-117,34,-117.5 -x 600
                  -y 600

          Add in some place names from a GNIS file you have prepared in advance
          (using llsearch):

          drawmap -g gnis_santa_ana_west -d santa_ana-w.gz
                  -l 33.5,-117,34,-117.5 -x 600 -y 600

                                        - 8 -         Formatted:  April 18, 2001

     DRAWMAP(1)                                                       DRAWMAP(1)

          Add in some DLG files for hydrography:

          drawmap -g gnis_santa_ana_west -d santa_ana-w.gz
                  -l 33.5,-117,34,-117.5 -x 600 -y 600
                  santa_ana-e_CA/hydrography/SN1.HYF03.opt.gz
                  santa_ana-e_CA/hydrography/SN1.HYF04.opt.gz
                  santa_ana-e_CA/hydrography/SN1.HYF07.opt.gz
                  santa_ana-e_CA/hydrography/SN1.HYF08.opt.gz

        LIMITS
          As distributed, drawmap is limited to 20 DEM files, 400 DLG files, one
          GNIS file, and one attribute file.  The DEM and DLG file limits are
          easily changed in the code.  As explained above, the GNIS limitation
          is not really a limitation, since you can concatenate as many GNIS
          records as you want into a single file.  I'm not sure how to implement
          multiple attribute files, or even what they would be used for.
          Another limitation arises from the fact that drawmap must be able to
          read all of the input data into memory.  If you want to produce large
          maps, then you must have large memory.

                                        - 9 -         Formatted:  April 18, 2001