- 1 - Formatted: April 26, 2024
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 26, 2024
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 26, 2024
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 26, 2024
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 26, 2024
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 26, 2024
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 26, 2024
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 26, 2024
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 26, 2024
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 26, 2024
